> ## 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. # Buy a card > **Scope:** `buy:cards` (needs a linked account). **Moves money.** Buys one card from the shop or a fixed-price listing: its price plus a $1 buyer fee, from your cash CatchCoins balance only. The card lands in your vault. Daily card and spend caps apply: see [Rate limits](/partner-api/rate-limits#card-purchases). **`needs_review: true` in any response means the order may have been charged and we are settling it.** Never place it again under a new key. Follow it with [Get an order](/partner-api/endpoints/get-order). See [Idempotency](/partner-api/idempotency). ## OpenAPI ````yaml /partner-api/openapi.yaml post /api/partner/v1/cards/purchase 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/cards/purchase: post: tags: - Marketplace summary: Buy a card description: >- **Scope:** `buy:cards` (needs a linked account). **Moves money.** Buys one card from the shop or a fixed-price listing: its price plus a $1 buyer fee, from your cash CatchCoins balance only. The card lands in your vault. Daily card and spend caps apply: see [Rate limits](/partner-api/rate-limits#card-purchases). **`needs_review: true` in any response means the order may have been charged and we are settling it.** Never place it again under a new key. Follow it with [Get an order](/partner-api/endpoints/get-order). See [Idempotency](/partner-api/idempotency). operationId: buyCard parameters: - $ref: '#/components/parameters/OrderIdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - card_id - max_price properties: card_id: type: string format: uuid description: '`card_id` from Search cards.' max_price: type: number exclusiveMinimum: 0 maximum: 1000000 description: >- The most you'll pay for the card in dollars, before the fee. Usually the `price` the search showed. example: card_id: 0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e max_price: 1450 responses: '200': description: >- The card is yours. A retry of a finished order returns the original body with `idempotent_replay: true`, and charges nothing. If we closed the order after its response was lost, the retry returns a shorter body with `reconciled: true` and no `fee`, `remaining_balance` or `item`: see Idempotency. content: application/json: schema: type: object required: - checkout_id - transaction_id - card_id - source - listing_id - price - total_charged properties: checkout_id: type: string description: Our id for the order. transaction_id: type: - string - 'null' description: >- The sale. It is the `purchase_id` that Get vault and Sell back use for this card. card_id: type: string source: type: string enum: - shop - listing listing_id: type: - string - 'null' price: type: number description: Charged for the card. fee: type: number description: The $1 buyer fee. total_charged: type: number remaining_balance: type: number item: anyOf: - $ref: '#/components/schemas/Card' - type: 'null' needs_review: type: boolean description: >- The sale went through and the card is yours, but our bookkeeping needs a manual check. Don't retry under a new key. idempotent_replay: type: boolean reconciled: type: boolean description: >- Present and `true` on the shorter body we return when we closed the order after its response was lost. message: type: string description: Present with `reconciled`. example: checkout_id: 5d1c… transaction_id: a17e… card_id: 0e94dc61-… source: shop listing_id: null price: 1450 fee: 1 total_charged: 1451 remaining_balance: 48549 item: id: 0e94dc61-… category: pokemon name: Charizard ex set: Pokemon Sv3 En-Obsidian Flames grading_company: PSA grading_rank: 10 slab_label: 2023 Obsidian Flames Charizard ex language: english cert_number: '84512377' market_value: 1450 front_image: https://…/0e94dc61-….png back_image: https://…/0e94dc61-…-back.png render_image: https://…/0e94dc61-…-render.png image_url: https://…/0e94dc61-…-render.png '400': description: >- A missing or malformed `Idempotency-Key`, a body that isn't JSON, a `card_id` that isn't a UUID, a missing or out-of-range `max_price`, or not enough balance. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Insufficient CatchCoins '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Nothing was charged. One of: - The key lacks `buy:cards` or isn't linked to an account. - The account can't buy cards. - `Partner account unavailable`: the account is deleted. - `FEATURE_RESTRICTED`: the marketplace is switched off for the account (`capability: "marketplace"`). Contact us. We also answer "not linked" or "unavailable" when we couldn't read your key or account just then, so one retry is worth it. content: application/json: schema: $ref: '#/components/schemas/RestrictedError' '404': description: >- No such card, or a read the purchase needs failed just then. One retry is worth it. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Nothing was charged, unless the body has `needs_review: true`. - No `code`: the card is never sold here (an energy card, a Steph Curry card, or a shop card with no valid price). Pick another. - `PRICE_CHANGED`: the price is above your `max_price`. The body has the current `price`. - `CARD_NO_LONGER_AVAILABLE`: sold, pulled from a pack, delisted or shipped, or an item that is only sold in packs. Search again. - `CARD_MOVED_TO_AUCTION`: the card is now in an auction, not sold at a fixed price. The body has `listing_id` and `listing_type`. - `OWN_LISTING`: the card is your own listing. - `IDEMPOTENCY_IN_PROGRESS`: an order with this key is still running, or is being settled after a failed attempt (`needs_review: true` says it's held for us to settle, so resending won't help until we do). The body usually has its `checkout_id`: follow it with Get an order, or retry later with the same key. Don't retry in a tight loop. - `IDEMPOTENCY_RETRY`: an earlier attempt with this key failed just as this one arrived. Retry with the same key. content: application/json: schema: allOf: - $ref: '#/components/schemas/OrderError' - type: object properties: code: type: string enum: - PRICE_CHANGED - CARD_NO_LONGER_AVAILABLE - CARD_MOVED_TO_AUCTION - OWN_LISTING - IDEMPOTENCY_IN_PROGRESS - IDEMPOTENCY_RETRY examples: price_changed: summary: PRICE_CHANGED value: checkout_id: 5d1c… error: >- The price changed to $1500.00 since you looked. Check the new price and try again. code: PRICE_CHANGED card_id: 0e94dc61-… price: 1500 max_price: 1450 '422': description: >- `IDEMPOTENCY_KEY_REUSED`: this key was used for a different order. Use a new key. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED '429': description: >- `DAILY_CARD_LIMIT_REACHED`: this key's cards-per-day or spend-per-day cap would be exceeded. A refused order charges nothing. Resets at `resets_at`, midnight UTC. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: type: string enum: - DAILY_CARD_LIMIT_REACHED cards_used: type: integer max_cards_per_day: type: integer spend_used: type: number max_card_spend_per_day: type: number resets_at: type: string format: date-time example: error: 'Daily card limit reached: 25 cards / $50000 per day.' code: DAILY_CARD_LIMIT_REACHED cards_used: 25 max_cards_per_day: 25 spend_used: 18240.5 max_card_spend_per_day: 50000 resets_at: '2026-10-29T00:00:00.000Z' '500': description: >- - No `code`: the purchase failed. Retry once with the same key, never a new one: if nothing was charged, it runs again. If the body has `needs_review: true`, or the retry answers `409 IDEMPOTENCY_IN_PROGRESS`, the order may have been charged and we're settling it: stop retrying and follow it with Get an order. - `PAYMENT_OUTCOME_UNKNOWN`: we couldn't confirm whether the order was charged. It may have been, and nothing was delivered. It's held for review (`needs_review: true`) and we settle any charge. **Stop retrying, and never place it again under a new key:** the same key answers `409 IDEMPOTENCY_IN_PROGRESS` until we settle it. The body has its `checkout_id`: follow it with Get an order. content: application/json: schema: allOf: - $ref: '#/components/schemas/OrderError' - type: object properties: code: type: string enum: - PAYMENT_OUTCOME_UNKNOWN example: error: >- We couldn't confirm whether this order was charged. It's held for review and we'll settle any charge, so check your balance before ordering again. code: PAYMENT_OUTCOME_UNKNOWN needs_review: true checkout_id: 5d1c… '503': description: >- We couldn't read your key's limits, record the order, count today's cards or take the payment, so the order didn't go through. Retry shortly with the same key. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: - buy:cards components: parameters: OrderIdempotencyKey: name: Idempotency-Key in: header required: true description: >- Your order id, 8–128 characters of `A-Za-z0-9_-`, unique per account across pack and card orders. Reuse it to retry the same order safely, and use a new one for every new order. schema: type: string pattern: ^[A-Za-z0-9_-]{8,128}$ example: order-1042 schemas: Card: type: object description: >- The [card object](/partner-api/card-object). Other fields appear only on the catalogs that have them. required: - id - category - name - set - grading_company - grading_rank - slab_label - language - market_value - cert_number - front_image - back_image - render_image - image_url properties: id: type: string description: The card's id. category: $ref: '#/components/schemas/CardCategory' name: type: - string - 'null' set: type: - string - 'null' year: type: - string - 'null' number: type: - string - 'null' variant: type: - string - 'null' rarity: type: - string - 'null' description: Printed rarity. card_type: type: - string - 'null' language: type: - string - 'null' slab_label: type: - string - 'null' description: The text on the grading label. grading_company: type: - string - 'null' grading_rank: type: - number - 'null' description: The grade. cert_number: type: - string - 'null' description: The grading company's certificate number. card_condition: type: - string - 'null' market_value: type: number description: Our current market valuation in USD. `0` when we have no valuation. price: type: - number - 'null' description: The shop sale price in USD. market_value_last_updated: type: - string - 'null' front_image: type: - string - 'null' back_image: type: - string - 'null' render_image: type: - string - 'null' image_url: type: - string - 'null' description: '`render_image`, or `front_image` when there is no render.' sport: type: - string - 'null' player_name: type: - string - 'null' team: type: - string - 'null' manufacturer: type: - string - 'null' parallel: type: - string - 'null' is_rookie: type: - boolean - 'null' is_autograph: type: - boolean - 'null' is_memorabilia: type: - boolean - 'null' serial_numbered: type: - string - 'null' brand: type: - string - 'null' reference_number: type: - string - 'null' video_url: type: - string - 'null' condition: type: - string - 'null' size: type: - string - 'null' description: type: - string - 'null' attributes: type: - object - 'null' description: Luxury goods only. Key-value details that vary by item. additionalProperties: true 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. OrderError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: checkout_id: type: string description: The order. Get an order takes it. needs_review: type: boolean description: >- The order may have been charged and we are settling it. Never place it again under a new key. started_at: type: string format: date-time description: On `IDEMPOTENCY_IN_PROGRESS`. card_id: type: string price: type: number description: On `PRICE_CHANGED`, the current price. max_price: type: number listing_id: type: string description: On `CARD_MOVED_TO_AUCTION`. listing_type: type: string description: On `CARD_MOVED_TO_AUCTION`. refund_pending: type: boolean description: You were charged and the refund didn't go through. CardCategory: type: string description: A card's catalog. `goods` is luxury goods and `singles` is raw singles. enum: - pokemon - onepiece - sports - riftbound - watches - goods - singles 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 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.