Skip to main content
POST
Create a shipment

Authorizations

Authorization
string
header
required

Your API key (cb_live_…), sent as a bearer token, with the scope nft:orders. Keep it on your servers: never in a browser, app or wallet. Use a separate key per environment. A request from a country on our sanctions list gets a 403 with Access denied, whether or not it has a valid key. See Authentication and keys.

Scopes

nft:orders

Headers

Idempotency-Key
string
required

Your own shipment id, 8-128 characters of A-Za-z0-9_-. Both shipment endpoints share one key space. The same key with a different request (tokens in any order, holder, address, rate, cover_amount) is 422.

Pattern: ^[A-Za-z0-9_-]{8,128}$

Body

application/json
token_ids
string[]
required

1-25 distinct decimal token ids of your program, all held by holder. Send them as strings.

Required array length: 1 - 25 elements
Pattern: ^[0-9]{1,78}$
holder
string
required
address
object
required
rate
object
required

A rate from the estimate. We re-quote it.

max_cost
number
required

The most the holder will pay for shipping, in dollars (the estimate's total).

cover_amount
number | null

Shipping insurance cover in dollars, with at most two decimals, within the range the items allow (a 400 COVER_NOT_ALLOWED gives the range). Leave it out or null for none.

Response

A replay of an earlier request with the same Idempotency-Key (idempotent_replay is true).

shipment
object
required

A shipment of 1-25 tokens in one box, named by shipment_id. Tokens are listed by token id.

payment
object | null
required

Null on a replay once the shipping is paid.

idempotent_replay
boolean