Shipping and compliance

Maglev exposes shipping estimates, provider availability, tracking, compliance planning and tariff candidates. These help an agent prepare the next decision. An estimate is not a booking, and a planning table is not a product certification.

Start with the product and cargo

Keep the product revision, intended use, market, radio/battery details and known test evidence with the project. For shipping, collect carton dimensions and weights, quantity, origin, destination and the declared value when known. Preserve unknown values instead of replacing them with zero or guessing “no battery.”

The current deterministic shipping calculator supports the China-to-US lane. A global sourcing preference in a project does not expand a calculator’s supported lanes.

Estimate shipping

This synthetic cargo example uses centimetres and kilograms:

curl --fail-with-body https://app.trymaglev.com/api/v1/shipping/estimate \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"cartons":[{"lengthCm":20,"widthCm":15,"heightCm":10,"weightKg":2,"count":1}],"destination":{"country":"US"},"modes":["air_express"],"batteries":"none"}'

Provide cartons or totals. Cartons take precedence if both are present. Read each option’s basis, cost range, fuel surcharge, transit range and exclusions. Missing duty or cost data remains unknown. Check the current source and obtain a reviewed quote before committing to a shipment.

Read the cost assumptions

In API 1.1.0, landedRange adds freight to the included duty and fee amounts. It does not include the declared goods value. It also omits the costs in landedRange.excludes. Keep the goods price, included shipping/import charges and unresolved costs as separate budget lines.

The calculator currently uses a fixed FY2026 formal-entry Merchandise Processing Fee (MPF) schedule. It does not accept a customs-entry date or entry type. CBP publishes different fees for informal entries and new formal-entry bounds effective October 1, 2026. Treat the returned fee as a stated planning assumption, then verify the applicable entry schedule. CBP FY2026 fees, CBP FY2027 notice.

A layer marked applies is not evidence that Maglev has checked every product exemption. The current calculator includes a China forced-labor Section 301 layer; CBP’s guidance identifies exemptions. Preserve the HTS candidate, country of origin, planned entry date and unresolved scope questions for review. A dispatch city alone does not establish country of origin.

The optional live: true flag requests marketplace data as well. It can return no usable quotes or hit a provider limit. Preserve marketQuotes, marketNote and any required attribution. Do not call a deterministic estimate a live carrier rate.

For a result stored against a project, use the shipping estimate action or landed cost action. The shipping booking action opens coordinated work; it does not confirm a carrier booking or purchase a label.

Check tracking availability

curl --fail-with-body https://app.trymaglev.com/api/v1/shipping/providers \
  -H "Authorization: Bearer $MAGLEV_API_KEY"

Provider configuration and a successful tracking lookup are different facts. The tracking endpoint accepts dhl, 17track or auto and a tracking number you are authorized to look up.

Result availability	Meaning
`live`	The provider returned events; keep its timestamps and descriptions
`planned`	The provider is not configured; no provider request was made
`unavailable`	No usable result for this lookup; read the message before deciding to retry

A response with HTTP 200 can still be planned or unavailable. Inspect the payload rather than treating success status as proof of live tracking. A tracking event is not proof of quality acceptance or payment completion.

Prepare a compliance review

POST /compliance/path accepts a product description, markets and relevant technical flags. It returns a planning table with a basis for each item. explain: true also requests a generated explanation; if that fails, the table can still be returned with an explanation note.

{
  "product": "Example battery-powered indoor sensor",
  "markets": ["US"],
  "radios": ["Bluetooth"],
  "moduleIsPreCertified": null,
  "battery": "liion_contained",
  "explain": false
}

This is a hypothetical example, not an assessment of your product. Set technical flags from evidence. Keep applies, basis, responsible party, source dates and missing information attached to each row. Confirm applicability and required evidence with the appropriate engineer, lab or specialist before treating any item as complete.

For a saved project draft, use the compliance path action. It does not issue certificates or submit an application to a regulator.

Record tariff candidates

POST /compliance/hts-candidates accepts product, description and optional materials and function text. It returns candidate code values with reasoning and sources; chosen remains null. An empty candidate list means this endpoint has not identified a match.

Use the customs profile action for a draft checklist and summary. Keep final classification and customs approval as separately evidenced decisions. Neither endpoint files an entry, grants clearance or turns an estimated duty into a final assessed charge.