---
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).
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `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

---

[API](https://skmtc.net/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.net/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/108ab4b41051/schema)