Lists and pagination
How Comecero API lists return pages of up to 100 items, the difference between offset and cursor lists, and how to sort them and filter them by date.
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
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.
curl "https://api.comecero.com/api/v1/products?limit=20" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"Two kinds of list
Some lists are offset based and some are cursor based. Each list endpoint in the API reference 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 for the whole account is a cursor list, while List customer payments is an offset list.
Offset lists
An offset list tells you where you are: how many items match and which page this is.
curl "https://api.comecero.com/api/v1/products?limit=100&offset=100" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"{
"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
Send sort_by with one of the fields the endpoint lists, and desc=true to reverse the order. For example, List products sorts by name by default and also takes date_created, date_modified and more:
curl "https://api.comecero.com/api/v1/products?sort_by=date_created&desc=true" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"Cursor lists
A cursor list has no total. It points to the pages next to this one by the id of an item.
curl "https://api.comecero.com/api/v1/orders?limit=2&desc=true" \
-H "Authorization: Bearer $COMECERO_TEST_TOKEN"{
"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_itemreturns the items after the item with that id. Usenext_page_after_itemfrom the page you have.before_itemreturns the items before it. Useprevious_page_before_item.- You cannot send both (
400). An id that does not exist is a404. - On the last page
next_page_urlandnext_page_after_itemarenull.current_page_urlis only there when you sentafter_itemorbefore_item.
A cursor list is ordered by date, oldest first. desc=true puts the newest first. sort_by does not apply.
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.
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
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:
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.
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 (up to 2 paths, applied to every item) and show and hide.
Next steps
Errors
The error object every failed Comecero API call returns, what each HTTP status code means, and what your code should do next, such as after a declined card.
Expanding objects
Use the expand query parameter to get related Comecero objects, such as an order's customer and payments, in the same API response instead of as URLs.