Standardized Pagination Across API Resources

Payiano's API implements a consistent approach for retrieving collections of resources through standardized list endpoints. This pattern is available across core resources including: Payment Links , Customers , and Customer Tags .

Key Features

  • Uniform Interface: All list endpoints follow the same structural pattern, reducing integration complexity and accelerating development.
  • Intuitive Parameters: Standardized controls including:
    • page and per_page for precise pagination control
    • q for full-text search
    • sort for sophisticated ordering (max 5 fields)
    • includes for retrieving related resources in a single request - learn more about including resources
  • Optimized Sorting:

    The sort parameter supports multi-column sorting while maintaining query performance:

    • Maximum of 5 sort fields per request
    • Explicit direction control for each field
    • Nested field support (e.g., payment_details.amount)
    [
    {     "field": "title", "direction": "asc" },
    {     "field": "created_at", "direction": "desc" },
    {     "field": "payment_details.amount", "direction": "asc" } ]
    Note: If a request includes more than 5 sort fields, the system will automatically limit the sort array to the first 5 valid fields to ensure optimal performance and maintain query efficiency.
  • Resource Relationships: Enhance your API responses by including related resources using the includes parameter. This powerful feature allows you to fetch associated data in a single request, reducing the need for multiple API calls.
    See our detailed guide on including resources to learn how to optimize your API requests by fetching related data efficiently.
  • Cross-Resource Consistency: Apply the same integration patterns across different business domains while maintaining type safety and predictable behavior.
  • Developer Efficiency: Reduced cognitive load when working with multiple resources, enabling faster implementation of data retrieval features.
GET/resource
Sandbox: https://api.payiano.dev/v1/resource
Live: https://api.payiano.com/v1/resource
Request
Request body schema:
application/json
Query parameters:
page
Type: integer|null
Default: 1

The page number to be retrieved, for the list of resource. So, a combination of page=1 and per_page=25 returns the first 25 resource items. A combination of page=2 and per_page=25 returns the next 25 resource items.

per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]

The maximum number of resource items to return in the response.

q
Type: array_of_strings|null
Min: 3

This parameter enables free-text search across key resource fields (including but not limited to title), requiring a minimum of 3 characters per search term. It performs case-insensitive partial matching, and returns relevance-ranked results while automatically handling special characters. This provides a simple yet powerful way to quickly find relevant resource items.

sort
Type: array_of_objects|null

Control the ordering of results with sophisticated multi-column sorting. Specify an array of objects, each containing a field and direction. Maximum 5 sort fields per request to maintain optimal performance.

field
Type: enum
Possible values:
[ "created_at", "payment_details.amount", "title" ]

This attribute specifies the field used for sorting. It can be a direct attribute of the resource or a related field referenced using dot notation.

direction
Type: enum
Possible values:
[ "asc", "desc" ]

This attribute specifies the sorting direction. It can be either asc for ascending order or desc for descending order. Please note that the value is case-sensitive.

includes
Type: array_of_enums|null
Possible values:
[ "payment_link.customer", "payment_link.payment_details" ]

A list of additional resource relations to return, if available. Feel free to send the relations you would like to return with every item. See Including Resources to better understand how this is working.

Response
200
Response schema:
application/json
Response body:
total_pages
Type: integer

The total number of pages that are available for the items search criteria.

current_page
Type: integer

The current pagination page.

per_page
Type: integer

The amount of items items return per page.

total_items
Type: integer

The total number of items that match the search criteria.

items
Type: array_of_objects

The list of items that match the search criteria.

Response sample:
1
{ 2 "per_page": 25, 3 "total_pages": 1, 4 "total_items": 1, 5 "current_page": 1, 6 "items": [] 7}