# Get order fulfillments

`GET /v2/order-fulfillments?order_id=970`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobgo.co.za`
- Production: `https://api.bobgo.co.za`

**Authentication:** Bearer token required (see the Authentication page).

## Example request

```bash
curl -X GET 'https://api.sandbox.bobgo.co.za/v2/order-fulfillments?order_id=970' \
  -H "Authorization: Bearer <API_KEY>"
```

Returns every fulfilment on an order, one per shipment or buyer collection,
newest first. There is no paging: `limit` and `offset` are ignored. This is
where a shipment's tracking reference lives; the order itself does not carry
one, because an order can be fulfilled more than once.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `order_id` | integer | yes | The Bob Go order id. An order that is not on your account returns `404`. |
| `id` | integer | no | Fetch one fulfilment. |
| `include_collection_address` | boolean | no | Include the address the parcel is collected from. |
| `include_return` | boolean | no | Include the return, if the fulfilment is one. |

## Response

Each entry wraps the fulfilment alongside whatever is fulfilling it. Note the
nested `order_fulfillment` key:

```json
{
  "order_fulfillments": [
    {
      "order_fulfillment": {
        "id": 6432,
        "account_id": 1234,
        "order_id": 22837,
        "method": "shipment",
        "method_id": 14273,
        "shipment_id": 14273,
        "method_reference": "UADPWTTF",
        "method_status": "pending-collection",
        "status": "success",
        "failed_reason": "",
        "type": "original",
        "source": "api",
        "time_created": "2022-10-20T19:42:00.642739Z",
        "items": [
          {
            "id": 9921,
            "order_fulfillment_id": 6432,
            "order_id": 22837,
            "order_item_id": 31119,
            "qty": 1,
            "order_item": {
              "id": 31119,
              "description": "Product 1",
              "sku": "",
              "qty": 1,
              "fulfilled_qty": 1,
              "unit_price": 599,
              "unit_weight_kg": 0.1
            }
          }
        ]
      },
      "buyer_collection": null,
      "shipment": { "...": "..." }
    }
  ],
  "count": 1
}
```

| Field | Notes |
| --- | --- |
| `method` | How it is being fulfilled, e.g. `shipment`. |
| `method_id` | The shipment or buyer-collection id. |
| `method_reference` | The tracking reference. |
| `method_status` | The shipment's tracking status, e.g. `pending-collection`. |
| `status` | Whether the fulfilment itself was created successfully. |
| `failed_reason` | Populated when `status` is a failure. |
| `type` | `original`, `return` or `replacement`. |
| `items` | The lines covered by this fulfilment. `qty` is how many of the line went out on this fulfilment, and the order line itself is nested under `order_item`. |
| `shipment` | The full shipment, when `method` is `shipment`; otherwise null. |
| `buyer_collection` | The buyer collection, when that is the method; otherwise null. |

On `order_item`, `fulfilled_qty` against `qty` is the line's progress across
every fulfilment so far, and is what makes an order partially fulfilled: a line
shipped 3 of 5 leaves the order in `partially-fulfilled` until the rest goes
out.

> The `fulfillment/created` webhook delivers the fulfilment **unwrapped**, and
> its `order_items` are flat order lines rather than the nested `items` above.
> If you handle both, normalise them. See [Webhooks](../11_Webhooks/README.md).