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

# Changelog

> What changed in the Partner API, newest first.

Changes to `v1` are additive: a response can gain fields, an enum can gain values, and a new endpoint can appear, so build your parser to ignore what it doesn't know. A breaking change would ship under a new version prefix. Dates are US Pacific time.

**November 3, 2026**

Withdrawal webhook

* New webhook event: [`withdrawal.updated`](https://catchbackcards.mintlify.site/partner-api/webhook-events#withdrawal-updated), sent when a USDC withdrawal changes status, with the object [Get a withdrawal](https://catchbackcards.mintlify.site/partner-api/endpoints/get-withdrawal.md) returns. Every webhook on the account whose key has `withdraw:funds` gets it.

**November 3, 2026**

Balance history

* New: [Balance history](https://catchbackcards.mintlify.site/partner-api/endpoints/get-balance-history.md) (`GET /balance-history`, scope `read:account`): every change to your balance in a window, newest first, in one list: orders, shipping charges, USDC withdrawals and money in (USDC deposits, wires we credited, card deposits). REST only.

**November 2, 2026**

Funding and withdrawals in USDC

* New guide: [Funding in USDC](https://catchbackcards.mintlify.site/partner-api/funding.md).
* New: [Get funding details](https://catchbackcards.mintlify.site/partner-api/endpoints/get-funding.md) (`GET /funding`, scope `read:account`): your permanent USDC deposit addresses. A deposit lands in your balance once it settles.
* New: [Withdraw](https://catchbackcards.mintlify.site/partner-api/endpoints/create-withdrawal.md) (`POST /withdrawals`), [List withdrawals](https://catchbackcards.mintlify.site/partner-api/endpoints/list-withdrawals.md) (`GET /withdrawals`) and [Get a withdrawal](https://catchbackcards.mintlify.site/partner-api/endpoints/get-withdrawal.md) (`GET /withdrawals/{id}`), scope `withdraw:funds`, granted on request: send your balance as USDC on Base to the escrow address we set on your account, with no fee. REST only.

**November 2, 2026**

Sell-back quotes, min\_payout, energy cards

* New: [Quote a sell-back](https://catchbackcards.mintlify.site/partner-api/endpoints/quote-sell-back.md) (`POST /cards/sell-back/quote`, scope `sell:cards`, MCP tool `quote_sell_back`): what a sell-back pays for up to 100 cards, now and later, as a schedule of phases with the exact UTC time each starts and ends. It moves no money.
* [Sell back cards](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md) takes an optional `min_payout` per item. If the sell-back would pay less, nothing is sold and the item fails with `PRICE_CHANGED` and what it pays now.
* [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) and the quote take `category=energy`: the energy cards from base packs, which sell back at 100% of their value with no 5-minute window and no lock.
* The vault's `catchback` offer now includes insurance or a boost bought on the pull, as the sell-back pays it.

**November 2, 2026**

Buy packs refusals

* [Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md) now refuses an order before it charges anything when the pack can't be bought: a `pack_type` that [List packs](https://catchbackcards.mintlify.site/partner-api/endpoints/list-packs.md) doesn't offer your key is a `404`, and a pack with `available: false` is a `409 PACK_UNAVAILABLE`, with its `reason`. A `risk_level` outside the pack's `risk_levels`, and the category `goods`, are a `400`. A refused order charges nothing and frees its order id. A retry of a finished order is unaffected.
* [Card catalog export](https://catchbackcards.mintlify.site/partner-api/endpoints/card-catalog.md) now lists only what [Buy a card](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-card.md) can sell, and `category=goods` is a `400`.

**November 2, 2026**

Optional shipping insurance

* [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/estimate-shipment.md) and [Create a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/create-shipment.md) take an optional `cover_amount`, so you can [insure a shipment](https://catchbackcards.mintlify.site/partner-api/shipping.md#insurance) from \$100 up to the cards' value, at most \$10,000. You pay the rate plus the premium, and `max_cost` applies to the total. New codes: `400 COVER_NOT_ALLOWED` and `409 COVER_UNAVAILABLE`.
* Every estimate now returns `order_value` and `max_cover`. A shipment, in responses and in `shipment.updated`, now has `cover_amount` and `insurance_cost`.
* An estimate with `cover_amount` counts as two against the limit of 60 a minute.

**November 1, 2026**

Test accounts, public card metadata, shipments, webhooks, orders held for review

* New: [Create a test account](https://catchbackcards.mintlify.site/partner-api/endpoints/create-test-account.md) (`POST /test-accounts`, MCP tool `create_test_account`) and [List test accounts](https://catchbackcards.mintlify.site/partner-api/endpoints/list-test-accounts.md) (`GET /test-accounts`, MCP tool `list_test_accounts`), scope `create:test_accounts`, granted on request: test logins with a \$10,000 test balance. A test account is a login, not a key, and it can't use the marketplace, gifts, drops, battles, shipping, chat, DMs or withdrawals. New guide: [Testing](https://catchbackcards.mintlify.site/partner-api/testing.md).
* New: [Public card metadata](https://catchbackcards.mintlify.site/partner-api/endpoints/get-public-card.md) (`GET /api/public/v1/cards/{id}`): a card's metadata and image URLs with no key and no prices, cached for 5 minutes at the CDN.
* New: [Estimate a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/estimate-shipment.md) (`POST /shipments/estimate`, MCP tool `estimate_shipment`), [Create a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/create-shipment.md) (`POST /shipments`, MCP tool `create_shipment`), [List shipments](https://catchbackcards.mintlify.site/partner-api/endpoints/list-shipments.md) (`GET /shipments`, MCP tool `list_shipments`) and [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) (`GET /shipments/{id}`, MCP tool `get_shipment`), scope `ship:cards`, granted on request: ship cards you hold to your customers at the carrier's full rate. New guide: [Shipping cards](https://catchbackcards.mintlify.site/partner-api/shipping.md).
* New: [Webhooks](https://catchbackcards.mintlify.site/partner-api/webhooks.md), which we set up for you: a signed `POST` with retries for [`order.completed`, `listing.sold` and `shipment.updated`](https://catchbackcards.mintlify.site/partner-api/webhook-events).
* New: [Where you can call from](https://catchbackcards.mintlify.site/partner-api/errors-and-limits.md#where-you-can-call-from). A key doesn't get around our sanctions list, and a valid key now gets past any other limit on where partner endpoints and the MCP server can be called from.
* [Rate limits](https://catchbackcards.mintlify.site/partner-api/rate-limits.md#shared-limit-per-ip) now says that everything under `/api/` has a shared limit of 300 requests a minute per IP address, on top of the per-key limits.
* [Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md) and [Buy a card](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-card.md): when we can't confirm whether a purchase was charged, the answer is now `500 PAYMENT_OUTCOME_UNKNOWN` with `needs_review: true` and the order's `checkout_id`, not a `503`. Nothing is delivered and the order is held for us to settle: stop retrying, never place it again under a new order id, and follow it with [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md).
* A resend with the same order id answers `409 IDEMPOTENCY_IN_PROGRESS` with `needs_review: true` until we settle the order, and nothing is charged twice. Once we settle it, [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md) answers `404` and the id is free to send again. See [Purchases that need review](https://catchbackcards.mintlify.site/partner-api/idempotency.md#purchases-that-need-review).
* A `503` on a purchase means that attempt didn't charge anything. An earlier attempt with the same order id may have gone through, so retry with the same order id, never a new one.

**October 29, 2026**

Pull proofs, one-step price changes, partner accounts

* [Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md): every pull carries a `proof`, its provably fair record, with a `verify_path` you can `GET` without a key to replay the draw. New guide: [Verify a pull](https://catchbackcards.mintlify.site/partner-api/verify-a-pull.md).
* [Change a listing's price](https://catchbackcards.mintlify.site/partner-api/endpoints/update-listing-price.md) writes the new price in one step, so it lands whole or not at all. A buy or delist that lands first makes it a `409 LISTING_NOT_ACTIVE`, another price change a `409 LISTING_CHANGED`, and neither writes anything.
* A partner account stays off CatchBack's VIP and Top Gifters leaderboards and recent-pull feeds, its pulls aren't posted as big-pull cards in chat, and it earns no CatchPoints or quest progress.

**October 28, 2026**

Card lookups, your listings, price changes, order history

* New: [Get a card](https://catchbackcards.mintlify.site/partner-api/endpoints/get-card.md) (`GET /cards/{id}`, MCP tool `get_card`) and [Find a card by cert](https://catchbackcards.mintlify.site/partner-api/endpoints/find-card-by-cert.md) (`GET /cards?cert=`, MCP tool `find_card_by_cert`), scope `read:catalog`: any card by its id or by the cert on its slab.
* New: [Price history](https://catchbackcards.mintlify.site/partner-api/endpoints/get-price-history.md) (`GET /cards/{id}/price-history`, MCP tool `get_price_history`): a card's CardLadder value readings, up to a year back.
* New: [Card activity](https://catchbackcards.mintlify.site/partner-api/endpoints/get-card-activity.md) (`GET /cards/{id}/activity`, MCP tool `get_card_activity`): a card's recent sales and listings, with nobody named.
* New: [Your listings](https://catchbackcards.mintlify.site/partner-api/endpoints/get-listings.md) (`GET /listings`, scope `read:account`, MCP tool `get_listings`): your own active listings, with your payout on each.
* New: [Change a listing's price](https://catchbackcards.mintlify.site/partner-api/endpoints/update-listing-price.md) (`PATCH /listings/{listing_id}`, scope `write:listings`, MCP tool `update_listing_price`): reprice a fixed-price listing in place, without delisting it.
* New: [List orders](https://catchbackcards.mintlify.site/partner-api/endpoints/list-orders.md) (`GET /orders`, MCP tool `list_orders`) and [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md) (`GET /orders/{checkout_id}`, MCP tool `get_order`), scope `read:account`: your order history, paged by cursor, and one order by its id, even while it is still running.
* [Search cards](https://catchbackcards.mintlify.site/partner-api/endpoints/search-cards.md) applies its filters to every listing it reads, up to 5,000 rows from each source, and gains `truncated`. `has_more` is `false` on the last page and on page 20.
* [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md): a listed card carries its `listing_id` and `listing_price`.
* [List a card](https://catchbackcards.mintlify.site/partner-api/endpoints/list-card.md) runs the app's seller checks, so the account needs a verified phone number.

**October 26, 2026**

Sealed pack pools

* [Get a pack's pool](https://catchbackcards.mintlify.site/partner-api/endpoints/get-pack-pool.md) covers sealed packs (the Starter and the sealed mystery packs). The response gains `kind` (`slab` or `sealed`); a sealed pack lists its products in `products`, with `total_products`, and one band per product.
* A sold-out pack with no pool to show returns `200` with `available: false` and an empty pool, instead of an error.
* The Starter pack opens at the `standard` risk level only, and [List packs](https://catchbackcards.mintlify.site/partner-api/endpoints/list-packs.md) says so in its `risk_levels`.

**October 18, 2026**

Vault acquisitions

* [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) finds each card's latest acquisition across every kind of pack pull and buy, so its `pull_id` or `purchase_id` always names the acquisition a sell-back pays on.

**October 14, 2026**

Who am I, card limits

* New: [Who am I](https://catchbackcards.mintlify.site/partner-api/endpoints/get-me.md) (`GET /me`, MCP tool `whoami`) works with any valid key and shows which account it acts as.
* [Get account](https://catchbackcards.mintlify.site/partner-api/endpoints/get-account.md) gains `card_limits`: your card and spend usage against the daily card caps.

**October 12, 2026**

Buying cards

* New: [Search cards](https://catchbackcards.mintlify.site/partner-api/endpoints/search-cards.md) (`GET /marketplace/listings`, MCP tool `search_cards`) finds every card you can buy, from the shop and fixed-price user listings.
* New: [Buy a card](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-card.md) (`POST /cards/purchase`, scope `buy:cards`, MCP tool `buy_card`), with a `max_price` guard and daily card and spend caps.
* [Sell back cards](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md) takes a `purchase_id` for a card you bought, and [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) returns `purchase_id` and `purchased_at`.
* Card orders share your account's order ids with pack orders, and an interrupted card order is closed the same way as a pack order.

**October 11, 2026**

Interrupted orders

* A pack order cut off after it was charged is now closed from our records, usually within about 10 minutes. Resending its order id then returns a shorter body marked `"reconciled": true`. See [Idempotency](https://catchbackcards.mintlify.site/partner-api/idempotency.md#timeouts-and-interrupted-orders).
* New error code: `409 IDEMPOTENCY_RETRY`, when an earlier attempt with the same order id failed just as the retry arrived. Resend it.

**October 6, 2026**

Pack pools and the full card object

* New: [Get a pack's pool](https://catchbackcards.mintlify.site/partner-api/endpoints/get-pack-pool.md) (`GET /catalog/packs/pool`, MCP tool `get_pack_pool`): a pack's value bands, their odds at a risk level, and every card a pull can produce.
* Every endpoint that returns a card returns the same [card object](https://catchbackcards.mintlify.site/partner-api/card-object.md), with front, back and render images and the slab, set and value fields.

**September 29, 2026**

Buying packs and managing cards

* New: [Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md) (`POST /packs/purchase`, scope `rip:packs`), with a required `Idempotency-Key`, one purchase per minute and 100 packs per day per key.
* New: [Sell back cards](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md) (`sell:cards`), [List a card](https://catchbackcards.mintlify.site/partner-api/endpoints/list-card.md) and [Delist a card](https://catchbackcards.mintlify.site/partner-api/endpoints/delist-card.md) (`write:listings`), [Get account](https://catchbackcards.mintlify.site/partner-api/endpoints/get-account.md) and [Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) (`read:account`).
* New: the [MCP server](https://catchbackcards.mintlify.site/partner-api/mcp.md) at `/api/mcp`, with the same key.
* [List packs](https://catchbackcards.mintlify.site/partner-api/endpoints/list-packs.md) returns exactly the packs your account can buy, at the price it will be charged.

**August 7, 2026**

Purchase report

* New: [Purchase report](https://catchbackcards.mintlify.site/partner-api/endpoints/purchase-report.md) (`GET /pulls`, scope `read:pulls`, opt-in): completed pack purchases in a time window, for revenue-share reporting.

**August 4, 2026**

Partner API v1

* Scoped API keys, and the first read-only endpoints: [List packs](https://catchbackcards.mintlify.site/partner-api/endpoints/list-packs.md) and the [Card catalog export](https://catchbackcards.mintlify.site/partner-api/endpoints/card-catalog.md) (scope `read:catalog`).


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