← Files Ship24 Tracking APIARCHIVED FILE
skills/ship24-integration/references/schemas.md
12.3 KB · Oct 2, 2026 · 00:34 UTC
<!-- GENERATED by scripts/generate-references.mjs from spec/ship24-tracking-api.yaml. Do not edit; run pnpm generate. -->
# Ship24 Tracking API schemas
### `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 | |
### `tracker`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackerId | string | yes | The id of the tracker that is providing this tracking. |
| trackingNumber | string | yes | The tracking number which the tracker is following. |
| shipmentReference | string \| null | yes | The `shipmentReference` you provided at the tracker's creation. |
| courierCode | string[] \| string | no | Code of the courier(s) handling the shipment. |
| clientTrackerId | string \| null | yes | The `clientTrackerId` you provided at the tracker's creation. |
| isSubscribed | boolean | yes | Indicates whether the tracker is active. A value of `false` means the tracker is archived and will not be used for tracking. |
| isTracked | boolean | yes | Indicates whether we are actively tracking the parcel. A value of `true` means new data is being searched for, while `false` indicates tracking has stopped due to delivery, inactivity, or unsubscription. Existing tracking results will remain accessible; however, new data will not be fetched, and notifications will no longer be sent. |
| createdAt | string (date-time) | yes | The date and time at which the tracker was created. |
### `tracking`
A `Tracking` object is used in our API to provide tracking results on your `Trackers` . tracking results are basically updated information about a shipments, including shipment-level information, events and statistics. The `Tracking` object is used both in the response body of our endpoints, as well as in the request body of your webhooks.
A `tracking` object can be composed of the following parts:
| Field | Description |
| -- | -- |
`tracker` | In case the `tracking` is pushed by webhook and fetched from a _tracker_, the object `tracker` will be present and will refer to which _tracker_ this `tracking` results comes from. |
| `shipment` | The object `shipment` contains the general shipment information. |
| `events` | The object `events` contains the tracking event(s), order by date descending (the most recent one is the first one of the array). When getting `tracking` by fetching results from our API, `events` will contains all events of the shipments. When getting `tracking` by webhooks, `events` will contains only the events discovered since the last push. |
| `statistics` | The object `statistics` contains statistics about the shipment lifecycle, such as timestamps of the key milestones of the shipment. |
| `metadata` *(in webhooks only)* | The object `metadata` contains webhooks related metadata, such as the `generatedAt` date, allowing you to know when the data contained in the webhook has been generated. |
#### `tracking` object in webhooks
In the webhooks, `tracking` objects are used in a `trackings` array, directly at the root of the JSON document:
```json
{
"trackings": [
{
"metadata": {
"generatedAt": "2023-01-19T09:12:39.052Z"
"messageId": "356a7f93-3ce5-4b49-b560-156537283df9",
"topic": "tracking/events"
},
"tracker": {
"trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
"trackingNumber": "9400115901047177598206",
"shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
"clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
"isSubscribed": true,
"createdAt": "2023-01-10T05:13:00.000Z"
},
"shipment": {
...
```
#### `tracking` object in API response
In the API response, `tracking` objects are used in a `trackings` array inside the `data` object in the JSON document:
```json
{
"data": {
"trackings": [
{
"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": "2023-01-10T05:13:00.000Z"
},
"shipment": {
...
```
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| tracker | tracker | no | |
| shipment | shipment | no | |
| events | event[] | no | |
| statistics | statistics | no | |
| metadata | metadata | no | |
### `shipment`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| shipmentId | string \| null | no | Unique identifier of the parcel in Ship24 system. |
| statusCode | string \| null | no | [statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment. |
| statusCategory | string \| null | no | [statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment. |
| statusMilestone | string | no | [statusMilestone](https:docs.ship24.com/status/#statusmilestone) of the shipment. |
| originCountryCode | string \| null | no | Detected country code of origin. |
| destinationCountryCode | string \| null | no | Detected country code of destination. |
| delivery | object | no | |
| trackingNumbers | object[] | no | List of tracking numbers linked to the shipment. |
| recipient | object \| null | no | Information on the recipient. |
### `event`
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.
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| eventId | string | no | Unique identifier of the event in Ship24 system. |
| trackingNumber | string | no | The original tracking number used to create the Tracker. |
| eventTrackingNumber | string | no | The tracking number associated with the event, on which the event has been found. |
| status | string \| null | no | Event raw text. |
| occurrenceDatetime | string (logistic-date-time) | no | [Date and time](http://docs.ship24.com/data-format#logistics-date-and-time) at which the event occurred. |
| order | integer \| null | no | Indicate the order of the events in case the occurrenceDatetime is the same between multiple events (lower is older). |
| location | string \| null | no | Location raw text of the event. |
| sourceCode | string \| null | no | Internal code of the source used to get this event. Please note that those codes may evolve at any point in time. |
| courierCode | string \| null | no | 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. |
| statusCode | string \| null | no | [statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.<br> |
| statusCategory | string \| null | no | [statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.<br> |
| statusMilestone | string | no | [statusMilestone](https://docs.ship24.com/status/#statusmilestone) of the shipment at the time of the event. |
| datetime (deprecated) | string (date-time) | no | |
| utcOffset (deprecated) | string | no | |
| hasNoTime (deprecated) | boolean | no | |
### `statistics`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| timestamps | object | no | Date and time of the occurrence of each milestone of the shipment.<br><br>[Date and time Format](https://docs.ship24.com/data-format#logistics-date-and-time)<br><br>[List of Milestones](https://docs.ship24.com/status/#statusmilestone) |
### `metadata`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| generatedAt | string (date-time) | no | Date at which the webhook data was generated. |
| messageId | string | no | Unique identifier of the tracking object across webhooks. |
| topic | string | no | Topic of the webhook: `tracking/events` for tracking results, `tracking/pod` for proofs of delivery. |
### `webhook-tracker`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackerId | string | yes | The id of the tracker that is providing this tracking. |
| trackingNumber | string | yes | The tracking number which the tracker is following. |
| shipmentReference | string \| null | yes | The `shipmentReference` you provided at the tracker's creation. |
| clientTrackerId | string \| null | yes | The `clientTrackerId` you provided at the tracker's creation. |
| isSubscribed | boolean | yes | Indicates whether the tracker is active. A value of `false` means the tracker is archived and will not be used for tracking. |
| createdAt | string (date-time) | yes | The date and time at which the tracker was created. |
### `bulk-create-trackers-request`
Array of `tracker-create-request` (minItems 1, maxItems 100).
### `bulk-create-trackers-response`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| status | `success` \| `partial` \| `error` | yes | Status of the bulk creation.<br><br>`success`: All trackers were created successfully or already existed. (Status code 200)<br><br>`partial`: Operation contains both successes and errors. (Status code 207)<br><br>`error`: All creations failed or error on request level. (Status codes 400, 403) |
| summary | object \| null | no | Summary of the bulk creation. Null if status is `error`. |
| data | object[] \| null | no | Detailed information about each tracker creation. Null if status is `error`. |
| error | object \| null | no | [Error details](https://docs.ship24.com/errors#error-response-format) of the request. Null if `status` is not `error`. |
### `error-response-format`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| errors | object[] | no | |
| data | object \| null | no | |
### `courier`
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| courierCode | string | no | The codified code of this courier in Ship24 system. |
| courierName | string | no | The courier name. |
| website | string \| null | no | The courier public website. |
| isPost | boolean | no | `true` in case the courier is a postal operator. |
| countryCode | string \| null (ISO 3166-1 alpha-2) | no | The main country in which the courier is operating. |
| requiredFields | (`destinationPostCode` \| `destinationCountryCode` \| `courierAccount`)[] \| null | no | Indicate which additional information is required by the courier to get optimal tracking results. See [Additional information](https://docs.ship24.com/couriers#required-fields) |
| isDeprecated | boolean | no | `true` in case the courier is deprecated. See [Deprecated couriers](https://docs.ship24.com/couriers#deprecated-couriers) |
SHA-256: 582a8e3820f2af635e02be55a0434e6b937911194946edf69ef51c488e271924