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
limitsets the page size, from 1 to 200. Without it a page has 50 records.meta.has_moreistruewhile another page exists.meta.next_cursoris the cursor of the next page. Send it back ascursor, with the same filters.A cursor is opaque: pass it as you received it, and never build one.
{
"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.
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);import os
import requests
cursor = None
while True:
params = {"limit": 200}
if cursor:
params["cursor"] = cursor
response = requests.get(
"https://api.birp.io/v1/products",
params=params,
headers={"Authorization": f"Bearer {os.environ['BIRP_API_KEY']}"},
timeout=10,
)
response.raise_for_status()
body = response.json()
for product in body["data"]:
handle(product)
if not body["meta"]["has_more"]:
break
cursor = body["meta"]["next_cursor"]<?php
$cursor = null;
do {
$query = ["limit" => 200];
if ($cursor !== null) $query["cursor"] = $cursor;
$ch = curl_init("https://api.birp.io/v1/products?" . http_build_query($query));
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BIRP_API_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($body["data"] as $product) handle($product);
$cursor = $body["meta"]["has_more"] ? $body["meta"]["next_cursor"] : null;
} while ($cursor !== null);# First page
curl "https://api.birp.io/v1/products?limit=200" \
-H "Authorization: Bearer $BIRP_API_KEY"
# Next page: pass meta.next_cursor of the previous answer
curl "https://api.birp.io/v1/products?limit=200&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $BIRP_API_KEY"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.
Filters of one resource
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.
curl "https://api.birp.io/v1/products?source=woocommerce&external_id=1042" \
-H "Authorization: Bearer $BIRP_API_KEY"const response = await fetch("https://api.birp.io/v1/products?source=woocommerce&external_id=1042", {
headers: {
Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
},
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();<?php
$ch = curl_init("https://api.birp.io/v1/products?source=woocommerce&external_id=1042");
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BIRP_API_KEY"),
],
CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);import os
import requests
response = requests.request(
"GET",
"https://api.birp.io/v1/products",
params={"source": "woocommerce", "external_id": "1042"},
headers={
"Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
},
timeout=10,
)
response.raise_for_status()
result = response.json()Related
- responses
- references-and-external-ids
- sync-products
- rate-limits