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

# Liste e recupere faturas de assinatura

> Liste as faturas de uma assinatura ou recupere uma única fatura pelo UUID dela.

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>;
};

O Therius cria uma fatura por ciclo de faturamento. Cada fatura registra a tentativa ou as tentativas de cobrança para aquele ciclo, o resultado e o valor final cobrado. Você pode recuperar todas as faturas de uma assinatura, ou buscar uma fatura específica diretamente pelo UUID dela.

<SchemaLangNote lang="pt" />

## Liste as faturas de uma assinatura

`GET /subscription/{id}/invoice` devolve todas as faturas de uma assinatura dada em ordem cronológica inversa, como um array simples — veja o painel de resposta acima para a forma completa de `Invoice` (`status` é `open`/`paid`/`failed`/`void`; o campo de novas tentativas é `paymentAttemptCount`).

<a id="line-items" />

`lines[]` está presente apenas quando o plano precifica um ou mais [medidores de uso](/pt/guides/subscriptions#faturamento-por-uso-e-híbrido): uma linha para a tarifa base do plano (sem `meterId`) mais uma linha por complemento medido. Ausente ou vazio em uma fatura de tarifa fixa — o `amount` de nível superior é então a cobrança inteira, e o `amount` de cada linha soma a ele.

### Exemplo

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

***

## Recupere uma fatura específica

`GET /subscription/invoice/{id}` recupera uma única fatura pelo UUID dela, independentemente de a qual assinatura ela pertence. Autentica da mesma forma que qualquer outro endpoint (`Authorization: Bearer prv_production_xxx` / `prv_sandbox_xxx`).

### Parâmetros de caminho

<ParamField path="id" type="string" required>
  O UUID da fatura a recuperar.
</ParamField>

### Parâmetros de consulta

<ParamField query="merchantCode" type="string" required>
  O seu identificador de conta de lojista.
</ParamField>

### Resposta

Devolve um único objeto de fatura com os mesmos campos descritos acima.

### Erros

| Código | Significado                                       |
| ------ | ------------------------------------------------- |
| `404`  | Fatura não encontrada sob a sua conta de lojista. |

### Exemplo

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

````