---
title: "Create a tracker and get tracking results"
method: POST
path: "/public/v1/trackers/track"
tags: ["📦 Trackers"]
---

# Create a tracker and get tracking results

`POST /public/v1/trackers/track`

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.

## Request body

- TrackerCreateRequest
  - `trackingNumber` string, required — Tracking number of the shipment.
  - `shipmentReference` string — Your reference for this shipment. Will be provided in our webhooks or API responses for this tracker.
  - `clientTrackerId` string — 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 — Sender country code.
  - `destinationCountryCode` string, ISO 3166-1 alpha-2/alpha-3 — Recipient country code - 📌 Recommended to improve tracking accuracy
  - `destinationPostCode` string — Recipient Post code (or ZIP code) - 📌 Recommended to improve tracking accuracy
  - `shippingDate` string, date-time — 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` union — Code of the courier(s) handling the shipment (Up to 3 max) (see Couriers list section) - 📌 Recommended to improve tracking accuracy
    - string[]
    - string
  - `courierName` string — Courier name and/or service.
  - `trackingUrl` string — Tracking URL of the courier.
  - `orderNumber` string — Order number in case of an eCommerce order.
  - `title` string — Title for this shipment, visible on the Tracking Dashboard.
  - `recipient` object
    - `email` string, email — Recipient email, used for optional email notifications.
    - `name` string — Recipient name, used for optional email notifications.
  - `settings` object
    - `restrictTrackingToCourierCode` boolean — If set to `true`, the tracker will only track the courier(s) specified in the `courierCode` field, if any. Otherwise, Ship24 may extend the tracking to other providers in case the shipment is handled by additional couriers.

## Response `200`

OK - Tracker already exists, returning tracking results

- CreateTrackerAndGetTrackingResultsResponse
  - `data` object, required
    - `trackings` object[]
      - `tracker` Tracker
        - `trackerId` string, required — The id of the tracker that is providing this tracking.
        - `trackingNumber` string, required — The tracking number which the tracker is following.
        - `shipmentReference` string, nullable, required — Your reference for this shipment, provided at the tracker's creation. Unlike clientTrackerId, this value is not validated for uniqueness.
        - `courierCode` union — Code of the courier(s) handling the shipment.
          - string[]
          - string
        - `clientTrackerId` string, nullable, required — Your unique identifier for this shipment, provided at the tracker's creation. Ship24 validates its uniqueness across all your active trackers.
        - `isSubscribed` boolean, required — Indicates whether the tracker is active. A value of `false` means the tracker is archived and will not be used for tracking.
        - `isTracked` boolean, required — 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, required — The date and time at which the tracker was created.
      - `shipment` Shipment
        - `shipmentId` string, nullable — Unique identifier of the parcel in Ship24 system.
        - `statusCode` string, nullable — [statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment.
        - `statusCategory` string, nullable — [statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the shipment.
        - `statusMilestone` string — [statusMilestone](https:docs.ship24.com/status/#statusmilestone) of the shipment.
        - `originCountryCode` string, nullable — Detected country code of origin.
        - `destinationCountryCode` string, nullable — Detected country code of destination.
        - `delivery` object
          - `estimatedDeliveryDate` string, date-time, nullable — Estimated delivery date of the shipment, if provided by the courier. Format: [Date and Time in UTC](http://docs.ship24.com/data-format#logistics-date-and-time)
          - `service` string, nullable — Name of logistics service or product for the shipment.
          - `signedBy` string, nullable — Name of the person who signed for the shipment.
        - `trackingNumbers` object[] — List of tracking numbers linked to the shipment.
          - `tn` string — Tracking number.
        - `recipient` object, nullable — Information on the recipient.
          - `name` string, nullable
          - `address` string, nullable
          - `postCode` string, nullable
          - `city` string, nullable
          - `subdivision` string, nullable
      - `events` Event[]
        - `eventId` string — Unique identifier of the event in Ship24 system.
        - `trackingNumber` string — The original tracking number used to create the Tracker.
        - `eventTrackingNumber` string — The tracking number associated with the event, on which the event has been found.
        - `status` string, nullable — Event raw text.
        - `occurrenceDatetime` string, logistic-date-time — [Date and time](http://docs.ship24.com/data-format#logistics-date-and-time) at which the event occurred.
        - `order` integer, nullable — Indicate the order of the events in case the occurrenceDatetime is the same between multiple events (lower is older).
        - `location` string, nullable — Location raw text of the event.
        - `sourceCode` string, nullable — Internal code of the source used to get this event. Please note that those codes may evolve at any point in time.
        - `courierCode` string, nullable — 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, nullable — [statusCode](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.
        - `statusCategory` string, nullable — [statusCategory](https://docs.ship24.com/status/#statuscode-and-statuscategory) of the event.
        - `statusMilestone` string — [statusMilestone](https://docs.ship24.com/status/#statusmilestone) of the shipment at the time of the event.
        - `datetime` string
        - `utcOffset` string
        - `hasNoTime` boolean
      - `statistics` Statistics
        - `timestamps` object — Date and time of the occurrence of each milestone of the shipment. [Date and time Format](https://docs.ship24.com/data-format#logistics-date-and-time) [List of Milestones](https://docs.ship24.com/status/#statusmilestone)
          - `infoReceivedDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `info_received` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `inTransitDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `in_transit` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `outForDeliveryDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `out_for_delivery` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `failedAttemptDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `failed_attempt` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `availableForPickupDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `available_for_pickup` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `exceptionDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `exception` [milestone](https://docs.ship24.com/status/#statusmilestone).
          - `deliveredDatetime` string, logistic-date-time, nullable — Occurrence [date and time](https://docs.ship24.com/data-format#logistics-date-and-time) of the first `delivered` [milestone](https://docs.ship24.com/status/#statusmilestone).

## Other responses

- `201` — Created - New tracker created and tracking results returned
- `400` — Bad Request
- `401` — Unauthorized - No valid API key provided.
- `403` — Forbidden - The API key provided does not have permissions to perform the request.
- `429` — Rate limit exceeded. The client has sent too many requests in a given amount of time.

---

[API](https://skmtc.net/botbrains-io/apis/ship24-tracking-api.md) · [All operations](https://skmtc.net/botbrains-io/apis/ship24-tracking-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/botbrains-io/ship24-tracking-api/revisions/9d68f8b1d086/schema)