openapi: 3.1.0
info:
title: Ship24 Tracking ➕ API for per-call plans ➕ API for per-call plans 📦 Trackers 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 | 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: 📦 Trackers
paths:
/public/v1/trackers:
parameters: []
post:
tags:
- 📦 Trackers
summary: Create a tracker
description: 'This endpoint allows you to create a new `Tracker`, based on the specified information. Once a `Tracker` is created, you will be able to receive webhook notifications and/or fetch its tracking result.
> This endpoint is idempotent, any subsequent calls with the same parameters won''t duplicate `Tracker`. However, providing different information in any of the fields will create a new `Tracker`, as it will be considered as a new shipment.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/tracker-create-request'
examples:
Valid request:
value:
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
originCountryCode: CN
destinationCountryCode: US
destinationPostCode: '94901'
shippingDate: '2021-03-01T11:09:00.000Z'
courierCode:
- us-post
courierName: USPS Standard
trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400115901047177598206
orderNumber: DF14R2022
settings:
restrictTrackingToCourierCode: true
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json; charset=utf-8
description: application/json; charset=utf-8
required: true
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
operationId: create-tracker
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
tracker:
$ref: '#/components/schemas/tracker'
examples:
Success:
value:
data:
tracker:
trackerId: 26148317-7502-d3ac-44a9-546d240ac0dd
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
isSubscribed: true
isTracked: true
createdAt: '2021-03-10T05:13:00.000Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error-response-format'
examples:
Invalid tracking number:
value:
errors:
- code: validation_error
message: The trackingNumber provided seems invalid. Please make sure it's between 5 and 50 characters, containing only letters, numbers, and hyphens, and without dummy patterns and consecutive numbers.
data: null
get:
tags:
- 📦 Trackers
summary: List existing Trackers
description: This endpoint return a list of all existing `Trackers`, using page-based pagination.
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
- name: page
in: query
schema:
type: integer
minimum: 1
description: The page index, starting from 1.
example: 1
required: true
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 500
description: The maximum number of trackers returned per page.
example: 100
required: true
- name: sort
in: query
schema:
type: integer
enum:
- 1
- -1
description: Defines the sorting order of trackers. Use `1` for ascending (`createdAt` oldest first) and `-1` for descending (`createdAt` newest first). The default is ascending (`1`) to ensure stable pagination.
example: 1
required: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
trackers:
type: array
items:
$ref: '#/components/schemas/tracker'
examples:
Success:
value:
data:
trackers:
- trackerId: 0018fa7d-0040-478c-9043-70c3e240e7b3
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.181Z'
- trackerId: 001a975d-768d-4e16-a2b2-cff8a8f7e7fb
trackingNumber: '9400111202544843610609'
shipmentReference: 85bff7fa-38ed-b1ba-4c15-322e41d16221
clientTrackerId: c284fa2c-0808-48ea-bb9e-05c9135dc127
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.179Z'
- trackerId: 002be605-6098-444c-8dff-762b314438ef
trackingNumber: LA680658838NL
shipmentReference: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.189Z'
- trackerId: 0035a920-c41b-4d12-8c2a-65b13a5da389
trackingNumber: LT621980897
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.195Z'
- trackerId: 004cece2-1a17-407f-97f8-9fd077dfa6b6
trackingNumber: 00340434639921278870
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.196Z'
- trackerId: 0077a6e2-39a3-48b7-a91f-e6e4f2bb9422
trackingNumber: H00F6A0043571732
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.189Z'
- trackerId: 008a8ebc-28d5-427b-92c4-4ab4a54e9eef
trackingNumber: SYRM129017918
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.187Z'
- trackerId: 00969ba9-9d16-4b14-803c-c47737cd0ece
trackingNumber: LY396870931DE
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.182Z'
- trackerId: 0098fa69-fa43-42c3-b315-6e72245f2f4c
trackingNumber: H00F6A0041475344
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.180Z'
- trackerId: 00b0ec18-ed69-48bc-90c0-8f5349f0fb5b
trackingNumber: H00F6A0043810576
shipmentReference: null
clientTrackerId: null
isSubscribed: true
isTracked: true
createdAt: '2022-12-23T10:55:39.194Z'
application/xml:
schema:
type: object
properties:
? ''
: type: string
multipart/form-data:
schema:
type: object
properties:
trackingNumber:
type: string
shipmentReference:
type: string
clientTrackerId:
type: string
originCountryCode:
type: string
destinationCountryCode:
type: string
destinationPostCode:
type: string
shippingDate:
type: string
format: date-time
courierCode:
type: array
items:
type: string
courierName:
type: string
trackingUrl:
type: string
operationId: list-trackers
/public/v1/trackers/bulk:
post:
tags:
- 📦 Trackers
summary: Bulk create trackers
description: 'This endpoint allows you to create up to 100 new `Trackers` in a single operation, based on the specified information. Once the `Trackers` are created, you will be able to receive webhook notifications and/or fetch their tracking results.
> While tracker creation is idempotent, this endpoint itself is not. Any duplicate within the request or any tracker parameters matching an existing tracker will not create a duplicate `Tracker`. However, providing different information in any of the fields will create a new `Tracker`, as it will be considered as a new shipment.
The response will include a summary of:
- The number of trackers successfully created.
- The number of trackers ignored because they already exist.
- The number of trackers that could not be created due to errors.
Additionally, the response will provide details about the created trackers and any errors that occurred during the tracker creation process.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-create-trackers-request'
examples:
Valid request:
value:
- trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
originCountryCode: CN
destinationCountryCode: US
destinationPostCode: '94901'
shippingDate: '2021-03-01T11:09:00.000Z'
courierCode:
- us-post
courierName: USPS Standard
trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400115901047177598206
orderNumber: DF14R2022
settings:
restrictTrackingToCourierCode: true
- trackingNumber: '9400111202544843610609'
shipmentReference: 85bff7fa-38ed-b1ba-4c15-322e41d16221
clientTrackerId: c284fa2c-0808-48ea-bb9e-05c9135dc127
originCountryCode: CN
destinationCountryCode: US
destinationPostCode: '94901'
shippingDate: '2021-03-05T14:21:00.000Z'
courierCode:
- us-post
courierName: USPS
trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111202544843610609
orderNumber: DF14R2024
settings:
restrictTrackingToCourierCode: true
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json; charset=utf-8
description: application/json; charset=utf-8
required: true
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
operationId: bulk-create-trackers
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-create-trackers-response'
examples:
Success:
$ref: '#/components/examples/response-bulk-create-trackers/Success'
'207':
description: Partially Created
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-create-trackers-response'
examples:
Partial:
$ref: '#/components/examples/response-bulk-create-trackers/Partial'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-create-trackers-response'
examples:
Bad request:
$ref: '#/components/examples/response-bulk-create-trackers/Bad request'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/bulk-create-trackers-response'
examples:
Forbidden:
$ref: '#/components/examples/response-bulk-create-trackers/Forbidden'
/public/v1/trackers/track:
post:
tags:
- 📦 Trackers
summary: Create a tracker and get tracking results
description: 'This endpoint creates a new `Tracker` on the specified tracking number , if it does not exist, and returns the tracking results directly. We advise using this endpoint if you are not interested in receiving webhook notifications and just want to fetch tracking results. This way, you can always call this unified endpoint to get tracking results, without worrying about `Tracker` creation and management.
> 🛑 During the very first call for a tracking number, this endpoint will create a `Tracker` and try to return tracking results synchronously if the courier allows it, which can delay the initial answer, at the benefit of getting the tracking results from the first call. **Initial response time may range from a few seconds, up to 1 minute, and results will depend on the courier''s system availability at that time.** Subsequent calls will be instantaneous as the `Tracker` will already exist with tracking results ready to use and constantly updated.
> This endpoint is idempotent, any subsequent calls with the same parameters won''t duplicate `Tracker`. However, providing different information in any of the fields will create a new `Tracker` as it will be considered as a new shipment.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/tracker-create-request'
examples:
Valid request:
value:
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
originCountryCode: CN
destinationCountryCode: US
destinationPostCode: '94901'
shippingDate: '2021-03-01T11:09:00.000Z'
courierCode:
- us-post
courierName: USPS Standard
trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400115901047177598206
orderNumber: DF14R2022
settings:
restrictTrackingToCourierCode: true
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json; charset=utf-8
description: application/json; charset=utf-8
required: true
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
trackings:
type: array
items:
type: object
properties:
tracker:
$ref: '#/components/schemas/tracker'
shipment:
$ref: '#/components/schemas/shipment'
events:
type: array
items:
$ref: '#/components/schemas/event'
statistics:
$ref: '#/components/schemas/statistics'
examples:
Success:
$ref: '#/components/examples/response-result-tracker'
operationId: create-tracker-and-get-tracking-results
/public/v1/trackers/{trackerId}:
get:
tags:
- 📦 Trackers
summary: Get an existing tracker
description: This endpoint return an existing `Tracker` for a given `trackerId`.
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
- name: trackerId
in: path
schema:
type: string
required: true
description: '**Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter.'
example: 26148317-7502-d3ac-44a9-546d240ac0dd
- name: searchBy
in: query
schema:
type: string
enum:
- trackerId
- clientTrackerId
example: trackerId
description: Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/tracker'
examples:
Success:
value:
data:
tracker:
trackerId: 26148317-7502-d3ac-44a9-546d240ac0dd
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
isSubscribed: true
isTracked: true
createdAt: '2021-03-10T05:13:00.000Z'
description: OK
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/error-response-format'
examples:
Not found:
value:
errors:
- code: tracker_not_found
message: Tracker not found.
data: null
operationId: get-tracker-by-trackerId
patch:
tags:
- 📦 Trackers
summary: Update an existing tracker
description: "This endpoint allows to modify an existing `Tracker` matching with the given `trackerId`. \n\n> Once the Tracker has gathered shipment tracking information, certain fields related to the shipment data cannot be modified. These include: \n> - `courierCode` \n> - `originCountryCode` \n> - `destinationCountryCode` \n> - `shippingDate`"
requestBody:
content:
application/json:
schema:
type: object
properties:
isSubscribed:
type: boolean
example: false
description: Setting at `false` will unsubscribe you from the `Tracker`. Once unsubscribed, you will still be able to fetch the existing tracking results but Ship24 won't search for new data or send webhook notifications. `Trackers` are automatically disabled after the parcel delivery or after a long period without any new events. Manually unsubscribing your tracker is not useful, except if you wish to stop receiving webhooks on it or if you need to reuse the `clientTrackerId` value in a new `Tracker`.
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
example:
- us-post
minItems: 0
maxItems: 3
items:
type: string
originCountryCode:
type: string
example: CN
description: Sender country code.
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
format: date-time
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)'
examples:
Patching:
value:
isSubscribed: false
originCountryCode: CN
destinationCountryCode: US
destinationPostCode: '94901'
shippingDate: '2021-03-01T11:09:00.000Z'
courierCode:
- us-post
description: 'Only the following property can be updated on a Tracker:'
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json; charset=utf-8
description: 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
- name: trackerId
in: path
schema:
type: string
required: true
example: 26148317-7502-d3ac-44a9-546d240ac0dd
description: '**Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter.'
- name: searchBy
in: query
schema:
type: string
enum:
- trackerId
- clientTrackerId
example: trackerId
description: Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/tracker'
examples:
Successfully updated:
value:
data:
tracker:
trackerId: 26148317-7502-d3ac-44a9-546d240ac0dd
trackingNumber: '9400115901047177598206'
shipmentReference: c6e4fef4-a816-b68f-4024-3b7e4c5a9f81
clientTrackerId: 3fa99515-3ca0-4901-85bb-056ee016799b
isSubscribed: true
isTracked: true
createdAt: '2021-03-10T05:13:00.000Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error-response-format'
examples:
Update refused:
value:
errors:
- code: tracker_not_updatable
message: This Tracker can't be updated as the corresponding shipment has been already processed by our system. Please create a new Tracker.
data: null
operationId: update-tracker-by-trackerId
/public/v1/trackers/search/{trackingNumber}/results:
get:
tags:
- 📦 Trackers
summary: Get tracking results for existing trackers by tracking number
description: "This endpoint will return the `tracking` result corresponding to the tracking number provided as a parameter. \n\nThe `tracking` object is detailed in the [SCHEMAS](/schemas/tracking) section. \n\nUnlike the `/v1/trackers/track` endpoint, a **`Tracker`** **must first be created on this tracking number before using this endpoint.** As a tracking number is not unique, the endpoint may return multiple `trackings` associated with different `Trackers`."
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
- name: trackingNumber
in: path
schema:
type: string
required: true
description: '**Required** Tracking number of the parcel.'
example: '9400115901047177598206'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
trackings:
type: array
items:
type: object
properties:
tracker:
$ref: '#/components/schemas/tracker'
shipment:
$ref: '#/components/schemas/shipment'
events:
type: array
items:
$ref: '#/components/schemas/event'
statistics:
$ref: '#/components/schemas/statistics'
examples:
Success:
$ref: '#/components/examples/response-result-tracker'
operationId: get-tracking-results-of-trackers-by-tracking-number
/public/v1/trackers/{trackerId}/results:
get:
tags:
- 📦 Trackers
summary: Get tracking results for an existing tracker
description: "This endpoint return the `Tracking` results of an existing `Tracker` matching with the given trackerId. As trackerId are unique, the `Trackings` array will always have only one item. \n\nThe `tracking` object is detailed in the [SCHEMAS](/schemas/tracking) section.\n\nUnlike the `/v1/trackers/track` endpoint, a **`Tracker`** **must first be created on this tracking number before using this endpoint.** As a tracking number is not unique, the endpoint may return multiple `trackings` associated with different `Trackers`."
parameters:
- name: Authorization
in: header
schema:
type: string
example: Bearer your_api_key
description: Your `api_key` prefixed with `Bearer`.
required: true
- name: trackerId
in: path
schema:
type: string
required: true
description: '**Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter.'
example: 26148317-7502-d3ac-44a9-546d240ac0dd
- name: searchBy
in: query
schema:
type: string
enum:
- trackerId
- clientTrack
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ship24/refs/heads/main/openapi/ship24-trackers-api-openapi.yml