openapi: 3.2.0
info:
  title: Shipcloud Pickup Requests API
  version: '1.0'
  contact:
    name: Developer Support
    email: developers@shipcloud.io
  termsOfService: https://www.shipcloud.io/en/terms-and-conditions
  description: 'Operations tagged Pickup Requests across 2 of this provider''s published API definitions: shipcloud_v1_oai3.json, shipcloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.shipcloud.io/v1
security:
- basic_auth: []
tags:
- name: Pickup Requests
paths:
  /pickup_requests:
    get:
      description: Get all pickup requests for this user
      responses:
        '200':
          description: A list of pickup requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pickup_request_object'
              examples:
                Pickup requests response:
                  $ref: '#/components/examples/pickup_requests_response_example_multiple'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Pickup Requests
      summary: Get pickup requests
      x-summary-source: derived
      operationId: getPickupRequests
      x-operation-id-source: derived
    post:
      description: Create a pickup request with a carrier, so they come and get the parcels
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/pickup'
              - type: object
                description: Pickup request for a one time pickup
                properties:
                  carrier:
                    type: string
                    enum:
                    - ups
                    - dpd
                    - hermes
                    - gls
                    description: acronym of the carrier you want to use
                  shipments:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          description: The identifier of the shipment that should be picked up
              required:
              - carrier
              - pickup_time
              - pickup_address
            examples:
              Pickup request for collecting all shipments from a carrier:
                $ref: '#/components/examples/pickup_requests_example'
              Pickup request using specific shipment IDs:
                $ref: '#/components/examples/pickup_requests_example_with_shipment_ids'
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                Pickup request response:
                  $ref: '#/components/examples/pickup_requests_response_example_single'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Pickup Requests
      summary: Create pickup requests
      x-summary-source: derived
      operationId: postPickupRequests
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
  /pickup_requests/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: Identifier of a pickup
      schema:
        type: string
    get:
      description: Returns a single pickup request based on the id
      responses:
        '200':
          description: Detailed information about a single pickup request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pickup_request_object'
              examples:
                Pickup requests response:
                  $ref: '#/components/examples/pickup_requests_response_example_single'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Pickup Requests
      summary: Get pickup requests by id
      x-summary-source: derived
      operationId: getPickupRequestsById
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
components:
  responses:
    '404':
      description: The api endpoint or ressource you were trying to reach can't be found.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '422':
      description: Your request was well-formed but couldn't be followed due to semantic errors. Please see the response body for more detailed information. A possible problem could be that you are not sending all the data that is required or data that is not necessary for this call.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '401':
      description: Something has gone wrong when authorizing with our API. Please check e.g. if you're trying to use your sandbox api key with an operation that can only be used with a live API key.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '403':
      description: You are not allowed to talk to this endpoint. This can either be due to a wrong authentication or when you're trying to reach an endpoint that your account isn't allowed to access.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '500':
      description: Something has seriously gone wrong. Don't worry, we'll have a look at it. If the error persists, please don't hesitate to contact us by sending us an email containing the `X-Request-ID` header we've returned.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '400':
      description: Your request was not correct. Please see the response body for more detailed information.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  description: Strings that describe, what has gone wrong. We're tunnelling error responses from the carriers. When this is the case, we try to prefix an error with 'The carrier {xyz} returned the following error:'
                  type: string
          examples:
            Single error:
              value:
                errors:
                - simple error message
            Multiple errors:
              value:
                errors:
                - simple error message
                - another error message
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '402':
      description: You've reached a maximum that is defined in your current plan. Please upgrade to a higher plan.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
  schemas:
    pickup:
      type: object
      description: for some carriers a pickup has to be requested when creating a shipment
      properties:
        pickup_time:
          $ref: '#/components/schemas/pickup_time_object'
        pickup_address:
          $ref: '#/components/schemas/address_with_id'
    pickup_time_object:
      type: object
      properties:
        earliest:
          type: string
          format: date-time
          description: Earliest pickup date and time
        latest:
          type: string
          format: date-time
          description: Latest pickup date and time
      description: defines a time window in which the carrier should pickup shipments
      required:
      - earliest
      - latest
    pickup_request_object:
      type: object
      properties:
        id:
          type: string
          description: shipcloud identifier for this pickup request
        carrier:
          allOf:
          - $ref: '#/components/schemas/carrier_pickup'
          - description: carrier used for this pickup request
        carrier_pickup_number:
          type: string
          description: Identifier that the carrier uses for this pickup request
        pickup_time:
          $ref: '#/components/schemas/pickup_time_object'
        pickup_address:
          $ref: '#/components/schemas/address_with_id'
        shipments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: id of the shipment included in this pickup request
          required:
          - id
      required:
      - id
      - carrier
      - pickup_time
    address:
      type: object
      properties:
        care_of:
          type:
          - string
          - 'null'
          description: Additional care of field
        city:
          type: string
          description: Name of the city
        country:
          type: string
          description: Country as uppercase ISO 3166-1 alpha-2 code
        first_name:
          type:
          - string
          - 'null'
          description: A persons first name
        state:
          type:
          - string
          - 'null'
          description: The state the address is in
        street:
          type: string
          description: Name of the street. Can hold the house number
        street_no:
          type:
          - string
          - 'null'
          description: House number of the address (when a carrier requires it separately)
        zip_code:
          type: string
          description: Zipcode of the address
        phone:
          type: string
          description: 'Telephone number (mandatory when using UPS and the following terms apply: service is `one_day` or `one_day_early` or ship to country is different than ship from country)'
        email:
          type: string
          description: Email address for this person. Some carrier are using the email address to send notifications
      required:
      - street
      - city
      - zip_code
      - country
    carrier_pickup:
      type: string
      enum:
      - dpd
      - hermes
      - ups
      description: acronym of the carrier
    address_with_id:
      allOf:
      - $ref: '#/components/schemas/address'
      - type: object
        properties:
          id:
            type: string
            description: identifier of a previously created address
        required:
        - id
        - first_name
        - last_name
        - company
        - care_of
        - state
        - street_no
  headers:
    RateLimit-Interval:
      description: The number of seconds the interval for this user is long (e.g. 60)
      schema:
        type: integer
    RateLimit-Reset:
      description: The number of seconds that shows when the request rate limit resets (e.g. 42)
      schema:
        type: integer
    RateLimit-Remaining:
      description: Remaining number of request in the current interval (e.g. 111)
      schema:
        type: integer
    shicloud-Request-ID:
      description: An internal identifier that we generate for every request. If you encounter a problem with your request, please send us this id when opening a support case.
      schema:
        type: string
    RateLimit-Limit:
      description: A number that shows the overall limit of requests this user can send (e.g. 120)
      schema:
        type: integer
  examples:
    pickup_requests_example:
      value:
        carrier: dpd
        pickup_time:
          earliest: '2018-07-30T09:00:00+02:00'
          latest: '2018-07-30T18:00:00+02:00'
        pickup_address:
          company: Muster-Company
          first_name: Max
          last_name: Mustermann
          care_of: null
          street: Musterstraße
          street_no: '42'
          zip_code: '22457'
          city: Hamburg
          state: null
          country: DE
          phone: 555-555
          id: 286daf26-c845-4dba-ae49-75582fbced00
    pickup_requests_response_example_multiple:
      value:
      - id: 123467a6-8e15-4a59-e145-0953f31c1196
        carrier: ups
        carrier_pickup_number: 299A80MA91P
        shipments:
        - id: 199f803bf82fab79e17654213b61993fa78b0524
        - id: 3a186c51d4281acbecf5ed38805b1db92a9d668b
        pickup_time:
          earliest: '2018-07-30T09:00:00+02:00'
          latest: '2018-07-30T18:00:00+02:00'
        pickup_date: 2018/07/30
        pickup_address:
          id: 7ea2a290-b456-4ecf-9010-e82b3da298f0
          company: Apple Inc.
          first_name: Tim
          last_name: Cook
          care_of: null
          street: Infinite Loop
          street_no: '1'
          zip_code: '95014'
          city: Cupertino
          state: CA
          country: US
          phone: 408-996-1010
      - id: c28a4ec0-e1ae-47a6-acae-1349ff0da52a
        carrier: dpd
        carrier_pickup_number: '9380'
        shipments:
        - id: 604681675415e96052cf8fbaba78153a2e6d6bee
        - id: 11acaa0c4f251aaac4889d5f10329eb1aed80ff2
        - id: 9a5b91d766a523447c16897f8e20f4d7d06c25ca
        pickup_time:
          earliest: '2018-07-30T09:00:00+02:00'
          latest: '2018-07-30T18:00:00+02:00'
        pickup_address:
          id: 286daf26-c845-4dba-ae49-75582fbced00
          company: Muster-Company
          first_name: Max
          last_name: Mustermann
          care_of: null
          street: Musterstraße
          street_no: '42'
          zip_code: '22457'
          city: Hamburg
          state: null
          country: DE
          phone: 555-555
    pickup_requests_example_with_shipment_ids:
      value:
        carrier: dpd
        pickup_time:
          earliest: '2018-07-30T09:00:00+02:00'
          latest: '2018-07-30T18:00:00+02:00'
        pickup_address:
          id: 286daf26-c845-4dba-ae49-75582fbced00
          company: Muster-Company
          first_name: Max
          last_name: Mustermann
          care_of: null
          street: Musterstraße
          street_no: '42'
          zip_code: '22457'
          city: Hamburg
          state: null
          country: DE
          phone: 555-555
        shipments:
        - id: 604681675415e96052cf8fbaba78153a2e6d6bee
        - id: 11acaa0c4f251aaac4889d5f10329eb1aed80ff2
        - id: 9a5b91d766a523447c16897f8e20f4d7d06c25ca
    pickup_requests_response_example_single:
      value:
        id: c28a4ec0-e1ae-47a6-acae-1349ff0da52a
        carrier: dpd
        carrier_pickup_number: '9380'
        shipments:
        - id: 604681675415e96052cf8fbaba78153a2e6d6bee
        - id: 11acaa0c4f251aaac4889d5f10329eb1aed80ff2
        - id: 9a5b91d766a523447c16897f8e20f4d7d06c25ca
        pickup_time:
          earliest: '2018-07-30T09:00:00+02:00'
          latest: '2018-07-30T18:00:00+02:00'
        pickup_address:
          id: 286daf26-c845-4dba-ae49-75582fbced00
          company: Muster-Company
          first_name: Max
          last_name: Mustermann
          care_of: null
          street: Musterstraße
          street_no: '42'
          zip_code: '22457'
          city: Hamburg
          state: null
          country: DE
          phone: 555-555
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  description: Find more info at the shipcloud developer portal
  url: https://developers.shipcloud.io
x-refined-from:
- shipcloud_v1_oai3.json
- shipcloud-openapi.yml