> ## 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.

# Lista y recupera facturas de suscripción

> Lista las facturas de una suscripción o recupera una sola factura por su UUID.

export const SchemaLangNote = ({lang}) => {
  const text = ({
    es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
    pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
  })[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
  return <Note>{text}</Note>;
};

Therius crea una factura por ciclo de facturación. Cada factura registra el intento o los intentos de cobro para ese ciclo, el resultado y el monto final cobrado. Puedes recuperar todas las facturas de una suscripción, o buscar una factura específica directamente por su UUID.

<SchemaLangNote lang="es" />

## Lista las facturas de una suscripción

`GET /subscription/{id}/invoice` devuelve todas las facturas de una suscripción dada en orden cronológico inverso, como un array simple — ver el panel de respuesta de arriba para la forma completa de `Invoice` (`status` es `open`/`paid`/`failed`/`void`; el campo de reintentos es `paymentAttemptCount`).

<a id="line-items" />

`lines[]` está presente solo cuando el plan tarifica uno o más [medidores de uso](/es/guides/subscriptions#facturación-por-uso-e-híbrida): una línea para la tarifa base del plan (sin `meterId`) más una línea por cada complemento medido. Ausente o vacío en una factura de tarifa fija — el `amount` de nivel superior es entonces el cobro completo, y el `amount` de cada línea suma a él.

### Ejemplo

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

***

## Recupera una factura específica

`GET /subscription/invoice/{id}` recupera una sola factura por su UUID, independientemente de a qué suscripción pertenezca. Se autentica igual que cualquier otro endpoint (`Authorization: Bearer prv_production_xxx` / `prv_sandbox_xxx`).

### Parámetros de ruta

<ParamField path="id" type="string" required>
  El UUID de la factura a recuperar.
</ParamField>

### Parámetros de consulta

<ParamField query="merchantCode" type="string" required>
  Tu identificador de cuenta de comercio.
</ParamField>

### Respuesta

Devuelve un solo objeto de factura con los mismos campos descritos arriba.

### Errores

| Código | Significado                                       |
| ------ | ------------------------------------------------- |
| `404`  | Factura no encontrada bajo tu cuenta de comercio. |

### Ejemplo

```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).

````