Panvaya API

All endpoints are served under a single base URL and return JSON. Every request must include your API key in the X-API-Key header. Live and sandbox keys use the same real provider flow, rate limit, and credit rules; the environment label only identifies the key used for the request.

https://api.panvaya.com/api/v1

Create a key from your dashboard under API & Integration. The full key is shown once at creation, so store it securely. Pass it on every request:

X-API-Key: pv_live_your_key_here

Live keys are prefixed pv_live_ and sandbox keys pv_test_. You may also send the key as Authorization: Bearer <key>.

Signed-in Free and Premium workspaces include 10 API trial credits. Enterprise uses a purchased credit pool for an exact 30-day period, priced at 120 credits per $1 USD. Each enabled product has an organization-specific per-success credit cost. A Sea Tracking cache hit is a successful, billed response. Failed and 404 NOT_FOUND calls are never billed. Live and sandbox keys are billed the same way. Sea Tracking and CO2 Calculator use one credit per successful response by default, while Sailing Schedules uses five; your workspace may have different product costs. Track your consumption on the Integration page. When the allotment is spent, requests return 402 QUOTA_EXCEEDED until the next 30-day credit period begins. No reset job is needed: the first API request on or after the reset time advances the period before it is evaluated.

Create Shipment uses two separate quotas. The product is included in normal product grants and can also be configured by a superadmin. Creating a shipment consumes no API credit and writes no API usage row. Its first successful asynchronous track consumes one normal web ocean shipment quota unit. Each successful Get Shipment or List Shipments request consumes the configured Create Shipment API credit cost, one credit by default, and appears in the API usage report. Pending GET responses are successful and billed; validation, authorization, quota, and not-found failures are not.

Each key has its own token-bucket rate limit, set to 10 requests per minute by default. Tokens refill continuously rather than all at once at the next minute. Every authenticated API request uses one rate-limit token, whether it ultimately succeeds or fails.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining. A throttled request returns 429 RATE_LIMIT_EXCEEDED with Retry-After in seconds.

Returns the organization credit limit, used credits, remaining credits, exact 30-day reset time, and enabled products with their per-call costs. This account endpoint is not billed.

curl "https://api.panvaya.com/api/v1/usage" \
  -H "X-API-Key: pv_live_your_key_here"

Downloads the success-only billing ledger as CSV. Filters are organization-scoped and optional. This reporting endpoint is not billed.

curl "https://api.panvaya.com/api/v1/usage/report?productCode=SEA_TRACKING&from=2026-08-01&to=2026-08-07" \
  -H "X-API-Key: pv_live_your_key_here" \
  -o panvaya-api-usage.csv

Look up an ocean container, bill of lading, or booking. Supply at least one reference; bol and bk cannot be combined. A container supplied with either document reference returns only that container from the document tracking result. Every reference type reuses the same successful response for two hours when fresh. Container, B/L, and booking responses all use data.containers; a container lookup normally contains one item, while B/L and booking lookups may contain several. Events reference shared locations and transports by response-local ids, keeping the response normalized and compact. Each container exposes the resolvediso_code, canonical dimensions, and capabilities underequipment. Each event usesid and event_time, and references transport details through transport_id. Transport mode and voyage are returned once in data.transports, not repeated in each event. Declared fields are always returned, withnull when a value is unavailable. Every successful response is billed and its normalized reference is written to the usage ledger.

curl -X POST https://api.panvaya.com/api/v1/track/ocean \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"container": "MSKU8094830"}'

curl -X POST https://api.panvaya.com/api/v1/track/ocean \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bol": "MAEU123456789"}'

curl -X POST https://api.panvaya.com/api/v1/track/ocean \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bk": "MAEU123456789"}'

curl -X POST https://api.panvaya.com/api/v1/track/ocean \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"container": "MSKU8094830", "include_route_data": true}'

Signed-in response example with include_route_data enabled

Creates a shipment for the user who created the API key, starts tracking asynchronously, and makes it visible on that user's Shipments page. It uses the same validation, duplicate checks, carrier support checks, and web ocean quota rules as a UI upload. The response is 202 Accepted with an opaque shipment_id UUID and a Location header. The Create Shipment API product must be enabled, but POST does not require an available API credit. Creation itself consumes no API credit and creates no API usage row; the first successful background track consumes one web ocean shipment quota unit.

curl -X POST https://api.panvaya.com/api/v1/shipments/ocean \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"container": "MSKU8094830", "shipping_line_scac": "MAEU"}'

Returns a shipment only when it belongs to the API-key creator. While tracking is running, the endpoint returns 202 and a null tracking field. Once finished it returns the normalized core tracking response without UI-only CO2 or exception fields. Every successful GET, including a pending response, consumes the configured Create Shipment product cost and records the shipment UUID in API usage.

curl "https://api.panvaya.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: pv_live_your_key_here"

Returns all non-deleted shipments belonging to the API-key creator, including shipments created through either the UI or API. Results use user_shipment as the source of truth and are ordered by created_at descending. Each successful page request consumes the configured Create Shipment product cost and is recorded in API usage.

curl "https://api.panvaya.com/api/v1/shipments?page=0&size=20" \
  -H "X-API-Key: pv_live_your_key_here"

{
  "data": [{
    "shipment_id": "550e8400-e29b-41d4-a716-446655440000",
    "references": {
      "container": "MSKU8094830",
      "bol": null,
      "bk": null
    },
    "shipping_line": { "scac": "MAEU", "name": "Maersk" },
    "status": "IN_TRANSIT",
    "tracking_status": "SUCCESS",
    "tracking_error": null,
    "created_at": "2026-08-11T16:30:00",
    "updated_at": "2026-08-11T16:35:00"
  }],
  "pagination": {
    "page": 0,
    "size": 20,
    "total_elements": 1,
    "total_pages": 1,
    "first": true,
    "last": true
  }
}

Returns supported carriers and their SCAC codes for the optional shipping_line_scac parameter. Panvaya tracking supports ocean containers, bills of lading, and booking references.

curl "https://api.panvaya.com/api/v1/carriers" \
  -H "X-API-Key: pv_live_your_key_here"

Look up one of the 11 Incoterms 2020 trade terms by code. The response includes the full name, applicable transport mode, risk and cost transfer points, and a 12-stage responsibility breakdown. View the Incoterms guide

curl "https://api.panvaya.com/api/v1/incoterms/FOB" \
  -H "X-API-Key: pv_live_your_key_here"

Search normalized point-to-point schedules across the existing carrier schedule providers. Results are sorted by departure and share the same per-carrier cache as the dashboard schedule search. Try sailing schedules

curl -X POST "https://api.panvaya.com/api/v1/schedules/search" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin":"CNSHA","destination":"NLRTM","date":"2026-09-01","carriers":["MAEU"]}'

Calculate carbon emissions for ocean and air freight shipments between any two locations. Uses GLEC Framework emission factors with distance-based routing uplift. Returns CO2e in kilograms and tonnes, the emission factor applied, equivalent car-km driven, and trees needed to offset. Try the carbon calculator

curl -X POST "https://api.panvaya.com/api/v1/carbon/calculate" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin": "NLRTM", "destination": "SGSIN", "weightKg": 18000, "mode": "ocean"}'

Get port congestion metrics including vessel anchor wait times, berthing durations, approaching vessel counts, and TEU throughput for major ports worldwide. Panvaya refreshes the shared provider snapshot after 12 hours; every successful API response is billed. View the congestion map

curl "https://api.panvaya.com/api/v1/port-congestion?locode=SGSIN" \
  -H "X-API-Key: pv_live_your_key_here"

Errors use a consistent envelope with a stable, machine-readable code. Branch on the code, not the message text.

{
  "errors": [{
    "code": "INVALID_REQUEST",
    "title": "Invalid request",
    "detail": "One of container, bol, or bk is required."
  }]
}

Create a sandbox key (prefixed pv_test_) to keep test and production credentials separate. Sandbox requests use the same endpoints, external tracking flow, rate limit, and credit consumption as live keys.