Pagination

Page through lists with a cursor, and filter them

Every list endpoint returns results newest first, in pages. You move through pages with a cursor: the id of the last object you received.

---

Parameters

Parameter	Type	Description
limit	integer	Objects per page. From 1 to 100. Defaults to 25.
starting_after	string	The id of the last object on the previous page. Returns the objects after it.

Response

{
  "data": [
    { "id": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11", "object": "customer", "…": "…" }
  ],
  "has_more": true
}

Field	Description
data	The objects on this page.
has_more	true when another page exists. When false, you have reached the end.

Lists use a cursor and not a page number. New rows can arrive while you are paging, and a page number would repeat or skip one. A cursor can’t.

---

Get every page

Take the id of the last object in data, pass it as starting_after, and stop when has_more is false.

Node.js

async function listAll(path, apiKey) {
  const results = [];
  let startingAfter;

  do {
    const url = new URL(`https://api.saasybill.com/v1${path}`);
    url.searchParams.set("limit", "100");
    if (startingAfter) url.searchParams.set("starting_after", startingAfter);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const page = await response.json();

    results.push(...page.data);
    startingAfter = page.has_more ? page.data.at(-1).id : undefined;
  } while (startingAfter);

  return results;
}

const subscriptions = await listAll("/subscriptions?status=active", process.env.SAASYBILL_API_KEY);

---

Filters

Filters combine with paging. An invalid value answers 422 and names the parameter. status takes one or more values separated by commas, such as ?status=active,draft. Leave it out to get every status.

Endpoint	Filter	Description
GET /v1/customers	code	The customer’s code.
	email	The customer’s email. Not case-sensitive.
	status	active or inactive.
GET /v1/plans	code	The plan’s code.
	status	draft, active, inactive or legacy.
GET /v1/charges	code	The charge’s code.
	status	draft, active, inactive or legacy.
GET /v1/subscriptions	customer	A customer id.
	customer_code	A customer code.
	status	pending, active, complete or ended.
GET /v1/invoices	subscription	A subscription id.
	customer	A customer id.
	status	draft, awaiting_approval, approved, paid, voided, deleted or not_in_external.
GET /v1/credit_notes	subscription	A subscription id.
	customer	A customer id.
	status	draft, awaiting_approval, approved, paid, voided, deleted or not_in_external.

Every list returns every status unless you set status. To list the plans and charges a new subscription can use, ask for ?status=active,draft.

GET /v1/customers lists customers only. A Xero contact that hasn’t been imported as a customer in Saasybill doesn’t appear.