POST /shipments/estimate and POST /shipments take a token_ids list and are the endpoints to build on. POST /tokens/{tokenId}/shipment/estimate and POST /tokens/{tokenId}/shipment do the same for one token, with the token in the path.
1
Estimate
POST /shipments/estimate with token_ids, holder, address and an optional cover_amount returns carrier rates. It charges nothing and stores nothing. amount is the carrier rate; total is what the holder pays (the rate plus any cover premium).2
Create and pay
POST /shipments with the chosen rate and max_cost (pass the estimate’s total). We re-quote the rate for all the tokens together and return the shipment and its payment. Pay it exactly like an order (Payments). An unpaid shipment never expires: it stays awaiting_payment and can be paid at any time.3
Burn
Once the shipping payment settles,
status becomes ready and each token’s burn in GET /shipments/{id} holds what the holder burns it with. The burn window is 24 hours from payment (expires_at), shared by every token in the shipment.4
Track
The box ships once every token in it is burned. Follow
fulfilment on GET /shipments/{id} or the nft_shipment.updated webhook for the carrier, tracking link and dates.The address
name,address1,cityandcountry(ISO 3166 alpha-2) are required;stateandzipwhere the country uses them;phoneis required outside the US.name,address1,address2,cityandstatetake up to 100 characters,zipandphoneup to 20.- An invalid address is
400 BAD_ADDRESS, withfieldsmapping each bad field to a message. - We never return the delivery address or the shipping label.
Insurance
cover_amount (optional) is shipping insurance cover in dollars, within the range the items allow. Outside it, 400 COVER_NOT_ALLOWED gives order_value, min_cover and max_cover (max_cover is null when the items can’t be insured). A service with no cover option answers 409 COVER_UNAVAILABLE on create: choose another rate or leave cover_amount out.
Burning
{id} in GET /shipments/{id} is a shipment_id, or any quote_id (a token in a multi-token shipment returns its whole shipment).
- EVM:
burnis{ "quote": { ...same tuple as a sell-back, "kind": 2, "amount": "0" }, "signature": "0x..." }. CallburnWithQuoteexactly as for a sell-back (burnForQuoteon Sell-back, with your contract address). - Solana:
burnis{ "transaction": "<base64>", "vault": "...", "last_valid_block_height": ... }. Each GET builds a fresh transaction, so fetch it right before signing.
holder). Each token’s status becomes redeemed with burned_at and burn_tx as its burn is seen.
Renew an expired burn window
If not every token was burned within the 24 hours, the shipment showsstatus: "expired", with no burn on the tokens still unburned. POST /shipments/{id}/renew gives the unburned tokens a new 24-hour window under the same quote_ids; the shipping already paid still counts.
- A window that is still open is returned unchanged with
renewed: false. - If a multi-token shipment’s window lapses and it isn’t renewed, it closes 24 hours after
expires_at: the tokens already burned ship, and the rest aredropped. A dropped token was never burned, so it stays in the holder’s wallet, live; ship it later in a new shipment. The shipment’sstatusbecomespartially_redeemed. - A one-token shipment renews the same way (
{id}is itsquote_id); it never closes by itself. - A burn window lapsing sends no webhook. Watch
expires_atand renew.
Statuses
expected_delivery is a date (YYYY-MM-DD), not a moment. Show your customer tracking_url (the carrier’s own tracking page).
What can’t ship
A refusal about particular tokens lists them in
token_ids.
