---
title: "Bulk create trackers"
method: POST
path: "/public/v1/trackers/bulk"
tags: ["📦 Trackers"]
---

# Bulk create trackers

`POST /public/v1/trackers/bulk`

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.

## Request body

- BulkCreateTrackersRequest
  - `trackers` TrackerCreateRequest[], required
    - `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

- BulkCreateTrackersResponse
  - `status` 'success' | 'partial' | 'error', required — Status of the bulk creation. `success`: All trackers were created successfully or already existed. (Status code 200) `partial`: Operation contains both successes and errors. (Status code 207) `error`: All creations failed or error on request level. (Status codes 400, 403)
  - `summary` object, nullable — Summary of the bulk creation. Null if status is `error`.
    - `totalInputs` integer — Total number of trackers to create.
    - `totalCreated` integer — Total number of trackers created.
    - `totalExisting` integer — Total number of already existing trackers.
    - `totalErrors` integer — Total number of errors (failed creations).
  - `data` object[], nullable — Detailed information about each tracker creation. Null if status is `error`.
    - `itemStatus` 'created' | 'existing' | 'error', required — Status of the tracker creation.
    - `inputData` TrackerCreateRequest, required
      - `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.
    - `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.
    - `errors` object[], nullable — [Error details](https://docs.ship24.com/errors#error-response-format) about a single tracker creation. Null if `itemStatus` is not `error`.
      - `code` string, required
      - `message` string, required
  - `error` object, nullable — [Error details](https://docs.ship24.com/errors#error-response-format) of the request. Null if `status` is not `error`.
    - `code` string, required
    - `message` string, required

## Other responses

- `207` — Partially Created
- `400` — Bad Request
- `401` — Unauthorized - No valid API key provided.
- `403` — Forbidden
- `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)