> ## 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. # List shipments > **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). Every shipment on your account, newest first, across every key linked to it. No address appears here: Get a shipment has that. [What each status means](/partner-api/shipping#status). Unlike the other list endpoints, this one doesn't clamp: a `page` or `per_page` out of range is a `400`. ## OpenAPI ````yaml /partner-api/openapi.yaml get /api/partner/v1/shipments 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 Wallet 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: support@catchbackcards.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: get: tags: - Shipping summary: List shipments description: >- **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). Every shipment on your account, newest first, across every key linked to it. No address appears here: Get a shipment has that. [What each status means](/partner-api/shipping#status). Unlike the other list endpoints, this one doesn't clamp: a `page` or `per_page` out of range is a `400`. operationId: listShipments parameters: - name: page in: query description: 1-based. schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: 1–100. schema: type: integer minimum: 1 maximum: 100 default: 50 responses: '200': description: One page of shipments. content: application/json: schema: type: object required: - page - per_page - total - shipments properties: page: type: integer per_page: type: integer total: type: - integer - 'null' description: '`null` on a page past the end, which has no shipments.' shipments: type: array items: $ref: '#/components/schemas/Shipment' example: page: 1 per_page: 50 total: 1 shipments: - id: 7c1e0000-… status: processing card_ids: - 0e94dc61-… carrier: USPS service: Priority Mail service_token: usps_priority cost: 12.85 cover_amount: null insurance_cost: 0 destination_country: US tracking_number: null tracking_url: null created_at: '2026-11-02T18:04:11.000Z' status_updated_at: null shipped_at: null expected_delivery: null delivered_at: null '400': description: '`page` isn''t a positive number, or `per_page` isn''t 1–100.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: The key lacks `ship:cards` or isn't linked to an account. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/ServerError' security: - bearerAuth: - ship:cards components: schemas: Shipment: allOf: - $ref: '#/components/schemas/ShipmentEvent' - type: object required: - destination_country properties: destination_country: type: string address_removed: type: boolean description: Present and `true` once we've removed the address. 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. ShipmentEvent: type: object description: >- A shipment as a webhook sends it. It has nothing from the customer's address. required: - id - status - card_ids - carrier - service - service_token - cost - cover_amount - insurance_cost - tracking_number - tracking_url - created_at - status_updated_at - shipped_at - expected_delivery - delivered_at properties: id: type: string description: The shipment's id. Get a shipment takes it. status: $ref: '#/components/schemas/ShipmentStatus' card_ids: type: array items: type: string carrier: type: - string - 'null' description: '`null` until we''ve confirmed a rate.' service: type: - string - 'null' service_token: type: - string - 'null' cost: type: - number - 'null' description: >- What the shipment charges in USD, including any insurance premium. `null` until we've confirmed a rate. cover_amount: type: - number - 'null' description: >- The insurance on this shipment, in USD. `null` without insurance, and before the order exists. insurance_cost: type: - number - 'null' description: >- The premium in USD, which is part of `cost`. `0` without insurance, and `null` before the order exists. tracking_number: type: - string - 'null' description: '`null` until there''s a label.' tracking_url: type: - string - 'null' created_at: type: string status_updated_at: type: - string - 'null' description: When the order's status last changed. shipped_at: type: - string - 'null' expected_delivery: type: - string - 'null' delivered_at: type: - string - 'null' needs_review: type: boolean description: Present and `true` while `status` is `needs_review`. ShipmentStatus: type: string description: >- - `pending`: the shipment hasn't reached an order yet. - `needs_review`: we couldn't confirm the charge, and it's with our team. - `processing`: the order is queued for fulfillment. - `shipped`, `delivered`: the carrier has it, or has delivered it. - `cancelled`: the order was cancelled or resolved outside shipping. enum: - pending - needs_review - processing - shipped - delivered - cancelled 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 ServerError: description: An error on our side. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' 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.