Pagination

The 4N NextDay API uses page-based pagination for endpoints that return multiple items. This guide covers how to navigate paginated responses.

Pagination Parameters

When making requests to list endpoints, you can use these query parameters:

Name
page
Type
integer
Description
The page number to retrieve. Default: 1
Name
per_page
Type
integer
Description
Number of items per page. Default: 15, Max: 100

Paginated Response Structure

All paginated responses return an items array inside data, along with a meta object containing pagination information:

Name
current_page
Type
integer
Description
The current page number.
Name
last_page
Type
integer
Description
The total number of pages.
Name
per_page
Type
integer
Description
Items per page.
Name
total
Type
integer
Description
Total number of items across all pages.

Paginated response

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": {
    "items": [
      {
        "id": 12345,
        "tracking_number": "4N000000012345"
        // ...
      },
      {
        "id": 12346,
        "tracking_number": "4N000000012346"
        // ...
      }
    ],
    "meta": {
      "current_page": 2,
      "last_page": 5,
      "per_page": 15,
      "total": 73
    }
  },
  "timestamp": "2025-02-03T10:00:00.000000Z"
}

Example: Fetching Orders

GET

/orders

# First page (default)
curl "https://api.4nortes.app/api/v1/orders" \
  -H "Authorization: Bearer {token}"

# Specific page with custom page size
curl "https://api.4nortes.app/api/v1/orders?page=2&per_page=25" \
  -H "Authorization: Bearer {token}"

Iterating Through All Pages

Here's how to iterate through all pages of results:

async function getAllOrders() {
  const allOrders = []
  let page = 1
  let hasMore = true

  while (hasMore) {
    const response = await fetch(
      `https://api.4nortes.app/api/v1/orders?page=${page}&per_page=100`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
        },
      }
    )

    const result = await response.json()
    allOrders.push(...result.data.items)

    hasMore = page < result.data.meta.last_page
    page++
  }

  return allOrders
}

def get_all_orders():
    all_orders = []
    page = 1

    while True:
        response = requests.get(
            'https://api.4nortes.app/api/v1/orders',
            headers={'Authorization': f'Bearer {token}'},
            params={'page': page, 'per_page': 100}
        )

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

        if page >= result['data']['meta']['last_page']:
            break

        page += 1

    return all_orders

Best Practices

Use appropriate page sizes: Request only what you need. Smaller page sizes mean faster responses.
Cache when possible: If you're displaying paginated data, cache pages to avoid repeated requests.
Handle empty results: Always check if items is empty before processing.
Respect rate limits: When iterating through many pages, add delays between requests to avoid rate limiting.

// Add delay between pagination requests
async function fetchWithDelay(page) {
  const response = await fetch(`/api/v1/orders?page=${page}`)
  await new Promise(resolve => setTimeout(resolve, 100)) // 100ms delay
  return response.json()
}