List shipments

Your account’s shipments, newest first, with their status and tracking. No addresses.

GET /api/partner/v1/shipments

cURL

curl "https://catchbackcards.com/api/partner/v1/shipments?page=1&per_page=50" \
  -H "Authorization: Bearer $CATCHBACK_KEY"

200

{
  "page": 1,
  "per_page": 50,
  "total": 1,
  "shipments": [
    {
      "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
    }
  ]
}

Scope: ship:cards, granted on request · MCP tool: list_shipments

Every shipment on your account, newest first, across every key linked to it. No address appears here: Get a shipment has that.

page · integer · default: "1"

1-based.

per_page · integer · default: "50"

1–100.

Unlike the other list endpoints, this one doesn’t clamp: a page or per_page out of range is a 400. See Pagination.

Response

page · integer

per_page · integer

total · integer | null

Shipments across all pages. null on a page past the end, which has no shipments.

shipments · object[]

Newest first.

Show shipment

id · string

The shipment’s id. Get a shipment takes it.

status · string

pending, needs_review, processing, shipped, delivered or cancelled: what they mean.

card_ids · string[]

The cards in the shipment.

carrier · string | null

null until we’ve confirmed a rate.

service · string | null

service_token · string | null

cost · number | null

What the shipment charges in USD, including any insurance premium. null until we’ve confirmed a rate.

cover_amount · number | null

The insurance on this shipment, in USD. null without insurance, and before the order exists.

insurance_cost · number | null

The premium in USD, which is part of cost. 0 without insurance, and null before the order exists.

destination_country · string

tracking_number · string | null

null until there’s a label.

tracking_url · string | null

The carrier’s tracking page. null until there’s a label, or if we don’t recognize the carrier.

created_at · string

status_updated_at · string | null

When the order’s status last changed. null until it first changes after the order is created. Between two shipment.updated events, the later one is the newer.

shipped_at · string | null

expected_delivery · string | null

delivered_at · string | null

needs_review · boolean

Present and true while status is needs_review.

address_removed · boolean

Present and true once we’ve removed the address: how long we keep it.

Errors

Status	When
400	page isn’t a positive number, or per_page isn’t 1–100
403	The key lacks ship:cards or isn’t linked to an account
500	We couldn’t load your shipments. Retry with backoff

cURL

curl "https://catchbackcards.com/api/partner/v1/shipments?page=1&per_page=50" \
  -H "Authorization: Bearer $CATCHBACK_KEY"

200

{
  "page": 1,
  "per_page": 50,
  "total": 1,
  "shipments": [
    {
      "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
    }
  ]
}