# Lists and pagination (/docs/basic-concepts/lists-and-pagination)

Any endpoint that returns many objects returns them one page at a time. This page shows how to read a page, move to the next one, sort the list and filter it by date.

## Page size [#page-size]

Send `limit` to choose how many items come back on one page, from 1 to 100. The default is 100. A `limit` outside 1 to 100, or one that is not a whole number, is a `400`.

```bash title="Request"
curl "https://api.comecero.com/api/v1/products?limit=20" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

## Two kinds of list [#two-kinds-of-list]

Some lists are offset based and some are cursor based. Each list endpoint in the [API reference](/api) says which one it is.

| | Offset lists | Cursor lists |
| --- | --- | --- |
| Used for | Lists that stay small, such as products, promotions, roles, and the items, payments or refunds of one order or customer | Lists that keep growing: orders, payments, refunds, carts, invoices, customers, subscriptions, events and more |
| Move between pages | `offset`, or follow `next_page_url` | `after_item` and `before_item`, or follow `next_page_url` |
| Total count | `total_items` and `total_pages` | None |
| Sorting | `sort_by` and `desc` | By date (`date_type`) and `desc` |
| Date filters | No | `date_start`, `date_end`, `date_type`, `timezone` |

The same kind of object can be in both. For example, [List payments](/api/payments/list-payments) for the whole account is a cursor list, while [List customer payments](/api/customers/list-customer-payments) is an offset list.

## Offset lists [#offset-lists]

An offset list tells you where you are: how many items match and which page this is.

```bash title="Request"
curl "https://api.comecero.com/api/v1/products?limit=100&offset=100" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```json title="Response"
{
  "total_items": 227,
  "total_pages": 3,
  "current_page": 2,
  "next_page_url": "https://api.comecero.com/api/v1/products?limit=100&offset=200",
  "next_page_offset": 200,
  "previous_page_url": "https://api.comecero.com/api/v1/products?limit=100&offset=0",
  "previous_page_offset": 0,
  "current_page_url": "https://api.comecero.com/api/v1/products?limit=100&offset=100",
  "data": [
    { "object": "product", "product_id": "widget-pro", "name": "Widget Pro" }
  ]
}
```

`offset` is how many items to skip before the page starts. Use `next_page_offset` and `previous_page_offset` from the page you have. On the last page `next_page_url` and `next_page_offset` are `null`.

### Sorting an offset list [#sorting-an-offset-list]

Send `sort_by` with one of the fields the endpoint lists, and `desc=true` to reverse the order. For example, [List products](/api/products/list-products) sorts by `name` by default and also takes `date_created`, `date_modified` and more:

```bash title="Request"
curl "https://api.comecero.com/api/v1/products?sort_by=date_created&desc=true" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

## Cursor lists [#cursor-lists]

A cursor list has no total. It points to the pages next to this one by the id of an item.

```bash title="Request"
curl "https://api.comecero.com/api/v1/orders?limit=2&desc=true" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```json title="Response"
{
  "next_page_url": "https://api.comecero.com/api/v1/orders?limit=2&desc=true&after_item=6622-NXKHE-858",
  "next_page_after_item": "6622-NXKHE-858",
  "previous_page_url": null,
  "previous_page_before_item": null,
  "data": [
    { "object": "order", "order_id": "7731-PQRST-112" },
    { "object": "order", "order_id": "6622-NXKHE-858" }
  ]
}
```

- `after_item` returns the items after the item with that id. Use `next_page_after_item` from the page you have.
- `before_item` returns the items before it. Use `previous_page_before_item`.
- You cannot send both (`400`). An id that does not exist is a `404`.
- On the last page `next_page_url` and `next_page_after_item` are `null`. `current_page_url` is only there when you sent `after_item` or `before_item`.

A cursor list is ordered by date, oldest first. `desc=true` puts the newest first. `sort_by` does not apply.

## Get every page [#get-every-page]

`next_page_url` keeps the query parameters you sent, so the simplest loop follows it until it is `null`. This works for both kinds of list.

```js
async function listAll(url) {
  const items = [];
  let next = url;
  while (next) {
    const response = await fetch(next, {
      headers: { Authorization: `Bearer ${process.env.COMECERO_TEST_TOKEN}` },
    });
    const page = await response.json();
    if (!response.ok) throw new Error(page.error.message);
    items.push(...page.data);
    next = page.next_page_url;
  }
  return items;
}

const orders = await listAll(
  'https://api.comecero.com/api/v1/orders?date_start=2026-11-01&date_end=2026-11-30',
);
```

## Filter by date [#filter-by-date]

Cursor lists and reports take a date range:

| Parameter | What it does |
| --- | --- |
| `date_start` | Only items on or after this date. |
| `date_end` | Only items on or before this date. |
| `date_type` | Which date the range applies to. The default is `date_created`. Each list names the values it supports, such as `date_modified` or `date_completed`. |
| `timezone` | The time zone a date without an offset is read in, for example `America/New_York`. The default is your account's time zone. |

All orders changed in November 2026, New York time:

```bash title="Request"
curl "https://api.comecero.com/api/v1/orders?date_start=2026-11&date_end=2026-11&date_type=date_modified&timezone=America/New_York" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

A short date such as `2026-11` means the start of November in `date_start` and the end of November in `date_end`. `date_start` must not be after `date_end` (`400`). Every date format you can send, including words like `yesterday`, is in [Dates and times](/docs/basic-concepts/dates-and-times).

## Other list options [#other-list-options]

Most lists also take their own filters, such as `status` or `q` for a search. These are listed on each endpoint's page. Lists also take [`expand`](/docs/basic-concepts/expanding-objects) (up to 2 paths, applied to every item) and [`show` and `hide`](/docs/basic-concepts/customizing-output).

## Next steps [#next-steps]

<Cards>
  <Card title="Dates and times" href="/docs/basic-concepts/dates-and-times" />
  <Card title="Expanding objects" href="/docs/basic-concepts/expanding-objects" />
</Cards>
