> ## 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. # Get a shipment > **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). One shipment on your account, with its cards and the address it ships to. It always has the current status, so it's the place to check after a `shipment.updated` event or a `SHIPMENT_OUTCOME_UNKNOWN`. We remove the address 90 days after a shipment closes, or 180 days after it shipped if the carrier never reported an end: [how long we keep it](/partner-api/shipping#customer-addresses). ## OpenAPI ````yaml /partner-api/openapi.yaml get /api/partner/v1/shipments/{id} 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/{id}: get: tags: - Shipping summary: Get a shipment description: >- **Scope:** `ship:cards`, opt-in, granted on request (needs a linked account). One shipment on your account, with its cards and the address it ships to. It always has the current status, so it's the place to check after a `shipment.updated` event or a `SHIPMENT_OUTCOME_UNKNOWN`. We remove the address 90 days after a shipment closes, or 180 days after it shipped if the carrier never reported an end: [how long we keep it](/partner-api/shipping#customer-addresses). operationId: getShipment parameters: - name: id in: path required: true description: >- The `id` Create a shipment returned, or the `shipment_id` in an error. schema: type: string format: uuid example: 7c1e0000-1111-4222-8333-444444444444 responses: '200': description: The shipment. content: application/json: schema: $ref: '#/components/schemas/ShipmentDetail' example: id: 7c1e0000-… status: shipped 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: '9400100000000000000000' tracking_url: >- https://tools.usps.com/go/TrackConfirmAction?tLabels=9400100000000000000000 created_at: '2026-11-02T18:04:11.000Z' status_updated_at: '2026-11-03T16:20:00.000Z' shipped_at: '2026-11-03T16:20:00.000Z' expected_delivery: null delivered_at: null items: - card_id: 0e94dc61-… name: Charizard ex grade: 10 grading_company: PSA value: 410 address: name: Sam Rivera address1: 1 Example Way address2: null city: Testville state: CA zip: '94000' country: US phone: null '401': $ref: '#/components/responses/Unauthorized' '403': description: >- - The key lacks `ship:cards` or isn't linked to an account. - `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, so its key can't read addresses. Contact us. content: application/json: schema: $ref: '#/components/schemas/RestrictedError' '404': description: >- No shipment with this id on your account. An unknown id, a malformed one and another account's shipment all look the same. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Shipment not found '500': $ref: '#/components/responses/ServerError' '503': description: We couldn't check the account. Try again. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: - ship:cards components: schemas: ShipmentDetail: allOf: - $ref: '#/components/schemas/Shipment' - type: object required: - items - address properties: items: type: array description: The cards in the shipment. Empty until the order exists. items: type: object required: - card_id - name - grade - grading_company - value properties: card_id: type: string name: type: - string - 'null' grade: type: - number - 'null' grading_company: type: - string - 'null' value: type: - number - 'null' description: >- The card's market value in USD when you created the shipment. address: type: - object - 'null' description: >- Where it ships to. `null` until the order exists, and after we've removed the address. properties: name: type: - string - 'null' address1: type: string address2: type: - string - 'null' city: type: string state: type: - string - 'null' zip: type: - string - 'null' country: type: string phone: type: - string - 'null' 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. 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. 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. 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.