Skip to content

Pagination and filtering

Read every page of a list with the cursor, and narrow it with filters.

Version v1.1, updated

On this page

Lists return one page at a time, ordered by id, with a cursor that points to the next page. Filters narrow a list, and updated_since returns only what changed.

Pages and the cursor

  • limit sets the page size, from 1 to 200. Without it a page has 50 records.

  • meta.has_more is true while another page exists.

  • meta.next_cursor is the cursor of the next page. Send it back as cursor, with the same filters.

  • A cursor is opaque: pass it as you received it, and never build one.

meta of a pageJSON
{
  "has_more": true,
  "limit": 50,
  "next_cursor": "opaque-cursor-example"
}

Read every page

Repeat the call with cursor until has_more is false. Each record appears once, in id order.

GET /v1/products
let cursor = null;
do {
  const url = new URL("https://api.birp.io/v1/products");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.BIRP_API_KEY}` },
  });
  if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
  const { data, meta } = await response.json();
  for (const product of data) handle(product);
  cursor = meta.has_more ? meta.next_cursor : null;
} while (cursor);

Read only what changed

updated_since returns the records changed at or after a time, written in ISO 8601 with an offset or Z. Keep the time you started the last sync and pass it at the next one.

Note. The first full sync reads every record. Later syncs with updated_since read only what changed since the previous one.

Stock levels have no updated_since. Keep a shop's stock in step with BIRP shows how to read them.

Filters per resource

Every list takes limit and cursor. Filters combine with "and".

Filters most lists take

Every list except GET /v1/stock/levels and GET /v1/tax-codes takes these.

Filter

What it keeps

updated_since

Only records changed at or after this time: ISO 8601 date and time with an offset or Z.

external_id

Identifier in an external system. Requires source.

source

External system of external_id, in lowercase. Requires external_id.

Filters of one resource

Filter

What it keeps

email on GET /v1/customers

Contact email, case-insensitive exact match.

tax_id on GET /v1/customers

Registration number, exact match, surrounding spaces ignored.

status on GET /v1/invoices

Document status.

customer_id on GET /v1/invoices

Invoices of one customer.

status on GET /v1/orders

Order status.

customer_id on GET /v1/orders

Orders of one customer.

sku on GET /v1/products

Exact product reference. May match one goods item and one finished product.

barcode on GET /v1/products

Exact barcode.

status on GET /v1/products

active or archived.

kind on GET /v1/products

goods or finished_product.

warehouse_id on GET /v1/stock/levels

A warehouse id, or none for stock not assigned to a warehouse.

product_id on GET /v1/stock/levels

One product.

date on GET /v1/tax-codes

YYYY-MM-DD. Left out: the company today.

Find a record by external id

Pass external_id and source together to find the record your own system knows by that id. The answer is a list with one record, or none.

GET /v1/products
curl "https://api.birp.io/v1/products?source=woocommerce&external_id=1042" \
  -H "Authorization: Bearer $BIRP_API_KEY"
  • responses
  • references-and-external-ids
  • sync-products
  • rate-limits