> ## 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

> Live carrier rates for shipping cards you hold to a customer's address. Charges nothing and stores nothing.

Scope: `ship:cards`, granted on request · MCP tool: `estimate_shipment`

Live carrier rates, at the full rate you'd pay. Send `cover_amount` to price [insurance](https://catchbackcards.mintlify.site/partner-api/shipping.md#insurance) as well. It charges nothing and stores nothing: the address only goes to our carrier partner for the quote. Take the `carrier` and `token` of the rate you choose to [Create a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/create-shipment.md). See [Shipping cards](https://catchbackcards.mintlify.site/partner-api/shipping.md) for how shipping works.

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

1–10 card ids from [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md), each once. A listed card has to be [delisted](https://catchbackcards.mintlify.site/partner-api/endpoints/delist-card.md) first.

**address** `object` *required*

Your customer's address.

**address**

**name** `string` *required*

The recipient's name. At most 100 characters.

**address1** `string` *required*

At most 100 characters.

**address2** `string`

At most 100 characters.

**city** `string` *required*

At most 100 characters.

**state** `string`

State or region, at most 100 characters. Required where the country has one and needs it, such as the US.

**zip** `string`

Postal code, at most 20 characters. Required, and checked against the country's format, where the country needs it, such as the US.

**country** `string` *required*

ISO 3166 alpha-2, e.g. `US`. [Where you can ship](https://catchbackcards.mintlify.site/partner-api/shipping.md#where-you-can-ship).

**phone** `string`

At most 20 characters. Required outside the US.

**cover\_amount** `number`

Optional. The dollars of insurance to price, with at most two decimals: from \$100 up to the `max_cover` for these cards. It counts as two estimates. [How insurance works](https://catchbackcards.mintlify.site/partner-api/shipping.md#insurance).

## Response

**destination\_country** `string`

The `country` you sent, in capitals.

**package\_type** `string`

The parcel we'd use, e.g. `mailer`.

**order\_value** `number`

Our valuation of the cards, in USD.

**max\_cover** `number | null`

The most you can insure: `order_value`, capped at $10,000. `null` when the order is worth $100 or less, which can't be insured.

**cover\_amount** `number`

The amount you sent. Present only when you sent `cover_amount`.

**rates** `object[]`

Cheapest first. Can be empty.

**rate**

**carrier** `string`

e.g. `USPS`. Send it back as `rate.carrier`.

**service** `string`

The service's name, e.g. `Priority Mail`.

**token** `string`

e.g. `usps_priority`. Send it back as `rate.token`.

**amount** `number`

The full rate in USD, without any premium. Normally what you send as `max_cost`.

**estimated\_days** `number | null`

The carrier's estimate, in days.

**cover\_available** `boolean`

Present when you sent `cover_amount`. `false` when no premium is quoted for this service.

**insurance\_premium** `number | null`

Present when you sent `cover_amount`. `null` when `cover_available` is `false`.

**total** `number | null`

Present when you sent `cover_amount`: `amount` plus `insurance_premium`, which is what you send as `max_cost` to insure this rate. `null` when `cover_available` is `false`.

## Errors

| Status | Code | When |
| - | - | - |
| `400` | | The body isn't JSON, `card_ids` isn't 1–10 card ids (or lists one twice), the address is invalid, or `cover_amount` isn't a dollar amount with at most two decimals or is 0 or negative. An address error is `"error": "Invalid address"` with `fields`, which names each bad field and never repeats its value |
| `400` | `COVER_NOT_ALLOWED` | `cover_amount` is outside the range: from \$100 up to the cards' value, capped at \$10,000. The body has `order_value`, `min_cover` and `max_cover` |
| `400` | `COUNTRY_NOT_SUPPORTED` | We don't ship to this country. A country code we don't recognize is a plain `400` (`"Invalid address"`, with `fields.country`) |
| `400` | `OVER_CUSTOMS_CAP` | An international shipment worth over \$2,500, or with a card we have no value for |
| `400` | `PARTNER_GOODS` | A partner's own goods ship from that partner |
| `403` | | The key lacks `ship:cards` or isn't linked to an account, the account needs a verified phone number (`"Phone verification required"`), the account is deleted (`"Partner account unavailable"`), or it can't request shipping |
| `403` | `FEATURE_RESTRICTED` | The account is restricted from the marketplace or from withdrawals (`capability` is `marketplace` or `withdraw`). Contact us |
| `409` | `CARDS_NOT_SHIPPABLE` | A card can't ship. `cards[]` gives each refused `card_id` and its `reason`: [what they mean](https://catchbackcards.mintlify.site/partner-api/shipping.md#which-cards-can-ship) |
| `429` | `RATE_LIMITED` | More than 60 estimates a minute on this key, where one with `cover_amount` counts as two. Wait `retry_after_seconds`, also sent as a `Retry-After` header |
| `502` | | The carrier quote failed. Try again |
| `503` | | We couldn't check the account or the cards. Try again |

```bash cURL theme={null}
curl -X POST https://catchbackcards.com/api/partner/v1/shipments/estimate \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
    "address": {
      "name": "Sam Rivera",
      "address1": "1 Example Way",
      "city": "Testville",
      "state": "CA",
      "zip": "94000",
      "country": "US"
    }
  }'
```

```json 200 theme={null}
{
  "destination_country": "US",
  "package_type": "mailer",
  "order_value": 410,
  "max_cover": 410,
  "rates": [
    { "carrier": "USPS", "service": "Ground Advantage", "token": "usps_ground_advantage", "amount": 5.4, "estimated_days": 3 },
    { "carrier": "USPS", "service": "Priority Mail", "token": "usps_priority", "amount": 12.85, "estimated_days": 2 }
  ]
}
```

```json 200 with cover_amount theme={null}
{
  "destination_country": "US",
  "package_type": "mailer",
  "order_value": 410,
  "max_cover": 410,
  "cover_amount": 400,
  "rates": [
    { "carrier": "USPS", "service": "Ground Advantage", "token": "usps_ground_advantage", "amount": 5.4, "estimated_days": 3, "cover_available": true, "insurance_premium": 5.07, "total": 10.47 },
    { "carrier": "USPS", "service": "Priority Mail", "token": "usps_priority", "amount": 12.85, "estimated_days": 2, "cover_available": true, "insurance_premium": 5.16, "total": 18.01 },
    { "carrier": "DHL Express", "service": "Express Worldwide", "token": "dhl_express_worldwide", "amount": 46.16, "estimated_days": 3, "cover_available": false, "insurance_premium": null, "total": null }
  ]
}
```

```json 400 theme={null}
{ "error": "Invalid address", "fields": { "zip": "Required", "phone": "Required for international shipments" } }
```

```json 400 COVER_NOT_ALLOWED theme={null}
{ "error": "cover_amount must be between $100 and $410.", "code": "COVER_NOT_ALLOWED", "order_value": 410, "max_cover": 410, "min_cover": 100 }
```

```json 409 theme={null}
{
  "error": "Some cards cannot ship.",
  "code": "CARDS_NOT_SHIPPABLE",
  "cards": [{ "card_id": "0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e", "reason": "listed" }]
}
```


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