Pagination and filtering

Pagination

List endpoints return a paginated payload:

{
  "count": 142,
  "next": "https://api.piriod.com/customers/?page=2",
  "previous": null,
  "results": [
    /* items of the current page */
  ]
}

Control pagination with query parameters:

Parameter	Type	Default	Notes
`page`	integer	`1`	1-indexed page number.
`page_size`	integer	`20`	Items per page (max `100`).

curl "https://api.piriod.com/customers/?page=2&page_size=50" \
  -H "Authorization: Token sk_live_xxxxx" \
  -H "x-simple-workspace: acc_..."

Filtering

Filters are exposed as query parameters. Each list endpoint declares the filterable fields in the API Reference (see the Parameters tab). For example, GET /customers/ accepts country, email, name, tax_id, created, subscriptions, sources. Common patterns:

# exact match
?status=active

# range (date or numeric fields)
?created__gte=2026-01-01&created__lte=2026-01-31

# membership
?status__in=draft,finalized

# nested foreign keys
?customer=cus_01H8XYZ123ABC

Filtering by metadata

Resources that expose a metadata field accept arbitrary filters using the metadata__<key> pattern:

?metadata__order_id=12345

Ordering

Use ordering to sort the results. Prefix the field name with - for descending order:

?ordering=name
?ordering=-created

Each list endpoint declares its supported ordering fields.

Search

Some endpoints expose search for free-text matching across configured fields:

?search=acme

Piriod API

Billing

Payments

Procurement

Collections

Pagination and filtering

Filtering

Filtering by metadata

Ordering

Search

​Pagination

​Filtering

​Filtering by metadata

​Ordering

​Search

Pagination

Filtering

Filtering by metadata

Ordering

Search