comecerodocs
Concepts

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.

Request
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 listsCursor lists
Used forLists that stay small, such as products, promotions, roles, and the items, payments or refunds of one order or customerLists that keep growing: orders, payments, refunds, carts, invoices, customers, subscriptions, events and more
Move between pagesoffset, or follow next_page_urlafter_item and before_item, or follow next_page_url
Total counttotal_items and total_pagesNone
Sortingsort_by and descBy date (date_type) and desc
Date filtersNodate_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.

Request
curl "https://api.comecero.com/api/v1/products?limit=100&offset=100" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
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

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:

Request
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.

Request
curl "https://api.comecero.com/api/v1/orders?limit=2&desc=true" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
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

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:

ParameterWhat it does
date_startOnly items on or after this date.
date_endOnly items on or before this date.
date_typeWhich date the range applies to. The default is date_created. Each list names the values it supports, such as date_modified or date_completed.
timezoneThe 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:

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.

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

On this page