Pagination

List endpoints return a page of results at a time. Each response has an items array and a pagination object that tells you whether more results exist and how to fetch them.

Response shape

Every list endpoint returns the same shape.

{
  "items": [],
  "pagination": {
    "next_cursor": "cur_20",
    "prev_cursor": null,
    "has_more": true,
    "limit": 20,
    "offset": 0,
    "returned": 20,
    "total": 47
  }
}

string | null

Pass as cursor on your next request to fetch the following page. null on the last page.

string | null

Pass as cursor to fetch the previous page. null on the first page.

boolean

true when more results exist beyond this page.

integer

The page size actually applied, after clamping to the maximum.

integer

The record offset this page starts from.

integer

The number of items in this page. May be less than limit on the last page.

integer

The total number of records matching the query.

Request parameters

Parameter	Type	Default	Description
`limit`	integer	20	Page size. Values above 100 are clamped to 100.
`cursor`	string	none	A `next_cursor` or `prev_cursor` from a previous response. Takes precedence over `offset`.
`offset`	integer	0	Record offset to start from. Ignored when `cursor` is set.

limit is clamped, not rejected. A limit above 100 returns 100 results rather than an error.

Walking through pages

With an official SDK, listAll in Node.js or list_all in Python walks every page for you and fetches each page only as you reach it. The examples below call the API directly. Start with no cursor, then pass next_cursor on each request until has_more is false.

import requests

API_KEY = "sk_sandbox_..."
BASE_URL = "https://api.bachs.io"

cursor = None
while True:
    params = {"limit": 20}
    if cursor:
        params["cursor"] = cursor

    page = requests.get(
        f"{BASE_URL}/v1/customers",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    ).json()

    for customer in page["items"]:
        print(customer["customer_id"])

    if not page["pagination"]["has_more"]:
        break
    cursor = page["pagination"]["next_cursor"]

const API_KEY = "sk_sandbox_...";
const BASE_URL = "https://api.bachs.io";

let cursor = null;
const all = [];

while (true) {
  const params = new URLSearchParams({ limit: "20" });
  if (cursor) params.set("cursor", cursor);

  const page = await fetch(`${BASE_URL}/v1/customers?${params}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }).then((r) => r.json());

  all.push(...page.items);

  if (!page.pagination.has_more) break;
  cursor = page.pagination.next_cursor;
}

Cursors

Cursors are opaque tokens returned by the API. Do not build them or read meaning from their value. Always use the next_cursor and prev_cursor from a response. Passing a malformed cursor returns a 400 with error_code BAD_REQUEST.

{
  "detail": "Invalid cursor format. Expected 'cur_<offset>'.",
  "error_code": "BAD_REQUEST",
  "doc_url": "https://docs.bachs.io/api-reference/error-reference#general"
}

Tips

Check has_more to decide whether to continue, rather than comparing returned to limit.
Store next_cursor between requests instead of computing offsets yourself.

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Files

Media

Misc

Transfers

Persons

Platform Fees

Reference

Response shape

Request parameters

Walking through pages

Cursors

Tips