Pagination

Overview

All Smartbills API list endpoints return paginated results. Pagination allows you to efficiently retrieve large datasets by splitting them into smaller pages.

Request Parameters

All list endpoints accept these pagination and sorting 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

string

default:"createdAt"

Field to sort results by (e.g., createdAt, date, amount)

string

default:"desc"

Sort direction: asc (ascending) or desc (descending)

Response Format

Paginated responses include both the data array and a pagination metadata object:

{
  "data": [
    {
      "id": 1,
      "merchant": "Office Depot",
      "amount": 45.99
    },
    {
      "id": 2,
      "merchant": "Staples",
      "amount": 32.50
    }
  ],
  "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 with sorting:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=20&sortBy=date&sortOrder=desc' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

const result = await client.expenses.list({
  page: 1,
  pageSize: 20,
  sortBy: 'date',
  sortOrder: 'desc'
});

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

from smartbills import SmartbillsClient

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

result = client.expenses.list(
    page=1,
    page_size=20,
    sort_by="date",
    sort_order="desc"
)

print(f"Page {result.pagination.page} of {result.pagination.total_pages}")
print(f"Total items: {result.pagination.total_count}")

Navigate to the next page by checking hasNext:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=2&pageSize=20&sortBy=date&sortOrder=desc' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

if (result.pagination.hasNext) {
  const nextPage = result.pagination.page + 1;
  const nextResult = await client.expenses.list({
    page: nextPage,
    pageSize: 20,
    sortBy: 'date',
    sortOrder: 'desc'
  });
}

if result.pagination.has_next:
    next_page = result.pagination.page + 1
    next_result = client.expenses.list(
        page=next_page,
        page_size=20,
        sort_by="date",
        sort_order="desc"
    )

Iterating Through All Pages

Simple Iteration

Loop through all pages to retrieve all results:

#!/bin/bash
PAGE=1
HAS_MORE=true

while [ "$HAS_MORE" = "true" ]; do
  RESPONSE=$(curl --silent --request GET \
    --url "https://api.smartbills.io/v1/expenses?page=${PAGE}&pageSize=100" \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'x-tenant-id: 123')
  
  echo "Page ${PAGE}: $(echo $RESPONSE | jq '.data | length') items"
  
  HAS_MORE=$(echo $RESPONSE | jq '.pagination.hasNext')
  PAGE=$((PAGE + 1))
done

async function getAllExpenses(client) {
  const allExpenses = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await client.expenses.list({
      page: page,
      pageSize: 100
    });

    allExpenses.push(...result.data);
    hasMore = result.pagination.hasNext;
    page++;
  }

  return allExpenses;
}

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

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

def get_all_expenses(client):
    all_expenses = []
    page = 1
    has_more = True

    while has_more:
        result = client.expenses.list(page=page, page_size=100)
        all_expenses.extend(result.data)
        has_more = result.pagination.has_next
        page += 1

    return all_expenses

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

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

With Error Handling and Rate Limiting

Production-ready pagination with error handling:

async function getAllExpensesSafely(client) {
  const allExpenses = [];
  let page = 1;
  const maxPages = 100; // Safety limit

  while (page <= maxPages) {
    try {
      const result = await client.expenses.list({
        page: page,
        pageSize: 100
      });

      allExpenses.push(...result.data);
      console.log(`Fetched page ${page}/${result.pagination.totalPages}`);

      if (!result.pagination.hasNext) {
        break;
      }

      page++;

      // Small delay to respect rate limits
      await new Promise(resolve => setTimeout(resolve, 100));
    } catch (error) {
      console.error(`Error fetching page ${page}:`, error);
      throw error;
    }
  }

  return allExpenses;
}

import time

def get_all_expenses_safely(client):
    all_expenses = []
    page = 1
    max_pages = 100  # Safety limit

    while page <= max_pages:
        try:
            result = client.expenses.list(page=page, page_size=100)
            all_expenses.extend(result.data)
            print(f"Fetched page {page}/{result.pagination.total_pages}")

            if not result.pagination.has_next:
                break

            page += 1
            time.sleep(0.1)  # Small delay to respect rate limits
        except Exception as e:
            print(f"Error fetching page {page}: {e}")
            raise

    return all_expenses

Pagination with Filters

Combine pagination with filtering to narrow your results:

curl --request GET \
  --url 'https://api.smartbills.io/v1/expenses?page=1&pageSize=50&status=pending&sortBy=amount&sortOrder=desc' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

const result = await client.expenses.list({
  page: 1,
  pageSize: 50,
  status: 'pending',
  sortBy: 'amount',
  sortOrder: 'desc'
});

result = client.expenses.list(
    page=1,
    page_size=50,
    status="pending",
    sort_by="amount",
    sort_order="desc"
)

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 400 Bad Request validation error.

Best Practices

Use Appropriate Page Sizes

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

Always Check hasNext

Always check hasNext before fetching the next page. This prevents unnecessary API calls when you have reached the end of the results.

Handle Rate Limits

Add small delays between requests when fetching multiple pages to avoid hitting rate limits. See Rate Limits for details.

Cache Results When Possible

Cache paginated results to reduce redundant API calls, especially for data that does not change frequently.

Use Filters to Reduce Data

Apply filters to narrow results before paginating, reducing the total number of pages and API calls needed.

Troubleshooting

Empty results on a valid page

Possible causes: Data was deleted between requests, filters are too restrictive, or a race condition with concurrent modifications. Solution: Refetch from the beginning or adjust your filters.

Inconsistent page counts

Reason: This is normal. Data can be added or removed while you are paginating. Solution: Use hasNext instead of relying on totalPages for iteration logic.

Slow pagination performance

Solutions: Use larger page sizes (up to 100), add filters to reduce the total dataset, cache results, or use webhooks for real-time updates instead of polling.

Rate Limits

Understand API rate limiting

Error Handling

Handle pagination errors

List Expenses

Expenses list endpoint

Webhooks

Real-time event notifications

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 and Rate Limiting

Maximum Page Size

Best Practices

Troubleshooting

Rate Limits

Error Handling

List Expenses

Webhooks

​Overview

​Request Parameters

​Response Format

​Pagination Object

​Basic Examples

​First Page

​Next Page

​Iterating Through All Pages

​Simple Iteration

​With Error Handling and Rate Limiting

​Pagination with Filters

​Pagination Limits

​Maximum Page Size

​Best Practices

​Troubleshooting

​Related Resources

Rate Limits

Error Handling

List Expenses

Webhooks

Overview

Request Parameters

Response Format

Pagination Object

Basic Examples

First Page

Next Page

Iterating Through All Pages

Simple Iteration

With Error Handling and Rate Limiting

Pagination with Filters

Pagination Limits

Maximum Page Size

Best Practices

Troubleshooting

Related Resources