Pagination & filtering

Every Tokeflow list endpoint returns results in pages. You ask for a page; Tokeflow returns that slice plus a meta.pagination block describing where you are in the full result set. The same conventions apply everywhere — transactions, orders, customers, products, subscriptions, and more — so once you learn them for one resource you know them for all.

This page covers two things:

• Pagination — page / limit, the meta.pagination block, and a loop that walks every page.
• Filtering — date ranges, multi-value status filters, and entity/currency filters that narrow a list before you paginate it.

Pagination

Query parameters

Two query parameters control paging. Both are optional.

Requesting page=1&limit=20 returns the first 20 items. Requesting page=2&limit=20 returns items 21–40, and so on. Values outside the allowed range return 400 validation_error.

The meta.pagination block

Paginated responses wrap the array in the standard success envelope. The array lives in data; paging details live in meta.pagination.

Iterating every page

To process an entire result set, request page 1 and keep advancing while has_next is true. Stop when it turns false.

The Node helper below walks every page of a list endpoint and yields each item. It uses the maximum limit to minimize requests, and relies on has_next rather than computing offsets by hand.

/**
 * Async generator that yields every item across all pages of a Tokeflow list endpoint.
 * `path` is a resource path, e.g. "/api/v1/customers".
 * `params` are extra filters, e.g. { currency: "BRL" }.
 */
async function* paginate(path, params = {}, { limit = 100 } = {}) {
  let page = 1;

  for (;;) {
    const url = new URL(`https://api.tokeflow.com${path}`);
    url.searchParams.set("page", String(page));
    url.searchParams.set("limit", String(limit));
    for (const [key, value] of Object.entries(params)) {
      url.searchParams.set(key, value);
    }

    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.TOKEFLOW_SECRET_KEY}`,
        Accept: "application/json",
      },
    });
    const body = await res.json();

    for (const item of body.data) {
      yield item;
    }

    if (!body.meta.pagination.has_next) break;
    page += 1;
  }
}

// Usage — collect every BRL customer.
const customers = [];
for await (const customer of paginate("/api/v1/customers", { currency: "BRL" })) {
  customers.push(customer);
}

Filtering

Filters are additional query parameters that narrow a list before pagination is applied. Combine as many as the endpoint supports; they are AND-ed together. The available filters vary per resource — check each endpoint reference for the exact set — but the conventions are consistent.

Date-range filters

Most list endpoints support a created-at window via date_from and date_to. Both take ISO 8601 timestamps in UTC. Either may be supplied alone.

?date_from=2026-01-01T00:00:00Z&date_to=2026-01-31T23:59:59Z

Multi-value filters (status)

Status filters accept multiple values. You can pass them two equivalent ways:

• Repeat the parameter: ?status=authorized&status=refunded
• Comma-separate the values: ?status=authorized,refunded

Both produce the same result — any item whose status matches any of the listed values. Use the exact enum values for the resource (for example, transaction statuses such as authorized, refunded, partially_refunded; see the endpoint reference for each resource's enum).

Entity & currency filters

List endpoints expose filters that scope results to a related entity or attribute. The exact set depends on the resource. Common examples:

Example: a filtered, paginated request

List the first page of transactions that are authorized or refunded, in BRL, created during January 2026. (Auth: Organization key with merchant_id, or Merchant key.)

curl -G https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxx" \
  -H "Accept: application/json" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=authorized,refunded" \
  --data-urlencode "currency=BRL" \
  --data-urlencode "date_from=2026-01-01T00:00:00Z" \
  --data-urlencode "date_to=2026-01-31T23:59:59Z"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "tx_9a8b7c6d",
      "status": "authorized",
      "amount": 15000,
      "currency": "BRL",
      "payment_method": "credit_card",
      "charge_type": "payment",
      "customer_id": "cust_7h2k9",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "id": "tx_5f4e3d2c",
      "status": "refunded",
      "amount": 9900,
      "currency": "BRL",
      "payment_method": "pix",
      "charge_type": "payment",
      "customer_id": "cust_3p9q1",
      "created_at": "2026-01-09T08:12:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a91",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Because has_next is true, request page=2 with the same filters to continue, and keep going until has_next is false.

Errors

Example (400 validation_error):

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_VALUE",
    "message": "limit must not be greater than 100",
    "details": { "field": "limit", "max": 100 },
    "request_id": "req_1b2c3d4e",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

See Errors for the full error-type reference.

Related reading

• API overview — base URL, versioning, and the success/error envelopes.
• Authentication — key types, scopes, and the merchant_id rule for Organization keys.
• Idempotency & rate limits — retry-safe mutations and per-key throughput.
• Errors — every error type and HTTP-status mapping.