Developers

API Reference

Everything your systems can do with Navlo over one REST API: track ocean and air shipments, read every milestone, ETA and risk signal, attribute usage to your own customers, ask Navlo AI, and get each change pushed to you by webhook.

Base URL  https://api.navlo.ioVersion  v1Endpoints  67Updated  22 Oct 2026

01 · Get started

Quick start

From a new API key to a tracked shipment and your first webhook in about five minutes.

The Navlo API lets your systems do what your team does in the app: start tracking ocean and air shipments, read every milestone, ETA and risk signal Navlo has, put shipments on your own customers, ask Navlo AI, and get each change pushed to you. Most examples in these docs use the same demo shipment — container MEDU1234562, shipped for the customer Acme Trading Ltd. (C-1042) — so you can follow one shipment from the first request to the usage report; webhook payloads are exactly what your endpoint receives.

Base URL
https://api.navlo.io
Format
JSON over HTTPS, UTF-8, camelCase field names
Authentication
X-API-Key: nvl_… header on every request
Version
/v1 — changes are additive only (Compatibility promise)
Machine-readable
OpenAPI 3 document and a Postman collection

1. Create an API key

  1. 1In the Navlo app, open Settings → API & Embedding and choose New key.
  2. 2Name it after the system that will use it (for example "ERP integration") and pick the REST API scope.
  3. 3Copy the key. It starts with nvl_ and is shown only once — store it in your secret manager.
Only organization admins can create keys. A request acts as the admin who created the key: shipments appear in the app under their name and use your organization’s credits. Details in Authentication.
export NAVLO_API_KEY="nvl_…"   # the key you just copied

2. Check the key works

GET /v1/credits is a safe first call: it changes nothing and returns the balances your requests draw from.

Request

curl "https://api.navlo.io/v1/credits" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "trackingCredits": 248,
  "aiCredits": 14.3725
}

3. Start tracking a shipment

Send the container, Master B/L, booking or Master AWB number with its mode. Add customer to put the shipment on one of your own customers — the first time Navlo sees a reference it creates that customer for you, so your billing codes work from day one.

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

201 Created
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "identifier": "MEDU1234562",
  "mode": "OCEAN",
  "status": "discovering",
  "carrier": "MSC",
  "createdAt": "2026-09-24T07:41:18Z"
}
Posting an identifier your organization already tracks returns the existing shipment — no duplicate and no second charge — so retrying a create after a timeout is always safe.

4. Read the shipment

The status starts as discovering (tracking for air) while Navlo finds the carrier and pulls the first data — usually within minutes — and becomes active once carrier data arrives. Ask for Navlo’s own intelligence with include:

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07?include=risk,navloEta,customer" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "identifier": "MEDU1234562",
  "mode": "OCEAN",
  "status": "active",
  "carrier": "MSC",
  "containers": [
    {
      "containerNumber": "MEDU1234562",
      "containerType": "40HC",
      "status": "DEPARTED",
      "etd": "2026-09-26T22:00:00Z",
      "atd": "2026-09-27T03:40:00Z",
      "eta": "2026-10-30T06:00:00Z",
      "ata": null,
      "origin": {
        "code": "CNSHA",
        "name": "Shanghai"
      },
      "destination": {
        "code": "TRAMR",
        "name": "Ambarli"
      },
      "currentVessel": "MSC MARTINA"
    }
  ],
  "airShipments": [],
  "events": [
    {
      "timestamp": "2026-09-24T14:12:00Z",
      "type": "ACTUAL",
      "status": "GATE_IN",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": null,
      "voyage": null,
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-26T21:30:00Z",
      "type": "ACTUAL",
      "status": "LOADED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-27T03:40:00Z",
      "type": "ACTUAL",
      "status": "DEPARTED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-23T08:00:00Z",
      "type": "EXPECTED",
      "status": "TRANSSHIPMENT",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-27T18:00:00Z",
      "type": "EXPECTED",
      "status": "DEPARTED",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-30T06:00:00Z",
      "type": "EXPECTED",
      "status": "ARRIVED",
      "location": "Ambarli",
      "locationCode": "TRAMR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    }
  ],
  "etaHistory": [
    {
      "field": "ETA",
      "previousValue": "2026-10-27T06:00:00Z",
      "newValue": "2026-10-30T06:00:00Z",
      "deltaHours": 72,
      "recordedAt": "2026-10-14T09:22:14Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    },
    {
      "field": "ETA",
      "previousValue": "2026-10-25T06:00:00Z",
      "newValue": "2026-10-27T06:00:00Z",
      "deltaHours": 48,
      "recordedAt": "2026-10-03T11:05:39Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    }
  ],
  "vessel": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z"
  },
  "risk": {
    "level": "MEDIUM",
    "score": 52,
    "summary": "ETA slipped 5 days since departure; the Piraeus transshipment is congested.",
    "computedAt": "2026-10-22T07:15:00Z",
    "stale": false
  },
  "navloEta": [
    {
      "containerNumber": "MEDU1234562",
      "predictedEta": "2026-10-31T02:00:00Z",
      "confidence": "MEDIUM",
      "computedAt": "2026-10-22T05:42:19Z",
      "carrierEta": "2026-10-30T06:00:00Z"
    }
  ],
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  }
}

5. Get changes pushed to you

Instead of polling, register an HTTPS endpoint. Navlo POSTs a signed JSON event for every status change, ETA move, risk, D&D warning and route change on your shipments. Leaving topics out subscribes the endpoint to every topic, including ones added later.

Request

curl -X POST "https://api.navlo.io/v1/webhooks" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP shipment updates",
    "url": "https://erp.example.com/webhooks/navlo"
  }'

Response

201 Created
{
  "id": "2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68",
  "name": "ERP shipment updates",
  "url": "https://erp.example.com/webhooks/navlo",
  "topics": [],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-10-22T08:15:00Z",
  "secret": "whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f"
}

Store secret — it is shown only here and when you rotate it — and check every delivery’s signature with it before trusting the body: Verifying signatures. To see a real payload right away, send a test event.

Next steps

  • Shipments — filters, updatedSince sync, batch create, customer assignment.
  • Shipment intelligence — risk, Navlo ETA, D&D, carbon, recommendations, route alerts.
  • Usage & credits — re-bill your own customers from Navlo’s usage report.
  • Navlo AI — ask questions about your shipments over the API, streamed.
  • Embed — put live tracking on your own website.
  • Errors and Rate limits — build a client that behaves under failure.

01 · Get started

Authentication

Every request carries a REST API key in the X-API-Key header — no OAuth, no tokens to refresh.

Send your key in the X-API-Key header on every request to https://api.navlo.io/v1/…. The key is the credential: there is no login call and nothing expires on its own.

Request

curl "https://api.navlo.io/v1/shipments?size=1" \
  -H "X-API-Key: $NAVLO_API_KEY"

Key types

KeyStarts withWorks onKeep it
REST APInvl_All /v1 endpointsServers only
Embednvle_Widget, /api/embed/resolveWeb pages

Both are created under Settings → API & Embedding by an organization admin, and both are shown in full only once, at creation. An embed key sent to a /v1 endpoint is rejected with 401.

Who a request acts as

  • A key belongs to your organization and acts as the person who created it. Shipments, notes and Navlo AI conversations created through the API show that person as the author in the app, and Navlo AI conversations appear in their Navlo AI list.
  • Credits come from the balance that person uses in the app. Keys are created by organization admins, whose balance is the organization’s pool.
  • Everything is scoped to your organization. An id that belongs to another organization behaves exactly like one that doesn’t exist: 404.
  • Admin-only operations — managing webhooks, deleting tags — work while the key’s creator is an organization admin, and answer 403 otherwise.

Rotating and revoking keys

  • To rotate, create the new key, deploy it, then revoke the old one under Settings → API & Embedding. A revoked key fails on its very next request.
  • A key works only while the person who created it is an active member of your organization: if they leave or their account is deactivated, it answers 401 Invalid or revoked API key (and works again if they are reactivated). Create the replacement as another admin.
  • The key list shows each key’s prefix, who created it and when it was last used, so unused keys are easy to find and revoke.
  • An organization can have at most 10 live keys, REST and embed together.

Treat the key like a password

Keep REST keys on your servers. Anyone holding one can start shipments on your credits and read every shipment in your organization. Never ship an nvl_ key in browser JavaScript or a mobile app — the embed key exists for that.

Authentication errors

401 Invalid or revoked API key
The header is missing, the key is mistyped or revoked, its creator is no longer an active member, or an embed key was sent to /v1.
401 API key owner no longer exists
The person who created the key was removed from your organization.
403 (message per operation)
The key works, but its creator may not do this — for example, they are not an admin.

Only GET /v1/openapi.json, the machine-readable reference, answers without a key.

01 · Get started

Errors

Standard HTTP status codes, and a JSON body whose message always explains what went wrong.

Navlo answers every failed request with an HTTP status code and a JSON body carrying a human-readable message. Read message — in every shape the API can return — and you will never lose an explanation.

Error body

404 Not Found
{
  "error": "Shipment not found",
  "message": "Shipment not found"
}

error and message carry the same text. error stays because integrations built before 2026-10-22 read it; new code should read message.

A few errors — an unexpected server error, a malformed path parameter, or insufficient credits on the original shipment endpoints — use a second shape. It has message too:

402 Payment Required
{
  "timestamp": "2026-10-22T09:14:03.512",
  "status": 402,
  "error": "Payment Required",
  "message": "Insufficient credits. Required: 1.00, Available: 0.00",
  "path": null
}
In this second shape error is the HTTP reason phrase ("Payment Required"), not the explanation. Always show or log message.

The embed endpoint, GET /api/embed/resolve, answers errors with an empty body: branch on the status code there.

Status codes

200 201 202 204
Success.
400 Bad Request
The request is invalid. Fix it — message names the field. Don’t retry it unchanged.
401 Unauthorized
Missing, invalid or revoked key. Check the key; don’t retry.
402 Payment Required
Not enough credits. Top up or transfer credits, then retry.
403 Forbidden
The key’s creator lacks the permission for this operation.
404 Not Found
No such resource in your organization (another organization’s ids read the same). Check the id.
409 Conflict
The request conflicts with the current state — e.g. the carrier was already changed once. Read message.
410 Gone
The resource expired; create it again.
429 Too Many Requests
Rate limit reached. Wait Retry-After seconds, then retry.
500 Internal Server Error
Unexpected error on Navlo’s side. Retry with backoff; contact support if it persists.
503 Service Unavailable
Temporarily unavailable (e.g. Navlo AI busy). Retry with backoff.

Retrying safely

  • Retry 429, 500, 502, 503, 504 and network errors with exponential backoff, honouring Retry-After when present. Never retry any other 4xx unchanged.
  • POST /v1/shipments and every batch item are idempotent per identifier: retrying a create that timed out never creates a duplicate or charges twice.
  • Stop, resume, mute, complete, share link, archive and restore are idempotent too. Creating a note, uploading a document or adding a subscriber is not — check before retrying those.

A small client with retries

const BASE = 'https://api.navlo.io'

// Retries 429 / 5xx with Retry-After or exponential backoff; throws with Navlo's message otherwise.
export async function navlo(path, { method = 'GET', body, retries = 3 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      method,
      headers: {
        'X-API-Key': process.env.NAVLO_API_KEY,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    })
    if ((res.status === 429 || res.status >= 500) && attempt < retries) {
      const waitSeconds = Number(res.headers.get('Retry-After')) || 2 ** attempt
      await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000))
      continue
    }
    if (res.status === 204) return null
    const data = await res.json()
    if (!res.ok) throw new Error(`Navlo ${res.status}: ${data.message}`)
    return data
  }
}

const shipment = await navlo('/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07')

01 · Get started

Rate limits

60 requests a minute per key, 10 a minute for Navlo AI, plus a few caps per organization — with headers that tell you where you stand.

Limits apply per API key, per minute. Every response tells you how much of the current window is left and when it resets. Request bodies are capped at 1 MB (uploads: 10 MB); a larger one answers 413.

General — 60 / minute
Every /v1 endpoint except Navlo AI.
Navlo AI — 10 / minute
Paths under /v1/ai/.
Tracking widget — 60 / minute
Lookups per embed key.

The buckets are independent: a burst of Navlo AI questions never slows your tracking sync, and a backfill never blocks Navlo AI.

Caps per organization

API keys — 10 live
REST and embed keys together. Revoke one you no longer use before creating another.
Navlo AI — 2 answers at once
A question sent while two are still being answered gets 429 and nothing is stored; send it when one finishes.
Share emails — 500 recipients / 24 hours
App and API together (subscribers). A request that would go over answers 429 and emails nobody.

Headers on every response

HeaderMeaning
X-RateLimit-LimitThe bucket’s limit per minute (60 or 10)
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix time, in seconds, when the window resets
Retry-AfterOnly on 429: seconds to wait before retrying

When you hit the limit

Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792656960
Retry-After: 23

{"error":"Rate limit exceeded (60 requests/minute)","message":"Rate limit exceeded (60 requests/minute)"}

Wait the Retry-After seconds and send the request again. The client on the Errors page does this for you.

Staying well under the limit

  • Use webhooks instead of polling every shipment: each change reaches you once, when it happens.
  • If you poll, poll the list with updatedSince — one request returns every shipment that changed since your last sync (how).
  • Start many shipments with POST /v1/shipments/batch: up to 50 per request, counted as one request.
  • A streamed Navlo AI answer counts once, however long it streams.
  • Webhook deliveries and the embed widget never count against your key.
  • Need a higher limit for a backfill? Write to support@navlo.io with the volume and the window.

01 · Get started

Compatibility promise

What stays stable on /v1, and the three habits that keep your integration working as the API grows.

An integration built on /v1 keeps working. This is what Navlo commits to — and what your code should do so a new field or value never breaks it.

What Navlo promises

  • /v1 stays. Documented paths, parameters and response fields are not removed or renamed, and their types don’t change.
  • Changes are additive. New endpoints, optional parameters, response fields, webhook topics and enum values can appear at any time without notice.
  • New data is opt-in. Richer shipment data arrives through include=; a request without it returns exactly what it returned before.
  • Breaking changes get a new version. Anything that must change incompatibly ships as /v2, announced in the Changelog with time to migrate. /v1 keeps running alongside it.

What your code should do

  • Ignore JSON fields you don’t recognise; never fail on them. Configure strict deserialisers to allow unknown properties.
  • Handle enum values you don’t recognise — statuses, milestone codes, recommendation kinds, alert types — with a generic fallback.
  • Acknowledge webhook topics you didn’t expect with 2xx: an endpoint without topics also receives topics added later.
  • Don’t depend on the order of object keys, or of list items unless a field documents its order.
  • Read error explanations from message.

Kept for compatibility

  • error in error bodies — the same text as message.
  • The original shipment endpoints answer exactly as before when you send no new parameters: same fields, same order, same status codes.

02 · Shipments

Shipments

Start tracking ocean containers, B/Ls, bookings and air waybills, then list, read, update, pause and delete them.

A shipment is one identifier you asked Navlo to track. Navlo finds the carrier, pulls the data and keeps it current on its own polling schedule; you read the result here or get it pushed through webhooks.

What you can track

IdentifierModeExample
Container number (ISO 6346)OCEANMEDU1234562
Master bill of ladingOCEANMEDUSH448021
Booking numberOCEAN177SHA2611987
Master air waybill (MAWB)AIR871-12345675 (dash optional)

A B/L or booking with several containers becomes one shipment with several containers. House B/Ls and house AWBs are not supported — send the master document.

Putting a shipment on a customer

Shipments, batch items, Navlo AI questions and vessel follows accept a customer object, so every credit you spend is attributed to one of your customers in the usage report. Send either Navlo’s id or your own reference:

{
  "customer": {
    "ref": "C-1042",
    "name": "Acme Trading Ltd."
  }
}
  • id — one of your customers. Unknown → 400 Unknown customer id, unless you also sent a ref.
  • ref — your own code (max 100 characters; matched case-insensitively and trimmed). The customer with that ref is used. An unknown ref creates a new customer named name (or the ref, without a name) — or, when a customer of that name already exists without a reference, gives it this ref. A same-named customer that already has another reference is refused: 400 A customer named "Acme Trading Ltd." already exists with the reference "C-9". Existing customers are never renamed this way.
  • Both id and ref: id wins when it exists; an unknown id falls back to the ref.
  • An empty object is rejected (400 customer needs an id or a ref), and an archived customer can’t take shipments (400 "Acme Trading Ltd." is archived. Restore it before assigning shipments.). All of this is checked before anything is created or charged.

Customers are the companies on the app’s Companies page; manage them with the Customers API.

POST/v1/shipments

Starts 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.

Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

identifierstringrequired

Container, Master B/L, booking or Master AWB number. Surrounding whitespace is trimmed.

modeenumrequired

An 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.

OCEANAIR
carrierstring

A 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.

customerobject

The shipment’s customer — how it resolves. On an identifier you already track, it sets or replaces the customer.

customer.iduuid

A Navlo customer id from GET /v1/customers. Wins when both id and ref are sent.

customer.refstring

Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer.

customer.namestring

Name 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

201 Created
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "identifier": "MEDU1234562",
  "mode": "OCEAN",
  "status": "discovering",
  "carrier": "MSC",
  "createdAt": "2026-09-24T07:41:18Z"
}

Response fields

iduuid

The shipment’s id — the {id} of every /v1/shipments/{id} call.

identifierstring

The number you tracked, trimmed (AWBs in the dashed IATA form, e.g. 871-12345675).

modeenum

Transport mode.

OCEANAIR
statusenum

Lifecycle 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.

discoveringresolvingactivetrackingcompletedstopped
carrierstringnullable

The carrier Navlo tracks this shipment with, e.g. MSC or SUPARANA_AIRLINES. Null until the carrier is known. Display it as-is.

createdAttimestamp

When the shipment was started in Navlo (UTC).

Errors

StatusMessageWhen
400identifier must not be blankidentifier missing or blank.
400mode is required: OCEAN or AIRmode missing or not OCEAN / AIR.
400Unknown customer idcustomer.id is not one of your customers.
400customer needs an id or a refcustomer was sent without id or ref.
400Malformed or unreadable request bodyThe body is not valid JSON (general error shape).
402Insufficient credits. Required: 1.00, Available: 0.00A new identifier and no tracking credits left (general error shape).
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

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 stopped at once). If discovery finds no data at all, Navlo keeps retrying and refunds the credit when it gives up.
  • A bad customer is rejected before anything is created or charged.
POST/v1/shipments/batch

Bulk-starts tracking in one call — built for integration platforms and backfills. The call counts as one request against the rate limit, and items succeed or fail on their own: there is no all-or-nothing rejection.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Body

shipmentsarray<object>required

1–50 items.

shipments[].identifierstringrequired

As on the single endpoint. A blank item fails alone.

shipments[].modeenumrequired

As on the single endpoint. An item without it fails alone.

OCEANAIR
shipments[].carrierstring

Code or your own wording — same resolution as the single endpoint.

shipments[].customerobject

{ "id" } or { "ref", "name" }. A bad customer fails that item only.

Request

curl -X POST "https://api.navlo.io/v1/shipments/batch" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipments": [
      {
        "identifier": "MEDU1234562",
        "mode": "OCEAN",
        "customer": {
          "ref": "C-1042"
        }
      },
      {
        "identifier": "TGHU8126501",
        "mode": "OCEAN",
        "carrier": "Hapag Lloyd",
        "customer": {
          "ref": "C-1042"
        }
      },
      {
        "identifier": "176-12345675",
        "mode": "AIR",
        "customer": {
          "ref": "C-2107",
          "name": "Sample Foods Ltd."
        }
      },
      {
        "identifier": "MSCU7362815",
        "mode": "OCEAN",
        "customer": {
          "id": "00000000-0000-0000-0000-000000000000"
        }
      }
    ]
  }'

Response

200 OK
{
  "submitted": 4,
  "created": 2,
  "existing": 1,
  "errors": 1,
  "results": [
    {
      "identifier": "MEDU1234562",
      "status": "existing",
      "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
      "error": null
    },
    {
      "identifier": "TGHU8126501",
      "status": "created",
      "id": "6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7",
      "error": null
    },
    {
      "identifier": "176-12345675",
      "status": "created",
      "id": "b5d13c88-9e2f-4a7b-8c41-6f0a3e9d72c5",
      "error": null
    },
    {
      "identifier": "MSCU7362815",
      "status": "error",
      "id": null,
      "error": "Unknown customer id"
    }
  ]
}

Response fields

submittedinteger

Items received.

createdinteger

New shipments started — one credit each.

existinginteger

Identifiers you already tracked — returned, not charged.

errorsinteger

Items that failed.

resultsarray<object>

One per item, in request order.

results[].identifierstring

The item’s identifier as sent (trimmed).

results[].statusenum

What happened to the item.

createdexistingerror
results[].iduuidnullable

The shipment id; null on error.

results[].errorstringnullable

Why the item failed, e.g. Insufficient credits, Unknown customer id; null otherwise.

Errors

StatusMessageWhen
400shipments must not be emptyshipments is empty.
400Maximum 50 shipments per batchMore than 50 items.
400Malformed or unreadable request bodyThe body is not valid JSON (general error shape).
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Notes

  • Running out of credits mid-batch fails the remaining new identifiers with Insufficient credits; items you already track still come back as existing.
GET/v1/shipments

Pages through your organization’s shipments, newest data first when you sort by -updatedAt. Every filter is optional and they combine with AND; a carrier, customer or tag that matches nothing gives an empty page, not an error. With no parameters the response is exactly what this endpoint has always returned.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Query parameters

pageintegerdefault 0

Zero-based page index.

sizeintegerdefault 20

Page size, 1–100. Larger values are capped at 100.

statuscsv

Only these statuses, e.g. active,completed. active also matches tracking.

discoveringresolvingactivetrackingcompletedstopped
modecsv

Only ocean or only air shipments (OCEAN,AIR means both).

OCEANAIR
carrierstring

Carrier code, e.g. MSC, MAERSK — exact, case-insensitive.

customerIduuid

Only shipments of this customer.

customerRefstring

Only shipments of the customer with this reference (case-insensitive). With customerId too, both must match.

tagcsv

Tag names (case-insensitive); shipments carrying any of them, e.g. Priority,Q4 launch.

riskcsv

Only these risk levels. Only fresh risk counts — shipments whose risk is stale or unknown never match.

LOWMEDIUMHIGH
etaFromtimestamp | date

ETA on or after this time (any container or waybill). ETAs are carrier-local times, compared as written. Every date filter takes an ISO instant, an offset date-time or a plain date.

etaTotimestamp | date

ETA on or before this time; a date means the end of that day.

createdFromtimestamp | date

Started in Navlo on or after this time (UTC).

createdTotimestamp | date

Started in Navlo on or before this time (UTC); a date means the end of that day.

updatedSincetimestamp

Only shipments whose data changed at or after this time — compared with lastChangedAt. The basis of incremental sync; air shipments can match without a visible change (see there).

sortenum

updatedAt sorts by lastChangedAt, eta by the soonest ETA (shipments without one last); prefix - for descending. Without sort, filtered lists come newest-created first, while a request with no filters (only include, or nothing) keeps the order it always had — pass sort whenever order matters.

createdAt-createdAtupdatedAt-updatedAteta-eta
includecsv

Extra keys on each item — see the response fields below.

customertagsrisklastChangedAt

Request

curl "https://api.navlo.io/v1/shipments?status=active&customerRef=C-1042&include=customer,tags,risk,lastChangedAt&sort=-updatedAt" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

{
  "page": 0,
  "size": 20,
  "totalElements": 2,
  "totalPages": 1,
  "shipments": [
    {
      "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
      "identifier": "MEDU1234562",
      "mode": "OCEAN",
      "status": "active",
      "carrier": "MSC",
      "createdAt": "2026-09-24T07:41:18Z",
      "customer": {
        "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
        "ref": "C-1042",
        "name": "Acme Trading Ltd.",
        "countryCode": "TR"
      },
      "tags": [
        {
          "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
          "name": "Priority",
          "color": "#ef4444"
        },
        {
          "id": "b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77",
          "name": "Q4 launch",
          "color": "#3b82f6"
        }
      ],
      "risk": {
        "level": "MEDIUM",
        "computedAt": "2026-10-22T07:15:00Z",
        "stale": false
      },
      "lastChangedAt": "2026-10-22T06:00:41Z"
    },
    {
      "id": "6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7",
      "identifier": "TGHU8126501",
      "mode": "OCEAN",
      "status": "active",
      "carrier": "HAPAG",
      "createdAt": "2026-10-02T13:20:07Z",
      "customer": {
        "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
        "ref": "C-1042",
        "name": "Acme Trading Ltd.",
        "countryCode": "TR"
      },
      "tags": [],
      "risk": {
        "level": null,
        "computedAt": "2026-10-21T19:02:00Z",
        "stale": true
      },
      "lastChangedAt": "2026-10-21T22:47:13Z"
    }
  ]
}

Response fields

pageinteger

The page you asked for.

sizeinteger

The page size used.

totalElementsinteger

Shipments matching the filters.

totalPagesinteger

Pages at this size.

shipmentsarray<object>

The page’s shipments, each with the fields below.

shipments[].iduuid

The shipment’s id — the {id} of every /v1/shipments/{id} call.

shipments[].identifierstring

The number you tracked, trimmed (AWBs in the dashed IATA form, e.g. 871-12345675).

shipments[].modeenum

Transport mode.

OCEANAIR
shipments[].statusenum

Lifecycle 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.

discoveringresolvingactivetrackingcompletedstopped
shipments[].carrierstringnullable

The carrier Navlo tracks this shipment with, e.g. MSC or SUPARANA_AIRLINES. Null until the carrier is known. Display it as-is.

shipments[].createdAttimestamp

When the shipment was started in Navlo (UTC).

shipments[].customerobjectnullable

With include=customer: the shipment’s customer (id, ref, name, countryCode), or null.

shipments[].tagsarray<object>

With include=tags: the shipment’s tags, [{ id, name, color }].

shipments[].riskobject

With include=risk: { level, computedAt, stale } — the same freshness rule as the detail’s risk.

shipments[].lastChangedAttimestampnullable

With include=lastChangedAt: when the shipment’s data last changed — the value updatedSince and sort=updatedAt use. If no change is recorded yet, it falls back to the shipment’s last update time.

Errors

StatusMessageWhen
400Unknown status 'shipped'. Allowed values: discovering, resolving, active, tracking, completed, stoppedA filter, sort or include value outside its allowed list — the message names the parameter.
400etaFrom must be an ISO-8601 timestamp or date, e.g. 2026-10-01T00:00:00Z or 2026-10-01A date parameter that doesn’t parse.
400customerId must be a UUIDA malformed customerId.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
GET/v1/shipments/{id}

The full shipment: containers or air waybills with their dates and ports, the merged event timeline, the ETA change history and the vessel’s last known position. Add include for Navlo’s intelligence — each value is documented on Shipment intelligence.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id from the create or list response.

Query parameters

includecsv

Extra blocks to add. A requested key is always present — null or [] when there is nothing. all adds every block.

riskrecommendationsnavloEtadndcarbonalertscustomertagsdetailsall

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "identifier": "MEDU1234562",
  "mode": "OCEAN",
  "status": "active",
  "carrier": "MSC",
  "containers": [
    {
      "containerNumber": "MEDU1234562",
      "containerType": "40HC",
      "status": "DEPARTED",
      "etd": "2026-09-26T22:00:00Z",
      "atd": "2026-09-27T03:40:00Z",
      "eta": "2026-10-30T06:00:00Z",
      "ata": null,
      "origin": {
        "code": "CNSHA",
        "name": "Shanghai"
      },
      "destination": {
        "code": "TRAMR",
        "name": "Ambarli"
      },
      "currentVessel": "MSC MARTINA"
    }
  ],
  "airShipments": [],
  "events": [
    {
      "timestamp": "2026-09-24T14:12:00Z",
      "type": "ACTUAL",
      "status": "GATE_IN",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": null,
      "voyage": null,
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-26T21:30:00Z",
      "type": "ACTUAL",
      "status": "LOADED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-27T03:40:00Z",
      "type": "ACTUAL",
      "status": "DEPARTED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-23T08:00:00Z",
      "type": "EXPECTED",
      "status": "TRANSSHIPMENT",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-27T18:00:00Z",
      "type": "EXPECTED",
      "status": "DEPARTED",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-30T06:00:00Z",
      "type": "EXPECTED",
      "status": "ARRIVED",
      "location": "Ambarli",
      "locationCode": "TRAMR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    }
  ],
  "etaHistory": [
    {
      "field": "ETA",
      "previousValue": "2026-10-27T06:00:00Z",
      "newValue": "2026-10-30T06:00:00Z",
      "deltaHours": 72,
      "recordedAt": "2026-10-14T09:22:14Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    },
    {
      "field": "ETA",
      "previousValue": "2026-10-25T06:00:00Z",
      "newValue": "2026-10-27T06:00:00Z",
      "deltaHours": 48,
      "recordedAt": "2026-10-03T11:05:39Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    }
  ],
  "vessel": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z"
  }
}

Response fields

iduuid

The shipment’s id.

identifierstring

The number you tracked.

modeenum

Branch on this: ocean shipments fill containers, air shipments fill airShipments.

OCEANAIR
statusenum

Lifecycle status. 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.

discoveringresolvingactivetrackingcompletedstopped
carrierstringnullable

The carrier, as on the list.

containersarray<object>

OCEAN: one entry per container. Always [] for air.

containers[].containerNumberstring

ISO 6346 container number.

containers[].containerTypestringnullable

Size/type as the carrier reports it, e.g. 40HC, 20DV.

containers[].statusstringnullable

The container’s current milestone code, e.g. DEPARTED, DISCHARGED (milestone codes).

containers[].etdtimestampnullable

Estimated departure from the port of loading — carrier local time (time zones).

containers[].atdtimestampnullable

Actual departure from the port of loading.

containers[].etatimestampnullable

Estimated arrival at the port of discharge — the carrier’s ETA.

containers[].atatimestampnullable

Actual arrival at the port of discharge.

containers[].origin.codestringnullable

Port of loading code — UN/LOCODE for ocean (CNSHA), IATA for air (AMS).

containers[].origin.namestringnullable

Port of loading name.

containers[].destination.codestringnullable

Port of discharge code — UN/LOCODE for ocean (CNSHA), IATA for air (AMS).

containers[].destination.namestringnullable

Port of discharge name.

containers[].currentVesselstringnullable

The vessel the container is on or booked on.

airShipmentsarray<object>

AIR: one entry per air waybill. Always [] for ocean.

airShipments[].awbNumberstringnullable

Dashed IATA form, e.g. 871-12345675.

airShipments[].statusstringnullable

Current milestone code, e.g. BOOKED, DEPARTED, ARRIVED, DELIVERED.

airShipments[].origin.codestringnullable

Origin airport code — UN/LOCODE for ocean (CNSHA), IATA for air (AMS).

airShipments[].origin.namestringnullable

Origin airport name.

airShipments[].destination.codestringnullable

Destination airport code — UN/LOCODE for ocean (CNSHA), IATA for air (AMS).

airShipments[].destination.namestringnullable

Destination airport name.

airShipments[].currentAirportobjectnullable

Where the cargo was last reported (code, name), when the airline says.

airShipments[].etdtimestampnullable

Estimated departure — airport local time.

airShipments[].atdtimestampnullable

Actual departure.

airShipments[].etatimestampnullable

Estimated arrival.

airShipments[].atatimestampnullable

Actual arrival.

airShipments[].piecesintegernullable

Pieces on the waybill.

airShipments[].weightnumbernullable

Gross weight, in weightUnit.

airShipments[].weightUnitenumnullable

Null reads as kilograms.

KILOGRAMPOUND
airShipments[].chargeableWeightnumbernullable

IATA chargeable (volumetric) weight, same unit.

airShipments[].volumenumbernullable

Volume, in volumeUnit (usually cubic metres).

airShipments[].volumeUnitstringnullable

Volume unit when the airline reports one.

airShipments[].flightsarray<object>

Booked and flown legs in order — empty until the airline publishes the routing.

airShipments[].flights[].flightNumberstring

e.g. Y87001.

airShipments[].flights[].fromobject

Departure airport (code, name).

airShipments[].flights[].toobject

Arrival airport (code, name).

airShipments[].flights[].etdtimestampnullable

Scheduled/estimated departure of the leg (atd, eta, ata likewise).

airShipments[].flights[].statusstringnullable

The airline’s booking status for the leg, e.g. BOOKED, PLANNED.

eventsarray<object>

The merged timeline across containers or waybills, oldest first (up to 200 events per container).

events[].timestamptimestampnullable

When it happened (or is expected) — carrier local time.

events[].typeenumnullable

ACTUAL — it happened. EXPECTED — a carrier projection that can still change. Null when the carrier doesn’t say.

ACTUALEXPECTED
events[].statusstringnullable

Navlo’s milestone code when the carrier event is mapped (DEPARTED), otherwise the carrier’s own text.

events[].locationstringnullable

Place name.

events[].locationCodestringnullable

UN/LOCODE (ocean) or IATA code (air).

events[].vesselstringnullable

OCEAN: vessel name. Null on air events.

events[].voyagestringnullable

OCEAN: voyage number.

events[].flightstringnullable

AIR: the flight the event refers to. Null on ocean events.

events[].piecesintegernullable

AIR: pieces this event covers — split consignments report a partial count per leg.

events[].weightnumbernullable

AIR: weight this event covers, in the waybill’s unit.

etaHistoryarray<object>

Every recorded ETA/ETD/ATA/ATD change, newest first, up to 100.

etaHistory[].fieldenum

Which time moved.

ETAETDATAATD
etaHistory[].previousValuetimestamp

The value before the change.

etaHistory[].newValuetimestamp

The value after it.

etaHistory[].deltaHoursinteger

Signed hours — positive means later (a delay).

etaHistory[].recordedAttimestamp

When Navlo observed the change (UTC) — not when the carrier decided it.

etaHistory[].containerNumberstringnullable

OCEAN: the container the change belongs to.

etaHistory[].awbNumberstringnullable

AIR: the waybill the change belongs to.

vesselobjectnullable

Last known position of the vessel the shipment is on. Always null for air.

vessel.vesselNamestringnullable

Vessel name.

vessel.latitudenumber

Latitude in degrees.

vessel.longitudenumber

Longitude in degrees.

vessel.headingnumbernullable

Course over ground in degrees, when the fix has one.

vessel.sourceenum

Branch on this before drawing a ship. LIVE — a fresh AIS fix for the vessel the container is verifiably on. STALE — that vessel’s real position, just old (see reportedAt). LAST_KNOWN — no trusted fix: the coordinates are the last port the shipment passed, NOT a ship position.

LIVESTALELAST_KNOWN
vessel.reportedAttimestampnullable

AIS fix time (UTC) for LIVE/STALE; null for LAST_KNOWN.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
400Unknown include 'eta'. Allowed values: risk, recommendations, navloEta, dnd, carbon, alerts, customer, tags, details, allAn include value outside the list — checked first, so even for an id that doesn’t exist.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Update a shipment

New · 2026-10-22
PATCH/v1/shipments/{id}

Changes the shipment’s customer. A key you leave out is not changed; "customer": null removes the customer. Usage already recorded follows the change: the usage report attributes a shipment’s credits to its customer at the time you run the report.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Body

customerobject | null

The new customer ({ "id" } or { "ref", "name" }), or null to clear it.

customer.iduuid

A Navlo customer id from GET /v1/customers. Wins when both id and ref are sent.

customer.refstring

Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer.

customer.namestring

Name used only when the ref creates a new customer. Defaults to the ref. Never renames an existing customer.

Request

curl -X PATCH "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "ref": "C-1042",
      "name": "Acme Trading Ltd."
    }
  }'

Response

{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  }
}

Response fields

iduuid

The shipment id.

customerobjectnullable

The shipment’s customer after the change.

customer.iduuid

Navlo’s customer id.

customer.refstringnullable

Your reference for the customer, when it has one.

customer.namestring

The customer’s name, as shown on the Companies page.

customer.countryCodestringnullable

ISO 3166-1 alpha-2 country code, e.g. TR.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
400Unknown customer idcustomer.id is not one of your customers.
400customer needs an id or a refcustomer was sent without id or ref.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
GET/v1/shipments/{id}/route

The line Navlo draws on the shipment map: sea legs follow real shipping lanes, inland rail and truck legs are straight, and the two never merge into one line. Air shipments get one straight AIR feature per flight leg between the airports (draw the arc yourself) and a null vessel. It has its own endpoint because the geometry is computed, not stored, and runs to hundreds of coordinate pairs — polling the detail never pays for it.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/route" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "shipmentId": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "ports": [
    {
      "code": "CNSHA",
      "name": "Shanghai",
      "latitude": 31.2304,
      "longitude": 121.4737
    },
    {
      "code": "GRPIR",
      "name": "Piraeus",
      "latitude": 37.9421,
      "longitude": 23.6465
    },
    {
      "code": "TRAMR",
      "name": "Ambarli",
      "latitude": 40.9667,
      "longitude": 28.6833
    }
  ],
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "kind": "SEA"
        },
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              121.4737,
              31.2304
            ],
            [
              122.6,
              29.1
            ],
            [
              114.3,
              21.4
            ],
            [
              103.9,
              1.2
            ],
            [
              80.1,
              5.6
            ],
            [
              51.2,
              12.4
            ],
            [
              43.4,
              12.6
            ],
            [
              32.5,
              29.9
            ],
            [
              32.3,
              31.3
            ],
            [
              23.6465,
              37.9421
            ]
          ]
        }
      },
      {
        "type": "Feature",
        "properties": {
          "kind": "SEA"
        },
        "geometry": {
          "type": "LineString",
          "coordinates": [
            [
              23.6465,
              37.9421
            ],
            [
              25.4,
              39.4
            ],
            [
              26.4,
              40.1
            ],
            [
              28.6833,
              40.9667
            ]
          ]
        }
      }
    ]
  },
  "vessel": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z"
  }
}

Response fields

shipmentIduuid

The shipment id.

portsarray<object>

Ports called at, in order: loading, transshipments, discharge. Air: the airports of the legs.

ports[].codestringnullable

UN/LOCODE or IATA code.

ports[].namestringnullable

Port or airport name.

ports[].latitudenumber

Latitude.

ports[].longitudenumber

Longitude.

geojsonobject

A GeoJSON FeatureCollection with one LineString Feature per leg. Coordinates are [longitude, latitude] — GeoJSON order, the reverse of every other field in this API.

geojson.features[].properties.kindenum

The leg’s transport.

SEALANDAIR
vesselobjectnullable

Same shape and rules as vessel on the detail.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404No route available for this shipment yetNothing on the shipment is geocoded yet (e.g. still discovering).
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
POST/v1/shipments/{id}/stop

Stops polling the carrier. The shipment, its history and its status stay as they are, and you can resume at any time. Idempotent: stopping a stopped shipment is a 200.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/stop" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "polling": "stopped"
}

Response fields

iduuid

The shipment id.

pollingenum

Always stopped.

stopped

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Notes

  • Pausing does not change status (stopped means Navlo can’t track the identifier). details.pollingStoppedAt (include) shows a pause.
POST/v1/shipments/{id}/resume

Re-arms polling and asks the carrier for fresh data straight away. Idempotent.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/resume" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "polling": "active"
}

Response fields

iduuid

The shipment id.

pollingenum

Always active.

active

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
DELETE/v1/shipments/{id}

Removes the shipment and everything under it — containers, events, notes, documents, tags. Credits already spent are not refunded. To stop updates but keep the record, pause instead; it can be undone.

Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The shipment id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Keeping your system in sync

Two patterns keep a copy of your shipments current. Most integrations use both: webhooks for speed, a periodic sync as the safety net.

  • Push — subscribe to webhooks. Each event carries the shipment snapshot and what changed; fetch the detail when you need the full picture.
  • Pull — every few minutes, list with updatedSince=<start of your previous run>&sort=updatedAt and refresh the shipments it returns. lastChangedAt (include=lastChangedAt) tells you the exact change time per shipment.

What counts as a change

Ocean shipments count as changed only when their status, ETA or discovery outcome changes. Air shipments can also appear in updatedSince results with no visible change — compare what you stored and skip those. A shipment with no recorded change falls back to its last update time.

Incremental sync

import { readFile, writeFile } from 'node:fs/promises'

// Incremental sync: everything that changed since the last run, oldest change first.
const since = await readFile('last-sync.txt', 'utf8').catch(() => '2026-10-01T00:00:00Z')
const startedAt = new Date().toISOString()

for (let page = 0; ; page++) {
  const params = new URLSearchParams({ updatedSince: since, sort: 'updatedAt', size: '100', page: String(page) })
  const res = await fetch(`https://api.navlo.io/v1/shipments?${params}`, {
    headers: { 'X-API-Key': process.env.NAVLO_API_KEY },
  })
  if (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)
  const { shipments, totalPages } = await res.json()
  for (const s of shipments) await upsertShipment(s.id) // e.g. fetch GET /v1/shipments/{id} and store it
  if (page + 1 >= totalPages) break
}

await writeFile('last-sync.txt', startedAt) // the NEXT run starts from when this one started
Store the time a run started as the next updatedSince, not the time it finished — changes that land while you page are then picked up next time instead of being skipped.

02 · Shipments

Shipment intelligence

Risk, Navlo’s own ETA, D&D, carbon, recommendations and route alerts — the signals the app shows, opt-in per request.

Navlo adds its own analysis on top of carrier data. Ask for it with include on GET /v1/shipments/{id}: a requested key is always present in the response (null or [] when there is nothing), and a request without include is unchanged. These are the same signals the app shows on the shipment page.

risk
Risk level, score and the reason. Nothing known: level: null, stale: true.
recommendations
The action cards the app shows. None: [].
navloEta
Navlo’s predicted arrival per container. None (and always for air): [].
dnd
Free time, demurrage and storage. No data: available: false.
carbon
CO₂e for the shipment and each unit. No figure: co2eKg: null.
alerts
Storms, quakes and security incidents near the route. None: [].
customer
The shipment’s customer, or null.
tags
The shipment’s tags, or [].
details
Terminals, vessel IMO, the next connection, polling times.
all
Every block above.

Request

cURL
curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07?include=all" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK · include=all
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "identifier": "MEDU1234562",
  "mode": "OCEAN",
  "status": "active",
  "carrier": "MSC",
  "containers": [
    {
      "containerNumber": "MEDU1234562",
      "containerType": "40HC",
      "status": "DEPARTED",
      "etd": "2026-09-26T22:00:00Z",
      "atd": "2026-09-27T03:40:00Z",
      "eta": "2026-10-30T06:00:00Z",
      "ata": null,
      "origin": {
        "code": "CNSHA",
        "name": "Shanghai"
      },
      "destination": {
        "code": "TRAMR",
        "name": "Ambarli"
      },
      "currentVessel": "MSC MARTINA"
    }
  ],
  "airShipments": [],
  "events": [
    {
      "timestamp": "2026-09-24T14:12:00Z",
      "type": "ACTUAL",
      "status": "GATE_IN",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": null,
      "voyage": null,
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-26T21:30:00Z",
      "type": "ACTUAL",
      "status": "LOADED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-09-27T03:40:00Z",
      "type": "ACTUAL",
      "status": "DEPARTED",
      "location": "Shanghai",
      "locationCode": "CNSHA",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-23T08:00:00Z",
      "type": "EXPECTED",
      "status": "TRANSSHIPMENT",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC MARTINA",
      "voyage": "438W",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-27T18:00:00Z",
      "type": "EXPECTED",
      "status": "DEPARTED",
      "location": "Piraeus",
      "locationCode": "GRPIR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    },
    {
      "timestamp": "2026-10-30T06:00:00Z",
      "type": "EXPECTED",
      "status": "ARRIVED",
      "location": "Ambarli",
      "locationCode": "TRAMR",
      "vessel": "MSC ARIANE",
      "voyage": "IP243A",
      "flight": null,
      "pieces": null,
      "weight": null
    }
  ],
  "etaHistory": [
    {
      "field": "ETA",
      "previousValue": "2026-10-27T06:00:00Z",
      "newValue": "2026-10-30T06:00:00Z",
      "deltaHours": 72,
      "recordedAt": "2026-10-14T09:22:14Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    },
    {
      "field": "ETA",
      "previousValue": "2026-10-25T06:00:00Z",
      "newValue": "2026-10-27T06:00:00Z",
      "deltaHours": 48,
      "recordedAt": "2026-10-03T11:05:39Z",
      "containerNumber": "MEDU1234562",
      "awbNumber": null
    }
  ],
  "vessel": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z"
  },
  "risk": {
    "level": "MEDIUM",
    "score": 52,
    "summary": "ETA slipped 5 days since departure; the Piraeus transshipment is congested.",
    "computedAt": "2026-10-22T07:15:00Z",
    "stale": false
  },
  "recommendations": [
    {
      "id": "eta:8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
      "severity": "HIGH",
      "title": "ETA at Ambarli slipped 3 days",
      "impact": "Arrival moves from 27 Oct to 30 Oct, and free time at Ambarli now starts on 30 Oct.",
      "recommendation": "Tell Acme Trading Ltd. the new arrival date and move the delivery truck to 31 Oct.",
      "kind": "eta",
      "confidence": "HIGH",
      "computedAt": "2026-10-14T09:30:02Z"
    },
    {
      "id": "congestion:GRPIR",
      "severity": "MEDIUM",
      "title": "Congestion at Piraeus, your transshipment port",
      "impact": "Vessels are waiting about 1.8 days at anchorage, against a 0.6-day baseline.",
      "recommendation": "Expect the MSC ARIANE connection on 27 Oct to slip; check the next feeder sailing.",
      "kind": "congestion",
      "confidence": "MEDIUM",
      "computedAt": "2026-10-22T07:18:41Z"
    }
  ],
  "navloEta": [
    {
      "containerNumber": "MEDU1234562",
      "predictedEta": "2026-10-31T02:00:00Z",
      "confidence": "MEDIUM",
      "computedAt": "2026-10-22T05:42:19Z",
      "carrierEta": "2026-10-30T06:00:00Z"
    }
  ],
  "dnd": {
    "available": true,
    "source": "CARRIER",
    "freeTimeStartAt": "2026-10-30T06:00:00Z",
    "freeTimeEndsAt": "2026-11-06T00:00:00Z",
    "freeTimeStarted": false,
    "freeTimeDaysLeft": null,
    "demurrageDaysSoFar": null,
    "demurrageStoppedAt": null,
    "carrierFreeTimeDays": 7,
    "carrierFreeTimeBasis": "Calendar Days"
  },
  "carbon": {
    "co2eKg": 1856.4,
    "source": "GLEC",
    "units": [
      {
        "containerNumber": "MEDU1234562",
        "awbNumber": null,
        "co2eKg": 1856.4,
        "source": "GLEC"
      }
    ]
  },
  "alerts": [
    {
      "type": "EARTHQUAKE",
      "severity": "MEDIUM",
      "title": "Earthquake near the route",
      "description": "Medium-severity earthquake reported near this shipment's route on 21 Oct 2026.",
      "location": {
        "name": null,
        "code": null,
        "latitude": 34.71,
        "longitude": 24.93
      },
      "startsAt": "2026-10-21T19:42:00Z",
      "endsAt": null
    }
  ],
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "tags": [
    {
      "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
      "name": "Priority",
      "color": "#ef4444"
    },
    {
      "id": "b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77",
      "name": "Q4 launch",
      "color": "#3b82f6"
    }
  ],
  "details": {
    "lastCarrierEventAt": "2026-09-27T03:40:00Z",
    "pollingStoppedAt": null,
    "notificationsMuted": false,
    "relatedIdentifiers": [
      "MEDUSH448021",
      "177SHA2611987"
    ],
    "containers": [
      {
        "containerNumber": "MEDU1234562",
        "originTerminal": "Yangshan Deep Water Port Phase IV",
        "destinationTerminal": "Marport Ambarli",
        "originCountryCode": "CN",
        "destinationCountryCode": "TR",
        "currentLocation": "Shanghai",
        "currentLocationCode": "CNSHA",
        "vesselImo": "9461805",
        "voyage": "438W",
        "aboardVessel": true,
        "nextPlannedVessel": {
          "vesselName": "MSC ARIANE",
          "voyageNumber": "IP243A",
          "plannedAt": "2026-10-27T18:00:00Z",
          "portName": "Piraeus",
          "portCode": "GRPIR"
        },
        "transshipmentPorts": [
          {
            "code": "GRPIR",
            "name": "Piraeus"
          }
        ]
      }
    ],
    "airShipments": []
  }
}

risk

Navlo’s risk assessment for the shipment. It is shown only while it is current, on a shipment that is not completed. Anything else reads level: null and stale: true — Navlo never reports LOW for a risk it doesn’t know.

risk
{
  "risk": {
    "level": "MEDIUM",
    "score": 52,
    "summary": "ETA slipped 5 days since departure; the Piraeus transshipment is congested.",
    "computedAt": "2026-10-22T07:15:00Z",
    "stale": false
  }
}
risk.levelenumnullable

The shipment’s risk while it is fresh; null when stale, never computed, or still discovering.

LOWMEDIUMHIGH
risk.scoreintegernullable

0–100. LOW is 0–29, MEDIUM 30–69, HIGH 70–100. Null when level is null.

risk.summarystringnullable

One sentence on what drives the risk, as the app shows it. Null when level is null.

risk.computedAttimestampnullable

When Navlo last assessed the risk (UTC).

risk.staleboolean

true when there is no current assessment — level is then null.

recommendations

The cards from the app’s recommendation feed for this shipment, most severe first. Completed shipments only keep D&D and idle-container cards.

recommendations
{
  "recommendations": [
    {
      "id": "eta:8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
      "severity": "HIGH",
      "title": "ETA at Ambarli slipped 3 days",
      "impact": "Arrival moves from 27 Oct to 30 Oct, and free time at Ambarli now starts on 30 Oct.",
      "recommendation": "Tell Acme Trading Ltd. the new arrival date and move the delivery truck to 31 Oct.",
      "kind": "eta",
      "confidence": "HIGH",
      "computedAt": "2026-10-14T09:30:02Z"
    },
    {
      "id": "congestion:GRPIR",
      "severity": "MEDIUM",
      "title": "Congestion at Piraeus, your transshipment port",
      "impact": "Vessels are waiting about 1.8 days at anchorage, against a 0.6-day baseline.",
      "recommendation": "Expect the MSC ARIANE connection on 27 Oct to slip; check the next feeder sailing.",
      "kind": "congestion",
      "confidence": "MEDIUM",
      "computedAt": "2026-10-22T07:18:41Z"
    }
  ]
}
recommendations[].idstring

Stable id of the card — the same card keeps its id across refreshes.

recommendations[].severityenum

How urgent. INFO marks purely informational cards.

CRITICALHIGHMEDIUMLOWINFO
recommendations[].titlestring

Headline.

recommendations[].impactstring

What it means for this shipment.

recommendations[].recommendationstring

What to do about it.

recommendations[].kindstring

Category of the signal. Treat unknown values generically.

etacongestiondndidleriskstormquakevolcanoincidentlive_trackingais_detected
recommendations[].confidenceenum

How sure Navlo is.

HIGHMEDIUMLOW
recommendations[].computedAttimestamp

When the card’s text was last produced (UTC).

navloEta

Navlo’s own arrival prediction for each live ocean container; confidence says how far to trust it. Always [] for air shipments.

navloEta
{
  "navloEta": [
    {
      "containerNumber": "MEDU1234562",
      "predictedEta": "2026-10-31T02:00:00Z",
      "confidence": "MEDIUM",
      "computedAt": "2026-10-22T05:42:19Z",
      "carrierEta": "2026-10-30T06:00:00Z"
    }
  ]
}
navloEta[].containerNumberstring

The container — one entry per live container.

navloEta[].predictedEtatimestampnullable

Navlo’s predicted arrival at the port of discharge; null when Navlo has no trustworthy prediction (then confidence and computedAt are null too).

navloEta[].confidenceenumnullable

How far to trust predictedEta.

HIGHMEDIUMLOW
navloEta[].computedAttimestampnullable

When the prediction last changed (UTC).

navloEta[].carrierEtatimestampnullable

The carrier’s ETA at the same moment, for comparison.

dnd

Free time and demurrage (ocean) or storage (air) at destination. The deadline comes from the first available source: free time your team set, the carrier’s published free time, then your accepted tariff.

dnd
{
  "dnd": {
    "available": true,
    "source": "CARRIER",
    "freeTimeStartAt": "2026-10-30T06:00:00Z",
    "freeTimeEndsAt": "2026-11-06T00:00:00Z",
    "freeTimeStarted": false,
    "freeTimeDaysLeft": null,
    "demurrageDaysSoFar": null,
    "demurrageStoppedAt": null,
    "carrierFreeTimeDays": 7,
    "carrierFreeTimeBasis": "Calendar Days"
  }
}
dnd.availableboolean

true when there is a free-time window or a carrier allowance; false otherwise, and every other field is then null.

dnd.sourceenumnullable

Where the free time comes from: CARRIER (the carrier’s own free time), MANUAL (set by your team), SYSTEM (your accepted tariff).

CARRIERMANUALSYSTEM
dnd.freeTimeStartAttimestampnullable

When the free-time clock starts — the discharge (or ETA while still sailing) for ocean, cargo availability for air.

dnd.freeTimeEndsAttimestampnullable

When free time ends; demurrage or storage charges start after it. Falls back to the carrier’s published expiry when no window could be anchored.

dnd.freeTimeStartedboolean

true once the cargo has actually arrived and the clock runs.

dnd.freeTimeDaysLeftintegernullable

Calendar days of free time left while the clock runs (started, not yet ended); null before it starts and after it ends.

dnd.demurrageDaysSoFarintegernullable

Days past the end of free time — day 1 is the first chargeable day. Null while still free.

dnd.demurrageStoppedAttimestampnullable

When charges stopped accruing (empty container returned, or shipment completed).

dnd.carrierFreeTimeDaysintegernullable

Free days the carrier grants, when it publishes them.

dnd.carrierFreeTimeBasisstringnullable

The carrier’s own wording for how days count, e.g. Calendar Days, Working Days.

carbon

CO₂e for the shipment and each unit: Navlo’s GLEC Framework estimate, or the carrier’s own published figure (source says which).

carbon
{
  "carbon": {
    "co2eKg": 1856.4,
    "source": "GLEC",
    "units": [
      {
        "containerNumber": "MEDU1234562",
        "awbNumber": null,
        "co2eKg": 1856.4,
        "source": "GLEC"
      }
    ]
  }
}
carbon.co2eKgnumbernullable

The shipment’s CO₂e in kilograms — the sum of the units that have a figure; null when none has.

carbon.sourceenumnullable

GLEC — Navlo’s GLEC Framework estimate. CARRIER — the carrier’s own published figure. Null when units disagree.

GLECCARRIER
carbon.unitsarray<object>

One per live container (ocean) or waybill (air), with or without a figure.

carbon.units[].containerNumberstringnullable

OCEAN: the container; null on air units.

carbon.units[].awbNumberstringnullable

AIR: the waybill; null on ocean units.

carbon.units[].co2eKgnumbernullable

That unit’s CO₂e in kg, or null when it can’t be computed yet.

carbon.units[].sourceenumnullable

As above, per unit.

GLECCARRIER

alerts

Natural hazards and maritime security incidents within 500 km of the shipment’s route — what the shipment map shows. At most 20, recent ones only. With none available right now you get [], never an error.

alerts
{
  "alerts": [
    {
      "type": "EARTHQUAKE",
      "severity": "MEDIUM",
      "title": "Earthquake near the route",
      "description": "Medium-severity earthquake reported near this shipment's route on 21 Oct 2026.",
      "location": {
        "name": null,
        "code": null,
        "latitude": 34.71,
        "longitude": 24.93
      },
      "startsAt": "2026-10-21T19:42:00Z",
      "endsAt": null
    }
  ]
}
alerts[].typeenum

Hazard category. SECURITY covers piracy, attacks and other maritime security incidents. Treat unknown values as OTHER.

TROPICAL_CYCLONEEARTHQUAKEFLOODTSUNAMIVOLCANODROUGHTWILDFIRESECURITYOTHER
alerts[].severityenum

Alert level. Low-level alerts are not returned.

MEDIUMHIGHCRITICAL
alerts[].titlestring

A short headline from the type, e.g. "Earthquake near the route".

alerts[].descriptionstringnullable

One sentence with the severity and the date.

alerts[].locationobjectnullable

Where it is: latitude and longitude (name and code are null for these point alerts).

alerts[].startsAttimestampnullable

When the alert was published (UTC).

alerts[].endsAttimestampnullable

When it ends; null when unknown.

customer and tags

customer, tags
{
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "tags": [
    {
      "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
      "name": "Priority",
      "color": "#ef4444"
    },
    {
      "id": "b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77",
      "name": "Q4 launch",
      "color": "#3b82f6"
    }
  ]
}
customerobjectnullable

The shipment’s customer, or null.

customer.iduuid

Navlo’s customer id.

customer.refstringnullable

Your reference for the customer, when it has one.

customer.namestring

The customer’s name, as shown on the Companies page.

customer.countryCodestringnullable

ISO 3166-1 alpha-2 country code, e.g. TR.

tagsarray<object>

The shipment’s tags.

tags[].iduuid

Tag id.

tags[].namestring

Tag name.

tags[].colorstringnullable

Hex colour, e.g. #ef4444.

details

Operational detail the app shows on the shipment page: terminals, the vessel’s IMO, the next connection, and Navlo’s polling times.

details
{
  "details": {
    "lastCarrierEventAt": "2026-09-27T03:40:00Z",
    "pollingStoppedAt": null,
    "notificationsMuted": false,
    "relatedIdentifiers": [
      "MEDUSH448021",
      "177SHA2611987"
    ],
    "containers": [
      {
        "containerNumber": "MEDU1234562",
        "originTerminal": "Yangshan Deep Water Port Phase IV",
        "destinationTerminal": "Marport Ambarli",
        "originCountryCode": "CN",
        "destinationCountryCode": "TR",
        "currentLocation": "Shanghai",
        "currentLocationCode": "CNSHA",
        "vesselImo": "9461805",
        "voyage": "438W",
        "aboardVessel": true,
        "nextPlannedVessel": {
          "vesselName": "MSC ARIANE",
          "voyageNumber": "IP243A",
          "plannedAt": "2026-10-27T18:00:00Z",
          "portName": "Piraeus",
          "portCode": "GRPIR"
        },
        "transshipmentPorts": [
          {
            "code": "GRPIR",
            "name": "Piraeus"
          }
        ]
      }
    ],
    "airShipments": []
  }
}
details.lastCarrierEventAttimestampnullable

The newest event the carrier reported — use it to spot carriers that went quiet.

details.pollingStoppedAttimestampnullable

Set while tracking is paused (stop).

details.notificationsMutedboolean

Whether the shipment’s emails and in-app notifications are muted. Webhooks fire regardless.

details.relatedIdentifiersarray<string>

Other numbers Navlo linked to the shipment — its B/L, booking, sibling containers.

details.containersarray<object>

OCEAN: per-container detail beyond the base response.

details.containers[].originTerminalstringnullable

Terminal at the port of loading.

details.containers[].destinationTerminalstringnullable

Terminal at the port of discharge.

details.containers[].originCountryCodestringnullable

ISO alpha-2 country of the port of loading.

details.containers[].destinationCountryCodestringnullable

ISO alpha-2 country of the port of discharge.

details.containers[].currentLocationstringnullable

Where the container was last reported.

details.containers[].currentLocationCodestringnullable

UN/LOCODE of that place.

details.containers[].vesselImostringnullable

IMO number of the current vessel.

details.containers[].voyagestringnullable

Current voyage number.

details.containers[].aboardVesselboolean

true when the container is verifiably on the vessel now (loaded and not yet discharged).

details.containers[].nextPlannedVesselobjectnullable

The next connection, when known: { vesselName, voyageNumber, plannedAt, portName, portCode }.

details.containers[].transshipmentPortsarray<object>

Transshipment ports in order, [{ code, name }].

details.airShipmentsarray<object>

AIR: [{ awbNumber }].

On the shipment list

GET /v1/shipments takes a lighter include: customer, tags, risk (level, computedAt and stale only) and lastChangedAt, so a list screen needs one request.

shipments[].customerobjectnullable

With include=customer: the shipment’s customer (id, ref, name, countryCode), or null.

shipments[].tagsarray<object>

With include=tags: the shipment’s tags, [{ id, name, color }].

shipments[].riskobject

With include=risk: { level, computedAt, stale } — the same freshness rule as the detail’s risk.

shipments[].lastChangedAttimestampnullable

With include=lastChangedAt: when the shipment’s data last changed — the value updatedSince and sort=updatedAt use. If no change is recorded yet, it falls back to the shipment’s last update time.

02 · Shipments

Shipment actions

Notes, documents, share links, email subscribers, mute, complete and change carrier — everything the shipment page lets your team do.

Every action here is what the shipment page in the app does, with the same rules. All routes take the shipment id and answer 404 Shipment not found for ids outside your organization. Tags have their own page.

Notes

Team notes on a shipment, newest first. Notes written through the API are authored by the key’s creator, and — as in the app — only the author can edit or delete a note. Mention a teammate with @[<user id>|Name] to notify them.

List notes

New · 2026-10-22
GET/v1/shipments/{id}/notes

The shipment’s notes, newest first.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Query parameters

pageintegerdefault 0

Zero-based page index.

sizeintegerdefault 20

Page size, 1–100.

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "notes": [
    {
      "id": "e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28",
      "content": "Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.",
      "authorName": "Elif Yılmaz",
      "createdAt": "2026-10-22T08:31:07Z",
      "updatedAt": "2026-10-22T08:31:07Z"
    }
  ]
}

Response fields

pageinteger

Page index.

sizeinteger

Page size.

totalElementsinteger

Notes on the shipment.

totalPagesinteger

Pages at this size.

notesarray<object>

The notes; fields as on create.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Add a note

New · 2026-10-22
POST/v1/shipments/{id}/notes
Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Path parameters

iduuidrequired

The shipment id.

Body

contentstringrequired

The note, up to 10,000 characters.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct."
  }'

Response

201 Created
{
  "id": "e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28",
  "content": "Customs broker confirmed the import declaration for Ambarli. Truck booked for 31 Oct.",
  "authorName": "Elif Yılmaz",
  "createdAt": "2026-10-22T08:31:07Z",
  "updatedAt": "2026-10-22T08:31:07Z"
}

Response fields

iduuid

Note id.

contentstring

The note text.

authorNamestring

Who wrote it — for API notes, the key’s creator.

createdAttimestamp

When it was written (UTC).

updatedAttimestamp

When it was last edited — equal to createdAt until then.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
400content is requiredcontent missing or blank.
400content must be at most 10000 charactersOver 10,000 characters.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Edit a note

New · 2026-10-22
PUT/v1/shipments/{id}/notes/{noteId}
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

noteIduuidrequired

The note id.

Body

contentstringrequired

The new text, up to 10,000 characters.

Request

curl -X PUT "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customs cleared. Truck booked for 31 Oct, 09:00."
  }'

Response

200 OK
{
  "id": "e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28",
  "content": "Customs cleared. Truck booked for 31 Oct, 09:00.",
  "authorName": "Elif Yılmaz",
  "createdAt": "2026-10-22T08:31:07Z",
  "updatedAt": "2026-10-22T10:02:44Z"
}

Response fields

iduuid

Note id.

contentstring

The note text.

authorNamestring

Who wrote it — for API notes, the key’s creator.

createdAttimestamp

When it was written (UTC).

updatedAttimestamp

When it was last edited — equal to createdAt until then.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Note not foundUnknown note id on this shipment.
403You can only edit your own notesThe note was written by someone else.
400content must be at most 10000 charactersOver 10,000 characters.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Delete a note

New · 2026-10-22
DELETE/v1/shipments/{id}/notes/{noteId}
Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The shipment id.

noteIduuidrequired

The note id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/notes/e2c7a9f1-4b3d-4e8c-a1f6-9d0b5c7e3a28" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Note not foundUnknown note id on this shipment.
403You can only delete your own notesThe note was written by someone else.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Documents

Files on a shipment — bills of lading, invoices, packing lists. Up to 10 MB per file; allowed types: pdf, png, jpg, jpeg, csv, xlsx, xls, doc, docx, tiff, bmp. Anyone in your organization can delete a document.

List documents

New · 2026-10-22
GET/v1/shipments/{id}/documents
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "id": "d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62",
    "fileName": "MEDUSH448021-bill-of-lading.pdf",
    "documentType": "BILL_OF_LADING",
    "contentType": "application/pdf",
    "sizeBytes": 284913,
    "uploadedBy": "Elif Yılmaz",
    "createdAt": "2026-10-22T08:34:52Z"
  }
]

Response fields

An array of documents, newest first.

[].iduuid

Document id.

[].fileNamestring

The original file name.

[].documentTypestring

The document’s type, e.g. BILL_OF_LADING.

[].contentTypestring

Set by Navlo from the file extension (application/pdf, image/png, … — application/octet-stream for doc, docx, tiff and bmp).

[].sizeBytesinteger

File size in bytes.

[].uploadedBystring

Who uploaded it.

[].createdAttimestamp

Upload time (UTC).

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Upload a document

New · 2026-10-22
POST/v1/shipments/{id}/documents

Send the file as multipart/form-data.

Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Path parameters

iduuidrequired

The shipment id.

Body · multipart/form-data

filefilerequired

The file, up to 10 MB. The type is taken from its extension.

documentTypeenumdefault OTHER

What the file is (case-insensitive) — the types the app offers.

BILL_OF_LADINGINVOICEPACKING_LISTCUSTOMS_DECLARATIONOTHER

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -F "file=@MEDUSH448021-bill-of-lading.pdf;type=application/pdf" \
  -F "documentType=BILL_OF_LADING"

Response

201 Created
{
  "id": "d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62",
  "fileName": "MEDUSH448021-bill-of-lading.pdf",
  "documentType": "BILL_OF_LADING",
  "contentType": "application/pdf",
  "sizeBytes": 284913,
  "uploadedBy": "Elif Yılmaz",
  "createdAt": "2026-10-22T08:34:52Z"
}

Response fields

iduuid

Document id.

fileNamestring

The original file name.

documentTypestring

The document’s type, e.g. BILL_OF_LADING.

contentTypestring

Set by Navlo from the file extension (application/pdf, image/png, … — application/octet-stream for doc, docx, tiff and bmp).

sizeBytesinteger

File size in bytes.

uploadedBystring

Who uploaded it.

createdAttimestamp

Upload time (UTC).

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
400file is requiredNo file part.
400File is emptyA zero-byte file.
400documentType must be one of BILL_OF_LADING, INVOICE, PACKING_LIST, CUSTOMS_DECLARATION, OTHERAnother documentType.
413The file is too large. The maximum upload size is 10 MB.Larger than 10 MB (general error shape, error: "File too large").
400File type .gif is not allowed for documents. Allowed: .pdf, .png, .jpg, .jpeg, .csv, .xlsx, .xls, .doc, .docx, .tiff, .bmpAn extension outside the list.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Get a download link

New · 2026-10-22
GET/v1/shipments/{id}/documents/{documentId}/download

Returns a short-lived link to the file. Fetch it with a plain GET — no API key — within 15 minutes. The link redirects to the file, so let your client follow redirects (curl -L).

An expired link, or one whose document was deleted, answers 404 — ask for a new one.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

documentIduuidrequired

The document id.

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62/download" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "url": "https://api.navlo.io/api/documents/d/AbC123.xYz789",
  "expiresAt": "2026-10-22T09:15:00Z"
}

Response fields

urlstring

Download link on api.navlo.io. Anyone with it can download the file, so keep it private until it expires.

expiresAttimestamp

When the link stops working (UTC), 15 minutes after the request.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Document not foundUnknown document id on this shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Delete a document

New · 2026-10-22
DELETE/v1/shipments/{id}/documents/{documentId}
Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The shipment id.

documentIduuidrequired

The document id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/documents/d4b8e1c3-6a2f-4d97-8c5e-1f0a3b7d9e62" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Document not foundUnknown document id on this shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

A public, read-only page for one shipment — milestones, vessel, ports and dates, with none of your internal data (no tags, customer, notes, risk). Anyone with the link can open it without a Navlo account.

Email subscribers

People outside Navlo — your customer’s team, a broker — who get an email with the share link now and on every status change from then on. Each email has a Stop these emails link; people who use it disappear from the list. Muted shipments send them nothing.

List subscribers

New · 2026-10-22
GET/v1/shipments/{id}/subscribers
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "id": "f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94",
    "email": "import.ops@acme-trading.example",
    "events": [
      "DESTINATION",
      "COMPLETED"
    ],
    "createdAt": "2026-10-22T08:40:16Z"
  }
]

Response fields

An array of live subscribers, oldest first.

[].iduuid

Subscriber id.

[].emailstring

Their address, lower-cased.

[].eventsarray<enum>

The status categories they get emails for; [] means every status change.

PRE_SHIPMENTORIGINTRANSITDESTINATIONCOMPLETED
[].createdAttimestamp

When they were subscribed (UTC).

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
POST/v1/shipments/{id}/subscribers

Sends each address an email with the share link (creating the link if needed) and subscribes them to status-change emails. Subscribing someone again updates their events.

Your organization can email at most 500 recipients per 24 hours, app and API together. A request that would go over answers 429 and emails nobody.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Body

emailsarray<string>required

1–10 addresses, all valid; stored lower-cased.

eventsarray<enum>

Only email them for these status categories. Omit or send [] for every status change.

PRE_SHIPMENTORIGINTRANSITDESTINATIONCOMPLETED
notestring

A personal message in the first email, up to 2,000 characters.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "import.ops@acme-trading.example",
      "broker@ambarli-customs.example"
    ],
    "events": [
      "DESTINATION",
      "COMPLETED"
    ],
    "note": "Live tracking for your MSC container to Ambarli."
  }'

Response

200 OK
{
  "sent": 2,
  "failed": []
}

Response fields

sentinteger

Emails sent.

failedarray<string>

Addresses the email could not be sent to.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
400emails is requiredemails missing or empty.
400At most 10 emails per requestMore than 10 addresses.
400Invalid email address: import.ops@An address that isn’t valid — nothing is sent.
400Unknown event SHIPPED. Allowed: PRE_SHIPMENT, ORIGIN, TRANSIT, DESTINATION, COMPLETEDAn events value outside the list.
400note must be at most 2000 charactersA longer note.
429Daily email limit: your organization can email 4 more recipient(s) in the next 24 hours.The addresses would take your organization past 500 recipients in 24 hours — nothing is sent. With none left: Daily email limit reached: ….
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Remove a subscriber

New · 2026-10-22
DELETE/v1/shipments/{id}/subscribers/{subscriberId}

Stops their emails. Idempotent.

Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The shipment id.

subscriberIduuidrequired

The subscriber id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/subscribers/f1a6c3e8-9d2b-4f47-b0e5-7c3a1d8f6b94" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Subscriber not foundUnknown subscriber id on this shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Mute notifications

Muting silences everything about the shipment for people: your team’s emails, push and in-app notifications, digest rows and subscriber emails. Webhooks keep firing — your systems still hear every change.

Mute a shipment

New · 2026-10-22
PUT/v1/shipments/{id}/mute

Idempotent. Allowed for organization admins and the person who added the shipment.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl -X PUT "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "notificationsMuted": true
}

Response fields

iduuid

The shipment id.

notificationsMutedboolean

true after muting, false after unmuting.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
403Only an organization admin or the person who added this shipment can mute or unmute its notificationsThe key’s creator is neither.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Unmute a shipment

New · 2026-10-22
DELETE/v1/shipments/{id}/mute

Idempotent. Same permission as muting.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/mute" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "notificationsMuted": false
}

Response fields

iduuid

The shipment id.

notificationsMutedboolean

Always false.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Mark as completed

Mark a shipment completed

New · 2026-10-22
POST/v1/shipments/{id}/complete

For a shipment you know is done when the carrier never says so. Polling stops, the shipment leaves active lists, and it stays in reports and history. Idempotent; there is no un-complete.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/complete" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "status": "completed"
}

Response fields

iduuid

The shipment id.

statusenum

Always completed.

completed

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Notes

  • No completion email and no shipment.completed webhook are sent — your system made the change, so it already knows.

Change carrier

Change the carrier

New · 2026-10-22
POST/v1/shipments/{id}/carrier

When Navlo tracks a shipment with the wrong carrier, switch it. Carrier data — containers, events, ETA history, risk, carbon — is cleared and discovery starts again with the new carrier; notes, tags, documents, free-time overrides and the customer stay. Allowed once per shipment.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Body

carrierstringrequired

The carrier code, e.g. MAERSK, HAPAG, EMIRATES — or its name as you write it, resolved like carrier on create.

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/carrier" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "MAERSK"
  }'

Response

200 OK
{
  "id": "8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07",
  "carrier": "MAERSK",
  "status": "discovering"
}

Response fields

iduuid

The shipment id.

carrierstring

The new carrier code.

statusenum

Navlo is fetching data from the new carrier: discovering for ocean, tracking for air.

discoveringtracking

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
409Carrier was already changed once on this shipment; no further changes allowed.The one change was already used.
400carrier is requiredcarrier missing or blank.
400Unknown carrier Oceanic Star Lines for OCEAN shipmentsNavlo can’t resolve the carrier — your one change is not used up.
400Carrier MAERSK does not support AIR trackingThe carrier doesn’t track this mode.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

02 · Shipments

Tags

Your organization’s labels for shipments — list, create and delete them, and put them on shipments.

Tags are shared across your organization and show on the Shipments page. Filter the shipment list by them with tag=, and read them per shipment with include=tags. Tag names are unique in your organization, ignoring case.

List tags

New · 2026-10-22
GET/v1/tags
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Request

curl "https://api.navlo.io/v1/tags" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
    "name": "Priority",
    "color": "#ef4444"
  },
  {
    "id": "b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77",
    "name": "Q4 launch",
    "color": "#3b82f6"
  }
]

Response fields

An array of your organization’s tags, sorted by name.

[].iduuid

Tag id.

[].namestring

Tag name, unique in your organization (case-insensitive).

[].colorstringnullable

Hex colour #rrggbb, or null.

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Create a tag

New · 2026-10-22
POST/v1/tags
Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

namestringrequired

1–50 characters (trimmed), unique in your organization ignoring case.

colorstringdefault #3b82f6

Hex colour, #rgb or #rrggbb. The app’s palette: #3b82f6, #10b981, #f59e0b, #ef4444, #8b5cf6, #ec4899, #6b7280, #06b6d4.

Request

curl -X POST "https://api.navlo.io/v1/tags" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priority",
    "color": "#ef4444"
  }'

Response

201 Created
{
  "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
  "name": "Priority",
  "color": "#ef4444"
}

Response fields

iduuid

Tag id.

namestring

Tag name, unique in your organization (case-insensitive).

colorstringnullable

Hex colour #rrggbb, or null.

Errors

StatusMessageWhen
409A tag with name 'Priority' already existsThe name is taken (ignoring case).
400name must be at most 50 charactersOver 50 characters.
400name is requiredname missing or blank.
400color must be a hex colour like #3b82f6A color that isn’t #rgb / #rrggbb.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Delete a tag

New · 2026-10-22
DELETE/v1/tags/{tagId}

Removes the tag from every shipment, then deletes it. Organization admins only.

Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

tagIduuidrequired

The tag id.

Request

curl -X DELETE "https://api.navlo.io/v1/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Tag not foundUnknown tag id, or another organization’s.
403Only organization admins can delete tagsThe key’s creator is not an admin.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Tag a shipment

New · 2026-10-22
POST/v1/shipments/{id}/tags

Adds a tag by id, or by name — a name is matched ignoring case and the tag is created (in #3b82f6) if it doesn’t exist yet. tagId wins when both are sent. Adding a tag the shipment already has changes nothing. Returns the shipment’s tags, sorted by name.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

Body

tagIduuid

An existing tag. Send tagId or name.

namestring

A tag name; created when new (up to 50 characters).

Request

curl -X POST "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 launch"
  }'

Response

200 OK
[
  {
    "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
    "name": "Priority",
    "color": "#ef4444"
  },
  {
    "id": "b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77",
    "name": "Q4 launch",
    "color": "#3b82f6"
  }
]

Response fields

The shipment’s tags after the change.

[].iduuid

Tag id.

[].namestring

Tag name, unique in your organization (case-insensitive).

[].colorstringnullable

Hex colour #rrggbb, or null.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
404Tag not foundUnknown tag id, or another organization’s.
400tagId or name is requiredNeither was sent.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Untag a shipment

New · 2026-10-22
DELETE/v1/shipments/{id}/tags/{tagId}

Removes the tag from this shipment only. Idempotent. Returns the shipment’s remaining tags.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The shipment id.

tagIduuidrequired

The tag id.

Request

curl -X DELETE "https://api.navlo.io/v1/shipments/8f41c2e5-5b0a-4a4e-9d3b-2f6a8e9c1d07/tags/b81e4d7a-2c9f-4a63-8d05-6e3b1f9c2a77" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "id": "a3f9c2d1-7b4e-4c8a-9e16-2d5f8b0c7e41",
    "name": "Priority",
    "color": "#ef4444"
  }
]

Response fields

[].iduuid

Tag id.

[].namestring

Tag name, unique in your organization (case-insensitive).

[].colorstringnullable

Hex colour #rrggbb, or null.

Errors

StatusMessageWhen
404Shipment not foundUnknown id, deleted, or another organization’s shipment.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

02 · Shipments

Reports & export

Download your shipments as CSV or Excel, and generate the same status, cost and D&D reports Navlo AI writes.

Export shipments

New · 2026-10-22
GET/v1/shipments/export

The Shipments page export: one row per container (ocean) or waybill (air), as CSV or XLSX, with the list filters applied. The file comes back directly as an attachment. Dates are yyyy-MM-dd HH:mm in UTC; CSV is UTF-8 with a byte-order mark so Excel opens accented names correctly.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK · text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Query parameters

formatenumdefault csv

File format.

csvxlsx
columnscsv

Column keys to include (see the table below); default all. trackingIdentifier is always included and columns keep the table’s order whatever order you send.

statuscsv

As on the shipment list: active also matches tracking.

discoveringresolvingactivetrackingcompletedstopped
modeenum

Only ocean or only air.

OCEANAIR
carrierstring

Carrier code.

customerIduuid | none

Only this customer’s shipments — or none for shipments without a customer.

tagcsv

Tag names (case-insensitive); shipments carrying any of them. Names that match no tag are ignored — if none match, the file is empty.

etaFromtimestamp | date

ETA on or after.

etaTotimestamp | date

ETA on or before; a date means the end of that day.

createdFromtimestamp | date

Started on or after (UTC).

createdTotimestamp | date

Started on or before (UTC); a date means the end of that day.

Request

curl "https://api.navlo.io/v1/shipments/export?format=xlsx&status=active&customerId=c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -o navlo-trackings.xlsx

Response

200 · format=csv&columns=mode,status,carrier,podCode,eta,customer
Tracking Identifier,Mode,Status,Carrier,PoD Code,ETA,Customer
MEDU1234562,OCEAN,In Transit,MSC,TRAMR,2026-10-30 06:00,Acme Trading Ltd.
TGHU8126501,OCEAN,In Transit,Hapag-Lloyd,TRMER,2026-11-04 18:00,Acme Trading Ltd.

The file, with Content-Disposition: attachment; filename="navlo-trackings-2026-10-22.xlsx" (date in UTC).

Errors

StatusMessageWhen
400format must be one of csv, xlsxAnother format.
400Unknown report column: vessel.A columns key outside the table.
400customerId must be a customer id or noneA malformed customerId.
400Unknown status shipped. Allowed: discovering, resolving, active, tracking, completed, stoppedA status outside the list.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Export columns

Column keyHeader in the file
trackingIdentifierTracking Identifier
identifierTypeIdentifier Type
modeMode
statusStatus
carrierCarrier
vesselFlightVessel/Flight
polCodePoL Code
polNamePoL Name
polCountryPoL Country
podCodePoD Code
podNamePoD Name
podCountryPoD Country
transshipmentCountTransshipment Count
containerAwbNumberContainer/AWB Number
etdETD
atdATD
etaETA
ataATA
trackedByTracked By
createdAtCreated At
lastUpdatedLast Updated
customerCustomer
relatedContainersRelated Containers
tagsTags
riskRisk
riskNoteRisk Note

Generate a report

New · 2026-10-22
POST/v1/reports

Builds the same Excel report Navlo AI produces when you ask it for a status, cost or D&D risk report — directly, with no AI credits spent. Returns a download link valid for 7 days.

Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

typeenumrequired

STATUS — one row per shipment (up to 500). COST — the cost analysis figures for a period. DND_RISK — free time, days remaining and D&D exposure per shipment (up to 200).

STATUSCOSTDND_RISK
filtersobject

Narrow the report. Any other key is rejected rather than ignored, so a report never looks filtered when it isn’t.

filters.modeenum

OCEAN or AIR. COST with AIR analyses air storage charges.

OCEANAIR
filters.statusarray<enum>

STATUS and DND_RISK only. A string or an array of public statuses; active also matches tracking.

discoveringresolvingactivetrackingcompletedstopped
filters.customerIduuid | none

STATUS and DND_RISK only: one customer’s shipments, or none for shipments without a customer. Not together with customerRef.

filters.customerRefstring

STATUS and DND_RISK only: the customer with your own reference, e.g. C-1042.

filters.tagstring | array<string>

STATUS and DND_RISK only: tag names — a string (comma-separated allowed) or an array; shipments carrying any of them. Every name must match one of your tags.

filters.carrierstring

Carrier code or name.

filters.originPortstring

Port of loading, UN/LOCODE (airport code for air). Not for COST — use originCountry.

filters.destinationPortstring

Port of discharge, UN/LOCODE (airport code for air). COST also takes a port name.

filters.originCountrystring

ISO alpha-2 country of loading.

filters.destinationCountrystring

ISO alpha-2 country of discharge.

filters.etaFromdate

ETA on or after this UTC day (an ISO timestamp is reduced to its day).

filters.etaTodate

ETA on or before this UTC day.

filters.shipmentsarray<string>

STATUS and DND_RISK only: exactly these identifiers (up to 100) — on its own, with no other filter (customerId, customerRef and tag included).

filters.fromdate

COST only: first day of the period (default 30 days before to).

filters.todate

COST only: last day of the period (default today).

Request

curl -X POST "https://api.navlo.io/v1/reports" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STATUS",
    "filters": {
      "status": [
        "active"
      ],
      "customerRef": "C-1042"
    }
  }'

Response

201 Created
{
  "type": "STATUS",
  "fileName": "shipment-status-report-20261022.xlsx",
  "url": "https://api.navlo.io/api/ai/d/AbC123.xYz789",
  "expiresAt": "2026-10-29T09:20:13Z"
}

Response fields

typeenum

The report type.

STATUSCOSTDND_RISK
fileNamestring

e.g. shipment-status-report-20261022.xlsx, cost-report-…, dnd-risk-report-….

urlstring

Download link (https://api.navlo.io/api/ai/d/…). Open it with a plain GET, no key: it redirects to the file. Keep it private until it expires.

expiresAttimestamp

When the link stops working (UTC), 7 days after generation.

Errors

StatusMessageWhen
400type must be one of STATUS, COST, DND_RISKA type outside the list.
400Unsupported report filter createdFrom. Supported: …A filter key the report can’t apply — the message lists the supported keys.
400from and to only apply to COST reportsA period on STATUS or DND_RISK.
400status does not apply to COST reportsstatus on COST.
400originPort does not apply to COST reports; use originCountryoriginPort on COST.
400shipments cannot be combined with other filters on STATUS and DND_RISK reportsshipments plus another filter.
400Unknown customerRef C-9999No customer has that reference.
400Unknown tag VIPA tag name that matches none of your tags — refused rather than ignored, so the report is never wider than asked.
400Send customerId or customerRef, not bothBoth were sent.
400customerId, customerRef and tag do not apply to COST reportsOne of them on COST.
400At most 100 shipments per reportMore than 100 identifiers.
500The report could not be generated. Please try again.Generation failed — retry.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

What each report contains

STATUS
Sheet “Shipments”, one row per shipment (up to 500): Identifier, Type, Mode, Status, Carrier, Vessel/Flight, Origin Port, Origin Country, Destination Port, Destination Country, ETA (UTC), Transshipments, Tracked By.
COST
Sheet “Cost Analysis”: Metric and Value rows — the period’s cost figures by carrier, route and port.
DND_RISK
Sheet “D&D Risk”, one row per shipment (up to 200): Container/BL, Carrier, Origin, Destination, Status, ETA, Free time (days), Days remaining, Notes.
Prefer data to files? Every figure in these reports is also available as JSON: shipments from GET /v1/shipments, D&D per shipment with include=dnd. Shipment MEDU1234562 shows up in all three.
  • Report links work without an API key — anyone holding the link can download the file until it expires.
  • Reports run on your data at the moment you call; generate a new one for fresh figures.
  • STATUS and DND_RISK reports take customerId or customerRef, and tag — a per-customer report is one call. COST takes none of the three; for per-customer figures use the usage report.

03 · Customers & billing

Customers

The companies you work for — called Companies in the app — with your own reference on each, so usage maps onto your billing.

Customers are the companies on the app’s Companies page. Give each one your own reference (ref) — the code your ERP or accounting system uses — and you can put shipments, vessel follows and Navlo AI questions on customers by that code, then pull per-customer usage for re-billing.

References

  • ref is optional, up to 100 characters, unique in your organization, matched ignoring case and surrounding spaces.
  • Sending customer: { "ref": "C-1042", "name": "Acme Trading Ltd." } on a shipment creates the customer when the ref is new, so you don’t have to create customers up front.
  • In the app the reference shows as Your reference on the Companies page and can be edited there, or added through the bulk import.

List customers

New · 2026-10-22
GET/v1/customers
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Query parameters

searchstring

Matches the name or the reference.

refstring

Exact reference (ignoring case) — returns at most one customer.

includeArchivedbooleandefault false

Include archived customers.

pageintegerdefault 0

Zero-based page index.

sizeintegerdefault 20

Page size, 1–100 (values outside are clamped).

Request

curl "https://api.navlo.io/v1/customers?search=foods" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "customers": [
    {
      "id": "5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13",
      "ref": "C-2107",
      "name": "Sample Foods Ltd.",
      "taxId": null,
      "address": null,
      "city": "Bursa",
      "countryCode": "TR",
      "archived": false,
      "contacts": [],
      "shipmentCount": 19,
      "createdAt": "2026-10-18T11:02:51Z",
      "updatedAt": "2026-10-18T11:02:51Z"
    }
  ]
}

Response fields

pageinteger

Page index.

sizeinteger

Page size.

totalElementsinteger

Matching customers.

totalPagesinteger

Pages at this size.

customersarray<object>

The customers, fields as on retrieve.

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Create a customer

New · 2026-10-22
POST/v1/customers
Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

namestringrequired

Company name, up to 200 characters, unique in your organization.

refstring

Your reference, up to 100 characters, unique.

taxIdstring

Tax / VAT number, up to 100 characters.

addressstring

Street address.

citystring

City, up to 100 characters.

countryCodestring

ISO 3166-1 alpha-2 (TR, DE); stored upper-case.

contactsarray<object>

People at the customer.

contacts[].namestringrequired

Full name, up to 200 characters.

contacts[].emailstring

Email (stored lower-cased), up to 320 characters.

contacts[].phonestring

Phone, up to 50 characters, any format.

contacts[].rolestring

Free text, up to 100 characters, e.g. "Import manager".

contacts[].primarybooleandefault false

The main contact. At most one; if several are flagged, the first wins.

Request

curl -X POST "https://api.navlo.io/v1/customers" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Trading Ltd.",
    "ref": "C-1042",
    "taxId": "1234567890",
    "city": "İzmir",
    "countryCode": "TR",
    "contacts": [
      {
        "name": "Deniz Kaya",
        "email": "deniz.kaya@acme-trading.example",
        "role": "Import manager",
        "primary": true
      }
    ]
  }'

Response

201 Created
{
  "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
  "ref": "C-1042",
  "name": "Acme Trading Ltd.",
  "taxId": "1234567890",
  "address": "Liman Cad. No: 12, 35210",
  "city": "İzmir",
  "countryCode": "TR",
  "archived": false,
  "contacts": [
    {
      "name": "Deniz Kaya",
      "email": "deniz.kaya@acme-trading.example",
      "phone": "+90 232 000 00 00",
      "role": "Import manager",
      "primary": true
    }
  ],
  "shipmentCount": 0,
  "createdAt": "2026-06-11T08:02:19Z",
  "updatedAt": "2026-06-11T08:02:19Z"
}

Response fields

iduuid

Navlo’s customer id.

refstringnullable

Your reference — the code your own systems use.

namestring

Company name.

taxIdstringnullable

Tax / VAT number.

addressstringnullable

Street address.

citystringnullable

City.

countryCodestringnullable

ISO 3166-1 alpha-2, e.g. TR.

archivedboolean

Archived customers are hidden from lists unless asked for and can’t be put on new shipments.

contactsarray<object>

People at the customer — name, email, phone, role, primary — the primary contact first, then by name.

shipmentCountinteger

Shipments currently assigned to the customer.

createdAttimestamp

Created (UTC).

updatedAttimestamp

Last changed (UTC).

Errors

StatusMessageWhen
400name cannot be emptyname missing or blank.
400countryCode: must be an ISO 3166-1 alpha-2 codeA countryCode that isn’t two letters.
409A customer with this reference already existsAnother customer has this ref (ignoring case).
400A customer named "Acme Trading Ltd." already exists.The name is taken (ignoring case).
400An archived customer named "Acme Trading Ltd." already exists. Restore it from Show archived.An archived customer has the name — restore it instead.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Retrieve a customer

New · 2026-10-22
GET/v1/customers/{id}
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The customer id.

Request

curl "https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
  "ref": "C-1042",
  "name": "Acme Trading Ltd.",
  "taxId": "1234567890",
  "address": "Liman Cad. No: 12, 35210",
  "city": "İzmir",
  "countryCode": "TR",
  "archived": false,
  "contacts": [
    {
      "name": "Deniz Kaya",
      "email": "deniz.kaya@acme-trading.example",
      "phone": "+90 232 000 00 00",
      "role": "Import manager",
      "primary": true
    },
    {
      "name": "Murat Demir",
      "email": "murat.demir@acme-trading.example",
      "phone": null,
      "role": "Customs",
      "primary": false
    }
  ],
  "shipmentCount": 38,
  "createdAt": "2026-06-11T08:02:19Z",
  "updatedAt": "2026-10-22T08:41:55Z"
}

Response fields

iduuid

Navlo’s customer id.

refstringnullable

Your reference — the code your own systems use.

namestring

Company name.

taxIdstringnullable

Tax / VAT number.

addressstringnullable

Street address.

citystringnullable

City.

countryCodestringnullable

ISO 3166-1 alpha-2, e.g. TR.

archivedboolean

Archived customers are hidden from lists unless asked for and can’t be put on new shipments.

contactsarray<object>

People at the customer — name, email, phone, role, primary — the primary contact first, then by name.

shipmentCountinteger

Shipments currently assigned to the customer.

createdAttimestamp

Created (UTC).

updatedAttimestamp

Last changed (UTC).

Errors

StatusMessageWhen
404Customer not foundUnknown id, or another organization’s customer.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Update a customer

New · 2026-10-22
PATCH/v1/customers/{id}

A merge patch: only the keys you send change. null or "" clears an optional field. contacts, when sent, replaces the whole list — send the full list you want to keep; "contacts": null removes them all. name can’t be cleared.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The customer id.

Body

namestring

New name.

refstring | null

New reference, or null / "" to remove it.

taxIdstring | null

Tax / VAT number.

addressstring | null

Street address.

citystring | null

City.

countryCodestring | null

ISO alpha-2 country.

contactsarray<object> | null

The complete new contact list; null removes all contacts.

Request

curl -X PATCH "https://api.navlo.io/v1/customers/c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Liman Cad. No: 12, 35210"
  }'

Response

200 OK
{
  "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
  "ref": "C-1042",
  "name": "Acme Trading Ltd.",
  "taxId": "1234567890",
  "address": "Liman Cad. No: 12, 35210",
  "city": "İzmir",
  "countryCode": "TR",
  "archived": false,
  "contacts": [
    {
      "name": "Deniz Kaya",
      "email": "deniz.kaya@acme-trading.example",
      "phone": "+90 232 000 00 00",
      "role": "Import manager",
      "primary": true
    },
    {
      "name": "Murat Demir",
      "email": "murat.demir@acme-trading.example",
      "phone": null,
      "role": "Customs",
      "primary": false
    }
  ],
  "shipmentCount": 38,
  "createdAt": "2026-06-11T08:02:19Z",
  "updatedAt": "2026-10-22T08:41:55Z"
}

Response fields

iduuid

Navlo’s customer id.

refstringnullable

Your reference — the code your own systems use.

namestring

Company name.

taxIdstringnullable

Tax / VAT number.

addressstringnullable

Street address.

citystringnullable

City.

countryCodestringnullable

ISO 3166-1 alpha-2, e.g. TR.

archivedboolean

Archived customers are hidden from lists unless asked for and can’t be put on new shipments.

contactsarray<object>

People at the customer — name, email, phone, role, primary — the primary contact first, then by name.

shipmentCountinteger

Shipments currently assigned to the customer.

createdAttimestamp

Created (UTC).

updatedAttimestamp

Last changed (UTC).

Errors

StatusMessageWhen
404Customer not foundUnknown id, or another organization’s customer.
400name cannot be emptyname sent blank or null.
400Request body must be a JSON objectThe body is not a JSON object.
409A customer with this reference already existsAnother customer has this ref (ignoring case).
400A customer named "Acme Trading Ltd." already exists.The name is taken (ignoring case).
400An archived customer named "Acme Trading Ltd." already exists. Restore it from Show archived.An archived customer has the name — restore it instead.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Archive a customer

New · 2026-10-22
POST/v1/customers/{id}/archive

Hides the customer from lists and stops it being put on new shipments; its shipments keep it and its history stays. Idempotent. Customers are archived, never deleted.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The customer id.

Request

curl -X POST "https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/archive" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13",
  "ref": "C-2107",
  "name": "Sample Foods Ltd.",
  "taxId": null,
  "address": null,
  "city": "Bursa",
  "countryCode": "TR",
  "archived": true,
  "contacts": [],
  "shipmentCount": 19,
  "createdAt": "2026-10-18T11:02:51Z",
  "updatedAt": "2026-10-22T09:30:00Z"
}

Response fields

iduuid

Navlo’s customer id.

refstringnullable

Your reference — the code your own systems use.

namestring

Company name.

taxIdstringnullable

Tax / VAT number.

addressstringnullable

Street address.

citystringnullable

City.

countryCodestringnullable

ISO 3166-1 alpha-2, e.g. TR.

archivedboolean

Archived customers are hidden from lists unless asked for and can’t be put on new shipments.

contactsarray<object>

People at the customer — name, email, phone, role, primary — the primary contact first, then by name.

shipmentCountinteger

Shipments currently assigned to the customer.

createdAttimestamp

Created (UTC).

updatedAttimestamp

Last changed (UTC).

Errors

StatusMessageWhen
404Customer not foundUnknown id, or another organization’s customer.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Restore a customer

New · 2026-10-22
POST/v1/customers/{id}/restore

Brings an archived customer back. Idempotent.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The customer id.

Request

curl -X POST "https://api.navlo.io/v1/customers/5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13/restore" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13",
  "ref": "C-2107",
  "name": "Sample Foods Ltd.",
  "taxId": null,
  "address": null,
  "city": "Bursa",
  "countryCode": "TR",
  "archived": false,
  "contacts": [],
  "shipmentCount": 19,
  "createdAt": "2026-10-18T11:02:51Z",
  "updatedAt": "2026-10-22T09:31:12Z"
}

Response fields

iduuid

Navlo’s customer id.

refstringnullable

Your reference — the code your own systems use.

namestring

Company name.

taxIdstringnullable

Tax / VAT number.

addressstringnullable

Street address.

citystringnullable

City.

countryCodestringnullable

ISO 3166-1 alpha-2, e.g. TR.

archivedboolean

Archived customers are hidden from lists unless asked for and can’t be put on new shipments.

contactsarray<object>

People at the customer — name, email, phone, role, primary — the primary contact first, then by name.

shipmentCountinteger

Shipments currently assigned to the customer.

createdAttimestamp

Created (UTC).

updatedAttimestamp

Last changed (UTC).

Errors

StatusMessageWhen
404Customer not foundUnknown id, or another organization’s customer.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
An archived customer still resolves by ref, but can’t be put on a shipment until it is restored — the request fails with 400 "Sample Foods Ltd." is archived. Restore it before assigning shipments. Restore it first.

03 · Customers & billing

Usage & credits

Your balances, and a usage report per customer, shipment or day — everything you need to invoice your own customers.

Navlo charges in credits: tracking credits for new shipments and vessel follows, AI credits for Navlo AI answers. These endpoints tell you what is left and where it went.

A new shipment
1 tracking credit. Free when your organization already tracks the identifier or Navlo can’t track that carrier; refunded when no data is ever found.
A vessel follow
2 tracking credits per voyage. Free when one of your tracked containers is on that vessel.
A Navlo AI answer
AI credits — each answer’s amount is in its creditsUsed and in this report.

Get balances

New · 2026-10-22
GET/v1/credits

The balances the key’s requests draw from — the key creator’s, which for an organization admin is the organization’s pool.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Request

curl "https://api.navlo.io/v1/credits" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "trackingCredits": 248,
  "aiCredits": 14.3725
}

Response fields

trackingCreditsnumber

Tracking credits available: shipments and vessel follows.

aiCreditsnumber

AI credits available: Navlo AI answers.

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Usage report

New · 2026-10-22
GET/v1/usage

Credits your organization spent in a date range, grouped the way you invoice. Built from the credit ledger: tracking charges and refunds, vessel follows and Navlo AI answers.

Attribution uses each item’s current customer when you run the report: a shipment’s credits follow its customer, a vessel follow’s its own customer, an AI answer its conversation’s customer. Re-assign a shipment and re-run the report to move its usage.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Query parameters

fromdatedefault first day of this month

First day included, YYYY-MM-DD (UTC). Sent alone: the calendar month starting there.

todatedefault first day of next month

First day NOT included, YYYY-MM-DD; at most 366 days after from. Sent alone: the calendar month ending there.

groupByenumdefault customer

One group per customer, per shipment or per day, or only totals.

customershipmentdaynone
customerIduuid

Only this customer’s usage. Wins over customerRef.

customerRefstring

Only the usage of the customer with this reference.

formatenumdefault json

csv returns one line per ledger row instead (see below).

jsoncsv

Request

curl "https://api.navlo.io/v1/usage?from=2026-10-01&to=2026-11-01&groupBy=customer" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

{
  "from": "2026-10-01",
  "to": "2026-11-01",
  "groupBy": "customer",
  "totals": {
    "shipmentsStarted": 61,
    "trackingCredits": 57,
    "refundedCredits": 2,
    "vesselCredits": 4,
    "aiCredits": 1.8125,
    "netCredits": 60.8125
  },
  "groups": [
    {
      "customer": {
        "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
        "ref": "C-1042",
        "name": "Acme Trading Ltd.",
        "countryCode": "TR"
      },
      "shipment": null,
      "day": null,
      "shipmentsStarted": 38,
      "trackingCredits": 36,
      "refundedCredits": 1,
      "vesselCredits": 2,
      "aiCredits": 1.235,
      "netCredits": 38.235
    },
    {
      "customer": {
        "id": "5a8e1f47-9c3d-4b26-8e71-0f4c2d9b6a13",
        "ref": "C-2107",
        "name": "Sample Foods Ltd.",
        "countryCode": "TR"
      },
      "shipment": null,
      "day": null,
      "shipmentsStarted": 19,
      "trackingCredits": 18,
      "refundedCredits": 1,
      "vesselCredits": 2,
      "aiCredits": 0.4625,
      "netCredits": 19.4625
    },
    {
      "customer": null,
      "shipment": null,
      "day": null,
      "shipmentsStarted": 4,
      "trackingCredits": 3,
      "refundedCredits": 0,
      "vesselCredits": 0,
      "aiCredits": 0.115,
      "netCredits": 3.115
    }
  ]
}

Response fields

fromdate

The range start used.

todate

The range end used (exclusive).

groupByenum

The grouping used.

customershipmentdaynone
totalsobject

The whole range: the six totals below.

totals.shipmentsStartedinteger

Shipments created in the range, free ones included.

totals.trackingCreditsnumber

Tracking credits charged for new shipments.

totals.refundedCreditsnumber

Tracking credits given back in the range, for example for identifiers that never produced data.

totals.vesselCreditsnumber

Credits charged for vessel follows.

totals.aiCreditsnumber

AI credits spent on Navlo AI answers.

totals.netCreditsnumber

trackingCredits − refundedCredits + vesselCredits + aiCredits — what to bill on.

groupsarray<object>

One per customer / shipment / day; [] for groupBy=none. Each carries the six totals plus the keys below.

groups[].customerobjectnullable

{ id, ref, name, countryCode }; null for usage with no customer — the “Unassigned” group. Set on groupBy=shipment groups too.

groups[].shipmentobjectnullable

groupBy=shipment: { id, identifier }. Vessel and Navlo AI usage has no shipment: it comes after the shipments as one group per customer with shipment: null. Shipments started in the range without a charge appear with 0 credits.

groups[].daydatenullable

groupBy=day: the UTC day, YYYY-MM-DD.

Errors

StatusMessageWhen
400from must be before toto is on or before from.
400The report can cover at most 366 daysA longer range.
400from must be a date like 2026-10-01Not a YYYY-MM-DD date.
400groupBy must be one of: customer, shipment, day, noneAnother groupBy.
400Unknown customer idcustomerId is not one of your customers (or not a UUID).
400Unknown customer refNo customer has that customerRef.
400format must be json or csvAnother format.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Notes

  • CSV (navlo-usage-<from>_<to>.csv, CRLF lines, no byte-order mark — the app’s Export CSV adds one for Excel): one line per ledger row with the header date,type,credits,shipment_id,identifier,vessel_follow_id,conversation_id,customer_id,customer_ref,customer_name,user_email. date is the row’s UTC timestamp; type is TRACKING_CHARGE, TRACKING_REFUND, VESSEL or AI; refund lines carry negative credits, so the column sums to netCredits; identifier is the shipment number, the vessel name on a VESSEL line, empty on AI; user_email is who spent the credits.
  • Every charge and refund in your credit ledger is counted, so the totals reconcile with the Ledger page. Numbers carry no trailing zeros (12, 0.5).

Re-billing your customers

  1. 1Put a customer on everything that costs credits. Send customer on POST /v1/shipments, batch items, vessel follows and Navlo AI — by your own ref, so no lookup is needed. Fix older shipments with PATCH /v1/shipments/{id} or on the Companies page.
  2. 2At month end, pull the report: GET /v1/usage?groupBy=customer&from=2026-10-01&to=2026-11-01. One group per customer, plus a customer: null group for anything unassigned — assign those and run it again.
  3. 3Turn credits into money with your own price per credit: netCredits × your rate, plus whatever service fee you add. shipmentsStarted is there if you bill per shipment instead.
  4. 4Attach the detail. format=csv&customerRef=C-1042 gives one line per charge, refund, vessel follow and AI answer for that customer — the invoice annex.

Invoice lines from the usage report

// Month-end: one invoice line per customer, priced at your own rate per credit.
const PRICE_PER_CREDIT_EUR = 2.5

const params = new URLSearchParams({ from: '2026-10-01', to: '2026-11-01', groupBy: 'customer' })
const res = await fetch(`https://api.navlo.io/v1/usage?${params}`, {
  headers: { 'X-API-Key': process.env.NAVLO_API_KEY },
})
if (!res.ok) throw new Error(`Navlo ${res.status}: ${(await res.json()).message}`)
const usage = await res.json()

for (const g of usage.groups) {
  if (!g.customer) {
    console.warn(`${g.netCredits} credits have no customer — assign them before invoicing`)
    continue
  }
  const amount = (g.netCredits * PRICE_PER_CREDIT_EUR).toFixed(2)
  console.log(`${g.customer.ref}\t${g.customer.name}\t${g.shipmentsStarted} shipments\t€${amount}`)
}
The same report is in the app under Ledger → By customer, with the same numbers and an Export CSV button — handy for checking your invoice run.

One customer’s month

Example group
{
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "shipment": null,
  "day": null,
  "shipmentsStarted": 38,
  "trackingCredits": 36,
  "refundedCredits": 1,
  "vesselCredits": 2,
  "aiCredits": 1.235,
  "netCredits": 38.235
}

05 · Webhooks & embed

Webhooks

Navlo POSTs a signed JSON event to your HTTPS endpoint when something happens to one of your shipments.

Webhooks push changes to you as they happen — milestones, ETA moves, risks, free-time warnings, route changes — so you don’t poll. Every event carries a snapshot of the shipment, a fixed details object per topic, and an HMAC signature so you can prove it came from Navlo.

  • Events fire for every shipment in your organization, however it was added — app, API, batch, import.
  • Muting a shipment silences people, not webhooks: muted shipments still send events.
  • Delivery is at least once, so one event can arrive more than once: deduplicate on id.

Setting up an endpoint

  1. 1Expose an HTTPS URL on the public internet that accepts POST with a JSON body and answers 2xx within 10 seconds. Navlo doesn’t follow redirects, so register the final URL.
  2. 2Register it — in the app under Settings → API & Embedding → Webhooks, or with POST /v1/webhooks. Leave topics empty to receive every topic, including future ones.
  3. 3Store the signing secret (whsec_…). It is shown once, at creation and when you rotate it.
  4. 4Verify the signature of every request, then send a test event to see a real payload arrive.

Organization admins manage endpoints. An organization can have up to 10, and every URL must be https://.

Topics

shipment.status_changed
The shipment reached a new status (loaded, departed, arrived, delivered...), was seen leaving or reaching port on the vessel's live position, or is approaching its destination.
shipment.eta_changed
The carrier's estimated arrival moved. Carries the previous and the new ETA.
shipment.completed
The shipment finished: every container completed its journey, or the air cargo was delivered.
shipment.risk_raised
A risk was raised: a container idle at a port, a rolled container, a transshipment delay, cargo not loaded or a booking the airline cancelled.
shipment.dnd
Demurrage, detention and storage: free time about to end, charges started, empty return due or done, air cargo near or past its free storage.
shipment.route_changed
The carrier changed the port of discharge. Carries the previous and the new destination.
shipment.discovery_finished
The search for a new shipment ended: the carrier returned it (RESOLVED), or Navlo found no carrier data and stopped searching on its own (NOT_FOUND).

The request Navlo sends

HTTP
POST /webhooks/navlo HTTP/1.1
Host: erp.example.com
Content-Type: application/json; charset=utf-8
User-Agent: Navlo-Webhooks/1.0
X-Navlo-Topic: shipment.eta_changed
X-Navlo-Event-Id: 3126abb4-12e8-4bff-b18d-d9227adc9a27
X-Navlo-Timestamp: 1791969735
X-Navlo-Delivery-Attempt: 1
X-Navlo-Signature: sha256=c5d25c40c6f3d01c36accfb213241730e6c5bcb289fcd9307b0983b6593f8c26

{"id":"3126abb4-12e8-4bff-b18d-d9227adc9a27","topic":"shipment.eta_changed","occurredAt":"2026-10-22T13:47:22.503768Z","shipment":{"id":"5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60","identifier":"MEDUSH123456","mode":"OCEAN","status":"active","carrier":"MSC","customer":{"id":"0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f","ref":"C-1042","name":"Acme Trading Ltd.","countryCode":"TR"},"origin":{"code":"CNSHA","name":"Shanghai"},"destination":{"code":"TRAMR","name":"Ambarli"},"eta":"2026-11-23T12:00:00Z","vessel":"MSC ANNA","voyage":"FA442W"},"details":{"previousEta":"2026-11-21T06:00:00Z","newEta":"2026-11-23T12:00:00Z","deltaHours":54,"containerNumber":"MSCU7382154","awbNumber":null}}
X-Navlo-Topic
The event’s topic.
X-Navlo-Event-Id
The event id — the same on every retry of the event.
X-Navlo-Timestamp
Unix seconds when this attempt was signed (new on every attempt).
X-Navlo-Delivery-Attempt
1 for the first attempt, up to 5.
X-Navlo-Signature
sha256= + hex HMAC-SHA256 of "<timestamp>.<raw body>".
User-Agent
Navlo-Webhooks/1.0

Payload

Every event has the same envelope. The body is compact JSON (shown pretty-printed in these docs, and key order is not part of the contract). The OpenAPI document describes all seven events under its webhooks section, so code generators can build the types.

Envelope

iduuid

Event id — the same on every retry. Deduplicate on it.

topicstring

One of the topics.

occurredAttimestamp

When Navlo raised the event (UTC) — the same for every endpoint that receives it. The carrier’s own event time is in details.

shipmentobject

The shipment as it is now. With several containers, origin, destination, eta, vessel and voyage describe the first one still on its way.

shipment.iduuid

Shipment id — read the full shipment with GET /v1/shipments/{id}.

shipment.identifierstring

The tracked number, as stored.

shipment.modeenum

Transport mode.

OCEANAIR
shipment.statusenum

Lifecycle status after the change. 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.

discoveringresolvingactivetrackingcompletedstopped
shipment.carrierstringnullable

Carrier code — the resolved carrier, else the predicted one, else (air) the waybill’s airline.

shipment.customerobjectnullable

The shipment’s customer: { id, ref, name, countryCode }.

shipment.originobjectnullable

Port of loading (ocean) or origin airport (air): { code, name }.

shipment.destinationobjectnullable

Port of discharge (ocean) or destination airport (air): { code, name }.

shipment.etatimestampnullable

The carrier’s ETA at the destination — carrier local time with a Z suffix.

shipment.vesselstringnullable

The vessel the cargo is on. Null for air.

shipment.voyagestringnullable

That vessel’s voyage number. Null for air.

detailsobject

What happened — a fixed shape per topic, documented below. Every key is present; a fact the event doesn’t carry is null.

dataobject

Deprecated, removed on 16 November 2026. The old block of shipment facts (container, B/L, ports, vessel, dates). Read shipment and details instead.

testboolean

Present and true only on test events.

The `data` block is going away

Until 16 November 2026 shipment events also carry the old data block, so integrations built on it keep working while they move to shipment and details. From that day it is no longer sent. Test events never carry it.

shipment.status_changed

A container or air waybill reached a new milestone — or Navlo saw the vessel leave or reach port on its live position, or the shipment is approaching its destination. Multi-container shipments may report several containers moving together in one event.

details.statusenum

The shipment’s lifecycle status after the change — the same value as shipment.status.

discoveringresolvingactivetrackingcompletedstopped
details.milestoneobjectnullable

The milestone reached: code and name (e.g. DEPARTED / "Departed"). Navlo’s own announcements use APPROACHING_DESTINATION, DEPARTURE_DETECTED and ARRIVAL_DETECTED (the last two from the vessel’s live position). Air codes can differ from ocean ones (e.g. DEPARTED_) — match on name for one vocabulary. code can be null when Navlo can’t map the name.

details.locationobjectnullable

Where: code (UN/LOCODE or IATA) and name. Air: the airport the cargo is at, named when it is the origin or destination. Live-position detections carry only the port name.

details.eventAttimestampnullable

When it happened — carrier local time, like event timestamps. Null for the approaching announcement.

details.containerNumberstringnullable

OCEAN: the container.

details.awbNumberstringnullable

AIR: the waybill, dashed (235-12345675).

{
  "id": "b218dce9-0e1a-442c-b3bd-f42f67001b41",
  "topic": "shipment.status_changed",
  "occurredAt": "2026-10-22T13:47:22.373797Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-21T06:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "status": "active",
    "milestone": {
      "code": "DEPARTED",
      "name": "Departed"
    },
    "location": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "eventAt": "2026-10-20T14:30:00Z",
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  }
}

shipment.eta_changed

The carrier’s ETA moved. Ocean events fire when the ETA moves at least 6 hours onto another day; air events fire on every announced change, including moves within the same day.

details.previousEtatimestamp

ETA before the change.

details.newEtatimestamp

ETA after the change.

details.deltaHoursnumber

Signed hours with one decimal; positive means later, negative earlier.

details.containerNumberstringnullable

OCEAN: the container.

details.awbNumberstringnullable

AIR: the waybill.

{
  "id": "3126abb4-12e8-4bff-b18d-d9227adc9a27",
  "topic": "shipment.eta_changed",
  "occurredAt": "2026-10-22T13:47:22.503768Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-23T12:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "previousEta": "2026-11-21T06:00:00Z",
    "newEta": "2026-11-23T12:00:00Z",
    "deltaHours": 54,
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  }
}

shipment.completed

The shipment finished — ocean once its last container is done, air when the cargo is delivered. Sent once per shipment.

details.completedAttimestamp

When it finished: the delivery date, else the actual arrival, else when Navlo raised the event.

details.containerNumberstringnullable

OCEAN: the last container to finish.

details.awbNumberstringnullable

AIR: the waybill.

{
  "id": "f10108a9-720c-46d0-9923-462a17ba781b",
  "topic": "shipment.completed",
  "occurredAt": "2026-10-22T13:47:22.507018Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "completed",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-23T12:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "completedAt": "2026-11-26T10:20:00Z",
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  }
}
Shipments you complete yourself with POST …/complete send no event — your system made the change.

shipment.risk_raised

details.kindenum

RISK_ALERT — Navlo’s risk monitor (e.g. a container idle for days). ROLLOVER — cargo rolled to a later vessel. TRANSSHIPMENT_DELAY — stuck at a transshipment port. CARGO_NOT_LOADED — air cargo missed its flight. BOOKING_CANCELLED — the airline cancelled the booking.

RISK_ALERTROLLOVERTRANSSHIPMENT_DELAYCARGO_NOT_LOADEDBOOKING_CANCELLED
details.levelenumnullable

How serious, for the kinds that grade it (the idle alert); null otherwise.

MEDIUMHIGHCRITICAL
details.summarystringnullable

One sentence for people; null for a cancelled booking.

details.containerNumberstringnullable

OCEAN: the container.

details.awbNumberstringnullable

AIR: the waybill.

{
  "id": "5bb76597-193a-4e8b-8c4a-678dbd42e707",
  "topic": "shipment.risk_raised",
  "occurredAt": "2026-10-22T13:47:22.508985Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-23T12:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "kind": "RISK_ALERT",
    "level": "HIGH",
    "summary": "MSCU7382154 has not moved for 6 days at Port Klang.",
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  }
}

shipment.dnd

Free time is running out, charges started, or the empty is due or returned. Warnings start 48 hours before free time ends and repeat daily.

details.kindenum

What happened.

FREE_TIME_WARNINGDEMURRAGE_STARTEDDETENTION_STARTEDEMPTY_RETURN_DUEEMPTY_RETURNEDAIR_STORAGE_RISK
details.freeTimeEndsAttimestampnullable

When free time ends (or ended); for DETENTION_STARTED when detention started, for EMPTY_RETURN_DUE the due date; null for EMPTY_RETURNED.

details.daysLeftintegernullable

Whole days until freeTimeEndsAt, never below 0 — 0 once demurrage or storage is accruing. Null only for EMPTY_RETURNED.

details.containerNumberstringnullable

OCEAN: the container.

details.awbNumberstringnullable

AIR: the waybill.

{
  "id": "e15f5e4a-1d3e-42cf-9884-156ee527bb31",
  "topic": "shipment.dnd",
  "occurredAt": "2026-10-22T13:47:22.510890Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-23T12:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "kind": "FREE_TIME_WARNING",
    "freeTimeEndsAt": "2026-10-24T19:00:00Z",
    "daysLeft": 2,
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  }
}

shipment.route_changed

details.previousDestinationobjectnullable

Port of discharge before: code, name.

details.newDestinationobjectnullable

Port of discharge now: code, name.

Port of discharge changed
{
  "id": "2b62a80e-5e5f-483d-9d3f-2f9875f1cf71",
  "topic": "shipment.route_changed",
  "occurredAt": "2026-10-22T13:47:22.514065Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRMER",
      "name": "Mersin"
    },
    "eta": "2026-11-24T08:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "previousDestination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "newDestination": {
      "code": "TRMER",
      "name": "Mersin"
    }
  }
}

shipment.discovery_finished

The search for a new shipment ended. Subscribe to it when you create shipments through the API and need to know how the identifier resolved. While Navlo is still retrying, no event is sent.

RESOLVED
The carrier returned the shipment; it now has containers or air waybills.
NOT_FOUND
Navlo got no usable carrier data and stopped searching on its own. status says how it rests: stopped — Navlo stopped looking; discovering — Navlo is still looking. If it’s found later, a RESOLVED event follows.
details.outcomeenum

How the search ended.

RESOLVEDNOT_FOUND
details.statusenum

The shipment’s status now.

discoveringresolvingactivetrackingcompletedstopped
details.carrierstringnullable

The carrier found; null for NOT_FOUND.

{
  "id": "e3da450d-85fa-48e9-abef-d8469dc25209",
  "topic": "shipment.discovery_finished",
  "occurredAt": "2026-10-22T13:47:22.516212Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MEDUSH123456",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-21T06:00:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "outcome": "RESOLVED",
    "status": "active",
    "carrier": "MSC"
  }
}

Delivery is at-least-once — deduplicate on id.

Verifying signatures

  1. 1Read the raw request body as bytes — before any JSON parsing.
  2. 2Compute HMAC-SHA256 over "<X-Navlo-Timestamp>.<raw body>", keyed with your endpoint’s whole secret, whsec_ prefix included.
  3. 3Compare "sha256=" + hex digest with X-Navlo-Signature in constant time.
  4. 4Reject timestamps more than 5 minutes from your clock — that stops a captured request being replayed.

Verify and acknowledge

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.NAVLO_WEBHOOK_SECRET // the whole "whsec_…" string, exactly as shown
const TOLERANCE_SECONDS = 300

// express.raw keeps the exact bytes Navlo signed — don't verify a re-serialised req.body.
app.post('/webhooks/navlo', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Navlo-Timestamp') ?? ''
  const signature = req.get('X-Navlo-Signature') ?? ''
  const expected =
    'sha256=' + crypto.createHmac('sha256', SECRET).update(`${timestamp}.`).update(req.body).digest('hex')

  const valid =
    signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS
  if (!valid || !fresh) return res.sendStatus(401)

  const event = JSON.parse(req.body.toString('utf8'))
  res.sendStatus(200) // acknowledge within 10 seconds…
  queue.add(event) // …then process asynchronously, skipping event.id values you have already handled
})

app.listen(3000)

Check your implementation against this test vector before going live:

Test vector
secret             whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f
X-Navlo-Timestamp  1791969735
raw body           {"id":"4f1c0a6b-2d83-4e57-9c11-7a5b3e08d642","topic":"shipment.eta_changed"}

X-Navlo-Signature  sha256=bc366d951a2acc630c9e028db4f2a71499301dd110bbdbd706e8afab0fb3c0d6
Frameworks that parse JSON before your handler runs (Express json(), ASP.NET model binding) change the bytes — whitespace, key order, unicode escapes — and the signature will not match. Verify the raw body.

Retries and failures

Success
Any 2xx within 10 seconds. Answer first, then do the work.
Redirects
A 3xx is a failed attempt — redirects are not followed. Point the webhook at the final URL.
Retries
5 attempts in total: right away, then after 1, 5, 20 and 60 minutes.
Order
Oldest first per endpoint, but retries can reorder events — trust occurredAt and the shipment’s current state.
Auto-disable
After 20 failed attempts in a row the endpoint is switched off and disabledReason says why. Failed test deliveries count too.
Re-enable
PATCH with "active": true (or the app) — this clears the failure streak.
History
Every attempt is listed in deliveries for 30 days.

Events raised while an endpoint is disabled are not replayed when you re-enable it. To catch up, sync with updatedSince from the time it was disabled. Redirects are followed, but don’t rely on them: give Navlo the final URL.

Test events

Send a realistic sample event to an endpoint at any time — from the app’s Send test event button or POST /v1/webhooks/{id}/test. It goes to that endpoint whatever its topics, through normal delivery — signature, retries and the failure streak included — within a minute. It carries "test": true and a fixed sample shipment (id 5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60), so don’t look that shipment up; its dates are relative to the moment you send it.

Test event
{
  "id": "33729788-59e4-4e9e-8e11-ef83b47ce78b",
  "topic": "shipment.status_changed",
  "occurredAt": "2026-10-22T13:47:22.703799Z",
  "shipment": {
    "id": "5e1c3a9b-0d2f-4f8e-9a61-3b7c2d4e5f60",
    "identifier": "MSCU7382154",
    "mode": "OCEAN",
    "status": "active",
    "carrier": "MSC",
    "customer": {
      "id": "0c7d2f6e-3a41-4b0e-9a55-1f2b3c4d5e6f",
      "ref": "C-1042",
      "name": "Acme Trading Ltd.",
      "countryCode": "TR"
    },
    "origin": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "destination": {
      "code": "TRAMR",
      "name": "Ambarli"
    },
    "eta": "2026-11-18T13:47:00Z",
    "vessel": "MSC ANNA",
    "voyage": "FA442W"
  },
  "details": {
    "status": "active",
    "milestone": {
      "code": "DEPARTED",
      "name": "Departed"
    },
    "location": {
      "code": "CNSHA",
      "name": "Shanghai"
    },
    "eventAt": "2026-10-22T11:47:00Z",
    "containerNumber": "MSCU7382154",
    "awbNumber": null
  },
  "test": true
}

Managing endpoints over the API

The same endpoints the app’s Webhooks screen manages. Creating, updating, rotating, testing and deleting need the key’s creator to be an organization admin.

List webhook endpoints

New · 2026-10-22
GET/v1/webhooks
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Request

curl "https://api.navlo.io/v1/webhooks" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "id": "2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68",
    "name": "ERP shipment updates",
    "url": "https://erp.example.com/webhooks/navlo",
    "topics": [],
    "active": true,
    "disabledReason": null,
    "consecutiveFailures": 0,
    "lastSuccessAt": "2026-10-22T07:14:44Z",
    "lastFailureAt": "2026-10-19T02:10:03Z",
    "createdAt": "2026-09-24T07:50:12Z"
  }
]

Response fields

An array of endpoints, disabled ones included.

[].iduuid

Endpoint id.

[].namestring

Your label for it.

[].urlstring

Where events are POSTed.

[].topicsarray<string>

Subscribed topics; [] means every topic, including topics added later.

[].activeboolean

false when you disabled it or Navlo did after repeated failures.

[].disabledReasonstringnullable

Why Navlo disabled it, e.g. "Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …".

[].consecutiveFailuresinteger

Failed deliveries since the last success; reset by a success and by re-enabling.

[].lastSuccessAttimestampnullable

Last successful delivery (UTC).

[].lastFailureAttimestampnullable

Last failed attempt (UTC).

[].createdAttimestamp

Created (UTC).

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
GET/v1/webhooks/{id}
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The endpoint id.

Request

curl "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68",
  "name": "ERP shipment updates",
  "url": "https://erp.example.com/webhooks/navlo",
  "topics": [],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": "2026-10-22T07:14:44Z",
  "lastFailureAt": "2026-10-19T02:10:03Z",
  "createdAt": "2026-09-24T07:50:12Z"
}

Response fields

iduuid

Endpoint id.

namestring

Your label for it.

urlstring

Where events are POSTed.

topicsarray<string>

Subscribed topics; [] means every topic, including topics added later.

activeboolean

false when you disabled it or Navlo did after repeated failures.

disabledReasonstringnullable

Why Navlo disabled it, e.g. "Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …".

consecutiveFailuresinteger

Failed deliveries since the last success; reset by a success and by re-enabling.

lastSuccessAttimestampnullable

Last successful delivery (UTC).

lastFailureAttimestampnullable

Last failed attempt (UTC).

createdAttimestamp

Created (UTC).

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Create a webhook endpoint

New · 2026-10-22
POST/v1/webhooks
Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

namestringrequired

Your label, up to 120 characters (longer names are cut).

urlstringrequired

HTTPS URL, without credentials in it.

topicsarray<string>

Topics to receive. Omit or send [] for every topic, including future ones.

shipment.status_changedshipment.eta_changedshipment.completedshipment.risk_raisedshipment.dndshipment.route_changedshipment.discovery_finished

Request

curl -X POST "https://api.navlo.io/v1/webhooks" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP shipment updates",
    "url": "https://erp.example.com/webhooks/navlo",
    "topics": [
      "shipment.status_changed",
      "shipment.eta_changed"
    ]
  }'

Response

201 Created
{
  "id": "2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68",
  "name": "ERP shipment updates",
  "url": "https://erp.example.com/webhooks/navlo",
  "topics": [
    "shipment.status_changed",
    "shipment.eta_changed"
  ],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "createdAt": "2026-10-22T08:15:00Z",
  "secret": "whsec_7d1f9a3c5e8b2d4f6a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f"
}

Response fields

iduuid

Endpoint id.

namestring

Your label for it.

urlstring

Where events are POSTed.

topicsarray<string>

Subscribed topics; [] means every topic, including topics added later.

activeboolean

false when you disabled it or Navlo did after repeated failures.

disabledReasonstringnullable

Why Navlo disabled it, e.g. "Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …".

consecutiveFailuresinteger

Failed deliveries since the last success; reset by a success and by re-enabling.

lastSuccessAttimestampnullable

Last successful delivery (UTC).

lastFailureAttimestampnullable

Last failed attempt (UTC).

createdAttimestamp

Created (UTC).

secretstring

The signing secret, whsec_ + 64 hex characters. Shown only in this response — store it now.

Errors

StatusMessageWhen
400Webhook name is requiredname missing or blank.
400Webhook URL is requiredurl missing.
400Webhook URL must use httpsAn http:// URL.
400Webhook URL is not a valid URLNot a URL.
400Webhook URL must not embed credentialshttps://user:pass@… URLs.
400Webhook URL must point to a public internet addressA private, local or internal host or address.
400Unknown webhook topic: shipment.createdA topic outside the list.
400Maximum 10 webhooks per organizationAlready 10 endpoints (disabled ones count).
403Only organization admins can manage webhooksThe key’s creator is not an organization admin.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Update a webhook endpoint

New · 2026-10-22
PATCH/v1/webhooks/{id}

Only the keys you send change. Re-enabling ("active": true) also clears the failure streak and disabledReason.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The endpoint id.

Body

namestring

New label.

urlstring

New HTTPS URL.

topicsarray<string>

New topic list; [] for every topic.

activeboolean

false pauses deliveries; true resumes them.

Request

curl -X PATCH "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true
  }'

Response

200 OK
{
  "id": "2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68",
  "name": "ERP shipment updates",
  "url": "https://erp.example.com/webhooks/navlo",
  "topics": [],
  "active": true,
  "disabledReason": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": "2026-10-22T07:14:44Z",
  "lastFailureAt": "2026-10-19T02:10:03Z",
  "createdAt": "2026-09-24T07:50:12Z"
}

Response fields

iduuid

Endpoint id.

namestring

Your label for it.

urlstring

Where events are POSTed.

topicsarray<string>

Subscribed topics; [] means every topic, including topics added later.

activeboolean

false when you disabled it or Navlo did after repeated failures.

disabledReasonstringnullable

Why Navlo disabled it, e.g. "Automatically disabled after 20 consecutive failed deliveries. Last error: HTTP 503: …".

consecutiveFailuresinteger

Failed deliveries since the last success; reset by a success and by re-enabling.

lastSuccessAttimestampnullable

Last successful delivery (UTC).

lastFailureAttimestampnullable

Last failed attempt (UTC).

createdAttimestamp

Created (UTC).

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
400Webhook URL must use httpsAn http:// URL.
400Webhook URL is not a valid URLNot a URL.
400Webhook URL must not embed credentialshttps://user:pass@… URLs.
400Webhook URL must point to a public internet addressA private, local or internal host or address.
400Unknown webhook topic: shipment.createdA topic outside the list.
403Only organization admins can manage webhooksThe key’s creator is not an organization admin.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Delete a webhook endpoint

New · 2026-10-22
DELETE/v1/webhooks/{id}

Stops deliveries at once, including queued retries.

Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The endpoint id.

Request

curl -X DELETE "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
403Only organization admins can manage webhooksThe key’s creator is not an organization admin.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Rotate the signing secret

New · 2026-10-22
POST/v1/webhooks/{id}/rotate-secret

Issues a new secret and invalidates the old one immediately — queued retries are signed with the new one. Deploy it to your receiver promptly; deliveries signed with the new secret fail verification until you do, and are retried.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The endpoint id.

Request

curl -X POST "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/rotate-secret" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "secret": "whsec_3a9e1c7f5b2d8e4a6c0f9b3d1e7a5c2f8b4d6e0a9c3f7b1d5e8a2c6f0b4d9e3a"
}

Response fields

secretstring

The new secret, shown only here.

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
403Only organization admins can manage webhooksThe key’s creator is not an organization admin.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

List deliveries

New · 2026-10-22
GET/v1/webhooks/{id}/deliveries

Every event sent to the endpoint in the last 30 days, newest first, with the outcome of its latest attempt.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The endpoint id.

Query parameters

pageintegerdefault 0

Zero-based page index.

sizeintegerdefault 20

Page size, 1–100.

Request

curl "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/deliveries?size=2" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "page": 0,
  "size": 2,
  "totalElements": 418,
  "totalPages": 209,
  "deliveries": [
    {
      "id": "0e6a3d9f-8b2c-4a71-9f5e-c4d1b7a3e820",
      "eventId": "0d6b3e9f-7a1c-4f25-8b4d-e2c9a5f7b130",
      "topic": "shipment.risk_raised",
      "shipmentId": "6b1f0c9a-4d2e-4f7b-9a3c-8e5d21f0a4b7",
      "status": "delivered",
      "attempts": 1,
      "responseStatus": 200,
      "error": null,
      "createdAt": "2026-10-21T09:26:58Z",
      "lastAttemptAt": "2026-10-21T06:01:02Z"
    },
    {
      "id": "b2f8d4a6-3c1e-4b97-8d05-e6a2c9f1b743",
      "eventId": "9b4e7a2d-6c8f-4d13-a0e5-1f3c8b6d9a27",
      "topic": "shipment.dnd",
      "shipmentId": "a7d3e9b1-5c2f-4e84-b6a0-3f9c1d7e2b58",
      "status": "delivered",
      "attempts": 2,
      "responseStatus": 200,
      "error": null,
      "createdAt": "2026-10-19T15:03:12Z",
      "lastAttemptAt": "2026-10-19T06:01:31Z"
    }
  ]
}

Response fields

pageinteger

Page index.

sizeinteger

Page size.

totalElementsinteger

Deliveries in the last 30 days.

totalPagesinteger

Pages at this size.

deliveriesarray<object>

The deliveries.

deliveries[].iduuid

Delivery id.

deliveries[].eventIduuid

The event id (X-Navlo-Event-Id).

deliveries[].topicstring

The topic.

deliveries[].shipmentIduuidnullable

The shipment the event is about; null for a test event.

deliveries[].statusenum

pending — not tried yet. retrying — failed, will retry. delivered. failed — gave up after 5 attempts, or the endpoint was switched off.

pendingretryingdeliveredfailed
deliveries[].attemptsinteger

Attempts so far (1–5).

deliveries[].responseStatusintegernullable

Your endpoint’s HTTP status on the last attempt.

deliveries[].errorstringnullable

What went wrong: HTTP 503: <first 500 characters of your response> or the network error.

deliveries[].createdAttimestamp

When the event was queued (UTC).

deliveries[].lastAttemptAttimestampnullable

When Navlo last tried it, or gave up on it (UTC); null before the first attempt.

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Send a test event

New · 2026-10-22
POST/v1/webhooks/{id}/test

Queues a sample event of the topic you choose to this endpoint, whatever its topics. It arrives within a minute and appears in the deliveries list; a failed test delivery counts toward the failure streak like any other. The body is optional.

Auth  X-API-KeyRate limit  60 / min per keyReturns  202 Accepted

Path parameters

iduuidrequired

The endpoint id.

Body

topicstringdefault shipment.status_changed

The sample’s topic.

shipment.status_changedshipment.eta_changedshipment.completedshipment.risk_raisedshipment.dndshipment.route_changedshipment.discovery_finished

Request

curl -X POST "https://api.navlo.io/v1/webhooks/2b7e9c41-6d3a-4f8e-a5c1-9e0d7b3f2a68/test" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "shipment.eta_changed"
  }'

Response

202 Accepted
{
  "eventId": "33729788-59e4-4e9e-8e11-ef83b47ce78b",
  "topic": "shipment.eta_changed"
}

Response fields

eventIduuid

The test event’s id — the payload id and X-Navlo-Event-Id, and the eventId of its delivery.

topicstring

The topic the sample was built for.

Errors

StatusMessageWhen
404Webhook not foundUnknown id, or another organization’s endpoint.
409Webhook endpoint is disabledThe endpoint is switched off — re-enable it first.
400Unknown webhook topic: shipment.createdA topic outside the list.
403Only organization admins can manage webhooksThe key’s creator is not an organization admin.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

List topics

New · 2026-10-22
GET/v1/webhooks/topics
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Request

curl "https://api.navlo.io/v1/webhooks/topics" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
[
  {
    "topic": "shipment.status_changed",
    "description": "The shipment reached a new status (loaded, departed, arrived, delivered...), was seen leaving or reaching port on the vessel's live position, or is approaching its destination."
  },
  {
    "topic": "shipment.eta_changed",
    "description": "The carrier's estimated arrival moved. Carries the previous and the new ETA."
  },
  {
    "topic": "shipment.completed",
    "description": "The shipment finished: every container completed its journey, or the air cargo was delivered."
  },
  {
    "topic": "shipment.risk_raised",
    "description": "A risk was raised: a container idle at a port, a rolled container, a transshipment delay, cargo not loaded or a booking the airline cancelled."
  },
  {
    "topic": "shipment.dnd",
    "description": "Demurrage, detention and storage: free time about to end, charges started, empty return due or done, air cargo near or past its free storage."
  },
  {
    "topic": "shipment.route_changed",
    "description": "The carrier changed the port of discharge. Carries the previous and the new destination."
  },
  {
    "topic": "shipment.discovery_finished",
    "description": "The search for a new shipment ended: the carrier returned it (RESOLVED), or Navlo found no carrier data and stopped searching on its own (NOT_FOUND)."
  }
]

Response fields

Every topic you can subscribe to.

[].topicstring

Topic name.

[].descriptionstring

When it fires.

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

05 · Webhooks & embed

Embed

Live shipment tracking on your own website — a ready-made widget, or the endpoint behind it for your own design.

Let your customers track their shipments on your website. They type a container, B/L, booking or air waybill number and see the live status — only for shipments your organization already tracks. The embed shows carrier facts only (milestones, vessel, ports, dates): never your customers, tags, notes, risk or costs, and it never starts a shipment or spends credits.

The tracking widget

  1. 1Create an embed key under Settings → API & Embedding → New key, scope Embed widget. It starts with nvle_.
  2. 2Optionally pin it to your website’s origins, e.g. https://www.example.com, https://portal.example.com.
  3. 3Paste the iframe into your page.
HTML
<iframe
  src="https://app.navlo.io/embed?key=nvle_your_embed_key"
  style="width:100%;height:640px;border:0;border-radius:12px"
  title="Shipment tracking"
  loading="lazy"></iframe>

The widget is responsive and needs about 640 px of height to show the map and timeline without scrolling.

Origin pinning

An embed key is meant to be public — it sits in your page’s HTML. Pinning it to your origins stops other sites from embedding it: the widget reports the page it is embedded in, and a request from any other origin is refused with 403. With no origins on the key, the widget works on any site.

  • Origins are scheme + host (+ port): https://www.example.com — no paths, no trailing slash needed.
  • The widget learns your page’s origin from the browser’s referrer. Don’t set referrerpolicy="no-referrer" on the iframe when the key is pinned, or every lookup is refused.
  • Revoke the key in Settings to switch the widget off immediately.

Building your own tracking box

Prefer your own design? Call the endpoint the widget uses. Call it from your server: api.navlo.io does not accept cross-origin browser requests from your domain, and your server can shape the answer for your page.

GET/api/embed/resolve

Finds the shipment your organization tracks under exactly the number typed — container, Master B/L, booking or Master AWB — and returns the public, read-only view your share links show. Unknown numbers are a plain 404; nothing is ever created.

Auth  X-Embed-Key (embed key)Rate limit  None per keyReturns  200 OK

Query parameters

numberstringrequired

The number as your customer typed it. Matched exactly against your tracked shipments (case-insensitive).

parentOriginstring

The origin of the page the lookup is for, e.g. https://www.example.com. Required — and checked — when the key pins origins.

keystring

The embed key, when you can’t send the X-Embed-Key header.

Headers

X-Embed-Keystringrequired

Your embed key (nvle_…). Or pass it as the key query parameter.

Request

curl "https://api.navlo.io/api/embed/resolve?number=MEDU1234562&parentOrigin=https:%2F%2Fwww.example.com" \
  -H "X-Embed-Key: $NAVLO_EMBED_KEY"

Response

200 OK
{
  "trackingIdentifier": "MEDU1234562",
  "trackingMode": "OCEAN",
  "status": "active",
  "containers": [
    {
      "id": "c1",
      "containerNumber": "MEDU1234562",
      "courierCode": "MSC",
      "courierName": "MSC",
      "courierLogoUrl": "https://cdn.example.com/couriers/msc.png",
      "navloStatusCode": "DEPARTED",
      "navloStatusName": "Departed",
      "navloStatusCategory": "TRANSIT",
      "statusListingCode": "IN_TRANSIT",
      "statusListingName": "In Transit",
      "containerType": "40HC",
      "containerIsoCode": "45G1",
      "originPortCode": "CNSHA",
      "originPortName": "Shanghai",
      "originPortCoordinates": {
        "lat": 31.2304,
        "lng": 121.4737
      },
      "originTerminal": "Yangshan Deep Water Port Phase IV",
      "destinationPortCode": "TRAMR",
      "destinationPortName": "Ambarli",
      "destinationPortCoordinates": {
        "lat": 40.9667,
        "lng": 28.6833
      },
      "destinationTerminal": "Marport Ambarli",
      "currentLocation": "Shanghai",
      "currentLocationCode": "CNSHA",
      "currentVesselName": "MSC MARTINA",
      "currentVoyageNumber": "438W",
      "currentVesselImo": "9461805",
      "originCountryCode": "CN",
      "destinationCountryCode": "TR",
      "demurrageFreeUntil": null,
      "carrierFreeTimeDays": 7,
      "carrierFreeTimeBasis": "Calendar Days",
      "estimatedArrival": "2026-10-30T06:00:00Z",
      "actualArrival": null,
      "estimatedDeparture": "2026-09-26T22:00:00Z",
      "actualDeparture": "2026-09-27T03:40:00Z",
      "estimatedDepartureUtc": "2026-09-26T14:00:00Z",
      "actualDepartureUtc": "2026-09-26T19:40:00Z",
      "estimatedArrivalUtc": "2026-10-30T03:00:00Z",
      "actualArrivalUtc": null,
      "estimatedDelivery": null,
      "actualDelivery": null,
      "completedAt": null,
      "co2eKg": 1856.4,
      "co2Source": "GLEC",
      "activities": [
        {
          "id": "c1-e1",
          "navloStatusCode": "GATE_IN",
          "navloStatusName": "Gate In",
          "navloStatusIcon": "log-in",
          "navloStatusDisplayOrder": 20,
          "navloStatusCategory": "ORIGIN",
          "courierStatus": "Export received at CY",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-24T14:12:00Z",
          "eventType": "ACTUAL",
          "vesselName": null,
          "voyageNumber": null,
          "transportMode": null,
          "detectionSource": null
        },
        {
          "id": "c1-e2",
          "navloStatusCode": "LOADED",
          "navloStatusName": "Loaded",
          "navloStatusIcon": "package",
          "navloStatusDisplayOrder": 40,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Export Loaded on Vessel",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-26T21:30:00Z",
          "eventType": "ACTUAL",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e3",
          "navloStatusCode": "DEPARTED",
          "navloStatusName": "Departed",
          "navloStatusIcon": "ship",
          "navloStatusDisplayOrder": 50,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Vessel Departure",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-27T03:40:00Z",
          "eventType": "ACTUAL",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e4",
          "navloStatusCode": "TRANSSHIPMENT",
          "navloStatusName": "Transshipment",
          "navloStatusIcon": "repeat",
          "navloStatusDisplayOrder": 90,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Estimated Time of Arrival",
          "location": "Piraeus",
          "locationCode": "GRPIR",
          "terminalName": null,
          "locationCountryCode": "GR",
          "locationCoordinates": {
            "lat": 37.9421,
            "lng": 23.6465
          },
          "activityTimestamp": "2026-10-23T08:00:00Z",
          "eventType": "EXPECTED",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e5",
          "navloStatusCode": "ARRIVED",
          "navloStatusName": "Arrived",
          "navloStatusIcon": "anchor",
          "navloStatusDisplayOrder": 70,
          "navloStatusCategory": "DESTINATION",
          "courierStatus": "Estimated Time of Arrival",
          "location": "Ambarli",
          "locationCode": "TRAMR",
          "terminalName": "Marport Ambarli",
          "locationCountryCode": "TR",
          "locationCoordinates": {
            "lat": 40.9667,
            "lng": 28.6833
          },
          "activityTimestamp": "2026-10-30T06:00:00Z",
          "eventType": "EXPECTED",
          "vesselName": "MSC ARIANE",
          "voyageNumber": "IP243A",
          "transportMode": "VESSEL",
          "detectionSource": null
        }
      ],
      "aboardVessel": true,
      "nextPlannedVessel": {
        "vesselName": "MSC ARIANE",
        "voyageNumber": "IP243A",
        "plannedAt": "2026-10-27T18:00:00Z",
        "portName": "Piraeus",
        "portCode": "GRPIR"
      }
    }
  ],
  "airShipments": [],
  "vesselPosition": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z",
    "ageHours": 3
  }
}

Response fields

trackingIdentifierstring

The tracked number the customer’s input matched.

trackingModeenum

Branch on it: OCEAN fills containers, AIR fills airShipments.

OCEANAIR
statusenum

Lifecycle status. 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.

discoveringresolvingactivetrackingcompletedstopped
containersarray<object>

OCEAN: one per container. The fields you need for a tracking box:

containers[].idstring

The container’s place in this answer (c1, c2, …); timeline rows extend it (c1-e1). Use it to key rows, not to store.

containers[].containerNumberstring

Container number.

containers[].courierNamestring

Carrier name (courierLogoUrl has its logo).

containers[].statusListingNamestringnullable

The status headline Navlo shows — "In Transit", "Discharged", "Completed". Use this as the big label.

containers[].navloStatusNamestringnullable

The latest milestone, e.g. "Departed".

containers[].navloStatusCategoryenumnullable

Phase of the journey.

PRE_SHIPMENTORIGINTRANSITDESTINATIONCOMPLETED
containers[].originPortNamestringnullable

Port of loading (originPortCode = UN/LOCODE, originCountryCode = ISO alpha-2, originPortCoordinates = { lat, lng }).

containers[].destinationPortNamestringnullable

Port of discharge (destinationPortCode, destinationCountryCode, destinationPortCoordinates likewise).

containers[].estimatedDeparturetimestampnullable

ETD — carrier local time; actualDeparture = ATD.

containers[].estimatedArrivaltimestampnullable

ETA — carrier local time; actualArrival = ATA. Display as-is.

containers[].estimatedArrivalUtctimestampnullable

The same times as true UTC instants, for arithmetic only (transit days). Never display these.

containers[].currentVesselNamestringnullable

Vessel now (currentVoyageNumber, currentVesselImo).

containers[].aboardVesselboolean

true while the container is verifiably on the vessel.

containers[].nextPlannedVesselobjectnullable

The next connection: vesselName, voyageNumber, plannedAt, portName, portCode.

containers[].activitiesarray<object>

The timeline rows. Sort by activityTimestamp for a strict chronology.

containers[].activities[].navloStatusNamestringnullable

Milestone, e.g. "Loaded" (navloStatusCode = LOADED).

containers[].activities[].courierStatusstring

The carrier’s own wording.

containers[].activities[].locationstringnullable

Place (locationCode, locationCountryCode, terminalName).

containers[].activities[].activityTimestamptimestampnullable

When — carrier local time.

containers[].activities[].eventTypeenumnullable

Happened, or still planned.

ACTUALEXPECTED
containers[].activities[].vesselNamestringnullable

Vessel for the event (voyageNumber).

containers[].activities[].detectionSourcestringnullable

AIS when Navlo detected the milestone from live vessel tracking before the carrier reported it.

airShipmentsarray<object>

AIR: one per waybill — awbNumber, courierName, originAirportCode/Name, destinationAirportCode/Name, statusListingCode, estimatedDeparture, actualDeparture, estimatedArrival, actualArrival, piecesCount, piecesWeight, milestones[], flightSegments[].

vesselPositionobjectnullable

Where the vessel was last seen, only while the container is sailing on it: vesselName, latitude, longitude, heading, source (LIVE or STALE), reportedAt, ageHours. Show "last seen N hours ago" for STALE.

Errors

StatusMessageWhen
400Required parameter 'number' is missingNo number (general error shape).
401empty bodyMissing, wrong or revoked embed key — or a REST key.
403empty bodyThe key pins origins and parentOrigin is missing or not one of them.
404empty bodyYour organization doesn’t track that number.
429empty bodyMore than 60 lookups in a minute with this key. Wait the Retry-After seconds.

Notes

  • Not charged, but limited to 60 lookups a minute per key — cache answers for a minute or two on your server if your page is busy.
  • Errors have an empty body: branch on the status code.

Reading the response

The status headline
containers[0].statusListingName (air: airShipments[0].statusListingCode).
From → to
originPortName → destinationPortName.
ETA
estimatedArrival, displayed as-is (carrier local time).
A timeline
activities[] — navloStatusName, location, activityTimestamp, eventType.
A map
originPortCoordinates, destinationPortCoordinates, vesselPosition.
The payload is the one Navlo’s own share page renders, so it carries more fields than a simple tracking box needs — ignore the rest. Your integration code should read it like any other Navlo response: unknown fields can appear.

Milestone code

activities[].navloStatusCodestring

Milestone code — see milestone codes.

Full response

Ocean shipment
{
  "trackingIdentifier": "MEDU1234562",
  "trackingMode": "OCEAN",
  "status": "active",
  "containers": [
    {
      "id": "c1",
      "containerNumber": "MEDU1234562",
      "courierCode": "MSC",
      "courierName": "MSC",
      "courierLogoUrl": "https://cdn.example.com/couriers/msc.png",
      "navloStatusCode": "DEPARTED",
      "navloStatusName": "Departed",
      "navloStatusCategory": "TRANSIT",
      "statusListingCode": "IN_TRANSIT",
      "statusListingName": "In Transit",
      "containerType": "40HC",
      "containerIsoCode": "45G1",
      "originPortCode": "CNSHA",
      "originPortName": "Shanghai",
      "originPortCoordinates": {
        "lat": 31.2304,
        "lng": 121.4737
      },
      "originTerminal": "Yangshan Deep Water Port Phase IV",
      "destinationPortCode": "TRAMR",
      "destinationPortName": "Ambarli",
      "destinationPortCoordinates": {
        "lat": 40.9667,
        "lng": 28.6833
      },
      "destinationTerminal": "Marport Ambarli",
      "currentLocation": "Shanghai",
      "currentLocationCode": "CNSHA",
      "currentVesselName": "MSC MARTINA",
      "currentVoyageNumber": "438W",
      "currentVesselImo": "9461805",
      "originCountryCode": "CN",
      "destinationCountryCode": "TR",
      "demurrageFreeUntil": null,
      "carrierFreeTimeDays": 7,
      "carrierFreeTimeBasis": "Calendar Days",
      "estimatedArrival": "2026-10-30T06:00:00Z",
      "actualArrival": null,
      "estimatedDeparture": "2026-09-26T22:00:00Z",
      "actualDeparture": "2026-09-27T03:40:00Z",
      "estimatedDepartureUtc": "2026-09-26T14:00:00Z",
      "actualDepartureUtc": "2026-09-26T19:40:00Z",
      "estimatedArrivalUtc": "2026-10-30T03:00:00Z",
      "actualArrivalUtc": null,
      "estimatedDelivery": null,
      "actualDelivery": null,
      "completedAt": null,
      "co2eKg": 1856.4,
      "co2Source": "GLEC",
      "activities": [
        {
          "id": "c1-e1",
          "navloStatusCode": "GATE_IN",
          "navloStatusName": "Gate In",
          "navloStatusIcon": "log-in",
          "navloStatusDisplayOrder": 20,
          "navloStatusCategory": "ORIGIN",
          "courierStatus": "Export received at CY",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-24T14:12:00Z",
          "eventType": "ACTUAL",
          "vesselName": null,
          "voyageNumber": null,
          "transportMode": null,
          "detectionSource": null
        },
        {
          "id": "c1-e2",
          "navloStatusCode": "LOADED",
          "navloStatusName": "Loaded",
          "navloStatusIcon": "package",
          "navloStatusDisplayOrder": 40,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Export Loaded on Vessel",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-26T21:30:00Z",
          "eventType": "ACTUAL",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e3",
          "navloStatusCode": "DEPARTED",
          "navloStatusName": "Departed",
          "navloStatusIcon": "ship",
          "navloStatusDisplayOrder": 50,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Vessel Departure",
          "location": "Shanghai",
          "locationCode": "CNSHA",
          "terminalName": "Yangshan Deep Water Port Phase IV",
          "locationCountryCode": "CN",
          "locationCoordinates": {
            "lat": 31.2304,
            "lng": 121.4737
          },
          "activityTimestamp": "2026-09-27T03:40:00Z",
          "eventType": "ACTUAL",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e4",
          "navloStatusCode": "TRANSSHIPMENT",
          "navloStatusName": "Transshipment",
          "navloStatusIcon": "repeat",
          "navloStatusDisplayOrder": 90,
          "navloStatusCategory": "TRANSIT",
          "courierStatus": "Estimated Time of Arrival",
          "location": "Piraeus",
          "locationCode": "GRPIR",
          "terminalName": null,
          "locationCountryCode": "GR",
          "locationCoordinates": {
            "lat": 37.9421,
            "lng": 23.6465
          },
          "activityTimestamp": "2026-10-23T08:00:00Z",
          "eventType": "EXPECTED",
          "vesselName": "MSC MARTINA",
          "voyageNumber": "438W",
          "transportMode": "VESSEL",
          "detectionSource": null
        },
        {
          "id": "c1-e5",
          "navloStatusCode": "ARRIVED",
          "navloStatusName": "Arrived",
          "navloStatusIcon": "anchor",
          "navloStatusDisplayOrder": 70,
          "navloStatusCategory": "DESTINATION",
          "courierStatus": "Estimated Time of Arrival",
          "location": "Ambarli",
          "locationCode": "TRAMR",
          "terminalName": "Marport Ambarli",
          "locationCountryCode": "TR",
          "locationCoordinates": {
            "lat": 40.9667,
            "lng": 28.6833
          },
          "activityTimestamp": "2026-10-30T06:00:00Z",
          "eventType": "EXPECTED",
          "vesselName": "MSC ARIANE",
          "voyageNumber": "IP243A",
          "transportMode": "VESSEL",
          "detectionSource": null
        }
      ],
      "aboardVessel": true,
      "nextPlannedVessel": {
        "vesselName": "MSC ARIANE",
        "voyageNumber": "IP243A",
        "plannedAt": "2026-10-27T18:00:00Z",
        "portName": "Piraeus",
        "portCode": "GRPIR"
      }
    }
  ],
  "airShipments": [],
  "vesselPosition": {
    "vesselName": "MSC MARTINA",
    "latitude": 34.9123,
    "longitude": 25.6342,
    "heading": 318,
    "source": "LIVE",
    "reportedAt": "2026-10-22T05:41:00Z",
    "ageHours": 3
  }
}

06 · Vessels & ports

Vessels

Follow a vessel’s voyage — live position, ETA changes and port calls — exactly like the app’s Vessel Tracking page.

Vessel tracking follows a ship rather than a container: its AIS position, the destination and ETA its crew broadcasts, and every port call. Use it for vessels you charter, or when you only know the ship.

Cost
2 tracking credits per voyage, charged when you start following — free when one of your tracked containers is on the vessel.
Refunds
None: completing or removing a follow doesn’t return credits.
Limit
50 active follows per organization.
Voyage end
Arrival at the broadcast destination, or 7 days idle in port; a reminder at day 45 and an automatic end at day 60.

Quote a follow

New · 2026-10-22
POST/v1/vessels/follows/quote

What following this vessel would cost, before you commit — including the next voyage of a vessel whose follow you completed. Same body as follow; customer is ignored. Changes nothing.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Body

namestringrequired

The vessel name, up to 100 characters.

imostring

IMO number, 7 digits. Send imo or mmsi — a name alone can match several ships.

mmsistring

MMSI, 9 digits.

Request

curl -X POST "https://api.navlo.io/v1/vessels/follows/quote" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NORDIC AURORA",
    "imo": "9734512"
  }'

Response

200 OK
{
  "credits": 2,
  "covered": false,
  "alreadyTracking": false,
  "enoughCredits": true
}

Response fields

creditsnumber

Tracking credits the follow would charge: 2, or 0 when covered or already followed.

coveredboolean

true when one of your tracked containers is on this vessel — following is free.

alreadyTrackingboolean

true when you already follow it — following again returns that follow at no charge.

enoughCreditsboolean

Whether your balance covers it.

Errors

StatusMessageWhen
400IMO must be 7 digitsMalformed imo.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Follow a vessel

New · 2026-10-22
POST/v1/vessels/follows

Starts following the vessel’s current voyage and charges for it. Following a vessel you already follow returns that follow without a charge (with customer, it sets or replaces the follow’s customer); following one whose voyage you completed starts — and charges — a new voyage. Always 201.

Auth  X-API-KeyRate limit  60 / min per keyReturns  201 Created

Body

namestringrequired

The vessel name, up to 100 characters.

imostring

IMO number, 7 digits. Send imo or mmsi — a name alone can match several ships.

mmsistring

MMSI, 9 digits.

vesselTypestring

As returned by search.

flagstring

As returned by search.

customerobject

Attribute the credits to a customer — { "ref", "name" } or { "id" }. Absent or null leaves the follow’s customer as it is.

customer.iduuid

A Navlo customer id from GET /v1/customers. Wins when both id and ref are sent.

customer.refstring

Your own code for the customer (max 100 characters, case-insensitive, trimmed). An unknown ref creates the customer.

customer.namestring

Name 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/vessels/follows" \
  -H "X-API-Key: $NAVLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NORDIC AURORA",
    "imo": "9734512",
    "mmsi": "636019274",
    "vesselType": "Container Ship",
    "flag": "LR",
    "customer": {
      "ref": "C-1042"
    }
  }'

Response

201 Created
{
  "id": "7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7",
  "status": "ACTIVE",
  "state": "IN_TRANSIT",
  "vessel": {
    "imo": "9734512",
    "mmsi": "636019274",
    "name": "NORDIC AURORA",
    "vesselType": "Container Ship",
    "flag": "LR",
    "callsign": "D5QK7",
    "yearBuilt": 2017,
    "grossTonnage": 94511,
    "lengthMeters": 299.9,
    "widthMeters": 48.2
  },
  "position": {
    "latitude": 13.1048,
    "longitude": 48.7431,
    "courseDegrees": 262.4,
    "speedKnots": 17.2,
    "navStatus": "Under way using engine",
    "reportedAt": "2026-10-22T07:58:00Z"
  },
  "destination": "TR AMR",
  "destinationPort": {
    "name": "Ambarli",
    "locode": "TRAMR",
    "countryCode": "TR",
    "arrivedAt": null,
    "departedAt": null
  },
  "eta": "2026-11-02T04:00:00Z",
  "firstEta": "2026-10-31T22:00:00Z",
  "etaChangeCount": 2,
  "delayed": true,
  "overdue": false,
  "currentPort": null,
  "lastPort": {
    "name": "Singapore",
    "locode": "SGSIN",
    "countryCode": "SG",
    "arrivedAt": null,
    "departedAt": "2026-10-09T16:20:00Z"
  },
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "followedBy": {
    "name": "Elif Yılmaz",
    "email": "elif.yilmaz@forwarder.example"
  },
  "createdAt": "2026-10-05T09:12:44Z",
  "completedAt": null
}

Response fields

iduuid

Follow id.

statusenum

ACTIVE while Navlo follows the voyage; COMPLETED when it ended.

ACTIVECOMPLETED
stateenum

What the vessel is doing now. UNKNOWN after 24 hours without a signal.

IN_TRANSITIN_PORTAT_ANCHORSTOPPEDUNKNOWN
vesselobject

The ship: imo, mmsi, name, vesselType, flag (ISO alpha-2), callsign, yearBuilt, grossTonnage, lengthMeters, widthMeters — any can be null.

positionobjectnullable

Latest AIS position: latitude, longitude, courseDegrees, speedKnots, navStatus and reportedAt (the AIS fix, UTC).

destinationstringnullable

The destination the crew entered in AIS, as broadcast.

destinationPortobjectnullable

That destination resolved to a port. Both times are null while the voyage runs; on a completed follow arrivedAt is the actual arrival: name, locode, countryCode, arrivedAt, departedAt (UTC).

etatimestampnullable

The vessel’s current ETA there (UTC); null once completed.

firstEtatimestampnullable

The ETA when you started following.

etaChangeCountinteger

How often the ETA has changed since.

delayedboolean

true when the ETA is more than 24 hours later than firstEta.

overdueboolean

true when the ETA passed more than 24 hours ago and the vessel is not in port.

currentPortobjectnullable

The port the vessel is in, with arrivedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

lastPortobjectnullable

The last port it left, with departedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

customerobjectnullable

The customer its credits are attributed to: { id, ref, name, countryCode }.

followedByobject

Who started following: name, email — for API follows, the key’s creator.

createdAttimestamp

Followed since (UTC).

completedAttimestampnullable

When following ended (UTC).

Errors

StatusMessageWhen
400IMO must be 7 digitsMalformed imo.
400MMSI must be 9 digitsMalformed mmsi.
400Pick a vessel with an IMO or MMSI number — a name alone can match several shipsNeither imo nor mmsi.
400name: must not be blankname missing or blank.
400Unknown customer idcustomer.id is not one of your customers.
402Insufficient tracking credits in organization pool. Required: 2, Available: 1Not enough tracking credits.
409Your organization already follows 50 vessels — complete or remove one to add another50 active follows.
400Request body is missing or is not valid JSONThe body could not be parsed.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

List followed vessels

New · 2026-10-22
GET/v1/vessels/follows
Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Query parameters

pageintegerdefault 0

Zero-based page index.

sizeintegerdefault 20

Page size, 1–100.

Request

curl "https://api.navlo.io/v1/vessels/follows" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "follows": [
    {
      "id": "7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7",
      "status": "ACTIVE",
      "state": "IN_TRANSIT",
      "vessel": {
        "imo": "9734512",
        "mmsi": "636019274",
        "name": "NORDIC AURORA",
        "vesselType": "Container Ship",
        "flag": "LR",
        "callsign": "D5QK7",
        "yearBuilt": 2017,
        "grossTonnage": 94511,
        "lengthMeters": 299.9,
        "widthMeters": 48.2
      },
      "position": {
        "latitude": 13.1048,
        "longitude": 48.7431,
        "courseDegrees": 262.4,
        "speedKnots": 17.2,
        "navStatus": "Under way using engine",
        "reportedAt": "2026-10-22T07:58:00Z"
      },
      "destination": "TR AMR",
      "destinationPort": {
        "name": "Ambarli",
        "locode": "TRAMR",
        "countryCode": "TR",
        "arrivedAt": null,
        "departedAt": null
      },
      "eta": "2026-11-02T04:00:00Z",
      "firstEta": "2026-10-31T22:00:00Z",
      "etaChangeCount": 2,
      "delayed": true,
      "overdue": false,
      "currentPort": null,
      "lastPort": {
        "name": "Singapore",
        "locode": "SGSIN",
        "countryCode": "SG",
        "arrivedAt": null,
        "departedAt": "2026-10-09T16:20:00Z"
      },
      "customer": {
        "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
        "ref": "C-1042",
        "name": "Acme Trading Ltd.",
        "countryCode": "TR"
      },
      "followedBy": {
        "name": "Elif Yılmaz",
        "email": "elif.yilmaz@forwarder.example"
      },
      "createdAt": "2026-10-05T09:12:44Z",
      "completedAt": null
    }
  ]
}

Response fields

pageinteger

Page index.

sizeinteger

Page size.

totalElementsinteger

Follows.

totalPagesinteger

Pages at this size.

followsarray<object>

Active follows first, then completed ones; newest first within each. Fields as on follow.

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
GET/v1/vessels/follows/{id}

The follow with its ETA history, the latest 20 port calls and the latest 100 events.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The follow id.

Request

curl "https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7",
  "status": "ACTIVE",
  "state": "IN_TRANSIT",
  "vessel": {
    "imo": "9734512",
    "mmsi": "636019274",
    "name": "NORDIC AURORA",
    "vesselType": "Container Ship",
    "flag": "LR",
    "callsign": "D5QK7",
    "yearBuilt": 2017,
    "grossTonnage": 94511,
    "lengthMeters": 299.9,
    "widthMeters": 48.2
  },
  "position": {
    "latitude": 13.1048,
    "longitude": 48.7431,
    "courseDegrees": 262.4,
    "speedKnots": 17.2,
    "navStatus": "Under way using engine",
    "reportedAt": "2026-10-22T07:58:00Z"
  },
  "destination": "TR AMR",
  "destinationPort": {
    "name": "Ambarli",
    "locode": "TRAMR",
    "countryCode": "TR",
    "arrivedAt": null,
    "departedAt": null
  },
  "eta": "2026-11-02T04:00:00Z",
  "firstEta": "2026-10-31T22:00:00Z",
  "etaChangeCount": 2,
  "delayed": true,
  "overdue": false,
  "currentPort": null,
  "lastPort": {
    "name": "Singapore",
    "locode": "SGSIN",
    "countryCode": "SG",
    "arrivedAt": null,
    "departedAt": "2026-10-09T16:20:00Z"
  },
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "followedBy": {
    "name": "Elif Yılmaz",
    "email": "elif.yilmaz@forwarder.example"
  },
  "createdAt": "2026-10-05T09:12:44Z",
  "completedAt": null,
  "etaHistory": [
    {
      "destination": "TR AMR",
      "eta": "2026-10-31T22:00:00Z",
      "observedAt": "2026-10-05T09:12:44Z"
    },
    {
      "destination": "TR AMR",
      "eta": "2026-11-01T10:00:00Z",
      "observedAt": "2026-10-12T21:40:00Z"
    },
    {
      "destination": "TR AMR",
      "eta": "2026-11-02T04:00:00Z",
      "observedAt": "2026-10-19T03:10:00Z"
    }
  ],
  "portCalls": [
    {
      "name": "Singapore",
      "locode": "SGSIN",
      "countryCode": "SG",
      "arrivedAt": "2026-10-08T05:30:00Z",
      "departedAt": "2026-10-09T16:20:00Z",
      "current": false
    },
    {
      "name": "Port Klang",
      "locode": "MYPKG",
      "countryCode": "MY",
      "arrivedAt": "2026-10-06T11:05:00Z",
      "departedAt": "2026-10-07T02:45:00Z",
      "current": false
    }
  ],
  "events": [
    {
      "id": "c1d7a3e9-5b2f-4e84-9a06-3f8b1d5c7e20",
      "type": "ETA_UPDATED",
      "occurredAt": "2026-10-19T03:10:00Z",
      "portName": null,
      "destination": "TR AMR",
      "previousEta": "2026-11-01T10:00:00Z",
      "newEta": "2026-11-02T04:00:00Z"
    },
    {
      "id": "8f2b4d6a-1c9e-4a73-b5d0-e7a3c1f9b246",
      "type": "DEPARTED",
      "occurredAt": "2026-10-09T16:20:00Z",
      "portName": "Singapore",
      "destination": "TR AMR",
      "previousEta": null,
      "newEta": null
    },
    {
      "id": "4a9c1e7f-3d5b-4f28-8e60-b2d4f6a8c913",
      "type": "ARRIVED",
      "occurredAt": "2026-10-08T05:30:00Z",
      "portName": "Singapore",
      "destination": "SG SIN",
      "previousEta": null,
      "newEta": null
    }
  ]
}

Response fields

iduuid

Follow id.

statusenum

ACTIVE while Navlo follows the voyage; COMPLETED when it ended.

ACTIVECOMPLETED
stateenum

What the vessel is doing now. UNKNOWN after 24 hours without a signal.

IN_TRANSITIN_PORTAT_ANCHORSTOPPEDUNKNOWN
vesselobject

The ship: imo, mmsi, name, vesselType, flag (ISO alpha-2), callsign, yearBuilt, grossTonnage, lengthMeters, widthMeters — any can be null.

positionobjectnullable

Latest AIS position: latitude, longitude, courseDegrees, speedKnots, navStatus and reportedAt (the AIS fix, UTC).

destinationstringnullable

The destination the crew entered in AIS, as broadcast.

destinationPortobjectnullable

That destination resolved to a port. Both times are null while the voyage runs; on a completed follow arrivedAt is the actual arrival: name, locode, countryCode, arrivedAt, departedAt (UTC).

etatimestampnullable

The vessel’s current ETA there (UTC); null once completed.

firstEtatimestampnullable

The ETA when you started following.

etaChangeCountinteger

How often the ETA has changed since.

delayedboolean

true when the ETA is more than 24 hours later than firstEta.

overdueboolean

true when the ETA passed more than 24 hours ago and the vessel is not in port.

currentPortobjectnullable

The port the vessel is in, with arrivedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

lastPortobjectnullable

The last port it left, with departedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

customerobjectnullable

The customer its credits are attributed to: { id, ref, name, countryCode }.

followedByobject

Who started following: name, email — for API follows, the key’s creator.

createdAttimestamp

Followed since (UTC).

completedAttimestampnullable

When following ended (UTC).

etaHistoryarray<object>

Every ETA the vessel broadcast on this voyage, oldest first: destination, eta, observedAt.

portCallsarray<object>

This voyage’s port calls, newest first: name, locode, countryCode, arrivedAt, departedAt, current.

eventsarray<object>

What happened, newest first: id, type, occurredAt, portName, destination, previousEta, newEta.

events[].typeenum

Event kind.

DEPARTEDARRIVEDIN_TRANSITIN_PORTAT_ANCHORSTOPPEDETA_UPDATEDAPPROACHINGSIGNAL_LOSTVOYAGE_COMPLETEDTRACKING_REMINDERTRACKING_ENDED

Errors

StatusMessageWhen
404Vessel not foundUnknown or removed follow, or another organization’s.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Complete a follow

New · 2026-10-22
POST/v1/vessels/follows/{id}/complete

Stops following the voyage now. The follow and its history stay. No credits are returned. Idempotent.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

iduuidrequired

The follow id.

Request

curl -X POST "https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7/complete" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "id": "7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7",
  "status": "COMPLETED",
  "state": "IN_TRANSIT",
  "vessel": {
    "imo": "9734512",
    "mmsi": "636019274",
    "name": "NORDIC AURORA",
    "vesselType": "Container Ship",
    "flag": "LR",
    "callsign": "D5QK7",
    "yearBuilt": 2017,
    "grossTonnage": 94511,
    "lengthMeters": 299.9,
    "widthMeters": 48.2
  },
  "position": {
    "latitude": 13.1048,
    "longitude": 48.7431,
    "courseDegrees": 262.4,
    "speedKnots": 17.2,
    "navStatus": "Under way using engine",
    "reportedAt": "2026-10-22T07:58:00Z"
  },
  "destination": "TR AMR",
  "destinationPort": {
    "name": "Ambarli",
    "locode": "TRAMR",
    "countryCode": "TR",
    "arrivedAt": null,
    "departedAt": null
  },
  "eta": "2026-11-02T04:00:00Z",
  "firstEta": "2026-10-31T22:00:00Z",
  "etaChangeCount": 2,
  "delayed": true,
  "overdue": false,
  "currentPort": null,
  "lastPort": {
    "name": "Singapore",
    "locode": "SGSIN",
    "countryCode": "SG",
    "arrivedAt": null,
    "departedAt": "2026-10-09T16:20:00Z"
  },
  "customer": {
    "id": "c7d2a9e4-3f1b-4e8a-9b6c-1d5e7f3a2b90",
    "ref": "C-1042",
    "name": "Acme Trading Ltd.",
    "countryCode": "TR"
  },
  "followedBy": {
    "name": "Elif Yılmaz",
    "email": "elif.yilmaz@forwarder.example"
  },
  "createdAt": "2026-10-05T09:12:44Z",
  "completedAt": "2026-10-22T09:40:00Z"
}

Response fields

iduuid

Follow id.

statusenum

ACTIVE while Navlo follows the voyage; COMPLETED when it ended.

ACTIVECOMPLETED
stateenum

What the vessel is doing now. UNKNOWN after 24 hours without a signal.

IN_TRANSITIN_PORTAT_ANCHORSTOPPEDUNKNOWN
vesselobject

The ship: imo, mmsi, name, vesselType, flag (ISO alpha-2), callsign, yearBuilt, grossTonnage, lengthMeters, widthMeters — any can be null.

positionobjectnullable

Latest AIS position: latitude, longitude, courseDegrees, speedKnots, navStatus and reportedAt (the AIS fix, UTC).

destinationstringnullable

The destination the crew entered in AIS, as broadcast.

destinationPortobjectnullable

That destination resolved to a port. Both times are null while the voyage runs; on a completed follow arrivedAt is the actual arrival: name, locode, countryCode, arrivedAt, departedAt (UTC).

etatimestampnullable

The vessel’s current ETA there (UTC); null once completed.

firstEtatimestampnullable

The ETA when you started following.

etaChangeCountinteger

How often the ETA has changed since.

delayedboolean

true when the ETA is more than 24 hours later than firstEta.

overdueboolean

true when the ETA passed more than 24 hours ago and the vessel is not in port.

currentPortobjectnullable

The port the vessel is in, with arrivedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

lastPortobjectnullable

The last port it left, with departedAt: name, locode, countryCode, arrivedAt, departedAt (UTC).

customerobjectnullable

The customer its credits are attributed to: { id, ref, name, countryCode }.

followedByobject

Who started following: name, email — for API follows, the key’s creator.

createdAttimestamp

Followed since (UTC).

completedAttimestampnullable

When following ended (UTC).

Errors

StatusMessageWhen
404Vessel not foundUnknown or removed follow, or another organization’s.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Remove a follow

New · 2026-10-22
DELETE/v1/vessels/follows/{id}

Stops following and removes it from your list. Credits already charged stay in the usage report.

Auth  X-API-KeyRate limit  60 / min per keyReturns  204 No Content

Path parameters

iduuidrequired

The follow id.

Request

curl -X DELETE "https://api.navlo.io/v1/vessels/follows/7c1e4a9d-3b6f-4d28-9e05-a2f8c6b1d3e7" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

204 No Content

No body.

Errors

StatusMessageWhen
404Vessel not foundUnknown or removed follow, or another organization’s.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
Tracking containers already shows the vessel they are on: vessel on GET /v1/shipments/{id} gives its last position for free. Follow a vessel only when you need the ship itself.

06 · Vessels & ports

Ports & airports

Port congestion from live AIS, and current airport delays — the data behind the map layers in Navlo Pulse.

The congestion and delay data the app draws on the Navlo Pulse map and uses in its risk scores. These reads are free. When the data is temporarily unavailable you get 200 with "available": false and empty data — never an error — so a dashboard keeps running.

Port congestion

New · 2026-10-22
GET/v1/ports/congestion

Current congestion, measured from AIS: vessels at anchor and in port and how long they stay, against each port’s own baseline. By default only the ports your live shipments load at, call at or discharge at — the Pulse map’s set; scope=all returns every monitored port. Readings are from the last 36 hours, most congested first.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Query parameters

scopeenumdefault shipments

shipments: ports of your live ocean shipments (empty when you have none). all: every monitored port.

shipmentsall
countrystring

ISO alpha-2 country, e.g. TR (matched on the UN/LOCODE prefix).

limitintegerdefault 100

Maximum ports, 1–500 (values outside are clamped).

Request

curl "https://api.navlo.io/v1/ports/congestion?scope=shipments" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

{
  "available": true,
  "scope": "shipments",
  "ports": [
    {
      "locode": "GRPIR",
      "name": "Piraeus",
      "countryCode": "GR",
      "latitude": 37.9421,
      "longitude": 23.6465,
      "congestionLevel": "HIGH",
      "calibrating": false,
      "vesselsAtAnchorage": 14,
      "medianWaitHours": 43.6,
      "vesselsInPort": 9,
      "medianTimeInPortHours": 38.2,
      "baselineDays": 30,
      "sampledAt": "2026-10-22T07:41:12.345Z"
    },
    {
      "locode": "TRAMR",
      "name": "Ambarli",
      "countryCode": "TR",
      "latitude": 40.9667,
      "longitude": 28.6833,
      "congestionLevel": "MEDIUM",
      "calibrating": false,
      "vesselsAtAnchorage": 6,
      "medianWaitHours": 18.5,
      "vesselsInPort": 11,
      "medianTimeInPortHours": 26.4,
      "baselineDays": 30,
      "sampledAt": "2026-10-22T07:41:12.345Z"
    }
  ]
}

Response fields

availableboolean

false when congestion data is temporarily unavailable — ports is then empty.

scopeenum

The scope used.

shipmentsall
portsarray<object>

Sorted by level (CRITICAL first), then vessels at anchorage.

ports[].locodestring

UN/LOCODE.

ports[].namestring

Port name.

ports[].countryCodestring

ISO alpha-2 (the LOCODE’s first two letters).

ports[].latitudenumber

Port centre.

ports[].longitudenumber

Port centre.

ports[].congestionLevelenum

Against the port’s own normal.

LOWMEDIUMHIGHCRITICAL
ports[].calibratingboolean

true while the port has under 14 days of baseline — read the level with care.

ports[].vesselsAtAnchorageintegernullable

Vessels waiting at anchor; null where Navlo doesn’t measure the port’s anchorage.

ports[].medianWaitHoursnumbernullable

Median hours vessels wait at anchor; null when none is waiting or the anchorage isn’t measured.

ports[].vesselsInPortintegernullable

Vessels at berth.

ports[].medianTimeInPortHoursnumbernullable

Median hours vessels spend in port.

ports[].baselineDaysintegernullable

Days of history behind the port’s normal.

ports[].sampledAttimestamp

Time of the reading (UTC).

Errors

StatusMessageWhen
400scope must be one of: shipments, allAnother scope.
400country must be an ISO 3166-1 alpha-2 code, e.g. TRA country that isn’t two letters.
400Invalid value for limitlimit is not a number.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.
GET/v1/ports/{locode}/congestion

One reading per day for a port, oldest first — for trend charts and for judging whether today is unusual.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Path parameters

locodestringrequired

UN/LOCODE of the port, e.g. GRPIR.

Query parameters

daysintegerdefault 30

Days of history, 1–90 (values outside are clamped).

Request

curl "https://api.navlo.io/v1/ports/GRPIR/congestion?days=3" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "available": true,
  "locode": "GRPIR",
  "name": "Piraeus",
  "countryCode": "GR",
  "latitude": 37.9421,
  "longitude": 23.6465,
  "days": 3,
  "history": [
    {
      "sampledAt": "2026-10-20T07:38:09Z",
      "congestionLevel": "MEDIUM",
      "calibrating": false,
      "vesselsAtAnchorage": 8,
      "medianWaitHours": 21.4,
      "vesselsInPort": 9,
      "medianTimeInPortHours": 38.2,
      "baselineDays": 30
    },
    {
      "sampledAt": "2026-10-21T07:40:11Z",
      "congestionLevel": "HIGH",
      "calibrating": false,
      "vesselsAtAnchorage": 12,
      "medianWaitHours": 36.8,
      "vesselsInPort": 9,
      "medianTimeInPortHours": 38.2,
      "baselineDays": 30
    },
    {
      "sampledAt": "2026-10-22T07:41:12Z",
      "congestionLevel": "HIGH",
      "calibrating": false,
      "vesselsAtAnchorage": 14,
      "medianWaitHours": 43.6,
      "vesselsInPort": 9,
      "medianTimeInPortHours": 38.2,
      "baselineDays": 30
    }
  ]
}

Response fields

availableboolean

false when the history could not be read; history is then empty.

locodestring

UN/LOCODE.

namestring

Port name.

countryCodestring

ISO alpha-2.

latitudenumber

Port centre.

longitudenumber

Port centre.

daysinteger

Days covered.

historyarray<object>

Daily readings, oldest first.

history[].sampledAttimestamp

Time of the reading (UTC).

history[].congestionLevelenum

Against the port’s own normal.

LOWMEDIUMHIGHCRITICAL
history[].calibratingboolean

true while the port has under 14 days of baseline — read the level with care.

history[].vesselsAtAnchorageintegernullable

Vessels waiting at anchor; null where Navlo doesn’t measure the port’s anchorage.

history[].medianWaitHoursnumbernullable

Median hours vessels wait at anchor; null when none is waiting or the anchorage isn’t measured.

history[].vesselsInPortintegernullable

Vessels at berth.

history[].medianTimeInPortHoursnumbernullable

Median hours vessels spend in port.

history[].baselineDaysintegernullable

Days of history behind the port’s normal.

Errors

StatusMessageWhen
404Port not foundNavlo doesn’t monitor that port.
400locode must be a 5-character UN/LOCODE, e.g. TRAMRA malformed locode.
400Invalid value for daysdays is not a number.
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Airport delays

New · 2026-10-22
GET/v1/airports/delays

Average delay and ground stops at the airports Navlo monitors, from readings in the last 3 hours — ground stops first, then the longest delays. The list can be empty when no airport has a current reading.

Auth  X-API-KeyRate limit  60 / min per keyReturns  200 OK

Request

curl "https://api.navlo.io/v1/airports/delays" \
  -H "X-API-Key: $NAVLO_API_KEY"

Response

200 OK
{
  "available": true,
  "airports": [
    {
      "iataCode": "AMS",
      "name": "Amsterdam Airport Schiphol",
      "latitude": 52.3086,
      "longitude": 4.7639,
      "delayed": true,
      "averageDelayMinutes": 34,
      "groundStop": false,
      "groundStopReason": null,
      "sampledAt": "2026-10-22T08:05:00Z"
    },
    {
      "iataCode": "IST",
      "name": "Istanbul Airport",
      "latitude": 41.2753,
      "longitude": 28.7519,
      "delayed": false,
      "averageDelayMinutes": 0,
      "groundStop": false,
      "groundStopReason": null,
      "sampledAt": "2026-10-22T08:05:00Z"
    }
  ]
}

Response fields

availableboolean

false when delay data is temporarily unavailable; the list is then empty.

airportsarray<object>

One per airport with a recent reading.

airports[].iataCodestring

IATA code.

airports[].namestringnullable

Airport name.

airports[].latitudenumbernullable

Location.

airports[].longitudenumbernullable

Location.

airports[].delayedboolean

true with any average delay or a ground stop.

airports[].averageDelayMinutesintegernullable

Average of departure and arrival delay, in minutes.

airports[].groundStopboolean

true while departures are held.

airports[].groundStopReasonstringnullable

The reason given for the ground stop.

airports[].sampledAttimestamp

Time of the reading (UTC).

Errors

StatusMessageWhen
401Invalid or revoked API keyThe X-API-Key header is missing, wrong or revoked.
429Rate limit exceeded (60 requests/minute)Over the per-key budget; wait Retry-After seconds.

Using it

  • Warn about shipments heading into a congested port: match ports[].locode against containers[].destination.code on your shipments — scope=shipments already narrows the list to those ports.
  • Navlo already folds congestion into each shipment’s risk and Navlo ETA — read those when you want the conclusion rather than the raw reading.
  • Readings change slowly; caching them for 15 minutes loses nothing.

07 · Reference

Statuses & time zones

What each status and milestone code means, and how to read the timestamps — carrier times are local to the port.

Shipment status

discovering
Navlo is finding the carrier and the first data. A shipment without carrier data yet stays here while Navlo keeps trying.
resolving
The carrier is known and the first full data set is being built.
active
Tracked and refreshed on Navlo’s polling schedule.
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.
completed
Finished — delivered, or the empty container returned. Polling has ended.
stopped
Navlo can’t track this identifier — an unsupported carrier, or a number no carrier recognises. Polling has ended.
  • The usual path is discovering → resolving → active → completed; air waybills go tracking → active → completed.
  • There is no failed status. An identifier that hasn’t resolved stays discovering while Navlo keeps trying — and if it never resolves, the credit is refunded and tracking stops.
  • Pausing with /stop doesn’t change status; it only halts polling (details.pollingStoppedAt).

Milestone codes

containers[].status, events[].status, airShipments[].status and webhook details.milestone.code use Navlo’s milestone codes — the same codes for every carrier. The list grows as carriers add events: show name (or the carrier’s own text) for codes you don’t recognise.

EMPTY_CONTAINER
Empty pickup or release. Phase PRE_SHIPMENT.
GATE_IN
Container entered the origin terminal. ORIGIN.
EXPORT_PROCESSING
Export received, ready to load. ORIGIN.
LOADED
Loaded on the vessel or transport. TRANSIT.
DEPARTED
Vessel, flight or transport left. TRANSIT.
IN_TRANSIT
Moving between locations. TRANSIT.
TRANSSHIPMENT
At an intermediate port. TRANSIT.
ARRIVED
Vessel, flight or transport arrived. DESTINATION.
DISCHARGED
Unloaded from the vessel. DESTINATION.
IMPORT_PROCESSING
Import positioning, customs. DESTINATION.
READY_FOR_DELIVERY
Available for pickup. DESTINATION.
GATE_OUT
Left the destination terminal for delivery. DESTINATION.
DELIVERED
Final delivery done. COMPLETED.
BOOKED
AIR: booked on a flight. PRE_SHIPMENT.
RECEIVED_FROM_SHIPPER
AIR: cargo accepted by the airline. ORIGIN.
CONSIGNEE_NOTIFIED
AIR: consignee told the cargo is ready. DESTINATION.
PARTIALLY_DELIVERED
AIR: some pieces of a split consignment delivered. DESTINATION.

The phase (PRE_SHIPMENT, ORIGIN, TRANSIT, DESTINATION, COMPLETED) is also what email subscribers choose their events by.

Time zones

  • System times are UTC — createdAt, recordedAt, computedAt, occurredAt and every other time Navlo itself records. They end in Z and mean it.
  • Carrier times are local to the place — ETD, ATD, ETA, ATA, event timestamps, flight times and details.eventAt carry the wall-clock time at the port or airport, written with a Z suffix. Display them exactly as they are, without converting to the viewer’s time zone: a departure from Shanghai at 03:40 local reads 2026-09-27T03:40:00Z and should show as 03:40.
  • Air times are airport-local too.
  • For arithmetic across zones (transit time), the embed payload also carries the four schedule times as true UTC instants (…Utc fields); don’t display those.
  • Dates without a time (YYYY-MM-DD in the usage report) are UTC days.
// Show a carrier time as written: read it as UTC so nothing shifts it.
const eta = new Date('2026-10-30T06:00:00Z')
const label = eta.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'medium', timeStyle: 'short' })
// → "30 Oct 2026, 06:00" — 06:00 at Ambarli, wherever the viewer is

Other values

events[].type
ACTUAL happened · EXPECTED carrier projection · null when unknown.
vessel.source
LIVE fresh fix · STALE old fix of the same ship · LAST_KNOWN last port, not a ship.
risk.level
LOW · MEDIUM · HIGH · null when stale or unknown.
mode
OCEAN · AIR
etaHistory[].field
ETA · ETD · ATA · ATD

07 · Reference

OpenAPI & Postman

A machine-readable description of the whole API, generated from the code — import it into Postman or generate a client.

OpenAPI 3
https://api.navlo.io/v1/openapi.json — no key needed.
These docs as JSON
developer-docs.json — every page, endpoint and example.

The OpenAPI 3.1 document is generated from the API’s own code on every release, so it can’t drift from what the API does. It covers every /v1 endpoint and GET /api/embed/resolve, with the ApiKeyAuth (X-API-Key) and EmbedKeyAuth (X-Embed-Key) security schemes, and describes the seven webhook events under webhooks.

Postman

  1. 1Download the collection and import it (File → Import).
  2. 2Open the collection’s Variables and set apiKey to your nvl_… key (and embedKey for the embed request). baseUrl is https://api.navlo.io.
  3. 3Requests are grouped by area — Shipments, Webhooks, Navlo AI… — with path variables ready to fill in.

Generating a client

Shell
# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate \
  -i https://api.navlo.io/v1/openapi.json -g typescript-fetch -o ./navlo-client

# Python
npx @openapitools/openapi-generator-cli generate \
  -i https://api.navlo.io/v1/openapi.json -g python -o ./navlo-client-python
Generated clients deserialise strictly by default. Turn on “ignore unknown properties” (or its equivalent) so new response fields never break you — see the Compatibility promise.
Streamed Navlo AI answers are not a request/response shape OpenAPI describes well: the Navlo AI page documents every event. Webhook payloads are in the document’s webhooks section and on the Webhooks page.

07 · Reference

Changelog

What changed in the API, newest first. Every change to /v1 is additive.

22 October 2026

The API now does what the app does. Requests without the new parameters answer exactly as before. The old data block in webhook payloads is deprecated: it is still sent until 16 November 2026, then removed.

  • Customers on requests — customer ({ "ref", "name" } or { "id" }) on POST /v1/shipments, batch items, Navlo AI and vessel follows; PATCH /v1/shipments/{id}; the Customers API.
  • Shipment list — filters (status, mode, carrier, customerId, customerRef, tag, risk, ETA and creation ranges, updatedSince), sort and include.
  • Shipment intelligence — include= on the detail: risk, recommendations, Navlo ETA, D&D, carbon, route alerts, customer, tags, details.
  • Shipment actions — notes, documents, share links, email subscribers, mute, complete, change carrier; the Tags API.
  • Reports & export — CSV/XLSX export and POST /v1/reports.
  • Usage & credits — GET /v1/credits and GET /v1/usage (JSON or CSV, per customer, shipment or day) for re-billing.
  • Navlo AI — POST /v1/ai/ask and conversations, streaming by default.
  • Webhooks — managed over the API (list, read, create, update, rotate, delete, deliveries, test events), a shipment snapshot with mode, status, carrier, customer, route, ETA and vessel, a fixed details object per topic (the old data block is deprecated and goes away on 16 November 2026), and the events in the OpenAPI document — every topic, shipment.discovery_finished included, fires for ocean and air shipments.
  • Vessels, ports & airports — vessel follows, port congestion and airport delays.
  • Embed — GET /api/embed/resolve answers only what the tracking box shows; ids are positions in the answer (c1, c1-e1).
  • Errors and limits — every error body has message; X-RateLimit-* headers on every response; Navlo AI has its own 10-a-minute budget and runs at most 2 answers at once per organization; bodies over 1 MB (uploads over 10 MB) answer 413; the tracking widget allows 60 lookups a minute per key; an organization has at most 10 live keys and emails at most 500 share recipients per 24 hours (caps per organization).
  • Statuses — the air-only tracking status is documented; list, export and report filters treat it as active.
  • OpenAPI & Postman — GET /v1/openapi.json and a Postman collection.

7 October 2026

  • A blank identifier is rejected with 400 identifier must not be blank.

22 September 2026

  • Air shipments on the detail: airShipments[] with flights, air events with flight, pieces and weight, and air legs on the route.
  • mode is required on create; an unambiguous identifier (container number, AWB with a valid check digit) wins over the value sent.

22 August 2026

  • GET /v1/shipments/{id}/route (GeoJSON), POST …/stop, POST …/resume and DELETE /v1/shipments/{id}.
  • etaHistory and vessel on the shipment detail.
  • Webhooks.

4 August 2026

  • Rate limit raised from 20 to 60 requests a minute per key.

1 August 2026

  • The API launches: start tracking (single and batch), shipment list and detail, and the embed widget.

Questions or missing capability? contact@navlo.io