---
title: "Create a tracker"
method: POST
path: "/public/v1/trackers"
tags: ["📦 Trackers"]
---

# Create a tracker

`POST /public/v1/trackers`

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.

## 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 `201`

Created

- object
  - `data` 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.

## Other responses

- `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)