Merchants

Book your first shipment

This tutorial takes you through the aggregator API with a test key: you quote every carrier, book an offer, print its label, follow the parcel, and cancel it. A test key never reaches a real carrier, so you can run it as often as you like.

Before you start

  • Ask shipping.nc for a merchant account. The shipping.nc team creates it and hands you two API keys, shown once:
    • a test key, mk_test_..., answered by the sandbox carrier Transporteur test;
    • a live key, mk_live_..., which books the real carriers.
  • Keep both keys on your server. Never put them in a web page or a mobile app.

Every request authenticates with the key in the Authorization header:

Code
Authorization: Bearer mk_test_...

The examples below use curl and the demo host. Set your key once:

TerminalCode
export SHIPPING_NC_KEY=mk_test_... export SHIPPING_NC_API=https://api.demo.shipping.nc

A test key and a live key see different shipments: a shipment booked with one is not found with the other.

Quote every carrier

Send the route and the parcels to POST /v1/aggregator/quotes. The destination is a commune of New Caledonia, written as in the API reference (Nouméa, Koné, Lifou).

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/quotes" \ -H "Authorization: Bearer $SHIPPING_NC_KEY" \ -H 'Content-Type: application/json' \ -d '{ "origin": { "commune": "Nouméa" }, "destination": { "commune": "Koné" }, "parcels": [{ "weight_grams": 2400, "length_mm": 400, "width_mm": 300, "height_mm": 200 }], "delivery": "home" }'

The answer lists the offers, cheapest first. With a test key, they are the offers of the sandbox carrier, at the same prices on every run:

JSONCode
{ "data": [ { "id": "ofr_c2FuZGJveDpob21lX2RlbGl2ZXJ5", "carrier": { "id": "sandbox", "name": "Transporteur test" }, "service_kind": "home_delivery", "delivery": "home", "delivery_confirmation": "none", "zone": "brousse_west", "weight_grams": 2400, "excluding_tax_xpf": 1000, "tgc_xpf": 0, "tgc_rate_basis_points": 0, "total_xpf": 1000, "commission_xpf": 0, "sandbox": true } ] }

Nothing is booked yet. An offer id names a carrier and a service, not a price: keep it to book.

To deliver to a pickup point, list the points with GET /v1/aggregator/pickup-points, then quote with "delivery": "pickup_point" and the relay_point_id of the point the recipient chose.

Book the offer

Send the offer, the sender, the recipient and the parcels to POST /v1/aggregator/shipments, with an Idempotency-Key header. Use a key that is unique for the order, such as its number.

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments" \ -H "Authorization: Bearer $SHIPPING_NC_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: CMD-20931' \ -d '{ "offer_id": "ofr_c2FuZGJveDpob21lX2RlbGl2ZXJ5", "merchant_reference": "CMD-20931", "sender": { "name": "Boutique du Caillou", "phone": "254321", "address_lines": ["12 rue Jules Garnier"], "commune": "Nouméa" }, "recipient": { "name": "Marie Martin", "phone": "781234", "address_lines": ["4 rue des Cocotiers"], "commune": "Koné", "landmark": "Blue gate after the bakery" }, "parcels": [{ "weight_grams": 2400, "description": "Clothes" }] }'

The API answers 201 with the shipment. A test shipment gets a tracking number that starts with ZZ:

JSONCode
{ "id": "0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10", "tracking_number": "ZZ000000014", "status": "created", "carrier": { "id": "sandbox", "name": "Transporteur test" }, "service_kind": "home_delivery", "delivery": "home", "delivery_confirmation": "none", "merchant_reference": "CMD-20931", "excluding_tax_xpf": 1000, "tgc_xpf": 0, "tgc_rate_basis_points": 0, "total_xpf": 1000, "commission_xpf": 0, "sandbox": true, "label_url": "/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label", "created_at": "2026-11-16T08:00:00.000Z" }

If the network fails, send the same request again with the same Idempotency-Key: you get the shipment booked first, never a second one. The same key with another body answers 409 idempotency_key_reused.

The shipment is priced again from the carrier rate card when you book it, so its total_xpf can differ from the quote when the carrier changed its rates in between.

Ask for the label document with GET on label_url. It answers with a short-lived download link of a PDF, one 10x15 label per parcel:

TerminalCode
curl "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/label?format=10x15&locale=fr" \ -H "Authorization: Bearer $SHIPPING_NC_KEY"
JSONCode
{ "url": "https://...", "expires_at": "2026-11-16T08:15:00.000Z", "format": "10x15", "label_count": 1, "shipment_count": 1 }

Download the PDF before expires_at, print it, and stick each label on its parcel. Use format=A4 for sheets of four labels.

Follow the parcel

Read the status and the history with the tracking number:

TerminalCode
curl "$SHIPPING_NC_API/v1/aggregator/tracking/ZZ000000014" \ -H "Authorization: Bearer $SHIPPING_NC_KEY"

The answer gives the status and the events, oldest first, as the public tracking page shows them: the time, a coarse place, and the reason of a failed delivery attempt. It never returns the recipient.

A sandbox shipment moves only when you move it. Ask for the next status with POST /v1/aggregator/shipments/{id}/simulate, as a carrier would record it:

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/simulate" \ -H "Authorization: Bearer $SHIPPING_NC_KEY" \ -H 'Content-Type: application/json' \ -d '{ "status": "picked_up" }'

Then out_for_delivery, and delivered, or delivery_failed with a failure_reason such as recipient_absent. A status that cannot follow the current one answers 409 invalid_status_transition. The route accepts test keys only: a live shipment moves when its carrier moves it.

Rather than polling the tracking route, receive the events: see Receive webhooks.

Cancel the shipment

Cancel a shipment the carrier has not picked up yet, while its status is created:

TerminalCode
curl -X POST "$SHIPPING_NC_API/v1/aggregator/shipments/0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10/cancel" \ -H "Authorization: Bearer $SHIPPING_NC_KEY"

The answer is the shipment, now cancelled. Cancelling it again returns it unchanged, so a retry is safe. Once the carrier has picked the parcels up, the answer is 409 invalid_status_transition.

Stay within the limits

Each key may send about 600 requests a minute in production, and 300 on the demo stage. Above that, the API answers 429 with a Retry-After: 60 header and the error code too_many_requests. Wait for the number of seconds in Retry-After, then retry. Quote once for a cart rather than on every page view.

Go live

When your integration works with the test key, swap it for the live key. Nothing else changes in your code:

  • the quotes list the offers of the real carriers that serve the destination, each priced from its own rate card;
  • a booking creates the shipment at the carrier, which picks it up, delivers it and tracks it;
  • the tracking numbers and labels are the carrier's own.

Register your live webhook endpoints with the live key: a key manages the endpoints of its own mode.

Next steps

Last modified on