> ## Documentation Index
> Fetch the complete documentation index at: https://catchbackcards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Estimate a shipment

> Carrier rates to ship 1-25 tokens held by one wallet in one box. Charges nothing and stores nothing.

Scope: `nft:orders` · Rate limit: 30 a minute, shared with [Estimate a one-token shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/estimate-token-shipment.md)

Carrier rates to ship every token's item to the holder in one box. Charges nothing and stores nothing. The whole flow: [Shipping](https://catchbackcards.mintlify.site/partner-api/v2/shipping.md).

**token\_ids** `string[]` *required*

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

**holder** `string` *required*

The wallet that holds every token now. Checked on chain.

**address** `object` *required*

`name`, `address1`, `city` and `country` (ISO 3166 alpha-2) are required; `address2` is optional; `state` and `zip` where the country uses them; `phone` is required outside the US. `name`, `address1`, `address2`, `city` and `state` take up to 100 characters, `zip` and `phone` up to 20.

**cover\_amount** `number | null`

Shipping insurance cover in dollars, within the range the items allow (a `400 COVER_NOT_ALLOWED` gives the range).

## Response

**rates** `object[]`

**rate**

**carrier** `string`

**service** `string`

**token** `string`

Pass `carrier` and `token` as `rate` to [Create a shipment](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-shipment.md).

**amount** `number`

The carrier rate.

**estimated\_days** `integer | null`

**total** `number`

What the holder pays: the rate plus any cover premium. Pass it as `max_cost`.

## Errors

A refusal about particular tokens lists them in `token_ids`.

| Status | Code | When |
| - | - | - |
| `400` | `BAD_JSON` | The body isn't JSON |
| `400` | `BAD_TOKEN_IDS` | `token_ids` isn't a list of 1-25 distinct decimal token ids |
| `400` | `BAD_HOLDER` | `holder` is not a wallet address on your mint chain |
| `400` | `BAD_ADDRESS` | The shipping address is invalid; `fields` maps each bad field to a message |
| `400` | `BAD_COVER` | `cover_amount` isn't a positive dollar amount with at most two decimals |
| `400` | `COVER_NOT_ALLOWED` | `cover_amount` is outside what the items can be insured for; the body has `order_value`, `min_cover` and `max_cover` |
| `400` | `NOT_SHIPPABLE` | An item can't ship |
| `400` | `PARTNER_GOODS` | An item is held by its brand partner and can't ship through CatchBack; it can still be sold back |
| `400` | `COUNTRY_NOT_SUPPORTED` | We don't ship to that country |
| `400` | `OVER_CUSTOMS_CAP` | The items are worth more than we can ship internationally |
| `403` | `NOT_HOLDER` | `holder` doesn't hold these tokens on chain right now |
| `404` | `UNKNOWN_TOKEN` | No such token on your program's contract |
| `409` | `TOKEN_NOT_LIVE` | A token isn't minted yet, or was already burned |
| `503` | `CHAIN_UNAVAILABLE` | We couldn't read the tokens' owner from the chain; retry shortly |

```bash cURL theme={null}
curl -X POST https://catchbackcards.com/api/partner/v2/shipments/estimate \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token_ids": ["81264573985362058461377125337283195667", "90311820476190023716442901288201455"],
    "holder": "0x8f3c...e21a",
    "address": { "name": "Alice Tester", "address1": "1 Market St", "address2": null, "city": "San Francisco", "state": "CA", "zip": "94105", "country": "US", "phone": "4155550100" },
    "cover_amount": null
  }'
```

```json 200 theme={null}
{
  "rates": [
    { "carrier": "USPS", "service": "Priority Mail", "token": "usps_priority", "amount": 9.85, "estimated_days": 3, "total": 9.85 }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.