Shipping Labels

The Shipping Labels endpoints allow you to generate carrier labels (Chronopost, Colissimo, …) for your orders and retrieve them later. Labels are returned as signed PDF URLs that are valid for 15 minutes — download the PDF immediately, or call the GET endpoint to obtain a fresh URL.

These endpoints use a different base URL from the Returns API: https://api.baback.co. The Bearer token is the same as the one used for the Returns API.

Authentication

Every request uses a Bearer token — the same token you use for the public Returns API.

Authorization: Bearer

The token automatically identifies your shop. You do not need to pass a shopId in the URL or the body. A missing or invalid token returns 401 Unauthorized.

Rate limiting

Limit	Window
100 requests	60 seconds

Going over the limit returns 429 Too Many Requests. Normal usage (1 label per second) stays well below this limit.

POST/public/v1/tracking/shipments

Create a shipping label

This endpoint generates a carrier shipping label for an order. The response contains a signed labelUrl valid for 15 minutes.

Required attributes

Name
orderId
Type
string
Description
Identifier of the order.
Name
carrierCode
Type
string
Description
Carrier code. Supported values: chronopost, colissimo.
Name
productCode
Type
string
Description
Baback product code (see the list of available product codes below).

Optional attributes

Name
reference
Type
string
Description
Free-form reference, printed on the carrier documents.
Name
pickupPointCode
Type
string
Description
Required when productCode is a pickup-point product (see the product code list below).

Notes

Accents in addresses are handled automatically (stripped for Chronopost).
Phone numbers are normalized to the international E.164 format.
You can only use products that are activated on your carrier contract and configured in your Baback workspace. A non-contractualized product returns 400.

Request

POST

/public/v1/tracking/shipments

curl -X POST https://api.baback.co/public/v1/tracking/shipments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_abc123",
    "carrierCode": "chronopost",
    "productCode": "chronopost-18",
    "originAddress": {
      "firstName": "Acme",
      "lastName": "Warehouse",
      "address1": "10 rue de la Paix",
      "city": "Paris",
      "zip": "75002",
      "countryCode": "FR",
      "phone": "+33100000000"
    },
    "destinationAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      "address1": "5 avenue des Champs-Élysées",
      "city": "Paris",
      "zip": "75008",
      "countryCode": "FR",
      "phone": "+33698765432",
      "email": "jane@example.com"
    },
    "parcels": [{ "weight": 500 }],
    "reference": "ORD-12345"
  }'

Response: 201 Created

{
  "id": "label_xyz789",
  "shopId": "shop_1",
  "orderId": "order_abc123",
  "carrierCode": "chronopost",
  "productCode": "chronopost-18",
  "trackingNumber": "XR087215020RR",
  "labelUrl": "https://s3.eu-west-3.amazonaws.com/.../label.pdf?X-Amz-Signature=...",
  "weight": 500,
  "status": "label_generated",
  "createdAt": "2026-04-09T16:00:00.000Z"
}

labelUrl is a signed URL valid for 15 minutes. Download the PDF immediately, or call the GET endpoint below to obtain a fresh URL.

GET/public/v1/tracking/shipments/:labelId

Retrieve a shipping label

Returns an existing label in the same format as the POST response, with a freshly signed labelUrl (valid 15 minutes). Use this endpoint when the previous URL has expired.

Required attributes

Name
labelId
Type
string
Description
Identifier of the label (returned as id by the POST endpoint).

If the label does not exist or does not belong to your shop, the endpoint returns 404 Not Found.

Request

GET

/public/v1/tracking/shipments/:labelId

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

Response: 200 OK

{
  "id": "label_xyz789",
  "shopId": "shop_1",
  "orderId": "order_abc123",
  "carrierCode": "chronopost",
  "productCode": "chronopost-18",
  "trackingNumber": "XR087215020RR",
  "labelUrl": "https://s3.eu-west-3.amazonaws.com/.../label.pdf?X-Amz-Signature=...",
  "weight": 500,
  "status": "label_generated",
  "createdAt": "2026-04-09T16:00:00.000Z"
}

Available product codes

You can only use products that are activated on your carrier contract. A non-contractualized product returns 400 Bad Request with code CHRONOPOST_PRODUCT_NOT_IN_CONTRACT (or the equivalent for the relevant carrier).

Chronopost

Baback code	Description
`chronopost-18`	Next day before 6 p.m.
`chronopost-13`	Next day before 1 p.m.
`chronopost_jour_j`	Same-day delivery
`chronopost_rapide_eco`	Fast & economic (Europe)
`chronopost_express_world`	Express Worldwide (international)
`relais`	Chrono Relais France (`pickupPointCode` required)
`chronopost_relais_europe_outre_mer`	Relais Europe / Overseas (`pickupPointCode` required)
`shop2shop`	Shop2Shop (`pickupPointCode` required)
`chronopost_2shopdirect`	2Shop Direct (`pickupPointCode` required)

Colissimo

Baback code	Description
`colissimo`	Generic Colissimo
`colissimo_domicile_signature_france`	Home, with signature (France)
`colissimo_domicile_sans_signature_france`	Home, without signature (France)
`colissimo_point_retrait_france`	Pickup point France (`pickupPointCode` required)
`colissimo_domicile_signature_europe`	Home, with signature (Europe)
`colissimo_domicile_sans_signature_europe`	Home, without signature (Europe)
`colissimo_point_retrait_europe`	Pickup point Europe (`pickupPointCode` required)
`colissimo_domicile_signature_outre_mer`	Home, with signature (Overseas)
`colissimo_domicile_sans_signature_outre_mer`	Home, without signature (Overseas)
`colissimo_domicile_signature_monde`	Home, with signature (Worldwide)

DHL, UPS, DPD France and Mondial Relay are planned but not yet available.

Error handling

HTTP code	Cause
`400 Bad Request`	Invalid body or product not activated on your carrier contract
`401 Unauthorized`	Missing or invalid token
`404 Not Found`	Label does not exist or belongs to another shop
`429 Too Many Requests`	Rate limit exceeded (100 req / min)
`502 Bad Gateway`	Unhandled carrier error
`500 Internal Server Error`	Baback-side error

Error payloads use the following shape:

{
  "message": "Le produit Chronopost 'chronopost-18' n'est pas activé sur votre contrat...",
  "code": "CHRONOPOST_PRODUCT_NOT_IN_CONTRACT",
  "statusCode": 400,
  "timestamp": "2026-04-09T16:00:00.000Z"
}