> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fulfillment Batches

> Retrieve the fulfillment batches for a completed order

Returns the fulfillment batches for an order. Large orders are split into batches internally by Orbt — this endpoint exposes each batch and its individual status. Useful for monitoring progress on large bulk orders where some batches may complete before others.

## Endpoint

**GET /v2/orders/\{orderId}/fulfillments**

## Path Parameters

| Name      | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `orderId` | string | Yes      | The order ID returned by `POST /v2/orders` |

## Query Parameters

| Name       | Type    | Required | Description                                 |
| ---------- | ------- | -------- | ------------------------------------------- |
| `page`     | integer | No       | Page number, default `1`                    |
| `pageSize` | integer | No       | Results per page, default `100`, max `2000` |

## Example Request

```bash theme={null}
curl -X GET "https://partner.orbt.com/v2/orders/ORD-123456/fulfillments" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-timestamp: 2026-08-13T10:00:00.000Z" \
  -H "x-body-hash: BODY_HASH" \
  -H "x-signature: SIGNATURE"
```

```javascript theme={null}
const orderId = 'ORD-123456';

const response = await fetch(
  `https://partner.orbt.com/v2/orders/${orderId}/fulfillments?page=1&pageSize=100`,
  {
    method: 'GET',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-client-id': 'YOUR_CLIENT_ID',
      'x-timestamp': timestamp,
      'x-body-hash': bodyHash,
      'x-signature': signature
    }
  }
);

const { data, meta } = await response.json();
```

## Response — 200 OK

```json theme={null}
{
  "data": [
    {
      "fulfillmentId": "FUL-0001",
      "status": "COMPLETED",
      "quantity": 200,
      "completedAt": "2026-08-13T10:01:00Z"
    },
    {
      "fulfillmentId": "FUL-0002",
      "status": "PROCESSING",
      "quantity": 100
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 100,
      "totalRecords": 2,
      "totalPages": 1,
      "hasNext": false
    }
  }
}
```

## Response Fields

| Field           | Type     | Description                                                            |
| --------------- | -------- | ---------------------------------------------------------------------- |
| `fulfillmentId` | string   | Unique identifier for this fulfillment batch                           |
| `status`        | string   | Batch status: `PENDING`, `PROCESSING`, `COMPLETED`, or `FAILED`        |
| `quantity`      | integer  | Number of codes in this batch                                          |
| `completedAt`   | datetime | Batch completion timestamp. Only present when `status` is `COMPLETED`. |

## When to Use This Endpoint

<CardGroup cols={2}>
  <Card title="Monitor large orders" icon="chart-bar">
    Track progress batch by batch for orders with hundreds or thousands of codes.
  </Card>

  <Card title="Diagnose partial failures" icon="triangle-exclamation">
    Identify which batches failed or are still processing when an order is taking longer than expected.
  </Card>
</CardGroup>

## Fulfillment vs Items vs Export

| Endpoint                                       | Best for                                          |
| ---------------------------------------------- | ------------------------------------------------- |
| `GET /v2/orders/{orderId}/items`               | Small orders — retrieve individual codes directly |
| `GET /v2/orders/{orderId}/fulfillments/export` | Large orders — single CSV download with all codes |
| `GET /v2/orders/{orderId}/fulfillments`        | Monitoring batch progress on very large orders    |

## Error Responses

| Status | Code                   | Description                               |
| ------ | ---------------------- | ----------------------------------------- |
| `401`  | `AUTHENTICATION_ERROR` | Missing or invalid authentication headers |
| `404`  | `RESOURCE_NOT_FOUND`   | Order not found                           |