List Purchase Invoices

Use this endpoint to poll inbound purchase invoices by date range and paginate through the result set.

Endpoint

GET /api/v3/documents?type=purchases&from=YYYY-MM-DD

Purpose

This endpoint is intended for buyer-side polling flows where you want to:

fetch recent purchase invoices received by your workspace
replay invoices within a specific date window
continue pagination with an opaque cursor

Required Headers

Authorization: Bearer <YOUR_API_KEY>
Accept: application/json
x-client-id: <YOUR_WORKSPACE_ID>
x-api-key-environment: production

Use mock instead of production when polling non-production purchase data.

Query Parameters

Field	Required	Description
`type`	✅ Required	Must be `purchases`
`from`	✅ Required	Start date in `YYYY-MM-DD` format
`to`	⬜ Optional	End date in `YYYY-MM-DD` format. Defaults to `from`
`limit`	⬜ Optional	Maximum items per page. Default `100`, max `100`
`cursor`	⬜ Optional	Opaque base64 cursor returned by a previous response

Example Request

curl -X GET 'https://YOUR_GATEWAY/api/v3/documents?type=purchases&from=2026-06-01&to=2026-06-08&limit=5' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'x-client-id: YOUR_WORKSPACE_ID' \
  -H 'x-api-key-environment: production'

Example Success Response

{
  "success": true,
  "data": {
    "items": [
      {
        "documentId": "01KT0SHAH3K21158AC72ZXVX4Z",
        "receivedAt": "2026-06-08T07:04:01.550Z",
        "storedAt": "2026-06-08T07:04:02.102Z",
        "status": "purchase.invoice.stored",
        "country": "AE",
        "environment": "production",
        "invoiceNumber": "INV-2026-001",
        "supplierName": "Acme Supplies LLC",
        "issueDate": "2026-06-05"
      }
    ],
    "hasMore": true,
    "nextCursor": "eyJ0cyI6IjIwMjYtMDYtMDhUMDc6MDQ6MDEuNTUwWiIsImV2ZW50SWQiOiJwdXJjaGFzZTowMUhBQkMxMjNERUY0NTYifQ=="
  }
}

Response Fields

Field	Description
`data.items[].documentId`	Purchase invoice document ID
`data.items[].receivedAt`	Timestamp when the invoice was received
`data.items[].storedAt`	Timestamp when the invoice was stored
`data.items[].status`	Purchase event status
`data.items[].country`	Country code
`data.items[].environment`	Source environment
`data.items[].invoiceNumber`	Supplier invoice number when available
`data.items[].supplierName`	Supplier name when available
`data.items[].issueDate`	Invoice issue date when available
`data.hasMore`	Whether more results are available
`data.nextCursor`	Cursor to request the next page

Cursor Pagination

When hasMore is true, send the returned nextCursor back on the next request:

curl -X GET 'https://YOUR_GATEWAY/api/v3/documents?type=purchases&from=2026-06-01&limit=100&cursor=PASTE_CURSOR_HERE' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'x-client-id: YOUR_WORKSPACE_ID' \
  -H 'x-api-key-environment: production'

Treat the cursor as opaque. Do not parse or modify it.

Common Errors

Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Missing `from`, invalid date format, invalid `type`, or invalid limit
`400`	`NOT_SUPPORTED`	`type=sales` listing is not supported here
`401`	`AUTHORIZATION_ERROR`	Authentication failed or client context missing
`500`	`INTERNAL_ERROR`	Unexpected polling failure

Notes

currently only type=purchases is supported for document listing
if to is omitted, the API uses the same date as from
the endpoint returns summary metadata, not the full invoice payload
use the single-document endpoint to retrieve the full purchase invoice body