/v1 /shipmentsStarts tracking one identifier and returns the shipment straight away, usually in discovering (tracking for air). Carrier data follows within minutes — read it with GET /v1/shipments/{id}, or subscribe to shipment.discovery_finished and shipment.status_changed.
Body
identifierstringrequiredContainer, Master B/L, booking or Master AWB number. Surrounding whitespace is trimmed.
modeenumrequiredAn unambiguous identifier wins over what you send: an ISO 6346 container number is always tracked as OCEAN, an AWB with a known airline prefix and a valid check digit as AIR. The response’s mode says which.
OCEANAIRcarrierstringA carrier code (MSC, MAERSK) or your own wording ("Hapag Lloyd", "MAERSK LINE A/S"). A name Navlo can’t match is still accepted and the carrier is detected from the identifier — never rejected. Informational for air: the AWB prefix decides.
customerobjectThe shipment’s customer — how it resolves. On an identifier you already track, it sets or replaces the customer.
customer.iduuidA Navlo customer id from GET /v1/customers. Wins when both id and ref are sent.
customer.refstringYour own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer.
customer.namestringName used only when the ref creates a new customer. Defaults to the ref. Never renames an existing customer.
Request
curl -X POST "https://api.navlo.io/v1/shipments" \
-H "X-API-Key: $NAVLO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "MEDU1234562",
"mode": "OCEAN",
"carrier": "MSC",
"customer": {
"ref": "C-1042",
"name": "Acme Trading Ltd."
}
}'Response
{
"id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
"identifier": "MEDU1234562",
"mode": "OCEAN",
"status": "discovering",
"carrier": "MSC",
"createdAt": "2026-09-24T07:41:18Z"
}Response fields
iduuidThe shipment’s id — the {id} of every /v1/shipments/{id} call.
identifierstringThe number you tracked, trimmed (AWBs in the dashed IATA form, e.g. 871-12345675).
modeenumTransport mode.
OCEANAIRstatusenumLifecycle status — see Statuses. tracking — air only: the waybill was accepted and Navlo is fetching the airline's first data. It becomes active when that data arrives (or discovering if no airline has it yet). A new air shipment's create response usually says tracking. List, export and report filters treat it as active.
discoveringresolvingactivetrackingcompletedstoppedcarrierstringnullableThe carrier Navlo tracks this shipment with, e.g. MSC or SUPARANA_AIRLINES. Null until the carrier is known. Display it as-is.
createdAttimestampWhen the shipment was started in Navlo (UTC).
Errors
identifier missing or blank.mode missing or not OCEAN / AIR.customer.id is not one of your customers.customer was sent without id or ref.Notes
- Idempotent. Posting an identifier your organization already tracks returns that shipment, still with
201— no duplicate, no charge. - Cost: 1 tracking credit for an identifier new to your organization. Free when your organization already tracks it, and when Navlo can’t track that carrier (the shipment is then
stoppedat once). If discovery finds no data at all, Navlo keeps retrying and refunds the credit when it gives up. - A bad
customeris rejected before anything is created or charged.