One API for every carrier of New Caledonia: quote them all at once, book the offer you choose, print its label,
find a pickup point, follow the parcel and cancel it before pickup. Authenticate with a merchant key
(Authorization: Bearer mk_...).
Test and live. A mk_test_ key never reaches a real carrier: the sandbox carrier answers it, with the same
offers, tracking numbers (ZZ...) and labels on every run. A mk_live_ key books the real carriers. Test and live
shipments never see each other.
Retry safely. POST /v1/aggregator/shipments requires an Idempotency-Key header: a retry with the same key
and body returns the shipment created first.
Webhooks. Register an endpoint under /v1/aggregator/webhook-endpoints to receive the events of your shipments,
signed and retried as the Webhooks tag explains (the merchant.* entries of the webhooks section show the body). A
key manages the endpoints of its own mode. A test key also emits events: on booking, on cancellation, and when
POST /v1/aggregator/shipments/{id}/simulate moves a sandbox shipment, so you can test your integration end to end
without a carrier.
Limits. Each key may send about 600 requests a minute in production (300 on demo). Above that, the answer is
429 with Retry-After: 60 and the error code too_many_requests: wait, then retry.
Quote every carrier
The offers of every active carrier that sells the delivery and serves the destination at that weight, each priced from the carrier own rate card, cheapest first. Nothing is booked. With delivery pickup_point and a relay_point_id, the offers are priced for the commune of the point.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Quote every carrier › Request Body
Where the carrier picks the parcels up.
Where the parcels go. With pickup_point, the commune of the point replaces it.
deliveryhome: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.
relay_point_id^([0-9a-fA-F]{8}-[0-…With delivery pickup_point: the point the recipient collects the parcels at, from GET /v1/aggregator/pickup-points. Without it, the offers are priced for the destination commune.
signatureAsk the recipient to sign at delivery.
Quote every carrier › Responses
The offers, cheapest first.
Cheapest first.
Book a shipment
Books the chosen offer. A live key creates the shipment at the carrier, which plans, delivers and tracks it; a test key creates a sandbox shipment that no carrier sees. The shipment is priced again from the carrier rate card in effect, so its price can differ from the quote when the carrier changed its rates in between. With a pickup point offer, relay_point_id is required and the parcels go to the address of the point.
Headers
Idempotency-KeyYour unique key for this booking, such as the order id. A retry with the same key and body returns the shipment booked first; the same key with another body answers 409 idempotency_key_reused.
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Book a shipment › Request Body
offer_idAn offer of POST /v1/aggregator/quotes.
merchant_referenceYour own reference, such as the order number.
declared_value_xpfDeclared value of the content, in whole XPF.
relay_point_id^([0-9a-fA-F]{8}-[0-…Required with a pickup point offer, refused otherwise: the point the recipient collects the parcels at. Its address replaces the recipient address.
signatureAsk the recipient to sign at delivery.
Book a shipment › Responses
The shipment booked.
idtracking_numberstatusservice_kinddeliveryhome: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.
delivery_confirmationmerchant_referenceexcluding_tax_xpftgc_xpftgc_rate_basis_pointstotal_xpfThe price at booking, TGC included.
commission_xpfThe commission of shipping.nc, not set yet.
sandboxTrue for a shipment of a test key, which no carrier sees.
label_urlThe API path that hands out the label.
created_at^(?:(?:\d\d[2468][04… · requiredCancel a shipment
Cancels a shipment the carrier has not picked up yet (status created); once picked up, the answer is 409 invalid_status_transition. The carrier sees the cancellation in its history, recorded by the merchant. Cancelling a cancelled shipment again returns it unchanged, so a retry is safe. Returns are not available yet.
path Parameters
idHeaders
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Cancel a shipment › Responses
The shipment, now cancelled.
idtracking_numberstatusservice_kinddeliveryhome: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.
delivery_confirmationmerchant_referenceexcluding_tax_xpftgc_xpftgc_rate_basis_pointstotal_xpfThe price at booking, TGC included.
commission_xpfThe commission of shipping.nc, not set yet.
sandboxTrue for a shipment of a test key, which no carrier sees.
label_urlThe API path that hands out the label.
created_at^(?:(?:\d\d[2468][04… · requiredMove a test shipment
Test keys only. Moves a sandbox shipment to the next status, as a carrier would: picked_up, then in_transit or out_for_delivery, then delivered or delivery_failed (with a failure_reason), and so on. The tracking shows the new status, and the test webhook endpoints receive its events. A status that cannot follow the current one answers 409 invalid_status_transition. A live key gets 404: only the carrier moves a live shipment.
path Parameters
idHeaders
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Move a test shipment › Request Body
statusThe next status. It must follow the current one, as a carrier would move the shipment.
failure_reasonRequired with delivery_failed, refused with any other status.
Move a test shipment › Responses
The shipment, in its new status.
idtracking_numberstatusservice_kinddeliveryhome: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.
delivery_confirmationmerchant_referenceexcluding_tax_xpftgc_xpftgc_rate_basis_pointstotal_xpfThe price at booking, TGC included.
commission_xpfThe commission of shipping.nc, not set yet.
sandboxTrue for a shipment of a test key, which no carrier sees.
label_urlThe API path that hands out the label.
created_at^(?:(?:\d\d[2468][04… · requiredGet the label of a shipment
Renders the label of the shipment as a PDF, one label per parcel, and hands back a short-lived download link. Print it and stick it on each parcel before the carrier picks them up.
path Parameters
idquery Parameters
formatA 10x15 sticker per parcel, or A4 sheets of four.
localeLanguage of the label captions.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get the label of a shipment › Responses
A download link of the label document.
urlA short-lived download link of the document.
expires_at^(?:(?:\d\d[2468][04… · requiredformatlabel_countOne label per parcel.
shipment_countSearch the pickup points
The shops of the shipping.nc network where a recipient can collect a parcel, for a checkout page: name, address, position, opening hours, shop phone, and whether the point takes a parcel now. Closed points are left out. Filter by commune, or by near_lat and near_lng for the nearest first within radius_km. Pass the id of the chosen point as relay_point_id to quote and book a pickup point delivery.
query Parameters
communeA commune of New Caledonia.
near_latnear_lngradius_kmWith near_lat and near_lng: only the points within this distance, nearest first.
limitHeaders
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Search the pickup points › Responses
The pickup points.
Get a pickup point
One shop of the network, with its address, opening hours and whether it takes a parcel now.
path Parameters
idHeaders
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get a pickup point › Responses
The pickup point.
idnameaddress_linespostal_codecommuneA commune of New Caledonia.
A GPS position in decimal degrees (WGS 84).
phoneThe shop phone number, in E.164 format.
statusactive: takes new parcels. paused: hands over the parcels it holds but takes no new one. closed: left the network.
accepts_parcelsWhether a new parcel can be addressed to the point now: active and not full.
distance_mThe straight-line distance from the near position, when one was given.
Track a shipment
The status and the history of a shipment the merchant booked, oldest event first, as the carrier records them: the time, a coarse place and the reason of a failed attempt. No recipient field, actor, note or position is returned. A test key tracks only its sandbox shipments, a live key only its live ones.
path Parameters
tracking_numberTwo-letter carrier prefix, 8 digits and a check digit. Spaces and case are ignored.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Track a shipment › Responses
The tracking of the shipment.
tracking_numberstatusservice_kinddelivery_confirmationWhat the recipient must do at the door.
destination_zoneparcel_countWhen the next delivery attempt is expected: the window of the current attempt while out for delivery, the next attempt after a failed one. null when unknown.
failure_reasonWhy the last attempt failed, while the status is delivery_failed.
iddeliveryhome: delivered to the recipient address. pickup_point: collected by the recipient at a pickup point.
merchant_referencesandboxTrue for a shipment of a test key, which no carrier sees.
List webhook endpoints
Newest first, cursor paginated. Never returns a secret. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
query Parameters
limitMaximum number of items in the page.
cursorThe next_cursor of the previous page, passed back as is. Omit it to get the first page.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List webhook endpoints › Responses
One page of endpoints.
next_cursorPass it as cursor to get the next page. null on the last page.
Create a webhook endpoint
The response carries the signing secret once. Each delivery is a POST of a JSON event about one of your shipments: data.shipment as the booking returns it, and data.tracking_event for a status change. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Create a webhook endpoint › Request Body
urlAn https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.
event_typesdescriptionCreate a webhook endpoint › Responses
The new endpoint, with its signing secret.
idurldescriptionstatusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredevent_typesmodetest: receives the sandbox shipments. live: receives the live shipments.
secretThe signing secret, shown once. Use it to check the Shipping-Nc-Signature header of each delivery.
Get a webhook endpoint
A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get a webhook endpoint › Responses
The endpoint.
idurldescriptionstatusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredevent_typesmodetest: receives the sandbox shipments. live: receives the live shipments.
Change a webhook endpoint
Changes only the fields sent. Disabling an endpoint gives up its pending deliveries; enabling it again clears its failure count. The secret never changes. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Change a webhook endpoint › Request Body
urlAn https URL on a public host name. Addresses that resolve to a private, loopback or link-local network are refused when the event is sent.
descriptionevent_typesstatusEnabling an endpoint again clears its failure count.
Change a webhook endpoint › Responses
The endpoint.
idurldescriptionstatusdisabled_reasonmanual: someone disabled it. failing: every attempt failed for a day, so it was disabled.
secret_prefixThe first characters of the signing secret, to recognise it.
failure_streakAttempts that failed in a row since the last success.
failing_since^(?:(?:\d\d[2468][04… · requiredcreated_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredevent_typesmodetest: receives the sandbox shipments. live: receives the live shipments.
Delete a webhook endpoint
Deletes the endpoint and its delivery log. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Delete a webhook endpoint › Responses
The endpoint is deleted.
List the deliveries of a webhook endpoint
Newest first, cursor paginated: what was sent, how many attempts, the last answer. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
query Parameters
limitMaximum number of items in the page.
cursorThe next_cursor of the previous page, passed back as is. Omit it to get the first page.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the deliveries of a webhook endpoint › Responses
One page of deliveries.
next_cursorPass it as cursor to get the next page. null on the last page.
Send a test event
Sends a signed webhook.test event now, tried once, and answers with the outcome. The endpoint must be enabled. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Send a test event › Responses
The delivery of the test event.
idendpoint_idevent_idThe id of the event sent. A replay sends the same event id again.
event_typestatuspending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.
attemptsnext_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_status_codeThe HTTP status of the last answer, if any.
last_errorWhy the last attempt failed.
replay_ofThe delivery this one replays, if any.
created_at^(?:(?:\d\d[2468][04… · requireddelivered_at^(?:(?:\d\d[2468][04… · requiredReplay a delivery
Sends the event of a delivery again now, under the same event id, as a new delivery with its own retries. The endpoint must be enabled. A key manages the endpoints of its own mode: a test key the endpoints that receive the sandbox shipments, a live key those that receive the live shipments. Each delivery is signed as the Webhooks tag explains.
path Parameters
idThe webhook endpoint id.
deliveryIdThe delivery id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Replay a delivery › Responses
The new delivery.
idendpoint_idevent_idThe id of the event sent. A replay sends the same event id again.
event_typestatuspending: an attempt is due. succeeded: the endpoint answered 2xx. failed: every attempt failed.
attemptsnext_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_attempt_at^(?:(?:\d\d[2468][04… · requiredlast_status_codeThe HTTP status of the last answer, if any.
last_errorWhy the last attempt failed.
replay_ofThe delivery this one replays, if any.
created_at^(?:(?:\d\d[2468][04… · requireddelivered_at^(?:(?:\d\d[2468][04… · required