Ship24 Tracking API

https://docs.ship24.com/
Admin
Ship24 is a global package tracking API that enables integration with hundreds of couriers worldwide...
Tokens:17,646
Snippets:88
Trust Score:9.7
Update:8 months ago
Show doc for...
Tokens:
Raw
### Webhook Message Structure Example

Source: https://docs.ship24.com/webhooks/delivery

This example demonstrates the structure of a webhook message, which can contain tracking updates for multiple shipments. Each shipment update includes metadata, tracker information, shipment details, and a list of events.

```APIDOC
## POST /websites/ship24/webhooks

### Description
Receives webhook notifications for tracking updates.

### Method
POST

### Endpoint
/websites/ship24/webhooks

### Request Body
- **trackings** (array) - Required - An array of tracking update objects.
  - **metadata** (object) - Required - Contains information about the webhook message generation.
    - **generatedAt** (string) - Required - Timestamp when the message was generated.
    - **messageId** (string) - Required - Unique identifier for the message.
  - **tracker** (object) - Required - Information about the tracker.
    - **trackerId** (string) - Required - Unique identifier for the tracker.
    - **trackingNumber** (string) - Required - The tracking number for the shipment.
    - **shipmentReference** (string) - Optional - A reference ID for the shipment.
    - **clientTrackerId** (string) - Optional - A client-defined tracker ID.
    - **isSubscribed** (boolean) - Required - Indicates if the tracker is subscribed to updates.
    - **createdAt** (string) - Required - Timestamp when the tracker was created.
  - **shipment** (object) - Optional - Details about the shipment.
    - **shipmentId** (string) - Required - Unique identifier for the shipment.
  - **events** (array) - Required - A list of tracking events. Typically contains one event per message.
    - **eventId** (string) - Required - Unique identifier for the event.
    - **status** (string) - Required - The status of the tracking event.
    - **occurrenceDatetime** (string) - Required - Timestamp when the event occurred.

### Request Example
```json
{
  "trackings": [
    {
      "metadata": {
        "generatedAt": "2025-03-04T17:13:35.000Z",
        "messageId": "356a7f93-3ce5-4b49-b560-156537283df9"
      },
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "9400115901047177598206",
        "shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
        "clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
        "isSubscribed": true,
        "createdAt": "2025-03-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098"
      },
      "events": [
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
          "status": "Delivered to the addressee",
          "occurrenceDatetime": "2025-03-04T17:12:57"
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the webhook reception.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get Trackers

Source: https://docs.ship24.com/trackers

Retrieve a list of all existing trackers. This endpoint supports pagination to manage large numbers of trackers.

```APIDOC
## GET /trackers

### Description
Get the list of existing trackers, using page-based pagination.

### Method
GET

### Endpoint
/trackers

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve (default is 1).
- **limit** (integer) - Optional - The number of trackers per page (default is 20).

### Response
#### Success Response (200 OK)
- **trackers** (array) - An array of tracker objects.
  - **trackerId** (string) - The unique identifier of the tracker.
  - **trackingNumber** (string) - The tracking number associated with the tracker.
  - **destinationCountry** (string) - The destination country of the shipment.
  - **courierCode** (string) - The courier code used for tracking.
- **pagination** (object) - Pagination details.
  - **currentPage** (integer) - The current page number.
  - **totalPages** (integer) - The total number of pages available.
  - **totalTrackers** (integer) - The total number of trackers.

#### Response Example
```json
{
  "trackers": [
    {
      "trackerId": "a1b2c3d4e5f6",
      "trackingNumber": "1Z999AA10123456784",
      "destinationCountry": "US",
      "courierCode": "ups"
    },
    {
      "trackerId": "f6e5d4c3b2a1",
      "trackingNumber": "JD0148000000000000",
      "destinationCountry": "DE",
      "courierCode": "dpd"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalTrackers": 200
  }
}
```
```

--------------------------------

### Create Tracker

Source: https://docs.ship24.com/trackers

Create a new tracker to start monitoring a shipment. This involves providing the tracking number and optionally other shipment details.

```APIDOC
## POST /trackers

### Description
Create a new tracker, which means you are asking Ship24 to start tracking this shipment based on its tracking number and other information if provided.

### Method
POST

### Endpoint
/trackers

### Parameters
#### Request Body
- **trackingNumber** (string) - Required - The tracking number of the shipment.
- **destinationCountry** (string) - Optional - The destination country code.
- **courierCode** (string) - Optional - The courier code for the shipment.

### Request Example
```json
{
  "trackingNumber": "1Z999AA10123456784",
  "destinationCountry": "US",
  "courierCode": "ups"
}
```

### Response
#### Success Response (201 Created)
- **trackerId** (string) - The unique identifier for the created tracker.
- **status** (string) - The status of the tracker creation.

#### Response Example
```json
{
  "trackerId": "a1b2c3d4e5f6",
  "status": "created"
}
```
```

--------------------------------

### Create Tracker and Get Tracking Results

Source: https://docs.ship24.com/trackers

Create a new tracker and retrieve its initial tracking results in a single synchronous call. Note that the initial response time can be up to one minute.

```APIDOC
## POST /trackers/track

### Description
Create a new tracker and get tracking results synchronously. As tracking results are fetched synchronously from couriers, the initial response time of the API may be up to one minute. This endpoint is idempotent and can be used to get subsequent results by calling it again with the same payload.

### Method
POST

### Endpoint
/trackers/track

### Parameters
#### Request Body
- **trackingNumber** (string) - Required - The tracking number of the shipment.
- **destinationCountry** (string) - Optional - The destination country code.
- **courierCode** (string) - Optional - The courier code for the shipment.

### Request Example
```json
{
  "trackingNumber": "1Z999AA10123456784",
  "destinationCountry": "US"
}
```

### Response
#### Success Response (200 OK)
- **trackerId** (string) - The unique identifier for the tracker.
- **trackingResults** (array) - An array of tracking events.
  - **eventDate** (string) - The date and time of the tracking event.
  - **location** (string) - The location where the event occurred.
  - **description** (string) - A description of the tracking event.
  - **courier** (string) - The courier that provided the tracking information.

#### Response Example
```json
{
  "trackerId": "a1b2c3d4e5f6",
  "trackingResults": [
    {
      "eventDate": "2023-10-27T10:00:00Z",
      "location": "Origin Scan, New York, NY",
      "description": "Package has been picked up by the carrier.",
      "courier": "UPS"
    }
  ]
}
```
```

--------------------------------

### Webhook Example: Single Update per Message (Default)

Source: https://docs.ship24.com/webhooks/delivery

This JSON example demonstrates the structure of a Ship24 webhook message when configured to send updates one by one. The 'trackings' array will always contain exactly one tracking update, and the 'events' array within that tracking will also contain a single event. This format is typically easier and faster to process.

```json
{
  "trackings": [
    {
      "metadata": {
        "generatedAt": "2025-03-04T17:13:35.000Z",
        "messageId": "356a7f93-3ce5-4b49-b560-156537283df9"
      },
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "9400115901047177598206",
        "shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
        "clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
        "isSubscribed": true,
        "createdAt": "2025-03-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
        ...
      },
      "events": [
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
          "status": "Delivered to the addressee",
          "occurrenceDatetime": "2025-03-04T17:12:57",
          ...
        }
      ]
      ...
    }
  ]
}
```

--------------------------------

### GET /couriers

Source: https://docs.ship24.com/couriers

Retrieves a list of all available couriers that can be used with the Ship24 API. This helps in selecting the correct courier code to improve tracking accuracy.

```APIDOC
## GET /couriers

### Description
Retrieves a list of all available couriers supported by the Ship24 API. Providing a `courierCode` for a shipment can significantly improve tracking accuracy by explicitly indicating which courier is handling the shipment.

### Method
GET

### Endpoint
/couriers

### Parameters
#### Query Parameters
- **courierCode** (string) - Optional - A specific courier code to filter the results. If not provided, all couriers are returned.
- **is_deprecated** (boolean) - Optional - Filter to include or exclude deprecated couriers. Defaults to false (only active couriers).

### Request Example
```json
{
  "example": "GET /couriers?is_deprecated=false"
}
```

### Response
#### Success Response (200)
- **couriers** (array) - A list of courier objects.
  - **courierCode** (string) - The unique code for the courier.
  - **courierName** (string) - The name of the courier.
  - **is_destination_postcode_required** (boolean) - Indicates if the destination postcode is required for this courier.
  - **is_destination_country_code_required** (boolean) - Indicates if the destination country code is required for this courier.
  - **is_courier_account_required** (boolean) - Indicates if the courier account number is required for this courier.
  - **is_deprecated** (boolean) - Indicates if the courier is deprecated.

#### Response Example
```json
{
  "example": [
    {
      "courierCode": "ups",
      "courierName": "UPS",
      "is_destination_postcode_required": false,
      "is_destination_country_code_required": false,
      "is_courier_account_required": false,
      "is_deprecated": false
    },
    {
      "courierCode": "fedex",
      "courierName": "FedEx",
      "is_destination_postcode_required": true,
      "is_destination_country_code_required": true,
      "is_courier_account_required": false,
      "is_deprecated": false
    }
  ]
}
```
```

--------------------------------

### Get Results for an Existing Tracker

Source: https://docs.ship24.com/trackers

Fetch the latest tracking results for a specific tracker using its ID. This is the recommended method if you store Ship24's tracker IDs.

```APIDOC
## GET /trackers/:trackerId/results

### Description
If you store Ship24's `trackerId` in your system, this is the best way to fetch tracking results from an existing `Tracker`.

### Method
GET

### Endpoint
/trackers/:trackerId/results

### Parameters
#### Path Parameters
- **trackerId** (string) - Required - The unique identifier of the tracker whose results are to be fetched.

### Response
#### Success Response (200 OK)
- **trackerId** (string) - The unique identifier of the tracker.
- **trackingResults** (array) - An array of tracking events.
  - **eventDate** (string) - The date and time of the tracking event.
  - **location** (string) - The location where the event occurred.
  - **description** (string) - A description of the tracking event.
  - **courier** (string) - The courier that provided the tracking information.

#### Response Example
```json
{
  "trackerId": "a1b2c3d4e5f6",
  "trackingResults": [
    {
      "eventDate": "2023-10-27T10:00:00Z",
      "location": "In Transit, Chicago, IL",
      "description": "Package is on its way to the destination.",
      "courier": "UPS"
    },
    {
      "eventDate": "2023-10-26T20:00:00Z",
      "location": "Out for Delivery, New York, NY",
      "description": "Package is out for delivery today.",
      "courier": "UPS"
    }
  ]
}
```
```

--------------------------------

### Get immediate tracking on a shipment

Source: https://docs.ship24.com/common-scenarios

This method allows you to obtain tracking results for a shipment directly within the initial API call. Be aware that response times can vary, and some couriers may not support synchronous fetching for the first request.

```APIDOC
## Get immediate tracking on a shipment

### Description
This method applies if you wish to get tracking results on a shipment directly during the very first API call to Ship24. However, as Ship24 has to search and fetch tracking results from couriers synchronously during the first call, response time will range from a few seconds to one minute. For some couriers, this synchronous fetching may not be supported, but tracking results will be available in subsequent calls.

### Steps
1. Start tracking a shipment and get synchronous tracking results using `POST /trackers/track`. This endpoint will directly return tracking results.
2. Get subsequent tracking results by calling again the same endpoint with the same parameters as point 1.
```

--------------------------------

### Get Tracker

Source: https://docs.ship24.com/trackers

Retrieve information about a specific tracker using its unique ID. This endpoint returns tracker details, not the tracking results.

```APIDOC
## GET /trackers/:trackerId

### Description
Get an existing tracker by id. Please note that this endpoint will only return the `Tracker` information and not the tracking result. See Get tracker results by id or Get tracker results by tracking number to get the tracking result.

### Method
GET

### Endpoint
/trackers/:trackerId

### Parameters
#### Path Parameters
- **trackerId** (string) - Required - The unique identifier of the tracker to retrieve.

### Response
#### Success Response (200 OK)
- **trackerId** (string) - The unique identifier of the tracker.
- **trackingNumber** (string) - The tracking number associated with the tracker.
- **destinationCountry** (string) - The destination country of the shipment.
- **courierCode** (string) - The courier code used for tracking.
- **createdAt** (string) - The timestamp when the tracker was created.
- **updatedAt** (string) - The timestamp when the tracker was last updated.

#### Response Example
```json
{
  "trackerId": "a1b2c3d4e5f6",
  "trackingNumber": "1Z999AA10123456784",
  "destinationCountry": "US",
  "courierCode": "ups",
  "createdAt": "2023-10-27T09:00:00Z",
  "updatedAt": "2023-10-27T09:00:00Z"
}
```
```

--------------------------------

### Shipment Event Status Example

Source: https://docs.ship24.com/status

This JSON object demonstrates the structure of a shipment event, highlighting the raw status provided by the courier and Ship24's normalized fields: statusCode, statusCategory, and statusMilestone.

```json
{
  "eventId": "67a64a66-c0cd-429c-a00b-4a30499fd997",
  "status": "ENTREGADO. Su envío está entregado.",
  "occurrenceDatetime": "2023-01-09T15:11:00",
  ...
  "statusCode": "delivery_delivered",
  "statusCategory": "delivery",
  "statusMilestone": "delivered"
}
```

--------------------------------

### Get Tracker Results by Tracking Number

Source: https://docs.ship24.com/trackers

Search for tracking results using only the tracking number. This is useful if you don't store Ship24's tracker IDs, but be aware that tracking numbers may not be unique.

```APIDOC
## GET /trackers/search/:trackingNumber/results

### Description
If you don't wish to store Ship24's `trackerId` in your system, you can use this endpoint to search a `Tracker` by tracking number. However, if you create two different `Tracker` for two different shipments going to two different destination countries with different couriers, that have the same tracking number, you will get an array of `Tracker` as a response. As tracking numbers are not unique, we always recommend using Get results for an existing tracker with Ship24's `trackerId` instead.

### Method
GET

### Endpoint
/trackers/search/:trackingNumber/results

### Parameters
#### Path Parameters
- **trackingNumber** (string) - Required - The tracking number to search for.

### Response
#### Success Response (200 OK)
- **trackers** (array) - An array of tracker objects matching the tracking number.
  - **trackerId** (string) - The unique identifier of the tracker.
  - **trackingNumber** (string) - The tracking number associated with the tracker.
  - **destinationCountry** (string) - The destination country of the shipment.
  - **courierCode** (string) - The courier code used for tracking.
  - **trackingResults** (array) - An array of tracking events for this tracker.
    - **eventDate** (string) - The date and time of the tracking event.
    - **location** (string) - The location where the event occurred.
    - **description** (string) - A description of the tracking event.
    - **courier** (string) - The courier that provided the tracking information.

#### Response Example
```json
{
  "trackers": [
    {
      "trackerId": "a1b2c3d4e5f6",
      "trackingNumber": "1Z999AA10123456784",
      "destinationCountry": "US",
      "courierCode": "ups",
      "trackingResults": [
        {
          "eventDate": "2023-10-27T10:00:00Z",
          "location": "In Transit, Chicago, IL",
          "description": "Package is on its way to the destination.",
          "courier": "UPS"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Example Webhook Message Structure with Multiple Trackings

Source: https://docs.ship24.com/webhooks/delivery

This JSON structure represents a webhook message from Ship24 containing tracking updates for multiple shipments. Each shipment can have multiple events, but the 'events' array within each tracking update typically contains a single event.

```json
{
  "trackings": [
    {
      "metadata": {
        "generatedAt": "2025-03-04T17:13:35.000Z",
        "messageId": "356a7f93-3ce5-4b49-b560-156537283df9"
      },
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "9400115901047177598206",
        "shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
        "clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
        "isSubscribed": true,
        "createdAt": "2025-03-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
        "..."
      },
      "events": [
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
          "status": "Delivered to the addressee",
          "occurrenceDatetime": "2025-03-04T17:12:57",
          "..."
        }
      ],
      "..."
    },
    {
      "metadata": {
        "generatedAt": "2025-02-03T13:12:25.010Z",
        "messageId": "36004adf-4d09-49af-83c7-caa1b4bb6840"
      },
      "tracker": {
        "trackerId": "cf9f566a-493b-d686-41f3-b085bb4e429f",
        "trackingNumber": "LD092249817CN",
        "shipmentReference": "c98a91fc-17f2-4b37-a494-6c540ef6f3e1",
        "clientTrackerId": "ca8db7d8-a39d-47bc-81b8-475a5e9168fb",
        "isSubscribed": true,
        "createdAt": "2025-02-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "9c2c13e9-dbc6-f79f-4199-693aadaa9ee0",
        "..."
      },
      "events": [
        {
          "eventId": "e726b49a-bea6-26a8-4610-553548ca765b",
          "status": "Arrived in destination country",
          "occurrenceDatetime": "2025-02-03T12:17:00",
          "..."
        }
      ],
      "..."
    },
    {
      "metadata": {
        "generatedAt": "2025-02-03T13:12:25.010Z",
        "messageId": "a10574fc-02ab-4a5a-aa9c-e3049c068bbc"
      },
      "tracker": {
        "trackerId": "cf9f566a-493b-d686-41f3-b085bb4e429f",
        "trackingNumber": "LD092249817CN",
        "shipmentReference": "c98a91fc-17f2-4b37-a494-6c540ef6f3e1",
        "clientTrackerId": "ca8db7d8-a39d-47bc-81b8-475a5e9168fb",
        "isSubscribed": true,
        "createdAt": "2025-02-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "9c2c13e9-dbc6-f79f-4199-693aadaa9ee0",
        "..."
      },
      "events": [
        {
          "eventId": "bbc4af45-9c99-749b-4945-e3211568ddb7",
          "status": "In transit",
          "occurrenceDatetime": "2025-02-02T20:10:00",
          "..."
        }
      ],
      "..."
    }
  ]
}
```

--------------------------------

### Bulk Create Trackers

Source: https://docs.ship24.com/trackers

Create multiple trackers simultaneously for several shipments. This is useful for efficiently adding many shipments to your tracking list.

```APIDOC
## POST /trackers/bulk

### Description
Create new trackers, which means you are asking Ship24 to start tracking those shipments based on their tracking numbers and other information if provided.

### Method
POST

### Endpoint
/trackers/bulk

### Parameters
#### Request Body
- **trackers** (array) - Required - An array of tracker objects to create.
  - **trackingNumber** (string) - Required - The tracking number of the shipment.
  - **destinationCountry** (string) - Optional - The destination country code.
  - **courierCode** (string) - Optional - The courier code for the shipment.

### Request Example
```json
{
  "trackers": [
    {
      "trackingNumber": "1Z999AA10123456784",
      "destinationCountry": "US"
    },
    {
      "trackingNumber": "JD0148000000000000",
      "courierCode": "dpd"
    }
  ]
}
```

### Response
#### Success Response (201 Created)
- **createdTrackers** (array) - An array of successfully created tracker objects.
  - **trackerId** (string) - The unique identifier for the created tracker.
  - **originalTrackingNumber** (string) - The tracking number provided for creation.
- **failedTrackers** (array) - An array of trackers that failed to be created.
  - **trackingNumber** (string) - The tracking number that failed.
  - **error** (string) - The reason for the failure.

#### Response Example
```json
{
  "createdTrackers": [
    {
      "trackerId": "a1b2c3d4e5f6",
      "originalTrackingNumber": "1Z999AA10123456784"
    }
  ],
  "failedTrackers": [
    {
      "trackingNumber": "JD0148000000000000",
      "error": "Invalid tracking number format"
    }
  ]
}
```
```

--------------------------------

### Receive tracking results on your shipments by webhook (recommended)

Source: https://docs.ship24.com/common-scenarios

This scenario details how to efficiently receive real-time tracking updates for your shipments using webhooks. It involves setting up an endpoint in your system to receive notifications and configuring the Ship24 Dashboard with your webhook URL.

```APIDOC
## Receive tracking results on your shipments by webhook (recommended)

### Description
Using webhooks is the most efficient way to get timely tracking results on your shipments. This method involves setting up an endpoint in your system to receive automatic updates from Ship24.

### Steps
1. In your system, create an endpoint to receive webhooks as described in the Webhooks section.
2. In your Ship24 Dashboard, set the webhook URL to point to your endpoint.
3. Start tracking your shipments using `POST /trackers` for individual shipments or `POST /trackers/bulk` for multiple shipments.

Tracking results will be pushed to your endpoint automatically.
```

--------------------------------

### Ship24 Tracking API Reference

Source: https://docs.ship24.com/tracking-api-reference

This section provides the specification for each endpoint available in the Ship24 Tracking API. You can import this OpenAPI 3.1 specification into your HTTP client.

```APIDOC
## Ship24 Tracking API Reference

### Description
This API Reference contains the specification of each of our endpoints. It is available in OpenAPI 3.1 format and can be imported into most HTTP clients like Postman and Insomnia.

### Endpoint Specification URL
`https://docs.ship24.com/assets/openapi/ship24-tracking-api.yaml`

### Importing into HTTP Clients

**Postman**
1. Click on "Import".
2. Go to the "Link" tab.
3. Paste the Endpoint Specification URL.

**Insomnia**
1. From Insomnia preferences, locate the "Import data" option.
2. Choose "From URL".
3. Paste the Endpoint Specification URL.
```

--------------------------------

### Rate Limit Headers

Source: https://docs.ship24.com/rate-limiter

Information about the rate limit headers provided in the API responses, including `RateLimit-*`, `X-RateLimit-*`, and `Retry-After`.

```APIDOC
## Rate Limit Headers

The response headers provide two different sets of rate limit information: `RateLimit-*` and `X-RateLimit-*`. You should choose one set that best suits your needs.

### `RateLimit-*` Headers
This set follows the IETF standardization draft.

| Header           | Example | Description                                     |
|------------------|---------|-------------------------------------------------|
| `RateLimit-Limit`  | 10      | The total requests allowed for a 1-second window. |
| `RateLimit-Remaining`| 9       | The number of requests left for a 1-second window.|
| `RateLimit-Reset`  | 1       | The delay in seconds before the rate limit resets.|

### `X-RateLimit-*` Headers

| Header                | Example        | Description                                     |
|-----------------------|----------------|-------------------------------------------------|
| `X-RateLimit-Limit`     | 10             | The total requests allowed for a 1-second window. |
| `X-RateLimit-Remaining` | 9              | The number of requests left for a 1-second window.|
| `X-RateLimit-Reset`     | 1645507056     | The Unix timestamp when the rate limit will reset.|

### `Retry-After` Header

The `Retry-After` header is also available and indicates the delay in seconds before the rate limit resets. It is equivalent to the `RateLimit-Reset` header.
```

--------------------------------

### Fetch tracking results on your shipments by regularly calling our API

Source: https://docs.ship24.com/common-scenarios

An alternative to webhooks, this method involves periodically polling the Ship24 API to fetch tracking results for your shipments. This is less efficient than webhooks but provides flexibility if real-time push notifications are not feasible.

```APIDOC
## Fetch tracking results on your shipments by regularly calling our API

### Description
An alternative to webhooks is to fetch tracking results regularly from our system. This method is less efficient compared to webhooks, as your system will have to call our system regularly for each shipment to get updates.

### Steps
1. Start tracking your shipments using `POST /trackers` for each of your shipments or `POST /trackers/bulk` with multiple shipments.
2. Save the `trackerId` Ship24 allocated to your `Tracker`.
3. Get tracking results using `GET /trackers/:trackerId/results` for each of your shipments.
```

--------------------------------

### Default Rate Limits Per Endpoint

Source: https://docs.ship24.com/rate-limiter

This section details the default rate limits (requests per second) for various endpoints within the Ship24 API.

```APIDOC
## Default Rate Limits Per Endpoint

This section details the default rate limits (requests per second) for various endpoints within the Ship24 API.

### POST /trackers
- **Method**: POST
- **Endpoint**: /trackers
- **Rate Limit**: 10 requests/second

### GET /trackers
- **Method**: GET
- **Endpoint**: /trackers
- **Rate Limit**: 10 requests/second

### POST /trackers/bulk
- **Method**: POST
- **Endpoint**: /trackers/bulk
- **Rate Limit**: 3 requests/second

### POST /trackers/track
- **Method**: POST
- **Endpoint**: /trackers/track
- **Rate Limit**: 10 requests/second

### GET /trackers/:trackerId
- **Method**: GET
- **Endpoint**: /trackers/:trackerId
- **Rate Limit**: 10 requests/second

### PATCH /trackers/:trackerId
- **Method**: PATCH
- **Endpoint**: /trackers/:trackerId
- **Rate Limit**: 10 requests/second

### GET /trackers/search/:trackingNumber/results
- **Method**: GET
- **Endpoint**: /trackers/search/:trackingNumber/results
- **Rate Limit**: 10 requests/second

### GET /trackers/:trackerId/results
- **Method**: GET
- **Endpoint**: /trackers/:trackerId/results
- **Rate Limit**: 10 requests/second

### POST /trackers/:trackerId/webhook-events/resend
- **Method**: POST
- **Endpoint**: /trackers/:trackerId/webhook-events/resend
- **Rate Limit**: 1 request/second

### POST /tracking/search
- **Method**: POST
- **Endpoint**: /tracking/search
- **Rate Limit**: 10 requests/second

### GET /couriers
- **Method**: GET
- **Endpoint**: /couriers
- **Rate Limit**: 1 request/second
```

--------------------------------

### Deprecated Fields

Source: https://docs.ship24.com/data-format

Information on fields that are deprecated but maintained for backward compatibility.

```APIDOC
## Deprecated Fields

The following fields are deprecated but remain in the API for backward compatibility purposes.

| Field        | Depreciation Date | Alternative      |
|--------------|-------------------|------------------|
| `datetime`   | 2022-12           | `occurrenceDatetime` |
| `utcOffset`  | 2022-12           | `occurrenceDatetime` |
| `hasNoTime`  | 2022-12           | `occurrenceDatetime` |
```

--------------------------------

### POST /your-endpoint

Source: https://docs.ship24.com/webhooks/specification

Ship24 will push tracking results to this endpoint using the POST method. The response should indicate success with a 2xx status code.

```APIDOC
## POST /your-endpoint

### Description
Ship24 will push tracking results to your specified webhook URL using the POST method. The format of the request is detailed in the API Reference.

### Method
POST

### Endpoint
`https://your-server.com/your-endpoint`

### Parameters
#### Query Parameters
None

#### Request Body
* **tracking_data** (object) - Required - Contains the tracking information pushed by Ship24.
  * **tracking_number** (string) - The tracking number for the shipment.
  * **status** (string) - The current status of the shipment.
  * **timestamp** (string) - The timestamp of the tracking update.
  * **location** (string) - The location associated with the tracking update.

### Request Example
```json
{
  "tracking_data": {
    "tracking_number": "1Z999AA10123456784",
    "status": "In Transit",
    "timestamp": "2023-10-27T10:00:00Z",
    "location": "Origin Facility"
  }
}
```

### Response
#### Success Response (200)
* **message** (string) - A confirmation message indicating the tracking data was received.

#### Response Example
```json
{
  "message": "Tracking data received successfully."
}
```
```

--------------------------------

### POST /tracking/search

Source: https://docs.ship24.com/per-call-api

Retrieves tracking results for a given tracking number. This endpoint is part of the 'Per-call Plans' and requires an active subscription. Each call is synchronous and dependent on courier system availability.

```APIDOC
## POST /tracking/search

### Description
Retrieves tracking results by providing a tracking number. This endpoint is designed for a 'Per-call' billing model, meaning each request consumes one unit of your plan. It performs a synchronous data fetch from courier systems, making it potentially slower and more susceptible to courier system downtime compared to the 'Per-shipment' plan.

### Method
POST

### Endpoint
/tracking/search

### Parameters
#### Query Parameters
- **tracking_number** (string) - Required - The tracking number for which to retrieve status updates.

### Request Body
This endpoint does not require a request body. All necessary information is passed via query parameters.

### Request Example
```json
{
  "tracking_number": "YOUR_TRACKING_NUMBER"
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the shipment (e.g., 'In Transit', 'Delivered').
- **history** (array) - An array of tracking events, each with a timestamp and location.
- **estimated_delivery** (string) - The estimated delivery date, if available.

#### Response Example
```json
{
  "status": "In Transit",
  "history": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "location": "Origin Facility"
    },
    {
      "timestamp": "2023-10-28T15:30:00Z",
      "location": "Transit Hub"
    }
  ],
  "estimated_delivery": "2023-10-30"
}
```
```

--------------------------------

### Standard Data Formats

Source: https://docs.ship24.com/data-format

Details on the standard data types and constraints used across the Ship24 API for requests and responses.

```APIDOC
## Standard Data Formats

This section describes the standard data types and constraints used by the Ship24 API. Adherence to these formats is required for successful requests and responses.

### Logistics Date and Time (`logistic-date-time`)

This format is used for tracking event timestamps, aiming for ISO-8601 compliance while accommodating variations in courier data precision.

**Format Examples:**
- `YYYY-MM-DDTHH:MM:SS` (Date and Time, local/courier time)
- `YYYY-MM-DDTHH:MM:SS+HH:MM` (Date and Time with offset)
- `YYYY-MM-DDTHH:MM:SSZ` (Date and Time in UTC)
- `YYYY-MM-DD` (Date only)

**Note:** When only the date is provided (`YYYY-MM-DD`), an `order` field may be present to help sort events chronologically.

### Other Date and Time (`date-time`)

All other dates and times in the API (e.g., `generatedAt`, `createdAt`) are represented in UTC using the ISO 8601 format.

**Format Example:** `YYYY-MM-DDTHH:MM:SSZ`

### Tracking Number

- **Length:** 5 to 50 characters.
- **Allowed Characters:** `A-Z`, `a-z`, `0-9`, `-`, `_`, `/`, `.`.
- **Rejection:** Dummy tracking numbers (e.g., `123456789`, `TEST123`, `00000`) are rejected.
- **Case Sensitivity:** Tracking numbers are converted to uppercase in API responses and webhooks. Comparisons should be case-insensitive.

### Country Code

- **API Response Format:** ISO 3166-1 alpha-2 (e.g., `FR`, `DE`, `CN`).
- **API Request Format:** Accepts ISO 3166-1 alpha-2 or alpha-3 (e.g., `FR`, `FRA`, `DE`, `DEU`).

### Postcode

- **Length:** 1 to 32 characters.
- **Allowed Characters:** `A-Z`, `a-z`, `0-9`, `-`, ` ` (Space), `.`, `_`, `/`.

## API Evolution

The Ship24 API maintains backward compatibility. Existing fields will not be removed or modified, though some may be deprecated and new fields may be added.
```

--------------------------------

### Webhooks Ordering and Retries

Source: https://docs.ship24.com/webhooks/delivery

Explains how to handle webhook messages that may not arrive in chronological order and describes the retry mechanism for failed webhook deliveries.

```APIDOC
## Webhooks Ordering

### Description
Webhook messages are not guaranteed to arrive or be processed in chronological order due to potential retries or asynchronous event reporting by couriers. Always compare the `occurrenceDatetime` of incoming events with the latest recorded `occurrenceDatetime` for a given shipment before updating status or triggering business rules.

## Webhooks Retries

### Description
If Ship24 does not receive an HTTP status code in the `2xx` range for a webhook request, the request will be retried up to 20 times. These retries employ an exponential backoff strategy, with intervals increasing from a few seconds to several hours between attempts.
```

--------------------------------

### List of HTTP Status Codes

Source: https://docs.ship24.com/errors

Provides a comprehensive list of HTTP status codes used by the Ship24 API and their corresponding descriptions.

```APIDOC
## List of HTTP Status Codes

Code| Description
---|---
200 - OK| Everything worked as expected.
201 - Created| Everything worked as expected.
207 - Multi-Status| Some sub-requests failed while others succeeded (used in bulk operations).
400 - Bad Request| The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized| No valid API key provided.
402 - Request Failed| The parameters were valid but, the request failed.
403 - Forbidden| The request is not allowed due to insufficient permissions or endpoints limitations.
404 - Not Found| The requested resource doesn't exist.
422 - Unprocessable Entity| The request was well-formed but was unable to be followed due to semantic errors.
409 - Conflict| The request conflicts with another request with the same payload or parameter made in parallel.
429 - Too Many Requests| Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
500, 502, 503, 504 - Server Errors| Something went wrong on Ship24's end.

More information can be found in the body of the response in cases of errors.
```

--------------------------------

### Shipment Tracking Dashboard

Source: https://docs.ship24.com/common-scenarios

The Shipment Tracking Dashboard provides a visual interface to monitor all your shipments tracked via the API. It allows for status checks, event viewing, manual shipment management, and easy reporting of issues.

```APIDOC
## View and manage your shipments on a visual dashboard

### Description
Our Shipment Tracking Dashboard allows you to monitor all your shipments tracked by our API, check their status and events, add and import shipments manually, and report any issues to our support team in just two clicks! This Shipment Tracking Dashboard is available as an option of your Tracking API plan, for which you can opt in when subscribing to a plan or anytime afterward.
```

--------------------------------

### List of Error Codes

Source: https://docs.ship24.com/errors

Details common error codes returned in the Ship24 API response body, along with general descriptions and resolution guidance.

```APIDOC
## List of Error Codes

Below is a list of possible error codes that can be returned in the body of the response, as well as further instructions on how to resolve them.

Code| General description
---|---
`validation_error`| One of the fields is not passing validation. Please refer to the details in `message`.
`no_active_subscription`| No active subscription (free or paid) allows you to access this resource. Please subscribe to a product allowing the use of this resource.
`quota_limit_reached`| Your shipments (trackers) or calls usage is above your quota for the billing period.
`tracker_not_found`| The requested Tracker can't be found. Please make sure it has been created beforehand.
`tracker_not_updatable`| The Tracker can't be updated. Usually, because the shipment corresponding to this Tracker has already been processed. (For example, if you create a Tracker on tracking `123456` on `dhl` to country `US` and, due to a data mistake, and you wish to change the courier to `fedex` to country `DE`, it is usually possible as long as Ship24 didn't find any trace of the shipment. However, it's not possible as soon as Ship24 detects the shipment.
`shipping_date_outdated`| Trackers with a shippingDate over 180 days old will be rejected, as Ship24 won't track shipments older than 6 months.
`parcel_not_found`| The shipment can't be found at the moment. It's usually because the shipment has been created recently and the first events are not yet available. Alternatively, you can try to provide more information about the shipment, such as `originCountryCode`, `destinationCountryCode`, `destinationPostCode`, and `shippingDate`.
`request_conflict`| The HTTP request conflicts with another request with the same payload or parameter made in parallel and processed concurrently. In such cases, only one request will succeed, and the rest will be in conflict. For idempotent endpoints, the request may be retried later on without impact.
`tracker_conflict`| A Tracker with similar conflicting parameters already exists. Please try to provide additional parameters, such as shippingDate and destinationCountryCode to differentiate your Tracker.
`bulk_create_limit_exceeded`| The number of Trackers in the bulk creation request exceeds the limit.
`processing_error`| An error occurred while processing the provided data.
`webhook_url_missing`| No webhook URL has been provided while it is required to process the request.
```
Tokens:
Raw