openapi: 3.2.0
info:
  title: Shipcloud Trackers API
  version: '1.0'
  contact:
    name: Developer Support
    email: developers@shipcloud.io
  termsOfService: https://www.shipcloud.io/en/terms-and-conditions
  description: 'Operations tagged Trackers 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: Trackers
paths:
  /trackers:
    get:
      description: Get a list of previously created trackers
      responses:
        '200':
          description: A list of trackers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  trackers:
                    type: array
                    items:
                      $ref: '#/components/schemas/tracker_object_with_id'
              examples:
                Getting all trackers:
                  $ref: '#/components/examples/trackers_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:
      - Trackers
      summary: Get trackers
      x-summary-source: derived
      operationId: getTrackers
      x-operation-id-source: derived
    post:
      description: Creating a tracker
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Trackers allow you to monitor a shipment even though it wasn't created using shipcloud
              properties:
                carrier_tracking_no:
                  type: string
                  description: Tracking number (provided by the carrier) of the shipment which should be monitored
                carrier:
                  allOf:
                  - $ref: '#/components/schemas/carrier_tracking_only'
                  - description: acronym of the carrier the shipment was created with
                to:
                  oneOf:
                  - allOf:
                    - $ref: '#/components/schemas/address'
                    - description: the receivers address
                  - type: object
                    properties:
                      id:
                        type: string
                        description: id of a receivers address
                    required:
                    - id
                from:
                  oneOf:
                  - allOf:
                    - $ref: '#/components/schemas/address'
                    - description: the senders address
                  - type: object
                    properties:
                      id:
                        type: string
                        description: id of a senders address
                    required:
                    - id
                notification_email:
                  type: string
                  description: email address that we should notify once there's an update for this shipment. Usually the recipients'
              required:
              - carrier_tracking_no
              - carrier
            examples:
              Tracker creation request:
                $ref: '#/components/examples/trackers_requests_example'
      responses:
        '200':
          description: A tracker has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tracker_object_with_id'
              examples:
                Tracker with ID response:
                  $ref: '#/components/examples/tracker_with_id_example'
          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:
      - Trackers
      summary: Create trackers
      x-summary-source: derived
      operationId: postTrackers
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
  /trackers/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: a tracker identifier
      schema:
        type: string
    get:
      description: Get a single tracker
      responses:
        '200':
          description: Returns information about a single tracker based on its identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tracker_object_with_id'
              examples:
                Tracker with ID response:
                  $ref: '#/components/examples/tracker_with_id_example'
          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:
      - Trackers
      summary: Get trackers by id
      x-summary-source: derived
      operationId: getTrackersById
      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'
  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
  schemas:
    tracker_object:
      type: object
      properties:
        carrier_tracking_no:
          type: string
          description: tracking number (provided by the carrier) for this shipment
        status:
          type: string
          enum:
          - registered
          - label_created
          - picked_up
          - delivered
          - not_delivered
          - transit
          - exception
          - out_for_delivery
          - destroyed
          - unknown
          - canceled
          description: key describing the current status
        created_at:
          type: string
          format: date-time
          description: timestamp the tracker was created
        from:
          anyOf:
          - $ref: '#/components/schemas/address_with_id'
          - type: object
            properties:
              id:
                type: string
                description: id of a senders address
            required:
            - id
        tracking_status_updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: timestamp the tracking status was last updated
        last_polling_at:
          type:
          - string
          - 'null'
          format: date-time
          description: timestamp the shipment status was last polled at the carrier
        next_polling_at:
          type: string
          format: date-time
          description: timestamp the shipment status will be polled the next time
        shipment_id:
          type: string
          description: id of the corresponding shipment within shipcloud
        carrier:
          allOf:
          - $ref: '#/components/schemas/carrier_tracking_only'
          - description: acronym of the carrier the shipment was sent with
        to:
          anyOf:
          - $ref: '#/components/schemas/address_with_id'
          - type: object
            properties:
              id:
                type: string
                description: id of a receivers address
            required:
            - id
        tracking_events:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
                description: timestamp of when this event occured
              location:
                type: string
                description: location of the package at this moment
              status:
                type: string
                enum:
                - registered
                - label_created
                - picked_up
                - delivered
                - not_delivered
                - transit
                - exception
                - out_for_delivery
                - destroyed
                - unknown
                - canceled
                description: key describing the status
              details:
                type: string
                description: message the carrier sends to describe the shipments status
            required:
            - timestamp
            - location
            - status
      required:
      - id
      - carrier_tracking_no
      - status
      - created_at
      - tracking_status_updated_at
      - last_polling_at
      - next_polling_at
      - shipment_id
      - carrier
    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
    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
    tracker_object_with_id:
      allOf:
      - $ref: '#/components/schemas/tracker_object'
      - properties:
          id:
            type: string
            description: the tracker id that can be used for requesting info about a tracker
        required:
        - id
    carrier_tracking_only:
      type: string
      enum:
      - dhl
      - dpd
      - gls
      - ups
      description: acronym of the carrier
  examples:
    tracker_with_id_example:
      value:
        id: 4a6922e2-09ad-4724-807c-7b4e572d3c6b
        carrier_tracking_no: '723558934169'
        status: registered
        created_at: '2015-07-20T09:35:23+02:00'
        to:
          id: 7ea2a290-b456-4ecf-9010-e82b3da298f0
          first_name: Hans
          last_name: Meier
          street: Semmelweg
          street_no: '1'
          zip_code: '12345'
          city: Hamburg
          country: DE
        tracking_status_updated_at: null
        last_polling_at: null
        next_polling_at: '2015-07-20T09:35:23+02:00'
        shipment_id: 12345abcdef
        carrier: ups
        tracking_events: []
    trackers_requests_example:
      value:
        carrier_tracking_no: '723558934169'
        carrier: ups
    trackers_requests_response_example_multiple:
      value:
        trackers:
        - id: 4a6922e2-09ad-4724-807c-7b4e572d3c6b
          carrier_tracking_no: '723558934169'
          to:
            id: 1c81efb7-9b95-4dd8-92e3-cac1bca3df6f
            first_name: Hans
            last_name: Meier
            street: Semmelweg
            street_no: '1'
            zip_code: '12345'
            city: Hamburg
            country: DE
          status: delivered
          created_at: '2015-07-20T09:35:23+02:00'
          tracking_status_updated_at: '2015-08-01T11:35:23+02:00'
          last_polling_at: '2015-08-03T10:23:45+02:00'
          next_polling_at: '2015-08-03T12:23:45+02:00'
          shipment_id: 6306d78506af51913c89b0af45b1ba7d430e4208
          carrier: ups
          tracking_events:
          - id: 0aa3479-8695-4a6a-8326-ed55df65b9a6
            timestamp: '2015-07-21T08:57:44+02:00'
            location: Hamburg
            status: out_for_delivery
            details: Some details
          - id: 0aa3479-8695-4a6a-8326-ed55df65b9a6
            timestamp: '2015-07-21T10:57:44+02:00'
            location: Hamburg
            status: delivered
            details: Some more details
        - id: 5452ec46-560e-42ba-adf7-8a1b46d60ece
          carrier_tracking_no: JJD000390006125214950
          to:
            id: 1c81efb7-9b95-4dd8-92e3-cac1bca3df6f
            first_name: Hans
            last_name: Meier
            street: Semmelweg
            street_no: '1'
            zip_code: '12345'
            city: Hamburg
            country: DE
          from:
            id: 1c81efb7-9b95-4dd8-92e3-cac1bca3df6f
            company: webionate GmbH
            last_name: Fahlbusch
            street: Lüdmoor
            street_no: 35a
            zip_code: '22175'
            city: Hamburg
            country: DE
          status: delivered
          created_at: '2016-12-26T08:48:21+02:00'
          tracking_status_updated_at: '2016-12-28T12:16:44+02:00'
          last_polling_at: '2016-12-28T22:10:45+02:00'
          next_polling_at: '2016-12-28T22:12:45+02:00'
          shipment_id: cbceeb51314c88e8047b8b5dfd92313528238b88
          carrier: dhl
          tracking_events:
          - id: 0aa3479-8695-4a6a-8326-ed55df65b9a6
            timestamp: '2016-12-26T08:48:21+02:00'
            location: Radefeld
            status: transit
            details: Lieferung hat das Logistikzentrum verlassen und ist unterwegs.
          - id: 0aa3479-8695-4a6a-8326-ed55df65b9a6
            timestamp: '2016-12-28T09:34:11+02:00'
            location: Hamburg
            status: out_for_delivery
            details: Sendung wird zugestellt.
          - id: 0aa3479-8695-4a6a-8326-ed55df65b9a6
            timestamp: '2016-12-28T12:16:44+02:00'
            location: Hamburg
            status: delivered
            details: 'Ihre Sendung wurde zugestellt. Die Sendung wurde zugestellt an Simon Fröhler shipcloud GmbH. '
  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