Public tracking

Read-only tracking of one shipment by its signed token.

Where the token comes from. Nucleo builds the tracking link …/track/{token} for every shipped parcel; it is the tracking page link on the shipment in Orders in Nucleo. The token is the last path segment. It is signed by Nucleo, cannot be guessed or altered, and does not expire; it stops working only if the shipment is voided.

Base URL, authentication and conventions of this API are on the Shipment Tracking API page.

Endpoints

get/public/tracking/{token}Get a shipment's public tracking

get/public/tracking/{token}

Get a shipment's public tracking

Status, dates, carrier and up to 50 most recent tracking events (newest first) of one shipment, under the merchant's company name. Only what the shopper needs: no email, phone or full address.

status is the normalised status of the latest event; before any event it is picked_up (or delivered if the shipment is already marked delivered).

Language: lang if supported, otherwise the order's language, otherwise (when the order has no language) one derived from the shipping country, otherwise en. It is returned as locale; event descriptions are shown as the carrier sent them.

Browsers. CORS is open (Access-Control-Allow-Origin: *, no credentials), so a storefront can call it straight from the shopper's browser.

Rate limit. 60 requests per minute per IP, shared with the other public Commerce endpoints called from the same IP. X-RateLimit-* headers are on every response, but a browser on another origin cannot read them (they are not exposed through CORS). Read-only and idempotent.

GET https://api-commerce.nucleoplatform.com/api/oms/v1/public/tracking/{token}

Authentication: None — public endpoint

Rate limit: 60 requests per 1m, per IP

Path parameters

tokenstringrequired
Signed tracking token, the last segment of the tracking link.

min length 20max length 200pattern ^[A-Za-z0-9_.-]{20,200}$
Example: MTA0Mjo3ZjNjMmE5MS00YjZkLTRlMmEtOWMxZi0zZDhlNWEyYjZjNDA.Qm9Yc1Z3Tm1LcFJ0WmFHaEpk

Query parameters

langstring
Preferred language.

One ofitendefres
Example: it

Responses

200Tracking information.application/json
Headers
- X-RateLimit-Limit Requests allowed per minute.
- X-RateLimit-Remaining Requests left in the current minute.
- dataPublicTrackingrequired
  Child attributes
  brandobjectrequired
  How the page presents the merchant: the company name, its public logo and favicon when the company has set them in Nucleo, no support contacts, accent #111111.
  
  Child attributes
  namestringrequired
  The merchant's company name in Nucleo.
  
  Example: Acme Apparel
  slugstring | nullrequired
  The merchant company's slug in Nucleo. Kept for compatibility.
  
  Example: acme
  logo_urlstring (uri) | nullrequired
  The company's public logo (an https URL), or null if it has none or it cannot be read right now.
  
  favicon_urlstring (uri) | nullrequired
  The company's public favicon (an https URL), or null if it has none or it cannot be read right now.
  
  accent_colorstringrequired
  Hex colour, currently always #111111.
  
  Example: #111111
  support_emailstring (email) | nullrequired
  Currently always null.
  
  support_urlstring (uri) | nullrequired
  Currently always null.
  
  localestringrequired
  One ofitendefres
  order_namestringrequired
  Example: #1042
  customer_first_namestringrequired
  Shipping first name, or empty.
  
  Example: Giulia
  destinationstringrequired
  City, COUNTRY of the shipping address (either part may be missing).
  
  Example: Milano, IT
  carrierstring | nullrequired
  Example: Example Express
  tracking_numbersarray of stringrequired
  One per parcel.
  
  carrier_urlstring (uri) | nullrequired
  The carrier's own tracking page, if known.
  
  statusstringrequired
  Normalised parcel status, the same for every carrier: pending (label created, not yet collected), picked_up, in_transit, out_for_delivery, delivered, exception (delivery problem), held (at a depot or pickup point), returned_to_sender.
  
  One ofpendingpicked_upin_transitout_for_deliverydeliveredexceptionheldreturned_to_sender
  status_atstring (date-time) | nullrequired
  shipped_atstring (date-time) | nullrequired
  delivered_atstring (date-time) | nullrequired
  estimated_delivery_atstring (date-time) | nullrequired
  itemsarray of objectrequired
  Items in this shipment.
  
  Attributes of each item
  titlestringrequired
  quantityintegerrequired
  min 1
  eventsarray of objectrequired
  Most recent first.
  
  max items 50
  Attributes of each item
  occurred_atstring (date-time) | nullrequired
  statusstringrequired
  Normalised parcel status, the same for every carrier: pending (label created, not yet collected), picked_up, in_transit, out_for_delivery, delivered, exception (delivery problem), held (at a depot or pickup point), returned_to_sender.
  
  One ofpendingpicked_upin_transitout_for_deliverydeliveredexceptionheldreturned_to_sender
  descriptionstring | nullrequired
  locationstring | nullrequired
404not_found: invalid or tampered token, unknown store, unknown or voided shipment. A token that does not match the path pattern gets the generic route-not-found message instead. application/json
One of the following shapes:
TrackingError
error"not_found"required
Message
messagestringrequired
429Too many requests from this IP.application/json
Headers
- Retry-After Seconds to wait.
- X-RateLimit-Limit Requests allowed per minute.
- X-RateLimit-Remaining Requests left in the current minute.
- X-RateLimit-Reset Unix time when the limit resets.
- messagestringrequired

Request

curl -X GET 'https://api-commerce.nucleoplatform.com/api/oms/v1/public/tracking/MTA0Mjo3ZjNjMmE5MS00YjZkLTRlMmEtOWMxZi0zZDhlNWEyYjZjNDA.Qm9Yc1Z3Tm1LcFJ0WmFHaEpk?lang=it' \
  -H 'Accept: application/json'

const res = await fetch("https://api-commerce.nucleoplatform.com/api/oms/v1/public/tracking/MTA0Mjo3ZjNjMmE5MS00YjZkLTRlMmEtOWMxZi0zZDhlNWEyYjZjNDA.Qm9Yc1Z3Tm1LcFJ0WmFHaEpk?lang=it", {
  method: "GET",
  headers: {
    Accept: "application/json",
  },
});
const data = await res.json();
console.log(res.status, data);

<?php

require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://api-commerce.nucleoplatform.com/api/oms/v1/public/tracking/MTA0Mjo3ZjNjMmE5MS00YjZkLTRlMmEtOWMxZi0zZDhlNWEyYjZjNDA.Qm9Yc1Z3Tm1LcFJ0WmFHaEpk?lang=it', [
    'headers' => [
        'Accept' => 'application/json',
    ],
    'http_errors' => false,
]);

echo $response->getStatusCode(), PHP_EOL;
echo $response->getBody();

Response

{
  "data": {
    "brand": {
      "name": "Acme Apparel",
      "slug": "acme",
      "logo_url": "https://cdn.acme.example/brand/logo.svg",
      "favicon_url": "https://cdn.acme.example/brand/favicon.png",
      "accent_color": "#111111",
      "support_email": null,
      "support_url": null
    },
    "locale": "it",
    "order_name": "#1042",
    "customer_first_name": "Giulia",
    "destination": "Milano, IT",
    "carrier": "Example Express",
    "tracking_numbers": [
      "1234567890"
    ],
    "carrier_url": "https://tracking.example.com/1234567890",
    "status": "out_for_delivery",
    "status_at": "2026-10-06T07:42:00+00:00",
    "shipped_at": "2026-10-05T15:10:00+00:00",
    "delivered_at": null,
    "estimated_delivery_at": "2026-10-06T18:00:00+00:00",
    "items": [
      {
        "title": "Organic Cotton Tee · M",
        "quantity": 1
      },
      {
        "title": "Fleece Hoodie · L",
        "quantity": 2
      }
    ],
    "events": [
      {
        "occurred_at": "2026-10-06T07:42:00+00:00",
        "status": "out_for_delivery",
        "description": "Shipment is out with courier for delivery",
        "location": "Milano, IT"
      },
      {
        "occurred_at": "2026-10-05T21:03:00+00:00",
        "status": "in_transit",
        "description": "Processed at MILANO - ITALY",
        "location": "Milano, IT"
      },
      {
        "occurred_at": "2026-10-05T15:10:00+00:00",
        "status": "picked_up",
        "description": "Shipment picked up",
        "location": "Bologna, IT"
      }
    ]
  }
}

{
  "error": "not_found"
}

{
  "message": "Too Many Attempts."
}

Was this page helpful?