Skip to content
JuicePay

JuicePay documentation

Create account

Documentation

Pagination and filtering

Cursor semantics plus the filter grammar shared by list endpoints.

Every list endpoint shares one pagination contract so you only have to implement it once.

Cursor pagination#

bash
curl -s "$JUICEPAY_URL/v1/payouts?limit=50" \
  -H "Authorization: Bearer $JUICEPAY_KEY" | jq
json
{
  "object": "list",
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "cur_8kL3mQ2xNpRt"
}

Pass the cursor to continue. Cursors are opaque — do not parse them, and do not construct them.

bash
curl -s "$JUICEPAY_URL/v1/payouts?limit=50&starting_after=cur_8kL3mQ2xNpRt" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

limit accepts 1 to 200 and defaults to 20.

Why not offset pagination#

Cursors are stable under concurrent writes. With offset, a row inserted while you are paging shifts every subsequent page and you silently skip records. For a payout ledger, silently skipping records is unacceptable.

Auto-pagination#

The SDKs expose an async iterator that handles cursors for you:

ts
for await (const payout of juicepay.payouts.list({ status: "settled" })) {
  await record(payout);
}

Filtering#

List endpoints accept created as a range, expressed with the usual comparison operators:

bash
curl -s "$JUICEPAY_URL/v1/payouts?created_gte=2026-08-01&created_lt=2026-09-01" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Use half-open ranges (gte with lt) for date windows. A closed range on both ends double-counts anything created exactly at midnight.

Resources reference related objects by ID. Request the expansion instead of making N calls.

bash
curl -s "$JUICEPAY_URL/v1/payment_intents/pi_9fK2xQ?expand[]=settlements&expand[]=ledger_entries" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Payouts, payment intents, and recipients support a limited search over your own references.

bash
curl -s "$JUICEPAY_URL/v1/payment_intents?search=INV-1042" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Search matches prefixes on references and exact matches on IDs. It is intended for support tooling, not for building your own reporting layer — use the settlement reports for that.

Report exports#

For anything beyond a few thousand records, use exports.

bash
curl -s -X POST "$JUICEPAY_URL/v1/reports" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{
    "type": "payout_ledger",
    "created_gte": "2026-08-01",
    "created_lt": "2026-09-01",
    "format": "csv"
  }'

Exports are generated asynchronously. Poll the report for status: "ready" and download from the signed URL, which expires after one hour.