shipping.nc API

Shipments

Server

Create, list and read the shipments of the authenticated carrier.


List shipments

GET
https://api.shipping.nc
/v1/shipments

Newest first, cursor paginated: pass next_cursor back as cursor to get the next page. Filters combine with AND; the values of one filter combine with OR. Allowed to carrier admins, dispatchers and shippers; a shipper user only sees the shipments of its own shipper account.

List shipments › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ
status
​string

Comma-separated statuses to keep.

Example: out_for_delivery,delivery_failed
zone
​string

Comma-separated destination zones to keep.

Example: grand_noumea
service
​string

Comma-separated services to keep.

Example: home_delivery,express_same_day
shipper_account
​string

Comma-separated shipper account ids to keep. A shipper always gets the shipments of its own account.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
created_from
​

Created at or after this instant, or from the start of this Noumea day.

created_to
​

Created before this instant, or up to the end of this Noumea day.

q
​string · minLength: 1 · maxLength: 100

Tracking number, recipient name or recipient phone.

Example: Martin

List shipments › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List shipments › Responses

One page of shipments.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Create a shipment

POST
https://api.shipping.nc
/v1/shipments

Allocates a tracking number, prices the shipment from the carrier rate card in whole XPF with the TGC, and records its first tracking event (created). Allowed to carrier admins, dispatchers and shippers.

Create a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Create a shipment › Request Body

service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
​object · required
​object · required
​object[] · minItems: 1 · maxItems: 50 · required
delivery_confirmation
​string · enum

What the driver must collect to complete the delivery.

Enum values:
none
signature
otp
Default: none
shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The shipper account billed for this shipment.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
shipper_reference
​string · minLength: 1 · maxLength: 60

The shipper's own reference, such as its order number.

Example: CMD-20931
declared_value_xpf
​integer · min: 0 · max: 9007199254740991

Declared value of the content, in whole XPF.

Example: 15000
relay_point_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Required with service_kind pickup_point, refused otherwise: the pickup point the parcel goes to, from GET /v1/relay/points. The shipment is delivered to the address and position of the point, and its zone is the zone of the point commune; recipient.address_lines, location and zone are replaced.

Create a shipment › Responses

The created shipment.

id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
shipper_account_id
​string | null · required
​object · required
​object · required
​object[] · required
declared_value_xpf
​integer | null · min: 0 · max: 9007199254740991 · required
​object · required

Whole XPF amounts from the carrier rate card. total_xpf includes the TGC.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_reference
​string | null

The shipper's own reference; null when it gave none.

Example: CMD-20931

Get the figures of a day

GET
https://api.shipping.nc
/v1/shipments/overview

Shipments created on a Noumea day, how many are delivered, out for delivery, failed or held by an open incident. Allowed to carrier admins, dispatchers and shippers; a shipper only counts the shipments of its own shipper account.

Get the figures of a day › query Parameters

day
​string · date · pattern: ^(?:(?:\d\d[2468][04…

The Noumea day to describe, today when omitted.

Example: 2026-11-11

Get the figures of a day › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get the figures of a day › Responses

The figures of the day.

Figures of a Noumea day for the carrier, or for the shipper account of a shipper.
day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required
​object · required

Shipments created on the day.

​object · required

Shipments of the day now delivered or collected.

​object · required

Shipments currently out for delivery, whatever their creation day.

​object · required

Failed delivery attempts.

​object · required

Incidents not resolved yet, whatever their day.


List the shipments to handle

GET
https://api.shipping.nc
/v1/shipments/attention

Live shipments a dispatcher should act on, most pressing first: an open incident, a failed attempt to reschedule, a recipient placed only roughly or not at all, a parcel on no tour, a label never printed. Each one carries every reason that holds; the counts cover every shipment, listed or not. Allowed to carrier admins, dispatchers and shippers; a shipper only sees its own shipments.

List the shipments to handle › query Parameters

limit
​integer · min: 1 · max: 50

How many shipments to list; the counts cover them all.

Example: 4
Default: 10

List the shipments to handle › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the shipments to handle › Responses

The shipments to handle and the counts per reason.

Live shipments that need a dispatcher, most pressing first.
​object[] · required
​object · required

Shipments per reason; a shipment with two reasons counts in both.

total
​integer · min: 0 · max: 9007199254740991 · required

Shipments with at least one reason.

Example: 4

List the locked pickup point handovers

GET
https://api.shipping.nc
/v1/shipments/locked-handovers

Parcels of the carrier waiting at a pickup point whose handover the counter locked after five wrong codes, longest locked first, with the recipient to call. Issuing a new code (issueNewPickupCode) unlocks one and takes it off the list. Allowed to carrier admins and dispatchers.

List the locked pickup point handovers › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the locked pickup point handovers › Responses

The locked handovers.

Parcels waiting at a pickup point whose handover is locked, longest locked first.
​object[] · required

Get the notifications of the signed-in user

GET
https://api.shipping.nc
/v1/shipments/notifications

New incidents and recipient requests of the last 7 days, newest first, with how many came after the user last opened them. Reading them also marks the user active now, which the team list shows as their last activity. Allowed to carrier admins, dispatchers and shippers; a shipper only hears of its own shipments.

Get the notifications of the signed-in user › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get the notifications of the signed-in user › Responses

The notifications and the unread count.

New incidents and recipient requests: what the bell of the back-office top bar counts.
unread_count
​integer · min: 0 · max: 9007199254740991 · required

Notifications since the user last opened the list.

Example: 3
seen_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the user last opened the list; null if never.

Example: 2026-11-11T08:42:10.000Z
​object[] · required

The latest notifications of the last 7 days, newest first.


Mark the notifications as read

POST
https://api.shipping.nc
/v1/shipments/notifications/seen

Marks every notification up to now as read for the signed-in user; sending it twice changes nothing more.

Mark the notifications as read › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Mark the notifications as read › Responses

The notifications are read.

No data returned

Quote a shipment

POST
https://api.shipping.nc
/v1/shipments/quote

Prices a shipment from the carrier rate card exactly as createShipment would, without storing anything. Allowed to carrier admins, dispatchers and shippers.

Quote a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Quote a shipment › Request Body

The fields of a new shipment that decide its price.
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
​object · required
​object[] · minItems: 1 · maxItems: 50 · required
delivery_confirmation
​string · enum

What the driver must collect to complete the delivery.

Enum values:
none
signature
otp
Default: none
shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The shipper account billed for this shipment.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67

Quote a shipment › Responses

The price and the bracket it comes from.

The price the shipment would get if created now. Nothing is stored.
zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
weight_grams
​integer · max: 9007199254740991 · required

Total weight of the parcels.

Example: 2400
​object · required

The rate card bracket the weight falls in.

​object · required
excluding_tax_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_xpf
​integer · min: 0 · max: 9007199254740991 · required
tgc_rate_basis_points
​integer · min: 0 · max: 10000 · required
total_xpf
​integer · min: 0 · max: 9007199254740991 · required

List the offered services

GET
https://api.shipping.nc
/v1/shipments/services

The services the carrier has turned on, with the proof each one asks of the recipient at the door. createShipment and quoteShipment refuse any other service with service_not_offered. Allowed to carrier admins, dispatchers and shippers.

List the offered services › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the offered services › Responses

The services a new shipment may use.

The services a new shipment may use now: the ones the carrier has turned on.
​object[] · required

In the order of the catalog.


Search shipments and shipper accounts

GET
https://api.shipping.nc
/v1/shipments/search

Matches shipments on their tracking number, the digits of the recipient phone (spaces ignored, without the +687 prefix) or the recipient name, and shipper accounts on their name, contact phone or contact email. Allowed to carrier admins, dispatchers and shippers; a shipper only finds the shipments of its own shipper account.

Search shipments and shipper accounts › query Parameters

q
​string · minLength: 2 · maxLength: 100 · required

Tracking number, phone digits, recipient name or shipper account name.

Example: 82 17
limit
​integer · min: 1 · max: 10

Maximum number of hits per group.

Example: 5
Default: 5

Search shipments and shipper accounts › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Search shipments and shipper accounts › Responses

The best hits per group.

The best hits per group, newest shipments first, capped by `limit`. The full, paginated list of matching shipments is `GET /v1/shipments?q=`.
​object[] · required
​object[] · required

Always empty for a shipper, who only sees their own account.


Suggest recipients already shipped to

GET
https://api.shipping.nc
/v1/shipments/recipients

The address book of the new-shipment form: the recipients of earlier shipments whose name or phone digits match, one per phone with the details of the last shipment to it. Allowed to carrier admins, dispatchers and shippers; a shipper only finds the recipients of its own shipper account.

Suggest recipients already shipped to › query Parameters

q
​string · minLength: 2 · maxLength: 100 · required

Part of the recipient name, or at least four digits of the recipient phone.

Example: roux
shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Only the recipients of this shipper account. Ignored for a shipper, who only sees their own.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
limit
​integer · min: 1 · max: 10

Maximum number of hits per group.

Example: 5
Default: 5

Suggest recipients already shipped to › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Suggest recipients already shipped to › Responses

The matching recipients, the most recent first.

One entry per recipient phone, as last shipped to, the most recent first, capped by `limit`.
​object[] · required

Read the recipient out of a pasted address

POST
https://api.shipping.nc
/v1/shipments/recipients/read

Reads the recipient name, phone, email, address, commune and landmark out of a pasted address or order, for the new-shipment form to fill. Nothing is stored. A field the text does not tell, or tells wrongly (an invalid phone, an unknown commune), comes back null. Allowed to carrier admins, dispatchers and shippers.

Read the recipient out of a pasted address › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Read the recipient out of a pasted address › Request Body

text
​string · minLength: 1 · maxLength: 2000 · required

The address or order the person pasted, as is.

Example: Rose Roux 78 12 34 22 rue des Flamboyants, Koutio Dumbéa

Read the recipient out of a pasted address › Responses

The recipient fields read from the text.

What the text says of the recipient; a field the text does not tell, or tells wrongly, is null.
name
​string | null · required
phone
​string | null · required

E.164 format, only when the text holds a valid phone.

Example: +687781234
email
​string | null · required
address_lines
​string[] · required

The street, the neighbourhood, then the commune.

Example: ["22 rue des Flamboyants","Koutio","Dumbéa"]
commune
​string | null · enum · required

Only a commune of New Caledonia.

Enum values:
Nouméa
Dumbéa
Mont-Dore
Païta
Boulouparis
La Foa
Farino
Sarraméa
landmark
​string | null · required
is_po_box
​boolean · required

Locate an address before creating its shipment

POST
https://api.shipping.nc
/v1/shipments/recipients/locate

Places an address with the geocoder the shipments use: its street within its commune, else the commune itself, so the new-shipment form can start its map pin there. Nothing is stored. The location is null when the geocoder cannot place the address now; send recipient.location on creation only for a point a person chose. Allowed to carrier admins, dispatchers and shippers.

Locate an address before creating its shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Locate an address before creating its shipment › Request Body

address_lines
​string[] · minItems: 1 · maxItems: 4 · required

The street, the neighbourhood, then the commune, as a shipment stores them.

Example: ["22 rue des Flamboyants","Koutio","Dumbéa"]

Locate an address before creating its shipment › Responses

Where the address lies.

Where an address lies, before any shipment is created.
​object | null · required

Where the geocoder places the address: the house, the street, or the commune as a last resort. Null when it cannot place it now.


List the proofs of a shipment

GET
https://api.shipping.nc
/v1/shipments/{id}/proofs

The signatures, photos and ID checks drivers recorded with its tracking events, oldest first. Each file is behind a private link valid 5 minutes. Allowed to carrier admins and dispatchers, never to shippers.

List the proofs of a shipment › path Parameters

id
​string · uuid · required

The shipment id.

List the proofs of a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List the proofs of a shipment › Responses

The proofs and when their links expire.

​object[] · required

Oldest first.

links_expire_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Ask again for new links after this time.


Get a shipment

GET
https://api.shipping.nc
/v1/shipments/{id}

The shipment with its full tracking history, oldest event first. Allowed to carrier admins, dispatchers and shippers.

Get a shipment › path Parameters

id
​string · uuid · required

The shipment id.

Get a shipment › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get a shipment › Responses

The shipment and its tracking events.

id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
shipper_account_id
​string | null · required
​object · required
​object · required
​object[] · required
declared_value_xpf
​integer | null · min: 0 · max: 9007199254740991 · required
​object · required

Whole XPF amounts from the carrier rate card. total_xpf includes the TGC.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
​object[] · required

Tracking history, oldest first.

​object[] · required

Every print of a label, newest first.

​object · required

Delivery attempts, as the tracking history tells them.

​object[] · required

The tours the shipment is or was on, newest first.

​object · required
​object[] · required

Who corrected the recipient and which fields, oldest first; never the old values.

recipient_editable
​boolean · required

Whether the recipient can still be corrected: not once out for delivery or done.

​object | null · required

The handover at the pickup point the parcel was sent to; null for a parcel sent to none.

shipper_reference
​string | null

The shipper's own reference; null when it gave none.

Example: CMD-20931

Correct the recipient

PATCH
https://api.shipping.nc
/v1/shipments/{id}/recipient

Changes the recipient name, phone, email, address, landmark or PO box flag; only the fields sent change. Refused with a 409 once the shipment is out for delivery, delivered, collected, returned or cancelled. Records who changed which fields, never the old values. A new address drops the position and is geocoded again. Allowed to carrier admins, dispatchers and shippers; a shipper only corrects its own shipments.

Correct the recipient › path Parameters

id
​string · uuid · required

The shipment id.

Correct the recipient › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Correct the recipient › Request Body

Only the fields sent change. The zone is left out because it sets the price.
name
​string · minLength: 1 · maxLength: 120
phone
​string

A phone number. Six digits without a prefix are read as a New Caledonia number (+687).

Example: +687 78 12 34
email
​string | null · email · pattern: ^(?:[A-Za-z0-9_'+\-]…

null removes the email.

Example: rose.roux@example.nc
address_lines
​string[] · minItems: 1 · maxItems: 4

A new address drops the position, and the address is geocoded again.

Example: ["22 rue des Flamboyants","Koutio"]
landmark
​string | null · minLength: 1 · maxLength: 500

null removes the directions.

Example: Blue house behind the pharmacy
is_po_box
​boolean

Correct the recipient › Responses

The shipment, with the corrected recipient.

id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
shipper_account_id
​string | null · required
​object · required
​object · required
​object[] · required
declared_value_xpf
​integer | null · min: 0 · max: 9007199254740991 · required
​object · required

Whole XPF amounts from the carrier rate card. total_xpf includes the TGC.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_reference
​string | null

The shipper's own reference; null when it gave none.

Example: CMD-20931

Place a pickup or delivery point

PUT
https://api.shipping.nc
/v1/shipments/{id}/{end}/location

Moves the position of the sender or the recipient to this point, as a dispatcher drops a pin on the map. The position becomes dispatcher and exact, and the geocoder never moves it again. Allowed to carrier admins and dispatchers.

Place a pickup or delivery point › path Parameters

id
​string · uuid · required

The shipment id.

end
​string · enum · required

sender (where the parcels are picked up) or recipient (where they go).

Enum values:
sender
recipient

Place a pickup or delivery point › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Place a pickup or delivery point › Request Body

A GPS position in decimal degrees (WGS 84).
lat
​number · min: -90 · max: 90 · required
lng
​number · min: -180 · max: 180 · required

Place a pickup or delivery point › Responses

The shipment, with the new position.

id
​string · required
tracking_number
​string · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
service_kind
​string · enum · required
Enum values:
home_delivery
express_same_day
pickup_point
delivery_confirmation
​string · enum · required
Enum values:
none
signature
otp
shipper_account_id
​string | null · required
​object · required
​object · required
​object[] · required
declared_value_xpf
​integer | null · min: 0 · max: 9007199254740991 · required
​object · required

Whole XPF amounts from the carrier rate card. total_xpf includes the TGC.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
updated_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
shipper_reference
​string | null

The shipper's own reference; null when it gave none.

Example: CMD-20931

Issue a new pickup code

POST
https://api.shipping.nc
/v1/shipments/{id}/pickup-code

Gives the recipient of a parcel waiting at a pickup point a new six-digit code. The old code stops working, the recipient reads the new one on the page of the link they were texted, and the counter may type five codes again: this is how a handover locked after five wrong codes is unlocked. Refused with a 409 once the parcel left the point. Allowed to carrier admins and dispatchers.

Issue a new pickup code › path Parameters

id
​string · uuid · required

The shipment id.

Issue a new pickup code › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Issue a new pickup code › Responses

The new code is issued and the handover is unlocked.

No data returned