Pagination

The OpenTiendas API uses a consistent pagination structure across all list endpoints.
This ensures that responses are lightweight and makes it easy to navigate large datasets.

How it works

All GET requests that return a list of resources include a pagination object alongside the data.

Here’s an example response from a paginated endpoint:

{
  "data": [
    // Array of resource objects
  ],
  "pagination": {
    "current_page": 2,
    "per_page": 50,
    "total": 250,
    "total_pages": 5,
    "next_page_url": "/api/v1/reviews?page=3",
    "previous_page_url": "/api/v1/reviews?page=1"
  }
}

Page numbering starts at 1.
The first page is page=1. Requests with page=0 or negative values are invalid and will return a 400 Bad Request.

info

The next_page_url and previous_page_url fields are only included when another page exists in that direction.

Parameters

You can control pagination using the following query parameters:

• page: Selects the page number to retrieve.
• per_page: Defines how many items to return per page.

GET /api/v1/suppliers?page=2&per_page=50

info

By default, most endpoints return 50 items per page. You can adjust this with per_page, depending on the resource and any maximum limits enforced by the API.

Best practices

• Always check for next_page_url before requesting the next page.
• Avoid hardcoding page numbers — use the pagination URLs for reliable navigation.

Additional considerations

• If you're using query parameters, they will be preserved in the pagination URLs:

"next_page_url": "/api/v1/reviews?page=2&status=published&sort=rating_desc"

• If an unsupported page is requested (e.g., too high), the API will return 404.
• OpenTiendas uses offset-based pagination with page and per_page query parameter.
  Each page starts at a calculated offset: offset = (page - 1) × per_page

GET /api/v1/brands?page=2

info

We do not use cursor-based pagination (e.g., starting_after, ending_before).
This behavior may differ from other APIs that rely on cursors for pagination.