Shipping
Base URL: https://app.trymaglev.com/api/v1. All endpoint families.
POST /shipping/estimate
Section titled “POST /shipping/estimate”Deterministic freight and landed cost estimate, China to US. Chargeable weight, cost band per mode with its published source, fuel surcharge range, transit days, the duty stack as of Sep 2026, and a landed range. Every number carries a basis; nothing is binding.
Required scope: shipping:read.
Authentication: bearer key.
| Field | Type | Required | Details |
|---|---|---|---|
cartons |
object[] | No | Min items 1. Max items 50 |
cartons[].lengthCm |
number | If parent supplied | Maximum 1000. Greater than 0 |
cartons[].widthCm |
number | If parent supplied | Maximum 1000. Greater than 0 |
cartons[].heightCm |
number | If parent supplied | Maximum 1000. Greater than 0 |
cartons[].weightKg |
number | If parent supplied | Maximum 2000. Greater than 0 |
cartons[].count |
integer | If parent supplied | Minimum 1. Maximum 10000 |
totals |
object | No | |
totals.grossWeightKg |
number | If parent supplied | Maximum 100000. Greater than 0 |
totals.volumeM3 |
number | If parent supplied | Minimum 0. Maximum 1000 |
originCity |
string | No | Min length 2. Max length 60 |
destination |
object | Yes | |
destination.country |
“US” | If parent supplied | |
destination.postcode |
string | No | Max length 10 |
destination.state |
string | No | Min length 2. Max length 2 |
destination.city |
string | No | Max length 60 |
modes |
string[] | No | Min items 1. Max items 3 |
declaredValueUsd |
number or null | No | |
hts |
string or null | No | |
productCategory |
string or null | No | |
batteries |
string | No | One of: none, contained, packed_with, standalone |
live |
boolean | No | Request optional market quotes; provider availability and additional limits apply. |
200 response schema
{ "type": "object", "properties": { "chargeableWeightKg": { "type": "object", "properties": { "air_express": { "type": "number" }, "air_freight": { "type": "number" }, "ocean_lcl": { "type": "number" } }, "required": [ "air_express", "air_freight", "ocean_lcl" ] }, "chargeable": { "type": "object", "properties": { "air_express": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] }, "air_freight": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] }, "ocean_lcl": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] } }, "required": [ "air_express", "air_freight", "ocean_lcl" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] }, "chargeableWeightKg": { "type": "number" }, "costUsdLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "costUsdHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseCostUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "ratePerKgUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "fuelSurchargePct": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "dangerousGoods": { "anyOf": [ { "type": "object", "properties": { "surchargeUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "surchargeUsd", "note" ] }, { "type": "null" } ] }, "transitDays": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "basis": { "type": "array", "items": { "type": "string" } }, "binding": { "const": false } }, "required": [ "mode", "chargeableWeightKg", "costUsdLow", "costUsdHigh", "baseCostUsd", "ratePerKgUsd", "fuelSurchargePct", "dangerousGoods", "transitDays", "basis", "binding" ] } }, "dutyStack": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratePct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "amountUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "applies", "conditional", "unknown", "terminated", "expired", "not_applicable" ] }, "appliesTo": { "anyOf": [ { "const": "all" }, { "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } } ] }, "basis": { "type": "string" }, "source": { "type": "string" } }, "required": [ "name", "ratePct", "amountUsd", "status", "appliesTo", "basis", "source" ] } }, "dutyEffectiveRatePct": { "type": "object", "properties": { "known": { "type": "number" }, "layersCounted": { "type": "array", "items": { "type": "string" } }, "layersUnknown": { "type": "array", "items": { "type": "string" } } }, "required": [ "known", "layersCounted", "layersUnknown" ] }, "landedRange": { "type": "object", "properties": { "lowUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "highUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "excludes": { "type": "array", "items": { "type": "string" } } }, "required": [ "lowUsd", "highUsd", "excludes" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "marketQuotes": { "anyOf": [ { "type": "object", "properties": { "attribution": { "type": "string" }, "link": { "type": "string" }, "fetchedAt": { "type": "string" }, "query": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "quantity": { "type": "number" }, "boxWeightKg": { "type": "number" }, "boxCm": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "destination", "quantity", "boxWeightKg", "boxCm", "note" ] }, "quotes": { "type": "array", "items": { "type": "object", "properties": { "freightosMode": { "type": "string" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl", "ocean_fcl" ] }, { "type": "null" } ] }, "priceUsdLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceUsdHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transitDays": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "high" ] } }, "required": [ "freightosMode", "mode", "priceUsdLow", "priceUsdHigh", "currency", "transitDays" ] } }, "binding": { "const": false } }, "required": [ "attribution", "link", "fetchedAt", "query", "quotes", "binding" ] }, { "type": "null" } ] }, "marketNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "binding": { "const": false }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "chargeableWeightKg", "chargeable", "options", "dutyStack", "dutyEffectiveRatePct", "landedRange", "notes", "marketQuotes", "marketNote", "binding", "requestId" ]}Errors: 400 Validation error. A body is read here, so one of five codes rides on this status and none is retryable unchanged. validation_error: the body parsed and failed the schema, and details names each path. invalid_json: there was no body, or it was not valid UTF-8 JSON. invalid_text: a string or property name holds a NUL or an unpaired Unicode surrogate, which storage cannot keep, so correct the source text. duplicate_key: a JSON object repeats a property name, no path is given, and the conflicting fields have to be resolved at the source. invalid_number: a number is outside the range that survives the round trip, so quote large identifiers as strings. Nothing was written in any of them.; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 413 body_too_large: the request body exceeds this operation’s limit, and it was not read to the end. Send less in one request rather than repeating it; 415 content_type: the request did not declare application/json, so no body was read and nothing was written. Set the header and send it again; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.
GET /shipping/track/{carrier}/{number}
Section titled “GET /shipping/track/{carrier}/{number}”Track a shipment through DHL unified tracking or 17TRACK. Without a configured provider key the response is HTTP 200 with availability planned and the missing environment variable named.
Required scope: shipping:read.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
carrier |
path | Yes | dhl, 17track or auto. One of: dhl, 17track, auto |
number |
path | Yes | Pattern: ^[A-Za-z0-9-]{6,40}$ |
200 response schema
{ "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "live" }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "time", "location", "description" ] } } }, "required": [ "provider", "trackingNumber", "availability", "carrier", "status", "events" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "planned" }, "missing": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "missing", "message" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "unavailable" }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "message" ] } ], "type": "object", "properties": { "tried": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "live" }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "time", "location", "description" ] } } }, "required": [ "provider", "trackingNumber", "availability", "carrier", "status", "events" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "planned" }, "missing": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "missing", "message" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "unavailable" }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "message" ] } ] } }, "note": { "type": "string" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "note", "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.
GET /shipping/providers
Section titled “GET /shipping/providers”Which tracking and rating providers are configured on this deployment (presence only, never values).
Required scope: shipping:read.
Authentication: bearer key.
200 response schema
{ "type": "object", "properties": { "rating": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "configured": { "type": "boolean" }, "env": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "provider", "configured", "note" ] } }, "tracking": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "configured": { "type": "boolean" }, "env": { "type": "string" }, "freeTier": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "provider", "configured", "env", "freeTier", "docs" ] } }, "note": { "type": "string" }, "requestId": { "type": "string", "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request." } }, "required": [ "rating", "tracking", "note", "requestId" ]}Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.