/api/v1/shipping-quote tenant key Fulfillment, step 1. Validates the ship-to address and returns live carrier rates (ascending by amount) for the listed cards. Opens a PENDING_PAYMENT order and snapshots the quoted rates, so committing bills exactly what you were quoted. The batch is atomic — one bad card fails the whole quote; you never get a partial order. An uncommitted quote is not a conflict: re-quoting silently supersedes it and cancels the old order, so you can re-quote a card freely until you commit. Hand the order_id + a chosen rate_id to POST /api/v1/orders.
POST /api/v1/shipping-quote write These inputs are shared across all docs pages, so an id entered here carries over.
{
"unique_ids": [
"CARD-EXAMPLE-1"
],
"address": {
"name": "Demo Buyer",
"street1": "1 Market St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}Not run yet. Press Run to make a live call against https://service.rip.fun (through this demo's server-side proxy; the API key never reaches the browser).
curl -X POST 'https://service.rip.fun/api/v1/shipping-quote' \
-H 'X-API-Key: rip_…' \
-H 'Content-Type: application/json' \
-d '{"unique_ids":["CARD-EXAMPLE-1"],"address":{"name":"Demo Buyer","street1":"1 Market St","city":"San Francisco","state":"CA","zip":"94105","country":"US"}}' | Field | Type | Required | Description |
|---|---|---|---|
unique_ids | string[] | yes | One or more card unique_ids. Always an array, even for a single card — a singular unique_id key returns 400. Every card must belong to you and be OFFCHAIN |
address.name | string | yes | Recipient full name |
address.street1 | string | yes | Street line 1 (`street2` optional) |
address.city | string | yes | City |
address.state | string | yes | State / region |
address.zip | string | yes | Postal code |
address.country | string | yes | ISO country code, e.g. `US` (`email`, `company` optional) |
address.phone | string | — | Recipient phone. REQUIRED for any non-US destination — carriers will not issue an international label without one. Any national ("0439 927 773") or international ("+61 439 927 773") format is accepted; we normalise it to E.164 for the destination country. Optional for US addresses |
data)| Field | Description |
|---|---|
order_id | New PENDING_PAYMENT order id. Pass it to POST /orders to commit |
unique_ids | Echoed card ids on the order |
rates[] | Live rates, cheapest first: rate_id, object_id, amount (decimal string), currency, provider, servicelevel {name, token}, estimated_days. Every rate offered is purchasable for the destination: outside the US and Canada USPS is never offered (carriers will not sell it), so expect DHL / UPS / FedEx there, and the customs declaration an international shipment needs is built for you from catalog values |
shippo_shipment_id / shippo_address_id | Shipment + validated address object ids |
ship_by_at / expires_at | Target ship date + the re-quote deadline we recommend (24h after quoting). The price you are billed is snapshotted at quote time either way. Shippo hard-expires a rate 7 days after it is quoted: committing an order older than that is re-quoted fresh at the current carrier price (you are still billed the snapshot), so re-quote rather than commit a stale order |
| Status | Code | When |
|---|---|---|
| 400 | unique_ids required | unique_ids missing/empty, invalid address, or address validation failed |
| 400 | phone_required | address.country is not US and no address.phone was supplied — international carriers require a recipient phone. Returned before any carrier call; add the phone (any format) and re-quote |
| 404 | card(s) not found | a unique_id is not a card of your account (the message names them) |
| 409 | card unavailable | a card is not OFFCHAIN (e.g. PENDING_WITHDRAWAL, or mid-redemption on another order) — the most common failure; the error names the offending cards and their statuses |
| 409 | card already on an order | a card belongs to a committed, in-flight or fulfilled order — data carries that order’s state |
| 409 | CARD_ALREADY_WITHDRAWING | a card is on a withdrawal that has not completed or been cancelled — it cannot be shipped and withdrawn at once |
| 400 | invalid_pagination | unique_ids has more than 500 entries or a non-string entry |
| 502 | no rates | Shippo could not be reached AND the backup rate table produced nothing for the destination — rare; retryable |
See Errors for the response envelope and the full code list.