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

# Create an order

> **Rate limit:** 30 a minute.

One order buys 1-10 packs of one kind for one wallet, paid with one payment. `quantity` 2-10 makes a multi-pack order (`OrderBatch`): one payment for `quantity` × the pack price, whose units each open, mint and (if they must) refund on their own. The pack opens and the NFT mints once the payment settles; follow it with Get an order or the `nft_order.updated` webhook.

A refused order creates nothing. A replay with the same `Idempotency-Key` and the same request answers `200` with `idempotent_replay: true` and the order as it stands now; once the order is past `awaiting_payment`, its `payment` has no `client_secret` and no deposit addresses.

If the odds stop selling before the payment settles, the pack isn't opened at other odds: the order goes to `refund_due` and the customer is refunded.



## OpenAPI

````yaml /partner-api/v2/openapi.yaml post /api/partner/v2/orders
openapi: 3.1.0
info:
  title: CatchBack Partner API v2 (wallets & NFTs)
  version: 2.0.0
  summary: >-
    Sell CatchBack packs to your users' own web3 wallets, and let the NFT holder
    sell back or ship.
  description: >-
    The official contract for Partner API v2. Generate clients from this file.


    Each customer pays for their own pack (USDC on Base or Solana, through a
    Unifold Payment

    Intent), and each pulled item is minted as an NFT to the customer's wallet.
    Whoever holds the

    NFT can trade it, sell it back for USDC, or have the physical item shipped.
    Selling back and

    shipping both burn the NFT. Guides: [Overview](/partner-api/v2/overview).


    - **Auth:** every `/api/partner/v2` request sends your key as a bearer
    token, and every key
      needs the scope `nft:orders`. The public token metadata needs no key.
    - **Your program:** your key is linked to your partner program, which fixes
    the chain your
      NFTs mint on (`mint_chain`) and your collection contract. An order, token, quote or shipment
      from another program answers `404`.
    - **Formats:** JSON, UTF-8. Money is USD as a number in dollars (`25`,
    `9.85`). New fields can be
      added to any response; ignore fields you don't know.
    - **Errors:** bodies are `{ "error": "<message>" }`, and errors your
    integration should act on
      also carry a stable `code` (see `ErrorCode`). Branch on the status and the `code`, never on the
      message text. [Errors](/partner-api/v2/errors).
    - **Idempotency:** `POST /orders`, `POST /shipments`, `POST
    /tokens/{tokenId}/shipment` and
      `POST /keys/rotate` require an `Idempotency-Key`. [Idempotency](/partner-api/v2/idempotency).
    - **Sandbox:** the sandbox runs the same API with simulated payments on a
    public testnet. Its base
      URL is issued on request, with a sandbox key. The operations tagged `Sandbox` exist only there
      and answer `404` in production.
  contact:
    name: CatchBack support
    email: support@catchbackcards.com
servers:
  - url: https://catchbackcards.com
    description: >-
      Production. Every payment is real money. The sandbox base URL is issued on
      request.
security:
  - bearerAuth:
      - nft:orders
tags:
  - name: Packs
    description: The packs you can sell, their odds and every item they can pull.
  - name: Orders
    description: >-
      Buy 1-10 packs for one wallet, follow the order to the mint, and prove the
      pull.
  - name: Tokens
    description: A wallet's tokens and one token's item, holder and sell-back schedule.
  - name: Sell-back
    description: >-
      Quote a sell-back, have the holder burn with it, and follow the USDC
      payout.
  - name: Shipments
    description: >-
      Pay shipping for 1-25 tokens, have the holder burn each one, and track the
      box.
  - name: Webhooks
    description: Register, read, test and remove your webhook URL.
  - name: Webhook events
    description: Signed POSTs we send to your webhook URL.
  - name: Keys
    description: Read, rotate and revoke your API key.
  - name: Revenue
    description: Your monthly revenue-share statement.
  - name: Sandbox
    description: Sandbox-only helpers. Every one answers `404` in production.
  - name: Metadata
    description: Public NFT metadata that wallets and marketplaces read with no key.
paths:
  /api/partner/v2/orders:
    post:
      tags:
        - Orders
      summary: Create an order
      description: >-
        **Rate limit:** 30 a minute.


        One order buys 1-10 packs of one kind for one wallet, paid with one
        payment. `quantity` 2-10 makes a multi-pack order (`OrderBatch`): one
        payment for `quantity` × the pack price, whose units each open, mint and
        (if they must) refund on their own. The pack opens and the NFT mints
        once the payment settles; follow it with Get an order or the
        `nft_order.updated` webhook.


        A refused order creates nothing. A replay with the same
        `Idempotency-Key` and the same request answers `200` with
        `idempotent_replay: true` and the order as it stands now; once the order
        is past `awaiting_payment`, its `payment` has no `client_secret` and no
        deposit addresses.


        If the odds stop selling before the payment settles, the pack isn't
        opened at other odds: the order goes to `refund_due` and the customer is
        refunded.
      operationId: createOrder
      parameters:
        - $ref: '#/components/parameters/OrderIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              pack_type: bronze
              category: pokemon
              odds: standard
              quantity: 1
              recipient: 0x8f3c...e21a
              refund_address: 0x8f3c...e21a
              partner_user_ref: okx-uid-102938
      responses:
        '200':
          description: >-
            A replay of an earlier request with the same `Idempotency-Key`
            (`idempotent_replay` is true). Nothing new is created and nothing is
            charged twice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '201':
          description: The order and how to pay it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
              examples:
                single:
                  summary: One pack
                  value:
                    order:
                      order_id: okx-ord-7f3a9c21
                      id: 3d2b8f0e-6c1a-4f7e-9a51-2b0d8c4e7f13
                      status: awaiting_payment
                      pack_type: bronze
                      category: pokemon
                      odds: standard
                      price: 25
                      recipient: 0x8f3c...e21a
                      mint_chain: evm:196
                      paid_at: null
                      pull: null
                      token: null
                      failure_reason: null
                      created_at: '2026-11-16T18:02:11.420Z'
                    payment:
                      intent_id: pi_01JD...
                      client_secret: pi_01JD..._secret_...
                      publishable_key: pk_live_...
                      amount: 25
                      deposit_addresses:
                        - chain: evm:8453
                          address: 0x5a4d...0001
                        - chain: solana:mainnet
                          address: 9xQe...Vf2p
                multi:
                  summary: Three packs
                  value:
                    order:
                      order_id: okx-ord-9b21e4c0
                      id: 5f1c2a90-8d3e-4b6a-9e1f-7c0a2b4d6e81
                      status: awaiting_payment
                      quantity: 3
                      pack_type: bronze
                      category: pokemon
                      odds: standard
                      unit_price: 25
                      price: 75
                      recipient: 0x8f3c...e21a
                      mint_chain: evm:196
                      paid_at: null
                      units:
                        - order_id: okx-ord-9b21e4c0
                          id: a0e1c3d5-2b4f-4e6a-8c1d-3f5a7b9c1e20
                          batch_id: 5f1c2a90-8d3e-4b6a-9e1f-7c0a2b4d6e81
                          unit: 1
                          status: awaiting_payment
                          pack_type: bronze
                          category: pokemon
                          odds: standard
                          price: 25
                          recipient: 0x8f3c...e21a
                          mint_chain: evm:196
                          paid_at: null
                          pull: null
                          token: null
                          failure_reason: null
                          created_at: '2026-11-16T18:02:11.420Z'
                        - order_id: okx-ord-9b21e4c0
                          id: b7d2e4f6-3c5a-4f7b-9d2e-4a6b8c0d2f31
                          batch_id: 5f1c2a90-8d3e-4b6a-9e1f-7c0a2b4d6e81
                          unit: 2
                          status: awaiting_payment
                          pack_type: bronze
                          category: pokemon
                          odds: standard
                          price: 25
                          recipient: 0x8f3c...e21a
                          mint_chain: evm:196
                          paid_at: null
                          pull: null
                          token: null
                          failure_reason: null
                          created_at: '2026-11-16T18:02:11.420Z'
                        - order_id: okx-ord-9b21e4c0
                          id: c4f9a1b3-4d6e-4a8c-8e3f-5b7c9d1e3a42
                          batch_id: 5f1c2a90-8d3e-4b6a-9e1f-7c0a2b4d6e81
                          unit: 3
                          status: awaiting_payment
                          pack_type: bronze
                          category: pokemon
                          odds: standard
                          price: 25
                          recipient: 0x8f3c...e21a
                          mint_chain: evm:196
                          paid_at: null
                          pull: null
                          token: null
                          failure_reason: null
                          created_at: '2026-11-16T18:02:11.420Z'
                      created_at: '2026-11-16T18:02:11.420Z'
                    payment:
                      intent_id: pi_01JD...
                      client_secret: pi_01JD..._secret_...
                      publishable_key: pk_live_...
                      amount: 75
                      deposit_addresses:
                        - chain: evm:8453
                          address: 0x5a4d...0001
                        - chain: solana:mainnet
                          address: 9xQe...Vf2p
        '400':
          description: >-
            - `BAD_IDEMPOTENCY_KEY`: `Idempotency-Key` missing, or not 8-128
            characters of `A-Za-z0-9_-`.

            - `BAD_JSON`: the body isn't JSON.

            - `BAD_RECIPIENT`: `recipient` is not a wallet address on your mint
            chain.

            - `BAD_PACK`: `pack_type` missing.

            - `BAD_CATEGORY`: unknown `category`.

            - `BAD_ODDS`: `odds` isn't `standard`, `hot`, `chill` or `classic`,
            or not one the pack sells (then `odds` lists the choices it sells).

            - `BAD_QUANTITY`: `quantity` isn't a whole number from 1 to 10.

            - `BAD_REFUND_ADDRESS`: no usable EVM `refund_address` (required
            when you mint on Solana).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: recipient must be a evm:196 wallet address
                code: BAD_RECIPIENT
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            - `WALLET_REFUSED`: a wallet in the request failed sanctions
            screening.

            - `WALLET_BLOCKED`: this wallet may not buy from CatchBack.

            - Any of the key and program refusals every endpoint can return
            (`NO_PROGRAM`, `PROGRAM_INACTIVE`, `NOT_AVAILABLE`, a missing scope,
            `Access denied`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: This wallet cannot buy here.
                code: WALLET_REFUSED
        '404':
          description: '`PACK_NOT_OFFERED`: that pack isn''t sold through your program.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: That pack is not sold through this program.
                code: PACK_NOT_OFFERED
        '409':
          description: >-
            Nothing is created.

            - `ODDS_UNAVAILABLE`: those odds aren't selling right now; try
            another choice or later. `odds` echoes the choice.

            - `PACK_UNAVAILABLE`: a pack that sells only its own odds can't open
            right now; `reason` says why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Bronze Pack isn't selling hot odds right now.
                code: ODDS_UNAVAILABLE
                odds: hot
        '422':
          description: >-
            `IDEMPOTENCY_KEY_REUSED`: the key was already used for a different
            order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: This Idempotency-Key was already used for a different order.
                code: IDEMPOTENCY_KEY_REUSED
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: >-
            - `SCREENING_UNAVAILABLE`: wallet screening is briefly unavailable;
            retry shortly with the same `Idempotency-Key`.

            - `AUTH_UNAVAILABLE`, or no code: we couldn't check your key or load
            your program; retry after `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Wallet screening is unavailable; try again shortly.
                code: SCREENING_UNAVAILABLE
components:
  parameters:
    OrderIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Your own order id, 8-128 characters of `A-Za-z0-9_-`, one per order. It
        becomes the order's `order_id`. Retry a timed-out or `500` call with the
        same key. The same key with a different request (`pack_type`,
        `category`, resolved `odds`, `quantity`, `recipient`, `refund_address`)
        is `422`.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_-]{8,128}$
      example: okx-ord-7f3a9c21
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - pack_type
        - recipient
      properties:
        pack_type:
          type: string
          description: A `pack_type` from List packs.
        category:
          $ref: '#/components/schemas/PackCategory'
        odds:
          allOf:
            - $ref: '#/components/schemas/Odds'
          description: 'One the pack sells. Default: the pack''s `default_odds`.'
        quantity:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: 2 or more makes a multi-pack order.
        recipient:
          type: string
          description: >-
            The customer's self-custody wallet on your mint chain. Never an
            exchange deposit address: the NFTs are minted to it.
        refund_address:
          type: string
          description: >-
            An EVM wallet that can receive USDC on Base, for refunds. Required
            on a Solana program; defaults to `recipient` on an EVM program.
        partner_user_ref:
          type: string
          pattern: ^[A-Za-z0-9_.:-]{1,128}$
          description: >-
            Your opaque user id. Never put personal data here. Not compared on
            an idempotent replay.
    CreateOrderResponse:
      type: object
      required:
        - order
        - payment
      properties:
        order:
          anyOf:
            - $ref: '#/components/schemas/OrderBatch'
            - $ref: '#/components/schemas/Order'
        payment:
          $ref: '#/components/schemas/Payment'
        idempotent_replay:
          type: boolean
          const: true
          description: Present on a replay.
    Error:
      type: object
      required:
        - error
      description: >-
        Every error body. `code` is stable where you might branch on it; some
        errors add the fields below.
      properties:
        error:
          type: string
          description: >-
            For people. The text can change, so branch on the status and the
            `code`.
        code:
          description: >-
            Machine-readable, where you might branch on it. New codes can be
            added, so treat an unknown one like a missing one.
          anyOf:
            - $ref: '#/components/schemas/ErrorCode'
            - type: string
        retry_after_seconds:
          type: integer
          description: On `RATE_LIMITED`.
        odds:
          description: >-
            On `BAD_ODDS` when the pack sells other odds: the choices it sells.
            On `ODDS_UNAVAILABLE` from Create an order: the choice asked for.
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/Odds'
            - $ref: '#/components/schemas/Odds'
        reason:
          type:
            - string
            - 'null'
          description: On `PACK_UNAVAILABLE`, why the pack can't open.
        status:
          type: string
          description: On `NOT_PULLED`, the order's status.
        token_ids:
          type: array
          items:
            type: string
          description: On a refusal about particular tokens, the token ids it is about.
        quote_id:
          type: string
          description: >-
            On `TOKEN_IN_SHIPMENT` from the one-token endpoint, the shipment
            waiting for the burn.
        fields:
          type: object
          additionalProperties:
            type: string
          description: >-
            On `BAD_ADDRESS` from a shipment or estimate, each bad address field
            and what is wrong with it.
        order_value:
          type: number
          description: On `COVER_NOT_ALLOWED`.
        min_cover:
          type: number
          description: On `COVER_NOT_ALLOWED`.
        max_cover:
          type:
            - number
            - 'null'
          description: On `COVER_NOT_ALLOWED`; null when the items can't be insured.
        amount:
          type: number
          description: On `PRICE_CHANGED`, the current shipping cost.
        successor:
          type: object
          description: On `ALREADY_ROTATED`, the key that replaced this one.
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: On `ALREADY_ROTATED`, when this key stops working.
    PackCategory:
      type: string
      enum:
        - pokemon
        - onepiece
        - sports
        - riftbound
        - watches
        - goods
      default: pokemon
      description: >-
        `goods` packs hold streetwear and jewelry. Raw singles have no category
        of their own: they come out of other categories' packs.
    Odds:
      type: string
      enum:
        - standard
        - hot
        - chill
        - classic
      description: >-
        The odds a pack is opened at, as in our app's picker. Standard, Hot and
        Chill share one value-band ladder and differ only in the chance of each
        band; Classic is the pack's own bands and chances. A pack that sells
        only its own odds sells just `classic`. [Odds](/partner-api/v2/odds).
    OrderBatch:
      type: object
      description: A multi-pack order (`quantity` 2-10), paid with one payment.
      required:
        - order_id
        - id
        - status
        - quantity
        - pack_type
        - category
        - odds
        - unit_price
        - price
        - recipient
        - mint_chain
        - paid_at
        - units
        - created_at
      properties:
        order_id:
          type: string
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - awaiting_payment
            - paid
            - rolled
            - minted
            - mint_failed
            - expired
            - refund_due
            - refunded
            - processing
            - completed
          description: >-
            `awaiting_payment` until paid; once paid, the units' status when
            they all agree; otherwise `processing` while any unit is still
            moving, and `completed` once every unit is final.
        quantity:
          type: integer
          minimum: 2
          maximum: 10
        pack_type:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        odds:
          $ref: '#/components/schemas/Odds'
        unit_price:
          type: number
          description: The price of one pack.
        price:
          type: number
          description: The total due.
        recipient:
          type: string
        mint_chain:
          $ref: '#/components/schemas/ChainKey'
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        units:
          type: array
          items:
            $ref: '#/components/schemas/OrderUnit'
        created_at:
          type: string
          format: date-time
    Order:
      type: object
      description: One single-pack order.
      required:
        - order_id
        - id
        - status
        - pack_type
        - category
        - odds
        - price
        - recipient
        - mint_chain
        - paid_at
        - pull
        - token
        - failure_reason
        - created_at
      properties:
        order_id:
          type: string
          description: Your `Idempotency-Key`.
        id:
          type: string
          format: uuid
          description: Our id.
        status:
          $ref: '#/components/schemas/OrderStatus'
        pack_type:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        odds:
          $ref: '#/components/schemas/Odds'
        price:
          type: number
        recipient:
          type: string
        mint_chain:
          $ref: '#/components/schemas/ChainKey'
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        pull:
          oneOf:
            - $ref: '#/components/schemas/Pull'
            - type: 'null'
        token:
          oneOf:
            - $ref: '#/components/schemas/OrderToken'
            - type: 'null'
        failure_reason:
          type:
            - string
            - 'null'
          description: 'On `mint_failed`, `expired`, `refund_due` and `refunded`: why.'
        created_at:
          type: string
          format: date-time
    Payment:
      type: object
      description: >-
        A Unifold Payment Intent for exactly the amount due. Open it in your app
        with `client_secret` and `publishable_key` (Unifold's web or React
        Native SDK), or show `deposit_addresses` and `amount`. Paid once at
        least 99% has arrived. [Payments](/partner-api/v2/payments).
      required:
        - intent_id
        - client_secret
        - publishable_key
        - amount
        - deposit_addresses
      properties:
        intent_id:
          type:
            - string
            - 'null'
          description: The Payment Intent's id (`sbx_pi_…` in the sandbox).
        client_secret:
          type:
            - string
            - 'null'
          description: Opens Unifold's checkout. Null once there is nothing left to pay.
        publishable_key:
          type:
            - string
            - 'null'
          description: The public Unifold key to initialise the SDK with.
        amount:
          type: number
          description: The amount due in USD (a multi-pack order's total).
        deposit_addresses:
          type: array
          description: >-
            Addresses the customer can send to directly, on Base and Solana.
            Empty once there is nothing left to pay. Never reuse one for another
            order.
          items:
            type: object
            required:
              - chain
              - address
            properties:
              chain:
                $ref: '#/components/schemas/ChainKey'
              address:
                type: string
    ErrorCode:
      type: string
      description: Every `code` v2 returns. Branch on these, never on the message text.
      enum:
        - RATE_LIMITED
        - AUTH_UNAVAILABLE
        - NO_PROGRAM
        - PROGRAM_INACTIVE
        - NOT_AVAILABLE
        - BAD_JSON
        - BAD_IDEMPOTENCY_KEY
        - IDEMPOTENCY_KEY_REUSED
        - BAD_RECIPIENT
        - BAD_PACK
        - BAD_CATEGORY
        - BAD_ODDS
        - BAD_QUANTITY
        - ODDS_UNAVAILABLE
        - BAD_REFUND_ADDRESS
        - PACK_NOT_OFFERED
        - PACK_UNAVAILABLE
        - WALLET_REFUSED
        - WALLET_BLOCKED
        - SCREENING_UNAVAILABLE
        - UNKNOWN_ORDER
        - NOT_PULLED
        - VERIFY_UNAVAILABLE
        - BAD_CURSOR
        - BAD_LIMIT
        - BAD_STATUS
        - BAD_ADDRESS
        - BAD_PARTNER_USER_REF
        - TOO_MANY_WALLETS
        - UNKNOWN_TOKEN
        - BAD_HOLDER
        - NOT_HOLDER
        - CHAIN_UNAVAILABLE
        - TOKEN_NOT_MINTED
        - TOKEN_BURNED
        - TOKEN_NOT_LIVE
        - NO_OFFER
        - PAYOUT_CHAIN_NOT_SUPPORTED
        - PAYOUT_CHAIN_NOT_ENABLED
        - BAD_PAYOUT_ADDRESS
        - USE_SHIPMENT_ENDPOINT
        - BAD_TOKEN_IDS
        - TOKEN_IN_SHIPMENT
        - BAD_COVER
        - COVER_NOT_ALLOWED
        - COVER_UNAVAILABLE
        - BAD_MAX_COST
        - NOT_SHIPPABLE
        - PARTNER_GOODS
        - COUNTRY_NOT_SUPPORTED
        - OVER_CUSTOMS_CAP
        - RATE_UNAVAILABLE
        - PRICE_CHANGED
        - UNKNOWN_SHIPMENT
        - NOT_PAID
        - ALREADY_REDEEMED
        - HOLDER_CHANGED
        - UNKNOWN_QUOTE
        - INVALID_WEBHOOK_URL
        - WEBHOOK_ACCOUNT_CHANGED
        - WEBHOOKS_UNAVAILABLE
        - UNKNOWN_WEBHOOK
        - KEY_ROTATED
        - BAD_PERIOD
        - INVALID_KEY
        - NO_PREVIOUS_KEY
        - ALREADY_ROTATED
        - UNKNOWN_PAYMENT
        - NOT_BURNED
    ChainKey:
      type: string
      description: >-
        A chain as `<family>:<id>`: `evm:8453` is Base, `evm:<chainId>` any
        other EVM chain (e.g. `evm:196`, X Layer), `solana:mainnet` Solana. The
        sandbox uses a public testnet.
      pattern: ^(evm:[0-9]+|solana:(mainnet|devnet))$
      examples:
        - evm:196
    OrderUnit:
      description: >-
        One pack of a multi-pack order, in the single-order shape under the
        order's `order_id`.
      allOf:
        - $ref: '#/components/schemas/Order'
        - type: object
          required:
            - batch_id
            - unit
          properties:
            batch_id:
              type: string
              format: uuid
              description: The multi-pack order's `id`.
            unit:
              type:
                - integer
                - 'null'
              minimum: 1
              maximum: 10
              description: 1 to `quantity`.
    OrderStatus:
      type: string
      enum:
        - awaiting_payment
        - paid
        - rolled
        - minted
        - mint_failed
        - expired
        - refund_due
        - refunded
      description: >-
        - `awaiting_payment`: waiting for the payment, for up to 24 hours.

        - `expired`: not paid within 24 hours. A payment that still arrives is
        refunded in full.

        - `paid`: settled; the pack opens next.

        - `rolled`: the pack opened (`pull` is set); the NFT is being minted.

        - `minted` (final): the NFT is in `recipient`'s wallet.

        - `mint_failed`: the mint hasn't landed yet; it is retried and never
        re-opens the pack.

        - `refund_due`: being refunded in USDC on Base to `refund_address`;
        `failure_reason` says why (e.g. `paid_after_expiry`, `underpaid`).

        - `refunded` (final): the refund was sent.
    Pull:
      type: object
      required:
        - card_id
        - category
        - name
        - value
        - pulled_at
      properties:
        card_id:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        name:
          type:
            - string
            - 'null'
        value:
          type: number
          description: The item's value when it was pulled; it anchors the sell-back offer.
        pulled_at:
          type: string
          format: date-time
    OrderToken:
      type: object
      description: >-
        The NFT. On an EVM program it has `contract`; on a Solana program
        `collection` and `asset` instead.
      required:
        - chain
        - token_id
        - status
        - tx
      properties:
        chain:
          $ref: '#/components/schemas/ChainKey'
        contract:
          type:
            - string
            - 'null'
          description: EVM only.
        collection:
          type:
            - string
            - 'null'
          description: Solana only.
        asset:
          type:
            - string
            - 'null'
          description: Solana only.
        token_id:
          type:
            - string
            - 'null'
          description: Decimal. Keep it as a string or bigint.
        status:
          type: string
          enum:
            - pending
            - submitted
            - confirmed
            - failed
            - burned
          description: >-
            `pending` (reserved, not sent), `submitted`, `confirmed`, `failed`
            (being retried), or `burned` once sold back or shipped.
        tx:
          type:
            - string
            - 'null'
          description: The mint transaction.
  responses:
    Unauthorized:
      description: >-
        - `Missing or malformed API key`: no `Bearer cb_live_…` header.

        - `Invalid API key`: unknown or disabled, or a rotated key past its 24
        hours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Missing or malformed API key
    RateLimited:
      description: >-
        `RATE_LIMITED`: too many requests from this key. Wait
        `retry_after_seconds`. Limits per key: `POST /orders` 30 a minute; the
        two shipment estimates 30 a minute together; every other endpoint 120 a
        minute together.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many requests. Slow down.
            code: RATE_LIMITED
            retry_after_seconds: 23
    ServerError:
      description: >-
        Our fault. Retry with backoff, with the same `Idempotency-Key` where the
        endpoint takes one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Something went wrong; retry with the same Idempotency-Key.
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cb_live_<48 hex>
      description: >-
        Your API key (`cb_live_…`), sent as a bearer token, with the scope
        `nft:orders`. Keep it on your servers: never in a browser, app or
        wallet. Use a separate key per environment. A request from a country on
        our sanctions list gets a `403` with `Access denied`, whether or not it
        has a valid key. See [Authentication and
        keys](/partner-api/v2/authentication).

````

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