Get a shipment

One shipment by its id: status, tracking, the cards in it and the address it ships to.

GET /api/partner/v1/shipments/{id}

cURL

curl https://catchbackcards.com/api/partner/v1/shipments/7c1e0000-1111-4222-8333-444444444444 \
  -H "Authorization: Bearer $CATCHBACK_KEY"

200

{
  "id": "7c1e0000-…",
  "status": "shipped",
  "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
  "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?tRef=fullpage&tLc=2&text28777=&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-5a2f-4b1e-9c3d-7f8a1b2c3d4e", "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
  }
}

Scope: ship:cards, granted on request · MCP tool: get_shipment, which takes the id as shipment_id

One shipment on your account, with the same fields as in List shipments plus the cards and the address. It always has the current status, so it’s the place to check after a shipment.updated event or a SHIPMENT_OUTCOME_UNKNOWN.

id · string · required

The id that Create a shipment returned, or the shipment_id in an error. A UUID.

Response

Every field of a shipment in List shipments, plus:

items · object[]

The cards in the shipment. Empty until the order exists, and if we’ve removed the order.

Show item

card_id · string

name · string | null

grade · number | null

grading_company · string | null

value · number | null

The card’s market value in USD when you created the shipment.

address · object | null

Where it ships to. null until the order exists, and if we’ve removed the order. Also null after we’ve removed the address, when address_removed is true: how long we keep it.

Show address

name · string | null

address1 · string

address2 · string | null

city · string

state · string | null

zip · string | null

country · string

phone · string | null

Errors

Status	Code	When
403		The key lacks ship:cards or isn’t linked to an account, the account is deleted ("Partner account unavailable"), or it can’t request shipping
403	FEATURE_RESTRICTED	The account is restricted from the marketplace or from withdrawals, so its key can’t read addresses. Contact us
404		No shipment with this id on your account. An unknown id, a malformed one, another account’s shipment and an unconfirmed shipment we’ve since removed all look the same
500		We couldn’t load the shipment. Retry with backoff
503		We couldn’t check the account. Try again

cURL

curl https://catchbackcards.com/api/partner/v1/shipments/7c1e0000-1111-4222-8333-444444444444 \
  -H "Authorization: Bearer $CATCHBACK_KEY"

200

{
  "id": "7c1e0000-…",
  "status": "shipped",
  "card_ids": ["0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e"],
  "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?tRef=fullpage&tLc=2&text28777=&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-5a2f-4b1e-9c3d-7f8a1b2c3d4e", "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
  }
}