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

# List Orders

Retrieve a paginated list of orders with powerful filtering, sorting, and response shaping capabilities.

## Endpoint

```
GET /api/v3/orders
```

---

## Query Parameters

### Pagination

| Parameter  | Type    | Default | Description                                    |
| ---------- | ------- | ------- | ---------------------------------------------- |
| `per_page` | integer | 100     | Items per page (1-500)                         |
| `cursor`   | string  | -       | Cursor token from `links.next` or `links.prev` |

### Includes

| Parameter | Type   | Description                                             |
| --------- | ------ | ------------------------------------------------------- |
| `include` | string | Comma-separated: `user`, `products`, `pending_checkout` |

### Fields Selection

| Parameter | Type   | Description                              |
| --------- | ------ | ---------------------------------------- |
| `fields`  | string | Comma-separated list of fields to return |

### Sorting

| Parameter | Type   | Default       | Description                                |
| --------- | ------ | ------------- | ------------------------------------------ |
| `sort`    | string | `-created_at` | Sort field. Prefix with `-` for descending |

**Allowed sort fields:** `created_at`, `updated_at`

### Filters

| Parameter                     | Type    | Description                                                       |
| ----------------------------- | ------- | ----------------------------------------------------------------- |
| `filter[id]`                  | string  | Filter by internal order ID (numeric)                             |
| `filter[uuid]`                | string  | Filter by order UUID                                              |
| `filter[external_id]`         | string  | Filter by your external ID                                        |
| `filter[status]`              | string  | Filter by status: `pending`, `approved`, `paused`, `cancelled`    |
| `filter[type]`                | string  | Filter by type: `permission`, `report`, `internal_report`, `sale` |
| `filter[user_id]`             | integer | Filter by user's internal ID                                      |
| `filter[user_external_id]`    | string  | Filter by user's external ID                                      |
| `filter[user_email]`          | string  | Filter by user's email                                            |
| `filter[product_type]`        | string  | Filter by product type: `content`, `subscription`                 |
| `filter[product_id]`          | integer | Filter by product's internal ID                                   |
| `filter[product_external_id]` | string  | Filter by product's external ID (ISBN, SKU, etc.)                 |

### Date Range Filters

| Parameter                  | Type     | Format                                | Description                     |
| -------------------------- | -------- | ------------------------------------- | ------------------------------- |
| `filter[created_at][from]` | datetime | `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss` | Orders created after this date  |
| `filter[created_at][to]`   | datetime | `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss` | Orders created before this date |
| `filter[updated_at][from]` | datetime | `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss` | Orders updated after this date  |
| `filter[updated_at][to]`   | datetime | `YYYY-MM-DD` or `YYYY-MM-DD HH:mm:ss` | Orders updated before this date |

---

## Response Structure

### Base Response

```json
{
  "data": [
    {
      "id": "12345",
      "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
      "external_id": "ORDER-123",
      "type": "permission",
      "status": "approved",
      "unit_price": 29.99,
      "currency_id": "USD",
      "created_at": "2025-12-03T22:43:44.000000Z",
      "updated_at": "2025-12-03T22:43:44.000000Z"
    }
  ],
  "links": {
    "next": "https://yourstore.publica.la/api/v3/orders?cursor=eyJ...",
    "prev": null
  },
  "meta": {
    "has_more": true
  }
}
```

### With `include=user`

```json
{
  "id": "12345",
  "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
  "external_id": "ORDER-123",
  "type": "permission",
  "status": "approved",
  "unit_price": 29.99,
  "currency_id": "USD",
  "created_at": "2025-12-03T22:43:44.000000Z",
  "updated_at": "2025-12-03T22:43:44.000000Z",
  "user": {
    "id": "67890",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "user-ext-123",
    "email": "customer@example.com"
  }
}
```

### With `include=products`

```json
{
  "id": "12345",
  "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
  "...": "...",
  "products": [
    {
      "id": "54321",
      "external_id": "9781234567890",
      "type": "content",
      "name": "Digital Marketing Handbook",
      "status": "approved",
      "expiration_date": "2026-12-31",
      "unit_price": 29.99,
      "currency_id": "USD",
      "cover_url": "https://cdn.publica.la/covers/book.jpg",
      "reader_url": "https://yourstore.publica.la/reader/digital-marketing",
      "product_url": "https://yourstore.publica.la/library/publication/digital-marketing"
    }
  ]
}
```

---

## Examples

### Basic List

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### With Includes

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders?include=user,products" \
  -H "X-User-Token: your-api-token"
```

### Filter by Status

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[status]=approved" \
  -H "X-User-Token: your-api-token"
```

### Filter by Type

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[type]=permission" \
  -H "X-User-Token: your-api-token"
```

### Filter by User

```bash
# By user's internal ID
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[user_id]=12345" \
  -H "X-User-Token: your-api-token"

# By user's external ID
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[user_external_id]=user-ext-123" \
  -H "X-User-Token: your-api-token"

# By user's email
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[user_email]=customer@example.com" \
  -H "X-User-Token: your-api-token"
```

### Filter by Product

```bash
# By product's internal ID
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[product_id]=67890" \
  -H "X-User-Token: your-api-token"

# By product's external ID (ISBN, SKU, etc.)
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[product_external_id]=9781234567890" \
  -H "X-User-Token: your-api-token"
```

### Filter by Date Range

```bash
# Orders created in the last week
curl -X GET "https://yourstore.publica.la/api/v3/orders?filter[created_at][from]=2025-11-26 00:00:00&filter[created_at][to]=2025-12-03 23:59:59" \
  -H "X-User-Token: your-api-token"
```

### Sort by Updated Date

```bash
# Newest updates first
curl -X GET "https://yourstore.publica.la/api/v3/orders?sort=-updated_at" \
  -H "X-User-Token: your-api-token"

# Oldest first
curl -X GET "https://yourstore.publica.la/api/v3/orders?sort=created_at" \
  -H "X-User-Token: your-api-token"
```

### Sparse Fieldsets

```bash
# Only return id, status, and type
curl -X GET "https://yourstore.publica.la/api/v3/orders?fields=id,status,type" \
  -H "X-User-Token: your-api-token"
```

### Combined Filters

```bash
curl -X GET "https://yourstore.publica.la/api/v3/orders?\
filter[type]=permission&\
filter[status]=approved&\
filter[created_at][from]=2025-01-01 00:00:00&\
sort=-created_at&\
include=user,products&\
per_page=50" \
  -H "X-User-Token: your-api-token"
```

### Pagination Flow

```bash
# First page
curl -X GET "https://yourstore.publica.la/api/v3/orders?per_page=100" \
  -H "X-User-Token: your-api-token"

# Response includes:
# "links": { "next": "...?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0xMi0wMyAxMDoxMDowNCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }

# Next page
curl -X GET "https://yourstore.publica.la/api/v3/orders?per_page=100&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0xMi0wMyAxMDoxMDowNCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" \
  -H "X-User-Token: your-api-token"
```

---

## Error Responses

### Invalid Sort Field (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "sort": ["Invalid sort field. Allowed: created_at, updated_at, status"]
  }
}
```

### Invalid Include (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "include": [
      "Invalid include: invalid_field. Allowed: user, products, pending_checkout"
    ]
  }
}
```

### Invalid Date Range (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "filter.created_at.from": ["Start date must be before end date"]
  }
}
```

### Per Page Out of Range (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "per_page": ["The per page must be between 1 and 500."]
  }
}
```

---

## Best Practices

1. **Use `per_page` wisely** - Higher values reduce API calls but increase payload size
2. **Always check `meta.has_more`** - Don't assume based on item count
3. **Use `fields` parameter** - Reduce payload size by requesting only needed fields
4. **Cache cursor tokens** - Store the last cursor for resumable syncs
5. **Filter at the API level** - Use filters instead of fetching all and filtering on your side

---

## See Also

- [Get Order](./orders-v3-get.md) - Get a specific order
- [Overview](./orders-v3-overview.md) - API overview