> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List and Retrieve Subscription Invoices

> List invoices for a subscription or retrieve a single invoice by its UUID.

Therius creates one invoice per billing cycle. Each invoice records the charge attempt or attempts for that cycle, the outcome, and the final amount collected. You can retrieve all invoices for a subscription, or look up a specific invoice directly by its UUID.

## List Invoices for a Subscription

`GET /subscription/{id}/invoice` returns all invoices for a given subscription in reverse-chronological order, as a bare array — see the response panel above for the full `Invoice` shape (`status` is `open`/`paid`/`failed`/`void`; the retry count field is `paymentAttemptCount`).

<a id="line-items" />

`lines[]` is present only when the plan prices one or more [usage meters](/guides/subscriptions#usage-based-and-hybrid-billing): one line for the base plan fee (no `meterId`) plus one line per metered add-on. Absent or empty for a flat-fee invoice — the top-level `amount` is then the whole charge, and each line's own `amount` sums to it.

### Example

```bash theme={"dark"}
curl "https://api.therius.io/v1/subscription/sub_abc123def456/invoice?merchantCode=MERCHANT_001" \
  -H "Authorization: Bearer prv_production_your_key_here"
```

***

## Retrieve a Specific Invoice

`GET /subscription/invoice/{id}` retrieves a single invoice by its UUID, regardless of which subscription it belongs to. Authenticates the same way as every other endpoint (`Authorization: Bearer prv_production_xxx` / `prv_sandbox_xxx`).

### Path Parameters

<ParamField path="id" type="string" required>
  The UUID of the invoice to retrieve.
</ParamField>

### Query Parameters

<ParamField query="merchantCode" type="string" required>
  Your merchant account identifier.
</ParamField>

### Response

Returns a single invoice object with the same fields as described above.

### Errors

| Code  | Meaning                                        |
| ----- | ---------------------------------------------- |
| `404` | Invoice not found under your merchant account. |

### Example

```bash theme={"dark"}
curl "https://api.therius.io/v1/subscription/invoice/inv_xyz789abc?merchantCode=MERCHANT_001" \
  -H "Authorization: Bearer prv_production_your_key_here"
```

<RequestExample>
  ```bash cURL theme={"dark"}
  curl "https://api.therius.io/v1/subscription/sub_abc123def456/invoice?merchantCode=MERCHANT_001" \
    -H "Authorization: Bearer prv_production_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {}
  ```
</ResponseExample>


## OpenAPI

````yaml GET /subscription/{id}/invoice
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /subscription/{id}/invoice:
    get:
      tags:
        - Subscriptions
      summary: List invoices for a subscription
      operationId: listSubscriptionInvoices
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Subscription UUID.
        - name: merchantCode
          in: query
          required: true
          description: Your merchant account identifier.
          schema:
            type: string
      responses:
        '200':
          description: List of invoices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
components:
  schemas:
    Invoice:
      type: object
      description: >-
        One billing cycle. `amount` is a flat integer in minor units with
        separate `currency` + `exponent`.
      properties:
        id:
          type: string
          description: Invoice UUID.
        subscriptionId:
          type: string
          description: The subscription this invoice belongs to.
        merchantId:
          type: integer
        status:
          type: string
          enum:
            - open
            - paid
            - failed
            - void
          description: >-
            `open` - awaiting payment; `paid` - settled; `failed` - all payment
            attempts failed; `void` - cancelled, no longer collectible.
        amount:
          type: integer
          description: Invoice total in the currency minor units.
        currency:
          type: string
          description: ISO 4217 currency code.
        exponent:
          type: integer
          description: Decimal places for `amount`.
        periodStart:
          type: string
          format: date-time
          description: Start of the service period this invoice covers.
        periodEnd:
          type: string
          format: date-time
          description: End of the service period this invoice covers.
        dueDate:
          type: string
          format: date-time
        paymentAttemptCount:
          type: integer
          description: >-
            Charge attempts made against this invoice, including dunning
            retries.
        paidAt:
          type: string
          format: date-time
        voidedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        attempts:
          type: array
          items:
            type: object
          description: >-
            Per-attempt gateway results. Present on the single-invoice endpoint
            (`GET /subscription/invoice/{id}`).
        lines:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLine'
          description: >-
            Itemisation - present only when the plan prices usage meters: one
            base-fee line (no `meterId`) plus one per metered add-on.
            Absent/empty for a flat-fee invoice.
    InvoiceLine:
      type: object
      properties:
        description:
          type: string
          example: API requests (api_requests)
        meterId:
          type: integer
          description: >-
            The usage meter this line was priced from. Omitted on the base
            plan-fee line.
        quantity:
          type: number
          description: >-
            Billable quantity for this meter over the invoice period, after
            subtracting the plan's included units.
          example: 12000
        unitAmount:
          type: integer
          description: >-
            Configured per-unit price in minor units (per_unit scheme). `0` for
            tiered (volume/graduated) pricing.
          example: 1
        amount:
          type: integer
          description: Line total in minor units.
          example: 12000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````