Pagination

All Tilta list endpoints use offset-based pagination, which lets you retrieve large result sets in manageable chunks by specifying a starting position and a maximum page size. Every paginated response includes a total field that tells you how many records exist in total, so you always know when you have retrieved everything.

Query parameters

Pass the following query parameters on any list endpoint to control pagination:

Parameter	Type	Default	Description
`offset`	Integer	`0`	The zero-based index of the first item to return. An offset of `0` returns items starting from the very beginning of the result set.
`limit`	Integer	`100`	The maximum number of items to return in a single response. `100` is also the highest accepted value – a larger `limit` is rejected with a `400`, not clamped.

How to paginate

Request the first page

Start with offset=0 and your desired limit. The response body will include the first batch of results and a total field indicating how many records exist across all pages.

curl --request GET \
     --url 'https://api.tilta.io/v1/orders?limit=100&offset=0' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Inspect the response

The response contains the result array and pagination metadata:

{
  "items": [ /* up to 100 order objects */ ],
  "total": 347,
  "limit": 100,
  "offset": 0
}

In this example, total is 347, meaning there are three more pages to fetch after this one.

Request the next page

Calculate the next offset by adding the previous limit to the previous offset:

next_offset = previous_offset + previous_limit

For the second page:

curl --request GET \
     --url 'https://api.tilta.io/v1/orders?limit=100&offset=100' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Detect the last page

You have retrieved all records when the next offset would exceed the total:

if (next_offset >= total) → stop

For the example above with total=347 and limit=100:

Page	Offset	Items returned
1	0	100
2	100	100
3	200	100
4	300	47
–	400	Stop – 400 ≥ 347

Complete pagination loop

The example below shows a full pagination loop in Python that collects every order into a single list:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.tilta.io/v1/orders"
LIMIT = 100

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Accept": "application/json",
}

all_orders = []
offset = 0

while True:
    response = requests.get(
        BASE_URL,
        headers=headers,
        params={"limit": LIMIT, "offset": offset},
    )
    response.raise_for_status()
    data = response.json()

    all_orders.extend(data["items"])

    offset += LIMIT
    if offset >= data["total"]:
        break

print(f"Fetched {len(all_orders)} orders in total.")

Request the largest limit your use case allows to minimise the number of round trips. For bulk exports or background sync jobs, a limit of 100 is a good starting point. For real-time UI pagination, a smaller limit (e.g. 20) typically provides a better user experience.

Offset-based pagination reflects the state of the result set at query time. If records are created or deleted between page requests, you may see slight inconsistencies (a record appearing on two pages, or being skipped). For critical reconciliation tasks, compare against the total field and re-fetch if the count changes unexpectedly.

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

Query parameters

How to paginate

​Query parameters

​How to paginate

​Complete pagination loop

Query parameters

How to paginate

Complete pagination loop