> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-reference/pagination.md).

# Pagination

List endpoints return their results a page at a time. You choose the page size and position with `limit` and `offset`, and every response tells you the total and whether there is more.

## Request parameters

| Parameter | Default                      | Meaning                                                                                              |
| --------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| `limit`   | `20`                         | Items per page, from `1` to `100`. A larger value is treated as `100`                                |
| `offset`  | `0`                          | How many items to skip before the page starts                                                        |
| `sort`    | the endpoint's default order | The field to sort by. Each endpoint accepts its own fields (below); an unrecognized value is ignored |
| `sortDir` | `asc`                        | `asc` or `desc`                                                                                      |

## Response

Items are in `data`. The `pagination` block describes the page you received:

```json
{
  "data": [ /* up to `limit` items */ ],
  "pagination": {
    "total": 137,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  },
  "nextActions": [ /* links to related calls */ ],
  "requestId": "…"
}
```

| Field     | Meaning                                            |
| --------- | -------------------------------------------------- |
| `total`   | Items matching your filters, across all pages      |
| `limit`   | The page size that was applied (after the 100 cap) |
| `offset`  | The offset that was applied                        |
| `hasMore` | `true` when items exist beyond this page           |

## Retrieve every page

Start at `offset=0` and add `limit` each time, until `hasMore` is `false`:

```bash
offset=0
while :; do
  page=$(curl -s "https://api.peakcommerce.app/api/v1/orders?limit=100&offset=$offset&sort=createdAt&sortDir=desc" \
    -H "Authorization: Bearer $PEAKCOMMERCE_API_KEY")
  echo "$page" | jq -c '.data[]'
  [ "$(echo "$page" | jq '.pagination.hasMore')" = "true" ] || break
  offset=$((offset + 100))
done
```

An `offset` beyond the end is not an error: it returns an empty `data` array with `hasMore: false`.

Pages are computed when you ask for them. If items are created while you walk a long list, an item can shift across a page boundary. Sort by `createdAt` so that new items land at one end, and use each item's `id` to deduplicate.

## Sorting and filtering by endpoint

| Endpoint                                    | `sort` fields              | Filters    |
| ------------------------------------------- | -------------------------- | ---------- |
| `GET /api/v1/orders`                        | `createdAt`, `totalCents`  | `status`   |
| `GET /api/v1/subscriptions`                 | `createdAt`                | `status`   |
| `GET /api/v1/payments`                      | `createdAt`, `amountCents` | `status`   |
| `GET /api/v1/webhooks`                      | —                          | `isActive` |
| `GET /api/v1/accounts/{id}/invoices`        | —                          | —          |
| `GET /api/v1/accounts/{id}/subscriptions`   | —                          | —          |
| `GET /api/v1/accounts/{id}/payment-methods` | —                          | —          |

Filters narrow `total` as well as the page, so `?status=active` on subscriptions pages through active subscriptions only.

## Short lists

A few endpoints return a short, bounded list in full, with no `pagination` block. Examples are the webhook event types and the shipping options. Each endpoint's reference page shows its response.

## Change detection

To react to changes, prefer [webhooks](https://docs.peakcommerce.com/developers/api-reference/webhooks-overview.md) to re-reading lists: they push each event as it happens.

## Related

* [Errors](https://docs.peakcommerce.com/developers/api-reference/errors.md)
* [Rate limits](https://docs.peakcommerce.com/developers/api-reference/rate-limits.md)
* [Webhooks](https://docs.peakcommerce.com/developers/api-reference/webhooks-overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/api-reference/pagination.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
