Pagination

Overview

The Dev API currently uses two pagination models:

Cursor-based pagination for most resource lists
Page-based pagination for operational lists where page navigation is clearer

Most resource lists (products, invoices, orders) use cursor-based. Operational lists like webhook delivery logs use page-based.

Cursor-Based
Page-Based

Use cursor-based pagination for feed-style lists like products, invoices, orders, customers, and subscriptions.

Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of items per page (1-100)
`cursor`	string	-	Cursor from previous response

Basic Usage

First Request

GET /products?limit=25

Response:

{
  "data": [
    { "uniqid": "prod_001", "title": "Product A" },
    { "uniqid": "prod_002", "title": "Product B" },
    // ... 23 more items
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MjUsImNyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxIn0",
    "has_more": true
  }
}

Use the next_cursor from the previous response:

GET /products?limit=25&cursor=eyJpZCI6MjUsImNyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxIn0

Final Page

When there are no more items:

{
  "data": [
    { "uniqid": "prod_099", "title": "Product Y" },
    { "uniqid": "prod_100", "title": "Product Z" }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code Examples

Fetch All Pages

async function fetchAllProducts(): Promise<Product[]> {
  const allProducts: Product[] = [];
  let cursor: string | null = null;

  do {
    const url = new URL('https://api.shoppex.io/dev/v1/products');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString(), {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    const { data, pagination } = await response.json();

    allProducts.push(...data);
    cursor = pagination.next_cursor;
  } while (cursor);

  return allProducts;
}

def fetch_all_products():
    all_products = []
    cursor = None

    while True:
        params = {'limit': 100}
        if cursor:
            params['cursor'] = cursor

        response = requests.get(
            'https://api.shoppex.io/dev/v1/products',
            headers={'Authorization': f'Bearer {API_KEY}'},
            params=params
        )

        result = response.json()
        all_products.extend(result['data'])

        if not result['pagination']['has_more']:
            break

        cursor = result['pagination']['next_cursor']

    return all_products

Async Generator (Streaming)

TypeScript

async function* fetchProductsStream(): AsyncGenerator<Product> {
  let cursor: string | null = null;

  do {
    const url = new URL('https://api.shoppex.io/dev/v1/products');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString(), {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    const { data, pagination } = await response.json();

    for (const product of data) {
      yield product;
    }

    cursor = pagination.next_cursor;
  } while (cursor);
}

// Usage
for await (const product of fetchProductsStream()) {
  console.log(product.title);
}

Filtering with Pagination

Filters work alongside pagination:

# Get completed invoices, paginated
GET /invoices?filters=status:COMPLETED&limit=50

# Continue with cursor
GET /invoices?filters=status:COMPLETED&limit=50&cursor=eyJ...

Always include the same filters and sorts when following cursors. Changing them invalidates the cursor.

GET /orders?filters=status:COMPLETED,customer_email:[email protected]&sorts=-created_at
GET /customers?filters=city:Berlin&sorts=created_at

Cursor-Based Endpoints

Endpoint	Default Limit	Max Limit
`GET /products`	50	100
`GET /invoices`	50	100
`GET /customers`	50	100
`GET /coupons`	50	100
`GET /subscriptions`	50	100
`GET /reviews`	50	100
`GET /tickets`	50	100
`GET /webhooks`	50	100
`GET /blacklist`	50	100

Use page-based pagination for operational lists where integrators often jump to a specific page.

Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number, starting at 1
`limit`	integer	25	Number of items per page

Basic Usage

GET /webhooks/logs?page=2&limit=10

{
  "data": [
    { "uniqid": "log_001", "status": "success" }
  ],
  "pagination": {
    "total": 37,
    "page": 2,
    "limit": 10,
    "total_pages": 4,
    "has_more": true
  }
}

Page-Based Endpoints

Endpoint	Default Limit
`GET /webhooks/logs`	25
`GET /affiliates/customers`	25
`GET /affiliates/applications`	25

Best Practices

Use Reasonable Limits

Fetching for a UI? 20-25 items is plenty. Background sync job? Crank it to 100. Larger limits increase response time.

Don't Store Cursors

Cursors are meant for immediate sequential use. They expire after 24 hours and become invalid if the underlying data changes significantly.

Handle Empty Results

An empty data array with has_more: false is valid - no items match your query.

Respect Rate Limits

When fetching all pages, add delays between requests to avoid rate limiting.

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Overview

Parameters

Basic Usage

First Request

Next Page

Final Page

Code Examples

Fetch All Pages

Async Generator (Streaming)

Cursor-Based Endpoints

Parameters

Basic Usage

Page-Based Endpoints

Best Practices

Use Reasonable Limits

Don't Store Cursors

Handle Empty Results

Respect Rate Limits

​Overview

​Parameters

​Basic Usage

​First Request

​Next Page

​Final Page

​Code Examples

​Fetch All Pages

​Async Generator (Streaming)

​Filtering with Pagination

​Cursor-Based Endpoints

​Parameters

​Basic Usage

​Page-Based Endpoints

​Best Practices

Use Reasonable Limits

Don't Store Cursors

Handle Empty Results

Respect Rate Limits

Overview

Parameters

Basic Usage

First Request

Next Page

Final Page

Code Examples

Fetch All Pages

Async Generator (Streaming)

Filtering with Pagination

Cursor-Based Endpoints

Parameters

Basic Usage

Page-Based Endpoints

Best Practices