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
paginationblock:
{
"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.
countis never more than100000, andnum_pagesis never more than4000.- On page
4000,next_pageisnull. If the list has older items,limit_reachedistrue. - A page number above
4000gives HTTP400. - To get the older items, use the
from_idparameter. Refer to Continue a list after the limit.
Get the newest items
- Request page
1. It has the25newest items. - If you need more items, request the page that
next_pagegives. - Stop when you have the number of items that you need.
Get all items of a list
- Request page
1. - Request the page that
next_pagegives. - Do step 2 again until
next_pageisnull. - If
limit_reachedistrueon that page, continue the list.
Rules:
next_pageis always correct. It isnullonly on the last page.- Do not calculate page numbers from
countornum_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
idof 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.
- Find the
idof the last item that you received. - Request the list with
from_idset to thatid. - Follow
next_pageuntil it isnull. - If
limit_reachedistrueon that page, do steps 1 to 3 again.
Example:
GET /v1/payouts/?from_id=2f6f7ed0-2b5a-4b5a-9d3c-0a3d1b7c9e11Rules:
- The result starts with the item that comes after the
from_iditem. Thefrom_iditem is not in the result. - With
from_id,countandnum_pagesarenull. Usenext_page. - You can use
from_idtogether with the filters and with thepparameter. from_idmust be theidof an item of the same list in your account. If it is not, the response is HTTP400.- You can send
from_idwith each request. Set it to theidof 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:
| Purpose | Method |
|---|---|
| Get each change when it occurs | Use callbacks. |
| Get the new items | Request page 1 and follow next_page. Stop when you get an item that you have. |
| Get the new status of an item that you have | Request 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:
| Request | Response |
|---|---|
A page number above 4000 | HTTP 400 |
A request with from_id | HTTP 200 with an empty result |
| A list without a filter, on an account with a large history | HTTP 200 with an empty result |
| All other lists | HTTP 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.