Ship24 ➕ API for per-call plans API

openapi: 3.1.0
info:
  title: Ship24 Tracking ➕ API for per-call plans ➕ API for per-call plans ➕ API for per-call plans API
  description: '## Getting started


    Make sure to read the [Getting started](https://docs.ship24.com/getting-started) section of our [API Documentation](https://docs.ship24.com/) before using the endpoints presented below.

    ## Documentation structure


    Use the top navigation bar to switch from:


    - Our [API Documentation](https://docs.ship24.com/), which contains a comprehensive explanation of how our API works.

    - Our [API Reference](https://docs.ship24.com/tracking-api-reference/), which contains the specification of each of our endpoints.

    - Our [Support](https://docs.ship24.com/support/introduction) section, which contains help articles for most of the common questions and issues you may encounter.


    ## Import our documentation into your HTTP client


    Our API Reference is available as an Open API 3.1 format file, which is supported by most HTTP clients.


    - Latest version: https://docs.ship24.com/assets/openapi/ship24-tracking-api.yaml


    | <!-- -->                                                     | <!-- -->                                                                                                                                                     |

    | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |

    | ![Postman](/img/postman-logo.svg) Postman                    | In Postman, click on "Import", go on the "Link" tab, and paste this URL `https://docs.ship24.com/assets/openapi/ship24-tracking-api.yaml`                           |

    | <img src="/img/insomnia-logo.png" width="32"></img> Insomnia | From Insomnia preferences, locate the "Import data" option, choose "From URL", and paste this URL `https://docs.ship24.com/assets/openapi/ship24-tracking-api.yaml` |'
  version: 1.0.0
  contact:
    name: Ship24
    url: https://www.ship24.com/contact-us
servers:
- url: https://api.ship24.com
tags:
- name: ➕ API for per-call plans
  description: 'The **Tracking API (Per-call Plans)** is a specific product and associated endpoint on which usage is measured per API Call made. Each API call is synchronously fetching data from couriers which make it slower and more depend on courier''s system availability.


    Our standard "Per-shipment" product & plans remain the best choice as it offers more features, allow faster tracking information fetching with less dependency on courier''s system availability at a lower cost overall.


    > ⚠ You need an active "Per-call" subscription to use this endpoint.'
paths:
  /public/v1/tracking/search:
    post:
      tags:
      - ➕ API for per-call plans
      summary: Get tracking results by tracking number
      description: "This endpoint will return the `tracking` corresponding to the tracking number provided as a parameter. \n\nThe `tracking` object is detailed in the [SCHEMAS](/schemas/tracking) section.\n\nFor better accuracy, we strongly advise to provide extra information such as the origin country, destination postcode & country, and the shipping date.\n\n> \U0001F6D1 You need an active \"Per-call\" subscription to use this endpoint. Our standard \"Per-shipment\" product & plans remain the best choice as it offers more features, allow faster tracking information fetching with less dependency on courier's system availability at a lower cost overall.\n\n\n> \U0001F6D1 As this endpoint is synchronously fetching tracking results from couriers, **response time may be up to 1 minute, and results depend on the courier's system availability** at the time of the call."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trackingNumber:
                  type: string
                  minLength: 5
                  maxLength: 50
                  example: '9400115901047177598206'
                  pattern: ^[a-zA-Z0-9-_/.]*$
                  description: Tracking number of the shipment.
                originCountryCode:
                  type: string
                  example: CN
                  description: Sender country code - 📌 Recommended to improve tracking accuracy
                  format: ISO 3166-1 alpha-2/alpha-3
                destinationCountryCode:
                  type: string
                  example: US
                  description: Recipient country code - 📌 Recommended to improve tracking accuracy
                  format: ISO 3166-1 alpha-2/alpha-3
                destinationPostCode:
                  type: string
                  example: '94901'
                  description: Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy
                shippingDate:
                  type: string
                  examples:
                  - '2021-03-01T11:09:00.000Z'
                  - '2021-03-01'
                  - '2021-03-01T11:09:00'
                  - '2021-03-01T11:09:00+02:00'
                  description: 'Date at which the shipment has been shipped  - 📌 Recommended to improve tracking accuracy: providing the shipping date helps us accurately identify the shipment and improves our ability to retrieve the correct data. However, an inaccurate shipping date could cause our system to exclude the right shipment. Therefore, please ensure the provided shipping date aligns closely with the actual shipment date, give or take a few days. [Format](http://docs.ship24.com/data-format#logistics-date-and-time)'
                  format: date-time
                courierCode:
                  type:
                  - array
                  - string
                  description: Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section)  - 📌 Recommended to improve tracking accuracy
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json; charset=utf-8
      - name: Authorization
        in: header
        schema:
          type: string
        example: Bearer your_api_key
        description: Your `api_key` prefixed with `Bearer`.
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackings:
                        type: array
                        items:
                          type: object
                          properties:
                            shipment:
                              $ref: '#/components/schemas/shipment'
                            events:
                              type: array
                              items:
                                $ref: '#/components/schemas/event'
                            statistics:
                              $ref: '#/components/schemas/statistics'
              examples:
                Success:
                  value:
                    data:
                      trackings:
                      - shipment:
                          shipmentId: f4f888d7-d140-423f-9a48-e0689d27e098
                          statusCode: delivery_delivered
                          statusCategory: delivery
                          statusMilestone: delivered
                          originCountryCode: US
                          destinationCountryCode: CN
                          delivery:
                            estimatedDeliveryDate: 2025-03-04 18:00:00
                            courierEstimatedDeliveryDate:
                              from: 2025-03-04 17:00:00
                              to: 2025-03-04 18:00:00
                            service: null
                            signedBy: null
                          trackingNumbers:
                          - tn: '9400115901047177598206'
                          - tn: '9400111202544843610364'
                          recipient:
                            name: null
                            address: null
                            postCode: '94901'
                            city: null
                            subdivision: null
                        events:
                        - eventId: ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400111202544843610364'
                          status: Delivered to the addressee
                          occurrenceDatetime: '2021-03-04T17:12:57'
                          order: 9
                          location: SAN RAFAEL, CA 94901
                          sourceCode: usps-tracking
                          courierCode: us-post
                          statusCode: delivery_delivered
                          statusCategory: delivery
                          statusMilestone: delivered
                        - eventId: ee8ebe96-4eae-4a91-9a99-8f3afa6a00ja
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400111202544843610364'
                          status: Out for Delivery
                          occurrenceDatetime: '2021-03-04T10:12:57'
                          order: 8
                          location: SAN RAFAEL, CA 94901
                          sourceCode: usps-tracking
                          courierCode: us-post
                          statusCode: delivery_out_for_delivery
                          statusCategory: delivery
                          statusMilestone: out_for_delivery
                        - eventId: ee8ebe96-4eae-4a91-9a99-8f3afa6a0765
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400111202544843610364'
                          status: Arrived at Hub, Your item arrived at the hub.
                          occurrenceDatetime: '2021-03-04T06:12:57'
                          order: 7
                          location: SAN RAFAEL, CA 94901
                          sourceCode: usps-tracking
                          courierCode: us-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: ee8ebe96-4eae-4a91-9a99-8f3afa6a0f67
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400111202544843610364'
                          status: Processed Through Regional Facility
                          occurrenceDatetime: '2021-03-03T17:12:57'
                          order: 6
                          location: LOS ANGELES CA INTERNATIONAL DISTRIBUTION CENTER
                          sourceCode: usps-tracking
                          courierCode: us-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: ee8ebe96-4eae-4a91-9a99-8f3afa6a0f24
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400111202544843610364'
                          status: Arrived at Regional Facility
                          occurrenceDatetime: '2021-03-03T15:38:57'
                          order: 5
                          location: LOS ANGELES CA INTERNATIONAL DISTRIBUTION CENTER
                          sourceCode: usps-tracking
                          courierCode: us-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: 5adff7f7-c370-4026-9ff5-2ff4156ff2ff
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400115901047177598206'
                          status: Flight Departure
                          occurrenceDatetime: '2021-03-02T23:24:50'
                          order: 4
                          location: Beijing airport
                          sourceCode: china-post-tracking
                          courierCode: cn-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: 918c20dc-9a9b-4588-bf62-ded9761d9621
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400115901047177598206'
                          status: Dispatched from Office of Exchange
                          occurrenceDatetime: '2021-03-02T22:23:41'
                          order: 3
                          location: Beijing
                          sourceCode: china-post-tracking
                          courierCode: cn-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: b8dabe5f-1022-41c5-ad3a-8c8e4aacc965
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400115901047177598206'
                          status: Departure from Local Sorting Center
                          occurrenceDatetime: '2021-03-02T19:24:57'
                          order: 2
                          location: Beijing
                          sourceCode: china-post-tracking
                          courierCode: cn-post
                          statusCode: null
                          statusCategory: null
                          statusMilestone: in_transit
                        - eventId: ee8ebe96-4eae-4a91-9a99-6f3afa6a0f45
                          trackingNumber: '9400111202544843610364'
                          eventTrackingNumber: '9400115901047177598206'
                          status: Package Received
                          occurrenceDatetime: '2021-03-02T15:38:57'
                          order: 1
                          location: Beijing
                          sourceCode: china-post-tracking
                          courierCode: cn-post
                          statusCode: null
                          statusCategory: transit
                          statusMilestone: in_transit
                        statistics:
                          timestamps:
                            infoReceivedDatetime: '2021-03-02T15:38:57'
                            inTransitDatetime: '2021-03-02T15:38:57'
                            outForDeliveryDatetime: '2021-03-04T10:12:57'
                            failedAttemptDatetime: null
                            availableForPickupDatetime: null
                            exceptionDatetime: null
                            deliveredDatetime: '2021-03-04T17:12:57'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response-format'
              example:
                errors:
                - code: validation_error
                  message: Please make sure that destinationCountryCode is a valid country code and is in ISO 3166-1 alpha-2 or alpha-3 format.
                data: null
      operationId: get-tracking
components:
  schemas:
    error-response-format:
      type: object
      x-internal: true
      title: Error response format
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
        data:
          type:
          - object
          - 'null'
    statistics:
      type: object
      x-internal: true
      properties:
        timestamps:
          type: object
          description: 'Date and time of the occurrence of each milestone of the shipment.


            [Date and time Format](https://docs.ship24.com/data-format#logistics-date-and-time)


            [List of Milestones](https://docs.ship24.com/status/#statusmilestone)'
          properties:
            infoReceivedDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `info_received` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-02T15:38:57'
            inTransitDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `in_transit` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-02T19:24:57'
            outForDeliveryDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `out_for_delivery` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-04T10:12:57'
            failedAttemptDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `failed_attempt` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-04T11:33:00'
            availableForPickupDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `available_for_pickup` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-04T15:26:00'
            exceptionDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `exception` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-04T11:33:00'
            deliveredDatetime:
              type:
              - string
              - 'null'
              format: logistic-date-time
              description: Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `delivered` [milestone](https://docs.ship24.com/status/#statusmilestone).
              example: '2021-03-05T17:12:57'
    shipment:
      type: object
      x-internal: true
      properties:
        shipmentId:
          type:
          - string
          - 'null'
          description: Unique identifier of the parcel in Ship24 system.
          example: f4f888d7-d140-423f-9a48-e0689d27e098
        statusCode:
          type:
          - string
          - 'null'
          description: '[statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment.'
          example: delivery_delivered
        statusCategory:
          type:
          - string
          - 'null'
          description: '[statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment.'
          example: delivery
        statusMilestone:
          type: string
          description: '[statusMilestone](https:docs.ship24.com/status/#statusmilestone) of the shipment.'
          example: delivered
        originCountryCode:
          type:
          - string
          - 'null'
          description: Detected country code of origin.
          example: CN
        destinationCountryCode:
          type:
          - string
          - 'null'
          description: Detected country code of destination.
          example: US
        delivery:
          type: object
          properties:
            estimatedDeliveryDate:
              type:
              - string
              - 'null'
              format: date-time
              description: 'Estimated delivery date of the shipment, if provided by the courier. Format: [Date and Time in UTC](http://docs.ship24.com/data-format#logistics-date-and-time)'
              example: '2021-03-04T18:00:00'
            courierEstimatedDeliveryDate:
              type:
              - object
              - 'null'
              description: The estimated delivery date provided by the courier.
              properties:
                from:
                  type:
                  - string
                  - 'null'
                  format: logistic-date-time
                  description: 'The earliest estimated delivery date of the shipment, if provided by the courier. Format: [Logistics date and time](http://docs.ship24.com/data-format#logistics-date-and-time)'
                  examples:
                  - '2021-03-04T17:00:00'
                to:
                  type:
                  - string
                  - 'null'
                  format: logistic-date-time
                  description: 'The latest estimated delivery date of the shipment, if provided by the courier. Format: [Logistics date and time](http://docs.ship24.com/data-format#logistics-date-and-time)'
                  examples:
                  - '2021-03-04T18:00:00'
            service:
              type:
              - string
              - 'null'
              description: Name of logistics service or product for the shipment.
              example: Parcel Post
            signedBy:
              type:
              - string
              - 'null'
              description: Name of the person who signed for the shipment.
              example: John Doe
        trackingNumbers:
          type:
          - array
          description: List of tracking numbers linked to the shipment.
          example:
          - tn: '9400111202544843610364'
          - tn: '9400115901047177598206'
          items:
            type: object
            properties:
              tn:
                type: string
                description: Tracking number.
        recipient:
          type:
          - object
          - 'null'
          description: Information on the recipient.
          properties:
            name:
              example: John Doe
              type:
              - string
              - 'null'
            address:
              example: 12515 Research Blvd
              type:
              - string
              - 'null'
            postCode:
              example: '78738'
              type:
              - string
              - 'null'
            city:
              example: city
              type:
              - string
              - 'null'
            subdivision:
              example: TX
              type:
              - string
              - 'null'
    event:
      type: object
      description: An event represents a tracking update for a shipment, such as 'In Transit', 'Out for Delivery', or 'Delivered'. Each event contains details about the status, location, time of the update, and more. The events object always contains one event at a time.
      x-internal: true
      properties:
        eventId:
          type: string
          description: Unique identifier of the event in Ship24 system.
          example: c6fbe883-49dc-7cba-48c4-46c6efd29db6
        trackingNumber:
          type: string
          description: The original tracking number used to create the Tracker.
          example: '9400111202544843610364'
        eventTrackingNumber:
          type: string
          description: The tracking number associated with the event, on which the event has been found.
          example: '9400111202544843610364'
        status:
          type: string
          nullable: true
          description: Event raw text.
          example: Delivered to the addressee
        occurrenceDatetime:
          type: string
          format: logistic-date-time
          description: '[Date and time](http://docs.ship24.com/data-format#logistics-date-and-time) at which the event occurred.'
          examples:
          - '2021-03-04T17:12:57'
          - '2021-03-04T10:12:57.000Z'
          - '2021-03-04T10:12:57+02:00'
          - '2021-03-04'
        order:
          type:
          - integer
          - 'null'
          nullable: true
          description: Indicate the order of the events in case the occurrenceDatetime is the same between multiple events (lower is older).
          example: 1
        location:
          type:
          - string
          - 'null'
          nullable: true
          description: Location raw text of the event.
          example: SAN RAFAEL, CA 94901
        sourceCode:
          type:
          - string
          - 'null'
          nullable: true
          description: Internal code of the source used to get this event. Please note that those codes may evolve at any point in time.
          example: usps-tracking
        courierCode:
          type:
          - string
          - 'null'
          nullable: true
          description: Code of the courier linked to this event, refers to our Couriers list. Please note that those codes may evolve at any point in time.
          example: us-post
        statusCode:
          type:
          - string
          - 'null'
          nullable: true
          description: '[statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.

            '
          example: delivery_delivered
        statusCategory:
          type:
          - string
          - 'null'
          nullable: true
          example: delivery
          description: '[statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.

            '
        statusMilestone:
          type: string
          example: delivered
          description: '[statusMilestone](https://docs.ship24.com/status/#statusmilestone) of the shipment at the time of the event.'
        datetime:
          deprecated: true
          type: string
          format: date-time
        utcOffset:
          deprecated: true
          type: string
        hasNoTime:
          deprecated: true
          type: boolean
  securitySchemes:
    Authorization:
      name: Bearer your_api_key
      type: apiKey
      in: header
      description: 'The Ship24 API uses API keys to authenticate requests. You can [view and manage them in your Dashboard](https://dashboard.ship24.com/integrations/api-keys). A `Default` API key is created after you subscribe to a plan.


        To authenticate your requests, include an `Authorization` HTTP header to all your requests with the following value: `Bearer your_api_key`. (Replace `your_api_key` by the one from your dashboard and don''t forget the `Bearer` prefix.)'