# Get orders

`GET /v2/orders?limit=10&offset=0`

**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/orders?limit=10&offset=0' \
  -H "Authorization: Bearer <API_KEY>"
```

Lists orders on your account, most recently placed first. Standard
[pagination](../1_Introduction/README.md#listing-and-pagination) applies:
`limit`, `offset`, `order_by` and `order`. The response carries a `count` of
the full result set.

A channel key only sees the orders on its own channel, except when it fetches
one order by `id`: that only checks the order is on your account.

## Parameters

| Name | Type | Notes |
| --- | --- | --- |
| `id` | integer | Fetch one order. |
| `channel_order_number` | string | Filter on your own order number. |
| `limit` | integer | Page size. Defaults to 100, capped at 100. |
| `offset` | integer | Rows to skip. Use with `limit` to page. |
| `start_date` | timestamp | Filters on the date the order was placed. |
| `end_date` | timestamp | Filters on the date the order was placed. |
| `order` | string | `asc` or `desc`. Ignored unless you also send `order_by`. |
| `order_by` | string | Field to sort on. Leave it out for the default, `date_placed_on_channel` descending. Sent without `order`, it sorts ascending. |
| `payment_status` | array of string | `unpaid`, `pending`, `authorized`, `partially-paid`, `paid`, `partially-refunded`, `refunded`, `voided`. |
| `status` | array of string | `new`, `processing`, `completed`, `cancelled`. A new order's `status` comes back empty, and `new` matches it. |
| `fulfillment_status` | array of string | `fulfilled`, `unfulfilled`, `partially-fulfilled`. |
| `tracking_reference` | string | The tracking reference of a shipment fulfilling the order. |
| `has_delivery_address` | boolean | `true` returns only orders with a delivery address, `false` only orders without one. |
| `delivery_address_zone` | array of string | Filter on the province code of the delivery address, e.g. `["GP","WC"]`. A province name such as `Gauteng` matches nothing. See [addresses](../4_Important%20concepts/README.md#addresses). |
| `archived` | boolean | `true` returns only archived orders, `false` only orders that are not archived. Leave it out to get both. |
| `include_items` | boolean | The order's line items, in `order_items`. Defaults to `true`. |
| `include_relations` | boolean | The delivery address, channel, tags and the users who created or archived the order. Defaults to `true`. |
| `include_fulfillments` | boolean | The fulfilments, with their tracking references. Defaults to `false`. |

Array filters are sent as a JSON array in the query string, with no spaces,
e.g. `?fulfillment_status=["unfulfilled","partially-fulfilled"]`. With a space
after the comma the filter matches nothing.

## Response

One order, trimmed to the fields most integrations read:

```json
{
  "orders": [
    {
      "id": 22837,
      "account_id": 1234,
      "channel_id": 311,
      "channel_order_number": "ABC123",
      "customer_name": "John",
      "customer_surname": "Doe",
      "customer_email": "john@doe.com",
      "customer_phone": "0123456789",
      "currency": "ZAR",
      "buyer_selected_shipping_cost": 49.99,
      "buyer_selected_shipping_method": "Standard Shipping",
      "payment_status": "paid",
      "status": "",
      "fulfillment_status": "unfulfilled",
      "total_price": 1500,
      "total_qty": 15,
      "total_weight_kg": 1.5,
      "date_placed_on_channel": "2026-09-05T08:30:00Z",
      "delivery_address": { "...": "..." },
      "order_items": [
        {
          "id": 31119,
          "description": "item1",
          "sku": "sku1",
          "vendor": "item1",
          "qty": 15,
          "fulfilled_qty": 0,
          "unit_price": 100,
          "unit_weight_kg": 0.1
        }
      ],
      "time_created": "2026-09-05T08:30:12Z"
    }
  ],
  "count": 1
}
```

Items and relations are on unless you turn them off, so on a large page ask
only for what you use.