shipping.nc API

Tracking events

Server

Record what happens to a shipment. Safe to retry: each event carries a client event id.


Record a tracking event

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

Moves the shipment to a new status. Idempotent on client_event_id: sending an event again returns the recorded one with a 200, so a device can retry after a lost connection without duplicates. Allowed to carrier admins, dispatchers and drivers.

Record a tracking event › path Parameters

id
​string · uuid · required

The shipment id.

Record a tracking event › Headers

x-correlation-id
​string · maxLength: 128

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

Record a tracking event › Request Body

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

A UUID the device generates once per event. Sending the same event again returns the recorded one instead of a duplicate.

Example: 3f2a9c84-6e1b-4f7d-8a20-5c9e1b7d3a46
status
​string · enum · required
Enum values:
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
returned_to_sender
occurred_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When it happened on the device, with its offset.

Example: 2026-11-11T14:05:00+11:00
​object

A GPS position in decimal degrees (WGS 84).

note
​string · maxLength: 500
place
​string · minLength: 1 · maxLength: 80

A coarse place name shown to the recipient, never an address.

Example: Ducos, Noumea
​object

When the recipient can expect the parcel. Only with the out_for_delivery status.

​object

Evidence of a delivery, or of a pickup at the sender (signature_key is then the shipper signature).

​object

Why the delivery failed. Only with delivery_failed.

​object

What the driver reports. Only with incident; it opens an incident for dispatch.

Record a tracking event › Responses

The event was already recorded; it is returned unchanged.

id
​string · required
client_event_id
​string | null · required
status
​string · enum · required
Enum values:
created
picked_up
in_transit
out_for_delivery
delivered
available_for_pickup
collected
delivery_failed
occurred_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
recorded_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
actor_user_id
​string | null · required
actor_kind
​string · enum · required

Who recorded the event: the system or a role.

Enum values:
system
carrier_admin
dispatcher
driver
shipper
relay_point
merchant
actor_name
​string | null · required

Full name of the person who recorded it, when known.

Example: Kevin Martin
correlation_id
​string · required

Correlation ID of the request that recorded it.

Example: 7f3c1d0a-41b2-4c8e-9d6f-2a5b8e1c4f70
​object | null · required

A GPS position in decimal degrees (WGS 84).

note
​string | null · required
​required

The failure reason of a delivery_failed event, or the incident kind of an incident event.

place
​string | null · required