> ## 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. # Shipping cards > Ship cards you hold to your customers, paid from your balance: what you pay, which cards can ship, how we handle your customers' addresses, and how to track a shipment. You can ship cards in your vault to your customers, paid from your CatchCoins balance at the carrier's full rate, plus a premium if you choose insurance. It takes the `ship:cards` scope, which we grant on request: [contact us](mailto:catchbackcards@gmail.com). The account needs a verified phone number. **1. Get rates** [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/estimate-shipment.md) with the card ids and your customer's address. It returns live carrier rates and charges nothing. We store nothing: the address goes to our carrier services, normally Shippo, to get the rates. **2. Create the shipment** [Create a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/create-shipment.md) with the same cards and address, the rate you chose and a `max_cost`, under your own id for the shipment. We quote again and charge the fresh amount, up to `max_cost`. **3. Track it** [List shipments](https://catchbackcards.mintlify.site/partner-api/endpoints/list-shipments.md) and [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) show its status and tracking. With a [webhook](https://catchbackcards.mintlify.site/partner-api/webhooks.md), [`shipment.updated`](https://catchbackcards.mintlify.site/partner-api/webhook-events#shipment-updated) tells you when it moves. ## What you pay The carrier's full rate for the service you pick, plus the premium if you choose [insurance](#insurance). There are no promo codes on a shipment, and no free or subsidized tier. > [!WARNING] > > **Without insurance, the only cover on a parcel is what the carrier includes automatically: up to \$100 on USPS and UPS labels. Other carriers may include less or none.** Keep that in mind before you ship a card worth more. There's no signature option on a shipment. ## Insurance Insurance is optional, and you choose it per shipment. To price it, send `cover_amount` to [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/estimate-shipment.md). Each rate then adds `cover_available`, `insurance_premium` and `total`, the rate plus the premium. To buy it, send the same `cover_amount` to [Create a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/create-shipment.md), with `max_cost` set to the `total` you saw: ```json theme={null} { "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"], "address": { "...": "..." }, "rate": { "carrier": "USPS", "token": "usps_priority" }, "cover_amount": 400, "max_cost": 18.01 } ``` * **How much:** any amount from \$100 up to `max_cover`, which every estimate returns: the value of the cards, capped at \$10,000. Outside that you get `400 COVER_NOT_ALLOWED`. An order worth \$100 or less can't be insured, and its `max_cover` is `null`. * **Orders worth more than \$10,000:** cover stops at \$10,000, and the rest of the order is uninsured. * **What it costs:** the premium our insurer quotes for that service. `max_cost` applies to the rate and the premium together. A new quote above it is `409 PRICE_CHANGED`, and a service with no premium quoted is `409 COVER_UNAVAILABLE`. Nothing is charged in either case. * **What it pays:** up to the amount you covered, and never more. **You carry any loss above your cover**, whether you chose less than the cards are worth or the order is over the cap. ### If a parcel is lost or damaged [Contact us](mailto:catchbackcards@gmail.com) with the shipment id. You can't claim from the insurer yourself, because the policy is tied to our sender details. We file the claim, and we credit your balance when it pays out. > [!WARNING] > > The insurer's deadlines are **60 days from shipping, or 15 days after a "delivered" scan for a parcel that never arrived**. Report well before them, so we have time to file. We can't file a claim after a deadline has passed. ## Which cards can ship Up to 10 cards per shipment, all to one address. A card has to be in your vault, and not: | `reason` in `cards[]` | Why it can't ship | What to do | | - | - | - | | `not_in_vault` | It isn't in your vault: not yours, not found, or not a kind of card [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) lists, such as an energy or Steph Curry card | Check the id | | `listed` | It's listed on the marketplace | [Delist it](https://catchbackcards.mintlify.site/partner-api/endpoints/delist-card.md) first | | `shipping` | It's already in a shipping request or on its way, or it's otherwise unavailable | Read [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) again | | `on_hold` | It came from a pack that holds its cards | Sell it back | | `not_a_card` | The id is a sealed pack | Sealed packs don't ship through the API | Any refused card is a `409 CARDS_NOT_SHIPPABLE` that lists every refused card. A partner's own goods ship from that partner, not through this API (`400 PARTNER_GOODS`). ## Where you can ship `GET https://catchbackcards.com/api/shipping-countries` lists the countries we ship to, with no key. Elsewhere is a `400 COUNTRY_NOT_SUPPORTED`. Outside the US, the address needs a phone number, and a shipment worth more than \$2,500 in total can't ship through the API (`400 OVER_CUSTOMS_CAP`). Neither can one with a card we have no value for. ## Customer addresses Each shipment carries its customer's address, because we hold no list of your customers. * **Where we keep it:** only with the shipment's order, which is what we buy the label from. It doesn't go on your account or in your address book. We never ask for your customer's email address. * **Who sees it:** you, through [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) (the list has no addresses, and no [event](https://catchbackcards.mintlify.site/partner-api/webhook-events.md) carries any part of one), our staff who fulfill the order, and the carrier services we buy labels through, normally Shippo, which quote and label it. * **Logs:** Our partner API doesn't write the address to our logs. * **How long:** we remove the address, phone number and label links **90 days after the shipment closes**, or 180 days after it shipped if the carrier never reported an end. An order still waiting to ship keeps its address. After that, `address` is `null` and `address_removed` is `true`, and the order stays with its cards, cost and tracking. `destination_country` stays on the shipment. The carrier services keep their own copies under their own terms. * **Your customer hears nothing from us.** We don't email or text them, so tell them about their tracking yourself. ## Status | `status` | Meaning | | - | - | | `pending` | We've taken the request and the order doesn't exist yet | | `needs_review` | We couldn't confirm the charge: [see below](#unconfirmed-shipments) | | `processing` | Charged and waiting for us to buy the label and send it | | `shipped` | On its way. A parcel that bounces stays `shipped` until someone resolves it | | `delivered` | Delivered | | `cancelled` | We closed the order or removed it. Contact us if you didn't expect this | New values can be added, so handle one you don't know. ## Limits | Limit | Set per key | When you go over | | - | - | - | | 50 shipments per key per UTC day | No | `429 DAILY_SHIPMENT_LIMIT_REACHED`, with `limit` and `resets_at` | | 60 estimates per key per minute, where one with `cover_amount` counts as two | No | `429 RATE_LIMITED`, with `retry_after_seconds` and a `Retry-After` header | | 1–10 cards per request | No | `400` | | `max_cost` up to \$10,000 | No | `400` | All of them: [Rate limits](https://catchbackcards.mintlify.site/partner-api/rate-limits.md#shipments). The address field limits are on [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/estimate-shipment.md). ## Unconfirmed shipments Rarely, we can't tell whether a shipment's charge went through. You get a `500 SHIPMENT_OUTCOME_UNKNOWN` with `needs_review: true` and the `shipment_id`, and it's with our team to check. Follow it with [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md), which takes the `shipment_id`. No [event](https://catchbackcards.mintlify.site/partner-api/webhook-events.md) tells you the outcome. | What you see | What it means | What to do | | - | - | - | | `status: "needs_review"` or `"pending"`, or `409 IDEMPOTENCY_IN_PROGRESS` with `needs_review: true` on a resend | We're still checking | Wait. A resend with the same id can't charge twice. Don't resend it under a new id until you hear from us | | `processing`, `shipped`, `delivered` or `cancelled`, or the shipment with `idempotent_replay: true` on a resend | It went through, and was charged once | Track it as usual | | `404` from Get a shipment | We found nothing was charged, and removed it | The id is free to send again. Check your balance before you do | Quote the `shipment_id` if you contact us. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.