Skip to content

Pagination ​

The list endpoints (invoices, transactions, payouts) return 25 items on each page. The newest items are first. Each response has a pagination block. Use the p query parameter to select a page.

Example of a response with the pagination block:

json
{
  "pagination": {
    "num_pages": 3,
    "count": 62,
    "page": 1,
    "next_page": 2,
    "previous_page": null,
    "per_page": 25,
    "limit_reached": false
  },
  "result": []
}

The limit of a list ​

A list returns the newest 100,000 items only. That is 4,000 pages.

  • count is never more than 100000, and num_pages is never more than 4000.
  • On page 4000, next_page is null. If the list has older items, limit_reached is true.
  • A page number above 4000 gives HTTP 400.
  • To get the older items, use the from_id parameter. Refer to Continue a list after the limit.

Get the newest items ​

  1. Request page 1. It has the 25 newest items.
  2. If you need more items, request the page that next_page gives.
  3. Stop when you have the number of items that you need.

Get all items of a list ​

  1. Request page 1.
  2. Request the page that next_page gives.
  3. Do step 2 again until next_page is null.
  4. If limit_reached is true on that page, continue the list.

Rules:

  • next_page is always correct. It is null only on the last page.
  • Do not calculate page numbers from count or num_pages. On an account with a large history, these two values are not accurate before the last page.
  • New items go to the first page while you read the list. Each new item moves the older items down by one position. Thus you can get the same item on two pages. Use the id of the item to ignore the second copy. You do not lose an item.

Continue a list after the limit ​

The from_id parameter makes a list start after an item. Use it to get the items that are older than the limit.

  1. Find the id of the last item that you received.
  2. Request the list with from_id set to that id.
  3. Follow next_page until it is null.
  4. If limit_reached is true on that page, do steps 1 to 3 again.

Example:

GET /v1/payouts/?from_id=2f6f7ed0-2b5a-4b5a-9d3c-0a3d1b7c9e11

Rules:

  • The result starts with the item that comes after the from_id item. The from_id item is not in the result.
  • With from_id, count and num_pages are null. Use next_page.
  • You can use from_id together with the filters and with the p parameter.
  • from_id must be the id of an item of the same list in your account. If it is not, the response is HTTP 400.
  • You can send from_id with each request. Set it to the id of the last item of the previous response. This method is the quickest for a long list.

The invoices, transactions and payouts lists have the from_id parameter.

Keep your data current ​

After the first synchronization, do not read all pages again. Use one of these methods:

PurposeMethod
Get each change when it occursUse callbacks.
Get the new itemsRequest page 1 and follow next_page. Stop when you get an item that you have.
Get the new status of an item that you haveRequest the item by its id, or use callbacks.

Get the items of a date range ​

Use the date_from and date_to query parameters to get the items of a period. Then follow next_page. The transactions list and the payouts list have these parameters.

A page number after the last page ​

The response depends on the request:

RequestResponse
A page number above 4000HTTP 400
A request with from_idHTTP 200 with an empty result
A list without a filter, on an account with a large historyHTTP 200 with an empty result
All other listsHTTP 400 with the message Invalid page number

When the result is empty and count is not null, count and num_pages show the end of the list. Go to the page in num_pages. Then follow next_page.