# Get Orders

`GET /api/v1/orders`

Retrieves a paginated list of Order objects for one location and at most 31 business dates. Every check since the tenant's POS archive began is available: `meta.data_from` is the first business date that can be served, and today's checks are included as they are imported. A request for several locations or a longer range is refused with a 422 pointing at Data Exports, which serves any range asynchronously. Requires the `read` ability and the export orders permission; franchisee tokens may read only locations in their portfolio.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page[number]` | integer | no | Page number (starts at 1). |
| `page[size]` | integer | no | Orders per page (default 30, max 1000). |
| `filter[location_id]` | string | yes | One location UUID the token may read. |
| `filter[start_date]` | string | no | Inclusive lower bound on business date. Defaults to six days before end_date. |
| `filter[end_date]` | string | no | Inclusive upper bound on business date. Defaults to today on the tenant's calendar. Must be on or after start_date, and the range at most 31 days. |
| `sort` | string | no | Allowed: business_date_on, order_created_at, net_sales_amount. Default: -business_date_on. |
| `include` | string | no | Comma-separated. Allowed: items, payments. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/orders?filter%5Blocation_id%5D=9d3f6b2e-5a41-4c7e-9a0b-2f1c8e7d4a63" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"
```

## Responses

### 200 Success

```json
{
    "links": {
        "first": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
        "last": "https://app.franchisesee.com/api/v1/locations?page[number]=10",
        "prev": "https://app.franchisesee.com/api/v1/locations?page[number]=1",
        "next": "https://app.franchisesee.com/api/v1/locations?page[number]=3"
    },
    "meta": {
        "data_from": "2024-01-01"
    },
    "data": [
        {
            "id": "100245871",
            "location": {
                "id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                "name": "Downtown Austin"
            },
            "order_created_at": "2026-06-08T10:01:17",
            "payment_at": "2026-06-08T10:14:02",
            "business_date_on": "2026-06-08",
            "check_number": "318",
            "device_id": "2",
            "employee_id": "10457",
            "day_part_id": "2",
            "channel": {
                "id": "3",
                "name": "Online"
            },
            "order_type": {
                "id": "1",
                "name": "Pickup"
            },
            "total_amount": 24.87,
            "tax_amount": 1.89,
            "tip_amount": 2,
            "service_charge_amount": 0,
            "discount_amount": 2,
            "gift_card_amount": 0,
            "net_sales_amount": 20.98,
            "void_amount": 0,
            "num_customers": 1,
            "guest_count": 1,
            "items": [
                {
                    "description": "Chicken Burrito Bowl",
                    "item_external_id": "10233",
                    "category_uuid": "b8d1f3a5-7c9e-4b2d-a6f8-0e3c5a7d9b12",
                    "quantity": 1,
                    "price": 11.49,
                    "discount_amount": 1,
                    "net_sales_amount": 10.49,
                    "num_customers": 1
                }
            ],
            "payments": [
                {
                    "tender_type_id": "4",
                    "card_brand": "Visa",
                    "amount": 24.87,
                    "tip_amount": 2,
                    "paid_at": "2026-06-08T10:14:02"
                }
            ]
        }
    ]
}
```

### 401 Authentication failed or missing.

```json
{
    "message": "Unauthenticated."
}
```

### 403 The token lacks the required ability or the caller is not permitted.

```json
{
    "message": "This API token does not have the 'create' ability."
}
```

### 422 Validation failed.

```json
{
    "message": "The name field is required.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
```

### 503 Order history is busy; retry after the `Retry-After` header's seconds.
