List and retrieve invoices

Billing10 minIntermediate

The invoices API supports page-based listing, filtering, and optional include flags for related records. This guide focuses on the read side: listing invoices, fetching a single invoice, and understanding when to include items, clients, or transactions.

Endpoints used in this guide

GET/api/v1/invoicesList invoices with page, limit, filters, and include flags.

GET/api/v1/invoices/{id}Fetch a single invoice.

GET/api/v1/invoices/{id}/itemsRead invoice items separately when needed.

GET/api/v1/invoices/{id}/transactionsRead payments and credits separately when needed.

Useful query parameters

pageintegerOptional

1-based page number. Defaults to 1.

limitintegerOptional

Page size. The API commonly caps list endpoints at 100.

statusstringOptional

Filter by invoice status.

include_itemsbooleanOptional

Include line items in the response.

include_clientbooleanOptional

Include client details in the response.

include_transactionsbooleanOptional

Include payments and credits in the response.

List invoices with include flags

curl

curl -X GET "https://algapsa.com/api/v1/invoices?page=1&limit=25&include_client=true&include_items=true" \
  -H "X-API-Key: $ALGA_API_KEY"

TypeScript

const url = new URL('https://algapsa.com/api/v1/invoices');
url.searchParams.set('page', '1');
url.searchParams.set('limit', '25');
url.searchParams.set('include_client', 'true');
url.searchParams.set('include_items', 'true');

const response = await fetch(url.toString(), {
  headers: {
    'X-API-Key': process.env.ALGA_API_KEY!,
  },
});

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error?.message ?? 'Invoice list failed');
}

console.log(result.pagination);

Fetch one invoice

Use the invoice ID when you need a single billing record. Add include flags only when the consuming screen actually needs them.

curl

curl -X GET "https://algapsa.com/api/v1/invoices/$INVOICE_ID?include_transactions=true" \
  -H "X-API-Key: $ALGA_API_KEY"

When to call nested endpoints

The include flags are convenient, but the nested endpoints are still useful when you want to defer loading large item lists or payment history.

curl

curl -X GET "https://algapsa.com/api/v1/invoices/$INVOICE_ID/items" \
  -H "X-API-Key: $ALGA_API_KEY"

curl -X GET "https://algapsa.com/api/v1/invoices/$INVOICE_ID/transactions" \
  -H "X-API-Key: $ALGA_API_KEY"