← Files Ship24 Tracking APIARCHIVED FILE
skills/ship24-troubleshooting/references/endpoints.md
24.6 KB · Oct 5, 2026 · 18:35 UTC
<!-- GENERATED by scripts/generate-references.mjs from spec/ship24-tracking-api.yaml, data/rate-limits.json, data/courier-required-fields.json. Do not edit; run pnpm generate. -->
# Ship24 Tracking API endpoints
Base URL: `https://api.ship24.com/public/v1`. Authenticate every request with an `Authorization: Bearer <api key>` header.
| Method | Path | operationId | Summary | Rate limit req/s |
| --- | --- | --- | --- | --- |
| POST | /trackers | create-tracker | Create a tracker | 10 |
| GET | /trackers | list-trackers | List existing Trackers | 10 |
| POST | /trackers/bulk | bulk-create-trackers | Bulk create trackers | 3 |
| POST | /trackers/track | create-tracker-and-get-tracking-results | Create a tracker and get tracking results | 10 |
| GET | /trackers/{trackerId} | get-tracker-by-trackerId | Get an existing tracker | 10 |
| PATCH | /trackers/{trackerId} | update-tracker-by-trackerId | Update an existing tracker | 10 |
| GET | /trackers/search/{trackingNumber}/results | get-tracking-results-of-trackers-by-tracking-number | Get tracking results for existing trackers by tracking number | 10 |
| GET | /trackers/{trackerId}/results | get-tracking-results-of-tracker-by-trackerId | Get tracking results for an existing tracker | 10 |
| GET | /couriers | get-couriers | Get all couriers | 1 |
| POST | /tracking/search | get-tracking | Get tracking results by tracking number | 10 |
| POST | /trackers/{trackerId}/webhook-events/resend | resend-webhooks | Resend webhooks of an existing tracker | 1 |
| GET | /trackers/{trackerId}/webhook-history/download | download-webhook-history | Download webhook history of an existing tracker | n/a |
### POST /trackers
**Create a tracker** (`create-tracker`)
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.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Content-Type | header | yes | string | application/json; charset=utf-8 |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
**Request body**
Schema: `tracker-create-request`.
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackingNumber | string | yes | Tracking number of the shipment. |
| shipmentReference | string | no | Your reference for this shipment. Will be provided in our webhooks or API responses for this tracker. |
| clientTrackerId | string | no | Your unique identifier for this shipment. Will be provided in our webhooks or API responses for this tracker. |
| originCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Sender country code. |
| destinationCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Recipient country code - 📌 Recommended to improve tracking accuracy |
| destinationPostCode | string | no | Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy |
| shippingDate | string (date-time) | no | 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) |
| courierCode | string[] \| string | no | Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section) - 📌 Recommended to improve tracking accuracy |
| courierName | string | no | Courier name and/or service. |
| trackingUrl | string | no | Tracking URL of the courier. |
| orderNumber | string | no | Order number in case of an eCommerce order. |
| title | string | no | Title for this shipment, visible on the Tracking Dashboard. |
| recipient | object | no | |
| settings | object | no | |
```json
{
"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
}
}
```
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 201 | Created | — |
| 400 | Bad Request | `error-response-format` |
### GET /trackers
**List existing Trackers** (`list-trackers`)
This endpoint return a list of all existing `Trackers`, using page-based pagination.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| page | query | no | integer | The page index. |
| limit | query | no | integer | The maximum number of trackers returned per page. |
| sort | query | no | `1` \| `-1` | Defines the sorting order of trackers. Use `1` for ascending (oldest tracker first) and `-1` for descending (newest tracker first). The default is ascending (`1`) to ensure stable pagination. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | | — |
### POST /trackers/bulk
**Bulk create trackers** (`bulk-create-trackers`)
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.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Content-Type | header | yes | string | application/json; charset=utf-8 |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
**Request body**
Schema: `bulk-create-trackers-request`.
_`bulk-create-trackers-request` has no top-level object fields; see the schema reference._
```json
[
{
"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
}
}
]
```
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 201 | Created | `bulk-create-trackers-response` |
| 207 | Partially Created | `bulk-create-trackers-response` |
| 400 | Bad Request | `bulk-create-trackers-response` |
| 403 | Forbidden | `bulk-create-trackers-response` |
### POST /trackers/track
**Create a tracker and get tracking results** (`create-tracker-and-get-tracking-results`)
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.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Content-Type | header | yes | string | application/json; charset=utf-8 |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
**Request body**
Schema: `tracker-create-request`.
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackingNumber | string | yes | Tracking number of the shipment. |
| shipmentReference | string | no | Your reference for this shipment. Will be provided in our webhooks or API responses for this tracker. |
| clientTrackerId | string | no | Your unique identifier for this shipment. Will be provided in our webhooks or API responses for this tracker. |
| originCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Sender country code. |
| destinationCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Recipient country code - 📌 Recommended to improve tracking accuracy |
| destinationPostCode | string | no | Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy |
| shippingDate | string (date-time) | no | 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) |
| courierCode | string[] \| string | no | Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section) - 📌 Recommended to improve tracking accuracy |
| courierName | string | no | Courier name and/or service. |
| trackingUrl | string | no | Tracking URL of the courier. |
| orderNumber | string | no | Order number in case of an eCommerce order. |
| title | string | no | Title for this shipment, visible on the Tracking Dashboard. |
| recipient | object | no | |
| settings | object | no | |
```json
{
"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
}
}
```
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | OK | — |
### GET /trackers/{trackerId}
**Get an existing tracker** (`get-tracker-by-trackerId`)
This endpoint return an existing `Tracker` for a given `trackerId`.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackerId | path | yes | string | **Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter. |
| searchBy | query | no | `trackerId` \| `clientTrackerId` | Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | OK | `tracker` |
| 404 | Not Found | `error-response-format` |
### PATCH /trackers/{trackerId}
**Update an existing tracker** (`update-tracker-by-trackerId`)
This endpoint allows to modify an existing `Tracker` matching with the given `trackerId`.
> Once the Tracker has gathered shipment tracking information, certain fields related to the shipment data cannot be modified. These include:
> - `courierCode`
> - `originCountryCode`
> - `destinationCountryCode`
> - `shippingDate`
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Content-Type | header | no | string | application/json; charset=utf-8 |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackerId | path | yes | string | **Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter. |
| searchBy | query | no | `trackerId` \| `clientTrackerId` | Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`. |
**Request body**
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| isSubscribed | boolean | no | 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 | string[] \| string | no | Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section) - 📌 Recommended to improve tracking accuracy |
| originCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Sender country code. |
| destinationCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Recipient country code - 📌 Recommended to improve tracking accuracy |
| destinationPostCode | string | no | Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy |
| shippingDate | string (date-time) | no | 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) |
| courierName | string | no | Courier name and/or service. |
| trackingUrl | string | no | Tracking URL of the courier. |
| recipient | object | no | Information on the recipient. Only the `name` property can be updated, `email` is not patchable. |
```json
{
"isSubscribed": false,
"originCountryCode": "CN",
"destinationCountryCode": "US",
"destinationPostCode": "94901",
"shippingDate": "2021-03-01T11:09:00.000Z",
"courierCode": [
"us-post"
],
"recipient": {
"name": "Marc"
}
}
```
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | | `tracker` |
| 400 | Bad Request | `error-response-format` |
### GET /trackers/search/{trackingNumber}/results
**Get tracking results for existing trackers by tracking number** (`get-tracking-results-of-trackers-by-tracking-number`)
This endpoint will return the `tracking` result corresponding to the tracking number provided as a parameter.
The `tracking` object is detailed in the [SCHEMAS](https://docs.ship24.com/tracking-api-reference/#/schemas/tracking) section.
Unlike 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 | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackingNumber | path | yes | string | **Required** Tracking number of the parcel. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | OK | — |
### GET /trackers/{trackerId}/results
**Get tracking results for an existing tracker** (`get-tracking-results-of-tracker-by-trackerId`)
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.
The `tracking` object is detailed in the [SCHEMAS](https://docs.ship24.com/tracking-api-reference/#/schemas/tracking) section.
Unlike 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 | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackerId | path | yes | string | **Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter. |
| searchBy | query | no | `trackerId` \| `clientTrackerId` | Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | OK | — |
| 404 | Not Found | `error-response-format` |
### GET /couriers
**Get all couriers** (`get-couriers`)
This endpoint will return the list of all couriers supported by Ship24, identified by their `courierCode`.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | OK | — |
### POST /tracking/search
**Get tracking results by tracking number** (`get-tracking`)
This endpoint will return the `tracking` corresponding to the tracking number provided as a parameter.
The `tracking` object is detailed in the [SCHEMAS](https://docs.ship24.com/tracking-api-reference/#/schemas/tracking) section.
For better accuracy, we strongly advise to provide extra information such as the origin country, destination postcode & country, and the shipping date.
> 🛑 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.
> 🛑 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.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Content-Type | header | no | string | |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
**Request body**
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackingNumber | string | yes | Tracking number of the shipment. |
| originCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Sender country code - 📌 Recommended to improve tracking accuracy |
| destinationCountryCode | string (ISO 3166-1 alpha-2/alpha-3) | no | Recipient country code - 📌 Recommended to improve tracking accuracy |
| destinationPostCode | string | no | Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy |
| shippingDate | string (date-time) | no | 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) |
| courierCode | string[] \| string | no | Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section) - 📌 Recommended to improve tracking accuracy |
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 201 | Created | — |
| 400 | Bad Request | `error-response-format` |
### POST /trackers/{trackerId}/webhook-events/resend
**Resend webhooks of an existing tracker** (`resend-webhooks`)
This endpoint allows to resend all webhook messages of an existing tracker.
This can be useful in case you missed some webhook messages or if you need to reprocess them for any reason.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackerId | path | yes | string | **Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter. |
| searchBy | query | no | `trackerId` \| `clientTrackerId` | Parameter allowing to search either by `trackerId`or `clientTrackerId`. Default behavior is by `trackerId`. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 201 | Created | — |
### GET /trackers/{trackerId}/webhook-history/download
**Download webhook history of an existing tracker** (`download-webhook-history`)
This endpoint allows you to download the full webhook history of an existing tracker as a JSON file attachment.
The response is a JSON file download containing metadata about the tracker and a list of all sent or failed webhook pushes, including the request body, response body, response headers, and HTTP status code for each.
Pending webhooks (not yet sent or failed) are excluded from the result. The list is sorted from most recent to oldest based on the last update timestamp.
**Parameters**
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| Authorization | header | yes | string | Your `api_key` prefixed with `Bearer`. |
| trackerId | path | yes | string | **Required** Id of the tracker, provided by Ship24 at creation. `clientTrackerId` can also be used in this field by employing the `searchBy` parameter. |
| searchBy | query | no | `trackerId` \| `clientTrackerId` | Parameter allowing to search either by `trackerId` or `clientTrackerId`. Default behavior is by `trackerId`. |
**Request body**
No request body.
**Responses**
| Status | Description | Schema |
| --- | --- | --- |
| 200 | A JSON file download containing the webhook history for the tracker. The `Content-Disposition` header will contain the filename in the format `webhook-history-{trackingNumber}-{YYYYMMDD}.json`. | — |
SHA-256: 4732344bf7c56f69010a938f29095c861689ab195024166c0d3e999f7a4e1086