Pagination

Overview

All Smartbills API list endpoints support pagination to help you efficiently retrieve large datasets. We use cursor-based pagination for optimal performance and consistency.

Cursor-based pagination: Smartbills uses cursor-based pagination rather than offset-based pagination for better performance and reliability with large datasets.

How Pagination Works

Request Parameters

All list endpoints accept these pagination parameters:

integer

default:"1"

Page number to retrieve (starts at 1)

integer

default:"20"

Number of items per page

Minimum: 1
Maximum: 100
Default: 20

Response Format

Paginated responses include both data and pagination metadata:

{
  "data": [
    // Array of objects
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95,
    "hasNext": true,
    "hasPrevious": false
  }
}

Pagination Object

object

Pagination metadata

Show Properties

integer

Current page number

integer

Number of items per page

integer

Total number of pages available

integer

Total number of items across all pages

boolean

Whether there is a next page available

boolean

Whether there is a previous page available

Basic Examples

First Page

Retrieve the first page of results:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch(
  'https://api.smartbills.io/v1/expenses?page=1&pageSize=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const result = await response.json();
console.log(`Page ${result.pagination.page} of ${result.pagination.totalPages}`);
console.log(`Total items: ${result.pagination.totalCount}`);

import requests

response = requests.get(
    'https://api.smartbills.io/v1/expenses',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'page': 1, 'pageSize': 20}
)

result = response.json()
print(f"Page {result['pagination']['page']} of {result['pagination']['totalPages']}")
print(f"Total items: {result['pagination']['totalCount']}")

Navigate to the next page:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=2&pageSize=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'

// Check if next page exists
if (result.pagination.hasNext) {
  const nextPage = result.pagination.page + 1;
  
  const response = await fetch(
    `https://api.smartbills.io/v1/expenses?page=${nextPage}&pageSize=20`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  
  const nextResult = await response.json();
}

# Check if next page exists
if result['pagination']['hasNext']:
    next_page = result['pagination']['page'] + 1
    
    response = requests.get(
        'https://api.smartbills.io/v1/expenses',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params={'page': next_page, 'pageSize': 20}
    )
    
    next_result = response.json()

Iterating Through All Pages

Simple Iteration

Loop through all pages to retrieve all results:

async function getAllExpenses() {
  const allExpenses = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api.smartbills.io/v1/expenses?page=${page}&pageSize=100`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const result = await response.json();
    allExpenses.push(...result.data);
    
    hasMore = result.pagination.hasNext;
    page++;
  }
  
  return allExpenses;
}

// Usage
const expenses = await getAllExpenses();
console.log(`Retrieved ${expenses.length} expenses`);

def get_all_expenses():
    all_expenses = []
    page = 1
    has_more = True
    
    while has_more:
        response = requests.get(
            'https://api.smartbills.io/v1/expenses',
            headers={'Authorization': 'Bearer YOUR_API_KEY'},
            params={'page': page, 'pageSize': 100}
        )
        
        result = response.json()
        all_expenses.extend(result['data'])
        
        has_more = result['pagination']['hasNext']
        page += 1
    
    return all_expenses

# Usage
expenses = get_all_expenses()
print(f"Retrieved {len(expenses)} expenses")

<?php
function getAllExpenses($apiKey) {
    $allExpenses = [];
    $page = 1;
    $hasMore = true;
    
    while ($hasMore) {
        $url = "https://api.smartbills.io/v1/expenses?page={$page}&pageSize=100";
        
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $apiKey
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        $result = json_decode($response, true);
        $allExpenses = array_merge($allExpenses, $result['data']);
        
        $hasMore = $result['pagination']['hasNext'];
        $page++;
    }
    
    return $allExpenses;
}

$expenses = getAllExpenses('YOUR_API_KEY');
echo "Retrieved " . count($expenses) . " expenses\n";
?>

With Error Handling

Production-ready pagination with error handling:

async function getAllExpensesSafely() {
  const allExpenses = [];
  let page = 1;
  const maxPages = 100; // Safety limit
  
  while (page <= maxPages) {
    try {
      const response = await fetch(
        `https://api.smartbills.io/v1/expenses?page=${page}&pageSize=100`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
      
      const result = await response.json();
      allExpenses.push(...result.data);
      
      console.log(`Fetched page ${page}/${result.pagination.totalPages}`);
      
      if (!result.pagination.hasNext) {
        break;
      }
      
      page++;
      
      // Rate limiting: small delay between requests
      await new Promise(resolve => setTimeout(resolve, 100));
      
    } catch (error) {
      console.error(`Error fetching page ${page}:`, error);
      throw error;
    }
  }
  
  return allExpenses;
}

Best Practices

Use Appropriate Page Sizes

Choose the right page size for your use case:

Small pages (20-50): Better for UI pagination, faster initial response
Large pages (100): Better for batch processing, fewer API calls
Default (20): Good balance for most use cases

// UI pagination - smaller pages
const uiResults = await fetch(
  'https://api.smartbills.io/v1/expenses?page=1&pageSize=20'
);

// Batch processing - larger pages
const batchResults = await fetch(
  'https://api.smartbills.io/v1/expenses?page=1&pageSize=100'
);

Check hasNext Before Fetching

Always check if there’s a next page before making the request:

// Good
if (result.pagination.hasNext) {
  // Fetch next page
}

// Avoid
// Fetching without checking (may result in empty pages)

This prevents unnecessary API calls when you’ve reached the end.

Handle Rate Limits

Add delays when fetching multiple pages:

for (let page = 1; page <= totalPages; page++) {
  await fetchPage(page);
  
  // Small delay to respect rate limits
  await new Promise(resolve => setTimeout(resolve, 100));
}

See Rate Limits for more details.

Cache Results When Possible

Cache paginated results to reduce API calls:

const cache = new Map();

async function getCachedPage(page) {
  const cacheKey = `expenses_page_${page}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const result = await fetchPage(page);
  cache.set(cacheKey, result);
  
  return result;
}

Show Progress for Large Datasets

Provide feedback when fetching many pages:

async function getAllWithProgress(onProgress) {
  const allItems = [];
  let page = 1;
  
  while (true) {
    const result = await fetchPage(page);
    allItems.push(...result.data);
    
    // Report progress
    const progress = (page / result.pagination.totalPages) * 100;
    onProgress(progress, page, result.pagination.totalPages);
    
    if (!result.pagination.hasNext) break;
    page++;
  }
  
  return allItems;
}

// Usage
await getAllWithProgress((progress, current, total) => {
  console.log(`Progress: ${progress.toFixed(1)}% (${current}/${total})`);
});

Pagination with Filters

Combine pagination with filtering:

// Get all pending expenses from January 2024
async function getPendingExpensesForMonth() {
  const allExpenses = [];
  let page = 1;
  
  while (true) {
    const params = new URLSearchParams({
      page: page,
      pageSize: 100,
      status: 'pending',
      startDate: '2024-01-01',
      endDate: '2024-01-31'
    });
    
    const response = await fetch(
      `https://api.smartbills.io/v1/expenses?${params}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const result = await response.json();
    allExpenses.push(...result.data);
    
    if (!result.pagination.hasNext) break;
    page++;
  }
  
  return allExpenses;
}

Pagination Limits

Maximum Page Size

Maximum: 100 items per page
Default: 20 items per page
Minimum: 1 item per page

Requesting more than 100 items per page will result in a validation error. The API will return a 400 Bad Request response.

Maximum Pages

There is no hard limit on the number of pages, but:

Very large datasets may take time to process
Consider using filters to narrow results
Implement caching for frequently accessed data

Common Patterns

Infinite Scroll (UI)

Implement infinite scroll in your application:

class ExpenseList {
  constructor() {
    this.expenses = [];
    this.currentPage = 1;
    this.loading = false;
    this.hasMore = true;
  }
  
  async loadMore() {
    if (this.loading || !this.hasMore) return;
    
    this.loading = true;
    
    try {
      const response = await fetch(
        `https://api.smartbills.io/v1/expenses?page=${this.currentPage}&pageSize=20`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
      
      const result = await response.json();
      this.expenses.push(...result.data);
      this.hasMore = result.pagination.hasNext;
      this.currentPage++;
      
    } finally {
      this.loading = false;
    }
  }
}

// Usage
const list = new ExpenseList();
await list.loadMore(); // Load first page

// User scrolls to bottom
await list.loadMore(); // Load next page

Implement page-based navigation:

class PaginatedExpenses {
  constructor() {
    this.currentPage = 1;
    this.totalPages = 1;
  }
  
  async goToPage(page) {
    const response = await fetch(
      `https://api.smartbills.io/v1/expenses?page=${page}&pageSize=20`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const result = await response.json();
    this.currentPage = result.pagination.page;
    this.totalPages = result.pagination.totalPages;
    
    return result.data;
  }
  
  async nextPage() {
    if (this.currentPage < this.totalPages) {
      return this.goToPage(this.currentPage + 1);
    }
  }
  
  async previousPage() {
    if (this.currentPage > 1) {
      return this.goToPage(this.currentPage - 1);
    }
  }
}

Troubleshooting

Empty results on valid page

Problem: Getting empty results even though pagination says there are more pagesPossible causes:

Data was deleted between requests
Filters are too restrictive
Race condition with concurrent modifications

Solution: Refetch from the beginning or adjust filters

Inconsistent page counts

Problem: Total pages changes between requestsReason: This is normal! Data can be added or removed while you’re paginating.Solution:

Use hasNext instead of relying on totalPages
Implement refresh mechanisms
Consider using timestamps to detect changes

Slow pagination performance

Problem: Pagination is slow, especially on later pagesSolutions:

Use larger page sizes (up to 100)
Add filters to reduce total dataset
Cache results when appropriate
Consider using webhooks for real-time updates instead

Filtering

Learn how to filter results

Rate Limits

Understand API rate limiting

List Expenses

Expenses list endpoint

Error Handling

Handle pagination errors

Summary

✅ Use page and pageSize parameters
✅ Check hasNext before fetching next page
✅ Maximum page size is 100 items
✅ Add delays between requests for rate limiting
✅ Handle errors gracefully
✅ Cache results when possible
✅ Show progress for large datasets

Performance tip: For batch processing, use the maximum page size (100) to minimize the number of API calls.

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Overview

Request Parameters

Response Format

Basic Examples

First Page

Next Page

Iterating Through All Pages

Simple Iteration

With Error Handling

Best Practices

Maximum Page Size

Maximum Pages

Common Patterns

Infinite Scroll (UI)

Page Navigation (UI)

Troubleshooting

Filtering

Rate Limits

List Expenses

Error Handling

Summary

​Overview

​How Pagination Works

​Request Parameters

​Response Format

​Pagination Object

​Basic Examples

​First Page

​Next Page

​Iterating Through All Pages

​Simple Iteration

​With Error Handling

​Best Practices

​Pagination with Filters

​Pagination Limits

​Maximum Page Size

​Maximum Pages

​Common Patterns

​Infinite Scroll (UI)

​Page Navigation (UI)

​Troubleshooting

​Related Topics

Filtering

Rate Limits

List Expenses

Error Handling

​Summary

Overview

How Pagination Works

Request Parameters

Response Format

Pagination Object

Basic Examples

First Page

Next Page

Iterating Through All Pages

Simple Iteration

With Error Handling

Best Practices

Pagination with Filters

Pagination Limits

Maximum Page Size

Maximum Pages

Common Patterns

Infinite Scroll (UI)

Page Navigation (UI)

Troubleshooting

Related Topics

Summary