Enable pagination for the /transactions endpoint

📘

This is now enabled by default

As of December 2023, pagination is enabled by default for all new client_ids.

You only need to follow the steps on this page to enable pagination if you created you client_id before December 2023.

Pagination is now the default behaviour for the /transactions endpoint. If you created your client_id before 2023, you can follow this guide to enable this feature for improved reliability and performance.

After you enable pagination, you receive a partial response when you try to retrieve more than 1,000 transactions at once. You then use the cursor to fetch subsequent pages in the response, with each containing 1,000 transactions.

You can retrieve a maximum of 31 days of data at once. To fetch more, perform multiple queries with different from and to values (and fetch all pages).

Enable Pagination

You enable pagination by adding the tl-enable-pagination: true header to your request to the merchant-accounts/{id}/transactions endpoint. If you do this correctly, the response contains the pagination object.

To use pagination, you should:

1. Send a GET request with:
   • The required bearer token.
   • The tl-enable-pagination:true header.
   • Appropriate dates for the from and to parameters.
   • Optionally, a value of payment or payout for the type parameter.
2. Check if the response contains pagination.next_cursor.
   If not, this is the end of all transactions.
3. If the response does contain pagination.next_cursor, pass the cursor in a subsequent request with a cursor query string.
   Ensure the cursor query string is correctly encoded, or you may get a 400 error with the error message Invalid cursor.
4. Inspect the pagination.next_cursor again.
   Repeat this process until the response no longer contains pagination.next_cursor, when you have retrieved all transactions.

Below is a diagram that illustrates the process.

Pagination response examples

Below are examples of successful responses where the pagination object is present.

{  
	"items": [  
		{"type": "payout", ... },  
		{"type": "external_payment", ... },  
		{"type": "merchant_account_payment" ... },  
    // truncated  
	],  
	"pagination": {  
		"next_cursor": "eyJkYXk...X0="  
  }  
}

{
	"items": [
		{"type": "payout", ... },
		{"type": "external_payment", ... },
		{"type": "merchant_account_payment" ... },
	],
	"pagination": {
     // no next_cursor
  }
}

Below is an example of an error response. This error is caused by setting your from and to values so that the range between them is greater than 31 days.

{
  "type": "https://docs.truelayer.com/docs/error-types#invalid-parameters",
  "title": "Invalid Parameters",
  "status": 400,
  "trace_id": "0f16d77a-be67-4128-b837-56142e064920",
  "detail": "Invalid value for parameter from/to: Date range exceeds the maximum allowed duration of 31 days",
  "errors": {
    "from/to": [
      "Date range exceeds the maximum allowed duration of 31 days"
    ]
  }
}

Incorrect cursor errors

A few validation errors can occur when you specify a cursor query string that is not compatible with other parameters:

• The cursor does not match the merchant account ID specified in the path parameter (id)
• The cursor does not match the type query string specified.
• The cursor is invalid or not URL-encoded.