Query and incremental sync
Use this guide when your ERP or middleware polls Paystand instead of consuming webhooks (for example, on-prem connectors that cannot receive HTTPS callbacks).
Authentication headers
Every request:
Authorization: Bearer {access_token}
X-CUSTOMER-ID: {merchant_customer_id}
Accept: application/json
Pattern A — f.querytype=by-query-filters
Date-range filtering applies only when you pass nested query parameters under f and set:
f.querytype=by-query-filters
Without f.querytype, other f.* parameters are ignored.
Common parameters
| Parameter | Required | Description |
|---|---|---|
f.querytype | Yes | Must be by-query-filters |
f.datepreset | For custom ranges | Use custom with start/end, or a preset such as past7days |
f.datestart | For custom ranges | Start date YYYY-MM-DD |
f.dateend | For custom ranges | End date YYYY-MM-DD (inclusive calendar day) |
f.datetype | Recommended | created or lastUpdated — use lastUpdated for incremental sync |
f.limit | No | Page size (default 50) |
f.offset | No | Skip rows for pagination |
f.order | No | e.g. lastUpdated DESC |
Optional: f.timezone (IANA name) affects how calendar days are interpreted before conversion to UTC. Retrieve the merchant default from Get Merchant Timezone. If that call returns 400 with Integrations OAuth, supply a known IANA timezone from merchant settings instead.
Example — receivables updated in a date range
GET /v3/receivables?f.querytype=by-query-filters&f.datepreset=custom&f.datestart=2026-05-01&f.dateend=2026-05-22&f.datetype=lastUpdated&f.limit=50&f.offset=0
Use GET /receivables (filtered list), not GET /receivables/read. The /read endpoint only supports limit, offset, and order.
Endpoints that support Pattern A
| Resource | Endpoint |
|---|---|
| Receivables | GET /receivables |
| Payments | GET /payments/all (also supports top-level startDate / endDate) |
| Refunds | GET /refunds or GET /refunds/all |
| Disputes | GET /disputes or GET /disputes/all |
| Transfers | GET /transfers |
| Withdrawals | GET /withdrawals or GET /withdrawals/all |
See also Webhook and REST polling matrix.
Pattern B — top-level startDate / endDate
Some list endpoints accept startDate and endDate as top-level query parameters. The API converts them internally to Pattern A. See List Payments, List Refunds, and List Disputes.
Credit memos — different list model
Credit memos do not support by-query-filters. List with:
f.querytype=own(default)f.querytype=by-payerCustomerIdf.querytype=by-erpName
See List Credit Memos.
Important limitations
- Calendar-day granularity —
f.datestart/f.dateendare dates, not times. You cannot request “10:00–11:00” in a single call; ranges expand to full days in the resolved timezone. - Large exports — Avoid
f.limit=-1on receivables; very large result sets can time out. - Voiding invoices — Use Cancel Receivable. Do not attempt to delete receivable rows.