---
title: "List billing history"
method: GET
path: "/billing/history"
tags: ["Billing"]
---

# List billing history

`GET /billing/history`

Paginated invoice history for the caller's organization with optional filters and sort.

## Query parameters

- `limit` integer — max items per page
- `offset` integer — pagination offset
- `search` string — free-text search across invoice number/description
- `billing_cycle` string — filter by billing cycle
- `sort_by` string — column to sort by
- `sort_order` string — asc or desc
- `status` string — invoice status filter (lowercase)
- `date_from` string — RFC3339 lower bound for invoice_date
- `date_to` string — RFC3339 upper bound for invoice_date (with date_from = an exact calendar month)
- `plan_name` string — filter by plan name
- `phone_id` string — filter to invoices for a dedicated phone

## Response `200`

OK

- BillingHistoryResponse — One page of billing history items, using the API's standard list envelope (items, total, limit, offset).
  - `items` BillingHistoryItem[], nullable, required — Page of invoice records.
    - `amount_cents` integer, required — Invoice amount in cents.
    - `amount_dollars` number, double, required — Invoice amount expressed in dollars.
    - `billing_cycle` string, required — Billing frequency for this invoice period.
    - `currency` string, required — ISO 4217 currency code (e.g., 'usd').
    - `description` string, required — Human-readable invoice description.
    - `due_date` string, date-time — Payment due date, if set.
    - `formatted_amount` string, required — Formatted display string (e.g., '$12.50').
    - `hosted_invoice_url` string — Hosted invoice page URL, if available.
    - `id` string, required — Billing history record identifier.
    - `invoice_date` string, date-time, required — Timestamp when the invoice was created.
    - `invoice_number` string, required — Human-readable invoice number.
    - `invoice_pdf_url` string — Direct URL to the invoice PDF, if available.
    - `paid_at` string, date-time — Timestamp when the invoice was paid.
    - `plan_name` string, required — Billing plan associated with this invoice.
    - `status` 'paid' | 'pending' | 'failed' | 'void', required — Current payment status of the invoice.
  - `limit` integer, required — Page size used for this response.
  - `offset` integer, required — Pagination offset used for this response.
  - `total` integer, required — Total number of invoices matching the query.

## Other responses

- `default` — Error

## Changes

- **2026-08-17** `261c340a3f6d` — 2 breaking, 4 warning, 4 info
  - removed the required property `has_more` from the response with the `200` status
  - removed the required property `total_count` from the response with the `200` status
  - added the new `failed` enum value to the `items/items/status` response property for the response status `200`
  - added the new `paid` enum value to the `items/items/status` response property for the response status `200`
  - …6 more

[Change history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/billing/history/get.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) · [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/axilio-api-2/revisions/261c340a3f6d/schema)