> ## 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 > **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). Live carrier rates for shipping cards you hold to a customer's address, at the full rate you would pay. Send `cover_amount` to price insurance as well: each rate then adds its premium and total. It stores nothing on our side: the address goes to our carrier services, normally Shippo, to get the rates. It is a `POST` so the address never lands in a URL. Create a shipment takes the `carrier` and `token` of the rate you choose. The account needs a verified phone number. 60 estimates a minute per key. Read [Shipping cards](/partner-api/shipping) first. ## OpenAPI ````yaml /partner-api/openapi.yaml post /api/partner/v1/shipments/estimate openapi: 3.1.0 info: title: CatchBack Partner API version: 1.0.0 summary: Open packs, trade cards, read card data and ship vaulted cards. description: >- The Partner API acts on one CatchBack account with its real CatchCoins balance. Several operations here move money or data, so read [Idempotency](/partner-api/idempotency) before you call them. Error bodies are JSON with a human-readable `error` and, where you might branch on it, a machine-readable `code`. Branch on the status and the `code`, because the `error` text can change. New fields can be added to any response. contact: name: CatchBack support email: catchbackcards@gmail.com servers: - url: https://catchbackcards.com description: Production. Every call acts on real money and real inventory. security: - bearerAuth: [] tags: - name: Gacha description: Open packs, see what they can pull, check a pull, and sell cards back. - name: Marketplace description: Search and buy cards, and manage your own listings. - name: Metadata description: Look cards up by id or cert, with price history and recent activity. - name: Shipping description: Estimate, create and track shipments of cards you hold. - name: Account description: Your key, balance, limits, vault and order history, across every rail. - name: Funding description: Deposit and withdraw your balance in USDC. - name: Testing description: Test logins for trying CatchBack without real money. - name: Webhooks description: Signed POSTs we send to your URL when something happens on your account. paths: /api/partner/v1/shipments/estimate: post: tags: - Shipping summary: Estimate a shipment description: >- **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). Live carrier rates for shipping cards you hold to a customer's address, at the full rate you would pay. Send `cover_amount` to price insurance as well: each rate then adds its premium and total. It stores nothing on our side: the address goes to our carrier services, normally Shippo, to get the rates. It is a `POST` so the address never lands in a URL. Create a shipment takes the `carrier` and `token` of the rate you choose. The account needs a verified phone number. 60 estimates a minute per key. Read [Shipping cards](/partner-api/shipping) first. operationId: estimateShipment requestBody: required: true content: application/json: schema: type: object required: - card_ids - address properties: card_ids: $ref: '#/components/schemas/ShipmentCardIds' address: $ref: '#/components/schemas/ShipmentAddress' cover_amount: $ref: '#/components/schemas/ShipmentCoverAmount' example: card_ids: - 0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e address: name: Sam Rivera address1: 1 Example Way city: Testville state: CA zip: '94000' country: US responses: '200': description: The rates. content: application/json: schema: type: object required: - destination_country - package_type - order_value - max_cover - rates properties: destination_country: type: string package_type: type: string description: e.g. `mailer`. order_value: type: number description: Our valuation of the cards in USD.: null max_cover: type: - number - 'null' description: >- 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: type: number description: >- The amount you sent. Present only when you sent `cover_amount`. rates: type: array items: type: object required: - carrier - service - token - amount - estimated_days properties: carrier: type: string service: type: string token: type: string amount: type: number description: The full rate, in USD, without any premium. estimated_days: type: - integer - 'null' cover_available: type: boolean description: >- Present when you sent `cover_amount`. `false` when no premium is quoted for this service. insurance_premium: type: - number - 'null' description: >- Present when you sent `cover_amount`. `null` when `cover_available` is `false`. total: type: - number - 'null' description: >- 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`. example: 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 '400': description: >- - No `code`: 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. - `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`. - `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`). - `OVER_CUSTOMS_CAP`: an international shipment worth over $2,500, or with a card we have no value for. - `PARTNER_GOODS`: a partner's own goods ship from that partner. content: application/json: schema: $ref: '#/components/schemas/ShipmentRequestError' example: error: Invalid address fields: phone: Required for international shipments '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ShipmentForbidden' '409': $ref: '#/components/responses/CardsNotShippable' '429': description: >- `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. headers: Retry-After: schema: type: integer content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - RATE_LIMITED retry_after_seconds: type: integer example: error: Too many estimates. Slow down. code: RATE_LIMITED retry_after_seconds: 12 '502': description: The carrier quote failed. Try again. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: We couldn't check the account or the cards. Try again. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: - ship:cards components: schemas: ShipmentCardIds: type: array minItems: 1 maxItems: 10 uniqueItems: true description: >- Card ids from Get vault, cards you hold in the vault. A listed card has to be delisted first. items: type: string format: uuid ShipmentAddress: type: object description: >- Your customer's address. Stored only with a shipment, never in logs or on your account. required: - name - address1 - city - country properties: name: type: string maxLength: 100 description: Recipient name. address1: type: string maxLength: 100 address2: type: string maxLength: 100 city: type: string maxLength: 100 state: type: string maxLength: 100 description: State or region, where the country has one. zip: type: string maxLength: 20 description: Postal code, where the country has one. country: type: string description: ISO 3166 alpha-2, e.g. `US`. Shipping countries lists where we ship. phone: type: string maxLength: 20 description: Required outside the US. ShipmentCoverAmount: type: number minimum: 100 maximum: 10000 description: >- Optional insurance: the dollars of cover, with at most two decimals, from $100 up to `max_cover` from the estimate. Leave it out and the only cover is what the carrier includes automatically: up to $100 on USPS and UPS labels. Other carriers may include less or none. You carry any loss above your cover. ShipmentRequestError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - INSUFFICIENT_BALANCE - COVER_NOT_ALLOWED - COUNTRY_NOT_SUPPORTED - OVER_CUSTOMS_CAP - PARTNER_GOODS fields: type: object description: >- On an invalid address, each bad field and what's wrong with it. It never repeats the value. additionalProperties: type: string amount: type: number description: On `INSUFFICIENT_BALANCE`, the rate plus any premium. order_value: type: number description: On `COVER_NOT_ALLOWED`, our valuation of the cards. min_cover: type: number description: On `COVER_NOT_ALLOWED`, the least you can insure. max_cover: type: - number - 'null' description: >- On `COVER_NOT_ALLOWED`, the most you can insure. `null` when the order can't be insured. Error: type: object required: - error properties: error: type: string description: >- For people. The text can change, so branch on the status and the `code`. code: type: string description: Machine-readable, where you might branch on it. RestrictedError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - FEATURE_RESTRICTED capability: type: string description: What is switched off for the account. CardsNotShippableError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - CARDS_NOT_SHIPPABLE cards: $ref: '#/components/schemas/RefusedCards' RefusedCards: type: array description: >- Each refused card and why. A card lost at the last moment comes with no list. items: type: object required: - card_id - reason properties: card_id: type: string reason: type: string enum: - not_in_vault - listed - shipping - on_hold - not_a_card responses: Unauthorized: description: A missing, malformed, disabled or unknown API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Missing or malformed API key ShipmentForbidden: description: >- - The key lacks `ship:cards` or isn't linked to an account. - `Phone verification required`. - `Partner account unavailable`: the account is deleted. - The account can't request shipping. - `FEATURE_RESTRICTED`: the account is restricted from the marketplace or from withdrawals (`capability` is `marketplace` or `withdraw`). Contact us. content: application/json: schema: $ref: '#/components/schemas/RestrictedError' CardsNotShippable: description: >- `CARDS_NOT_SHIPPABLE`: a card can't ship. `cards[]` gives each refused `card_id` and its `reason`: [what they mean](/partner-api/shipping#which-cards-can-ship). content: application/json: schema: $ref: '#/components/schemas/CardsNotShippableError' example: error: Some cards cannot ship. code: CARDS_NOT_SHIPPABLE cards: - card_id: 0e94dc61-… reason: listed securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: cb_live_<48 hex> description: >- Your API key, sent as a bearer token. Keep it on your server. See [Authentication](/partner-api/authentication). A request from a location we refuse gets a `403` with `Access denied`, whether or not it has a valid key: [where you can call from](/partner-api/errors-and-limits#where-you-can-call-from). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.