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

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

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](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) 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](https://catchbackcards.mintlify.site/partner-api/pagination.md).

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

**shipment**

**id** `string`

The shipment's id. [Get a shipment](https://catchbackcards.mintlify.site/partner-api/endpoints/get-shipment.md) takes it.

**status** `string`

`pending`, `needs_review`, `processing`, `shipped`, `delivered` or `cancelled`: [what they mean](https://catchbackcards.mintlify.site/partner-api/shipping.md#status).

**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`](https://catchbackcards.mintlify.site/partner-api/webhook-events#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](https://catchbackcards.mintlify.site/partner-api/shipping.md#customer-addresses).

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

```bash cURL theme={null}
curl "https://catchbackcards.com/api/partner/v1/shipments?page=1&per_page=50" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

```json 200 theme={null}
{
  "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
    }
  ]
}
```


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