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

{
  "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

{
  "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": "[email protected]"
  }
}

With include=products

{
  "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

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

With Includes

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

Filter by Status

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

Filter by Type

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

Filter by User

# 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][email protected]" \
  -H "X-User-Token: your-api-token"

Filter by Product

# 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

# 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

# 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

# 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

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

# 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)

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

Invalid Include (422)

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

Invalid Date Range (422)

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

Per Page Out of Range (422)

{
  "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 - Get a specific order
• Overview - API overview

---