Tracking — Parcels

The Tracking Parcels endpoint lets you fetch the current status, carrier events, and line items of any parcel owned by your shop, using the tracking number you already have (e.g. from the carrier label or the Baback dashboard).

This endpoint uses the same base URL and Bearer token as the Shipping Labels API: https://api.baback.co.

Authentication

Every request uses a Bearer token — the same token you use for the Returns and Shipping Labels APIs.

Authorization: Bearer

The token automatically identifies your shop. A missing or invalid token returns 403 Forbidden.

Rate limiting

Limit	Window
100 requests	60 seconds

Going over the limit returns 429 Too Many Requests.

GET/public/v1/tracking/parcels/:trackingNumber

Get a parcel by tracking number

Returns parcel info — carrier status, events, destination address, and line items — for a given tracking number, strictly scoped to the authenticated shop. A tracking number that belongs to another shop returns 404 (and does not reveal its existence).

The :trackingNumber parameter is matched against two fields:

trackingId — the primary tracking number of the parcel
trackingNumbers[] — the array of tracking numbers for multi-package shipments

If multiple parcels of the same shop match, the most recently created one is returned (orderBy: createdAt desc).

Path parameters

Name
trackingNumber
Type
string
Description
The tracking number to look up. Matched against trackingId and trackingNumbers[].

Response attributes

Name
id
Type
string
Description
Unique identifier of the parcel (primary key in database).
Name
shopId
Type
string
Description
Identifier of the shop that owns this parcel.
Name
orderId
Type
string
Description
Identifier of the order this parcel belongs to.
Name
orderNumber
Type
string
Description
Human-readable order number (e.g. 1042).
Name
trackingId
Type
string
Description
Primary tracking number of the parcel. Note: this is not the primary key — use id for unambiguous lookups.
Name
trackingNumbers
Type
string[]
Description
All tracking numbers associated with this parcel (multi-package shipments may have more than one).
Name
carrierCode
Type
string
Description
Carrier code (e.g. colissimo, chronopost).
Name
carrierProduct
Type
string | null
Description
Carrier product code, if available (e.g. DOM).
Name
carrierDisplayName
Type
string | null
Description
Human-readable carrier name (e.g. Colissimo Domicile).
Name
lastStatus
Type
TrackingStatus | null
Description
Current Baback tracking status. See the status list below.
Name
lastStatusUpdatedAt
Type
number | null
Description
Unix timestamp (ms) of the last status update.
Name
deliveryDate
Type
number | null
Description
Unix timestamp (ms) when the parcel was actually delivered. null until delivery is confirmed.
Name
endDepositDate
Type
number | null
Description
Unix timestamp (ms) after which the parcel is returned to sender if unclaimed.
Name
createdAt
Type
number
Description
Unix timestamp (ms) when the parcel was created in Baback.
Name
updatedAt
Type
number
Description
Unix timestamp (ms) of the last update.

Request

GET

/public/v1/tracking/parcels/:trackingNumber

curl https://api.baback.co/public/v1/tracking/parcels/8C12345678901 \
  -H "Authorization: Bearer {token}"

Response: 200 OK

{
  "id": "parcel_abc123",
  "shopId": "shop_1",
  "orderId": "shopify_4567890123",
  "orderNumber": "1042",
  "trackingId": "8C12345678901",
  "trackingNumbers": ["8C12345678901"],
  "carrierCode": "colissimo",
  "carrierProduct": "DOM",
  "carrierDisplayName": "Colissimo Domicile",
  "lastStatus": "IN_TRANSIT",
  "lastStatusUpdatedAt": 1714377600000,
  "carrierLastStatus": {
    "code": "PCH",
    "description": "Pris en charge par le transporteur",
    "date": 1714377600000
  },
  "estimatedDeliveryDateWindow": {
    "exactDeliveryDay": 1714723200000,
    "minimumDeliveryDate": 1714636800000,
    "maximumDeliveryDate": 1714809600000
  },
  "deliveryDate": null,
  "endDepositDate": 1715241600000,
  "destination": {
    "firstName": "Jane",
    "lastName": "Doe",
    "name": "Jane Doe",
    "company": "",
    "address1": "5 avenue des Champs-Élysées",
    "address2": null,
    "city": "Paris",
    "zip": "75008",
    "province": "Île-de-France",
    "provinceCode": "IDF",
    "country": "France",
    "countryCode": "FR",
    "phone": "+33698765432",
    "latitude": null,
    "longitude": null,
    "isPickupPoint": false
  },
  "lineItems": [
    {
      "lineItemId": "li_001",
      "name": "T-shirt Acme — taille M",
      "imageUrl": "https://cdn.shopify.com/.../tshirt.jpg",
      "sku": "TSHIRT-M-001",
      "quantity": 2,
      "price": 29.9,
      "productId": "prod_42",
      "metadata": null
    }
  ],
  "events": [
    {
      "status": "IN_TRANSIT",
      "createdAt": 1714377600000,
      "label": "Pris en charge par le transporteur",
      "carrierStatusCode": "PCH",
      "isNotificationSkipped": false,
      "notifications": []
    },
    {
      "status": "FULFILLED",
      "createdAt": 1714291200000,
      "label": "Commande expédiée",
      "carrierStatusCode": null,
      "isNotificationSkipped": false,
      "notifications": []
    }
  ],
  "createdAt": 1714291200000,
  "updatedAt": 1714377600000
}

GET/public/v1/tracking/search

Search parcels by order number and/or email

Search for parcels when you don't have a tracking number — by order number (orderName) and/or customer email (email), strictly scoped to the authenticated shop. This is the lookup counterpart to GET /public/v1/tracking/parcels/:trackingNumber.

At least one of orderName or email is required. When both are provided, the filters are combined (logical AND). Because a single order can span several parcels, the response is an array of parcels, ordered from most recently created to oldest and capped at 50 results.

Both filters are exact matches (not partial or fuzzy). orderName is matched against Parcel.orderNumber (the bare order number, e.g. 1042 — without any # prefix), and email against Parcel.customerEmail. The email match is case-sensitive, so pass it exactly as stored on the order.

Query parameters

Name
orderName
Type
string
Description
Order number to search for — exact match against orderNumber (e.g. 1042).
Name
email
Type
string
Description
Customer email to search for — exact match against customerEmail.

Response attributes

Returns an array of parcel objects, each with the exact same shape as GET /public/v1/tracking/parcels/:trackingNumber (see the response attributes above). The same PII fields are stripped. An empty array [] is returned when nothing matches.

Request

GET

/public/v1/tracking/search

# By order number
curl "https://api.baback.co/public/v1/tracking/search?orderName=1042" \
  -H "Authorization: Bearer {token}"

# By customer email
curl "https://api.baback.co/public/v1/tracking/search?email=jane@example.com" \
  -H "Authorization: Bearer {token}"

Response: 200 OK

[
  {
    "id": "parcel_abc123",
    "shopId": "shop_1",
    "orderId": "shopify_4567890123",
    "orderNumber": "1042",
    "trackingId": "8C12345678901",
    "trackingNumbers": ["8C12345678901"],
    "carrierCode": "colissimo",
    "carrierProduct": "DOM",
    "carrierDisplayName": "Colissimo Domicile",
    "lastStatus": "IN_TRANSIT",
    "lastStatusUpdatedAt": 1714377600000,
    "carrierLastStatus": {
      "code": "PCH",
      "description": "Pris en charge par le transporteur",
      "date": 1714377600000
    },
    "estimatedDeliveryDateWindow": null,
    "deliveryDate": null,
    "endDepositDate": null,
    "destination": {
      "firstName": "Jane",
      "lastName": "Doe",
      "name": "Jane Doe",
      "company": "",
      "address1": "5 avenue des Champs-Élysées",
      "address2": null,
      "city": "Paris",
      "zip": "75008",
      "province": "Île-de-France",
      "provinceCode": "IDF",
      "country": "France",
      "countryCode": "FR",
      "phone": "+33698765432",
      "latitude": null,
      "longitude": null,
      "isPickupPoint": false
    },
    "lineItems": [],
    "events": [
      {
        "status": "IN_TRANSIT",
        "createdAt": 1714377600000,
        "label": "Pris en charge par le transporteur",
        "carrierStatusCode": "PCH",
        "isNotificationSkipped": false,
        "notifications": []
      }
    ],
    "createdAt": 1714291200000,
    "updatedAt": 1714377600000
  }
]

Response: 400 Bad Request

{
  "message": "At least one of `orderName` or `email` must be provided",
  "statusCode": 400,
  "timestamp": "2026-04-29T12:00:00.000Z"
}

Tracking statuses

Status	Description
`FULFILLED`	Order shipped — parcel handed to the carrier
`IN_TRANSIT`	Parcel in transit
`OUT_FOR_DELIVERY`	Out for delivery
`DELIVERED`	Delivered
`DELIVERY_FAILURE`	Delivery attempt failed
`WAITING_FOR_PICKUP`	Awaiting pickup at a relay / pickup point
`RETURN_TO_SENDER`	Parcel being returned to sender
`RETURNED_TO_SENDER`	Parcel returned to sender
`EXCEPTION`	Carrier exception (lost, damaged, etc.)

Privacy

The following fields are present internally on a parcel but are never exposed through this endpoint:

customerEmail, customerLocale, previousEmails — customer PII
giftConfig, crossSellRecommendations, webTemplate — reserved for the customer-facing tracking page

Error handling

HTTP code	Cause
`400 Bad Request`	Search request with neither `orderName` nor `email`
`403 Forbidden`	Missing or invalid Bearer token
`404 Not Found`	No parcel found with this tracking number for your shop
`429 Too Many Requests`	Rate limit exceeded (100 req / 60 s)
`500 Internal Server Error`	Baback-side error

Error payloads use the following shape:

{
  "message": "Parcel not found with trackingId: 8C12345678901",
  "statusCode": 404,
  "timestamp": "2026-04-29T12:00:00.000Z"
}