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 } }, "required": [ "chargeableWeightKg", "chargeable", "options", "dutyStack", "dutyEffectiveRatePct", "landedRange", "notes", "marketQuotes", "marketNote", "binding" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. 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" } }, "required": [ "note" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. 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" } }, "required": [ "rating", "tracking", "note" ]}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.