---
title: "List a subscription's billing history"
method: GET
path: "/gateway/subscriptions/{id}/invoices"
tags: ["Subscriptions"]
---

# List a subscription's billing history

`GET /gateway/subscriptions/{id}/invoices`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/invoices`
- Auth: API key in header `x-api-key`

Every invoice minted at a renewal cycle for this subscription, newest first. Bounded (latest 100); not paginated. `amount`/`currency` is one already-resolved figure per invoice: the linked capture's settlement earnings when one is available in the invoice's own fiat currency, falling back to the merchant's fiat amount, then to the settlement-token amount. Every field on this resource is camelCase on the wire.

## Path parameters

- `id` string, uuid, required

## Response `200`

The subscription's billing history.

- SubscriptionInvoice[]
  - `id` string, uuid, required
  - `invoiceNumber` string, required
  - `status` 'issued' | 'paid' | 'voided', required
  - `issuedAt` string, date-time, required
  - `amount` number, required: The settled amount for this cycle: the linked capture's settlement earnings (net + fee + vat) when one is available in the invoice's own fiat currency, else the merchant's fiat_amount, else the settlement-token amount. Already resolved server-side — never recompute this.
  - `currency` string, required
  - `disputed` boolean, required: Derived from the linked capture's dispute state, never persisted — reverts to false the instant a won dispute restores the capture. Only ever true when status is 'paid'.

## Other responses

- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.
- `404`: Resource not found (or not visible to your key; the two are not distinguished).

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)