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

# Listar faturas da assinatura

> Lista as faturas da assinatura, da mais recente para a mais antiga. A listagem não tem cursor de paginação: use `limit` (até 100) e confira `has_more`.


<Info>
  As faturas vêm da **mais recente para a mais antiga**. Use `limit` (padrão `10`, máximo `100`) e o filtro opcional `status`.
</Info>

<Warning>
  A listagem **não tem paginação por cursor**. A resposta traz apenas as primeiras `limit` faturas e o campo `has_more`, que indica se existem outras além delas. Não há como buscar a página seguinte.
</Warning>

<Note>
  O filtro `status` aceita `paid`, `failed`, `pending`, `canceled`, `refunded`, `partially_refunded` e `chargeback`. O valor `pending` reúne as faturas em andamento, exibidas como `processing` ou `requires_action`.
</Note>


## OpenAPI

````yaml GET /v2/subscriptions/{id}/invoices
openapi: 3.1.0
info:
  title: 4Selet Pay API
  description: >
    API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
    cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
    rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
  version: 1.0.0
  contact:
    name: 4Selet Pay
    email: suporte@4selet.com.br
servers:
  - url: https://sandbox.4seletpay.com.br/api
    description: Servidor de Sandbox
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Rotas de autenticação e criação de usuários
  - name: Cobranças
    description: Criação, consulta, cancelamento e reembolso de cobranças
  - name: Pedidos
    description: Consulta de pedidos e gerenciamento de confirmações desafiadas
  - name: Cartões
    description: Cadastro e gerenciamento dos cartões salvos de um cliente
  - name: Assinaturas
    description: Criação e gerenciamento de assinaturas recorrentes
  - name: Faturas
    description: Gerenciamento de faturas e pagamento de faturas em atraso
  - name: Clientes Bloqueados
    description: Gerenciamento de lista negra de clientes
  - name: Contas
    description: Criação e gerenciamento de contas na plataforma
  - name: Aplicativo
    description: Endpoints para dashboard e uso via aplicativo mobile
  - name: Notificações Push
    description: Envio e gerenciamento de notificações push
  - name: Utilitários
    description: Endpoints utilitários como listagem de fusos horários
  - name: Gestão
    description: Relatórios gerenciais (acesso restrito a Super Admins)
  - name: Webhooks
    description: Endpoints para receber notificações de gateways de pagamento
  - name: Endpoints de Webhook
    description: >-
      Gerenciamento de endpoints de webhook para receber notificações de eventos
      da plataforma
  - name: Links de Pagamento
    description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
  - name: Análise de Fraude
    description: >-
      API de Risco — consulta o risco de fraude de uma transação (autenticada
      por chave de API)
  - name: Pedidos (v2)
    description: >-
      API v2 — pedidos com um ou mais meios de pagamento, captura, cancelamento
      e verificação por código
  - name: Cobranças (v2)
    description: API v2 — consulta e estorno de cobranças
  - name: Cartões (v2)
    description: API v2 — cadastro e consulta de cartões salvos
  - name: Assinaturas (v2)
    description: API v2 — criação e gerenciamento de assinaturas recorrentes
  - name: Faturas (v2)
    description: >-
      API v2 — consulta, pagamento e verificação por código das faturas de
      assinaturas
paths:
  /v2/subscriptions/{id}/invoices:
    get:
      tags:
        - Assinaturas (v2)
      summary: Listar faturas da assinatura
      description: >
        Lista as faturas da assinatura, da mais recente para a mais antiga. A
        listagem não tem cursor de paginação: use `limit` (até 100) e confira
        `has_more`.
      operationId: v2ListSubscriptionInvoices
      parameters:
        - $ref: '#/components/parameters/V2Id'
        - name: status
          in: query
          required: false
          description: Filtra as faturas pelo status
          schema:
            type: string
            enum:
              - paid
              - failed
              - pending
              - canceled
              - refunded
              - partially_refunded
              - chargeback
        - name: limit
          in: query
          required: false
          description: Quantidade máxima de faturas
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Lista de faturas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2InvoiceList'
              example:
                object: list
                data:
                  - id: '719305'
                    object: invoice
                    subscription: sub_4Hn8Qw2Rt6Yp1Zx3
                    number: 1
                    status: paid
                    currency: brl
                    amount: 9000
                    attempts: 1
                    items:
                      - code: SKU-SUB
                        description: Assinatura
                        quantity: 1
                        amount: 10000
                    discounts:
                      - type: fixed
                        value: 1000
                        invoice_number: 1
                    increments: []
                    payments:
                      - id: cha_8Kq2Lm9XvB3nT7pZ
                        object: payment_intent
                        status: paid
                        amount: 9000
                        amount_refunded: 0
                        currency: brl
                        payment_method_details:
                          type: card
                          card:
                            brand: visa
                            last_four: '1111'
                            holder_name: João Silva
                    next_action: null
                    created_at: '2026-09-14T12:00:00-03:00'
                has_more: false
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2AccountBlocked'
        '404':
          $ref: '#/components/responses/V2SubscriptionNotFound'
        '422':
          description: Filtro inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  type: invalid_request_error
                  code: validation_error
                  message: The selected status is invalid.
                  param: status
        '429':
          $ref: '#/components/responses/V2ThrottleExceeded'
      security:
        - secretKeyAuth: []
components:
  parameters:
    V2Id:
      name: id
      in: path
      required: true
      description: Identificador do recurso (o campo `id` devolvido pela API)
      schema:
        type: string
  schemas:
    V2InvoiceList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/V2Invoice'
        has_more:
          type: boolean
          description: >-
            Existem mais faturas além do `limit`. A listagem não tem cursor de
            paginação
    V2Error:
      type: object
      description: Envelope de erro da API v2
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - idempotency_error
                - authentication_error
                - api_error
              description: Categoria do erro
            code:
              type: string
              description: Código estável do erro. Use este campo na sua lógica
              example: validation_error
            message:
              type: string
              description: Texto técnico, para log e depuração. Não exiba ao pagador
              example: The payments field is required.
            param:
              type: string
              description: >-
                Campo que causou o erro, em notação de ponto. Presente só quando
                se aplica
              example: payments
            customer_message:
              type: string
              description: Texto para exibir ao pagador. Presente só quando se aplica
    V2Invoice:
      type: object
      description: >
        Fatura de um ciclo da assinatura. `processing`: em processamento.
        `requires_action`: PIX aguardando pagamento ou verificação por código
        (veja `next_action`). `paid`: paga. `failed`: recusada (veja
        `failure_reason`). `canceled`: cancelada. `refunded` e
        `partially_refunded`: estornada. `chargeback`: contestada.
      properties:
        id:
          type: string
          example: '719305'
        object:
          type: string
          enum:
            - invoice
        subscription:
          type: string
          example: sub_4Hn8Qw2Rt6Yp1Zx3
        number:
          type: integer
          description: Número da fatura na assinatura
          example: 1
        status:
          type: string
          enum:
            - processing
            - requires_action
            - paid
            - failed
            - canceled
            - refunded
            - partially_refunded
            - chargeback
        currency:
          type: string
          example: brl
        amount:
          type: integer
          description: Valor da fatura, em centavos, já com descontos e acréscimos
          example: 9000
        attempts:
          type: integer
          description: Tentativas de cobrança
        items:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionItem'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        increments:
          type: array
          items:
            $ref: '#/components/schemas/V2SubscriptionAdjustment'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/V2PaymentIntent'
        next_action:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/V2NextAction'
        created_at:
          type: string
        failure_reason:
          $ref: '#/components/schemas/V2FailureReason'
    V2ThrottleError:
      type: object
      description: >
        Corpo padrão, fora do envelope `error`, do limite geral de requisições e
        do limite de reenvio do código de verificação
      properties:
        message:
          type: string
          example: Too Many Attempts.
    V2SubscriptionItem:
      type: object
      required:
        - code
        - description
        - quantity
        - amount
      properties:
        code:
          type: string
          maxLength: 255
          example: SKU-SUB
        description:
          type: string
          maxLength: 255
          example: Assinatura
        quantity:
          type: integer
          minimum: 1
          example: 1
        amount:
          type: integer
          minimum: 1
          description: Valor unitário, em centavos
          example: 10000
    V2SubscriptionAdjustment:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - fixed
            - percentage
        value:
          type: number
          exclusiveMinimum: 0
          description: >
            Em `fixed`, valor inteiro em centavos. Em `percentage`, percentual
            (em descontos, no máximo 100).
          example: 1000
        invoice_number:
          type: integer
          minimum: 1
          nullable: true
          description: >-
            Número da fatura a que o ajuste se aplica. Sem valor, vale para
            todas as faturas
          example: 1
    V2PaymentIntent:
      type: object
      description: >
        Um meio de pagamento dentro de um pedido ou fatura. O `id` é o mesmo da
        cobrança (`GET /v2/charges/{id}`).
      properties:
        id:
          type: string
          example: cha_8Kq2Lm9XvB3nT7pZ
        object:
          type: string
          enum:
            - payment_intent
        status:
          type: string
          enum:
            - requires_action
            - requires_capture
            - processing
            - paid
            - failed
            - canceled
            - refund_processing
            - partially_refunded
            - refunded
            - chargeback
          description: >
            `requires_action`: PIX aguardando pagamento ou verificação por
            código. `requires_capture`: cartão autorizado, aguardando captura.
            `processing`: em processamento. `paid`: pago. `failed`: recusado.
            `canceled`: cancelado. `refund_processing`: estorno em
            processamento. `partially_refunded` e `refunded`: estornado em parte
            ou totalmente. `chargeback`: contestado pelo portador.
        amount:
          type: integer
          description: Valor em centavos
          example: 10000
        amount_refunded:
          type: integer
          description: Valor estornado, em centavos
          example: 0
        currency:
          type: string
          example: brl
        payment_method_details:
          type: object
          properties:
            type:
              type: string
              enum:
                - card
                - pix
                - boleto
            card:
              type: object
              description: Presente em pagamentos com cartão
              properties:
                brand:
                  type: string
                  example: visa
                last_four:
                  type: string
                  example: '1111'
                holder_name:
                  type: string
                  example: João Silva
            pix:
              $ref: '#/components/schemas/V2Pix'
    V2NextAction:
      type: object
      description: >
        O que precisa acontecer para o pagamento seguir. `pix_display_qr_code`:
        exiba o QR Code para o pagador. `otp_confirmation`: a análise de fraude
        pediu verificação — nada é cobrado até o código ser confirmado na rota
        `/confirm`.
      properties:
        type:
          type: string
          enum:
            - pix_display_qr_code
            - otp_confirmation
        pix:
          $ref: '#/components/schemas/V2Pix'
        otp:
          type: object
          description: Presente quando `type` é `otp_confirmation`
          properties:
            confirmation_id:
              type: string
              example: 5f1c2a9e-7b3d-4e8f-9a6c-1d2e3f4a5b6c
            expires_at:
              type: string
              description: Data e hora de expiração do código
              example: '2026-09-14T12:15:00.000000Z'
    V2FailureReason:
      type: object
      description: Motivo da recusa. Presente só quando o status é `failed`
      required:
        - code
        - message
        - customer_message
        - merchant_message
      properties:
        code:
          type: string
          enum:
            - card_declined
            - insufficient_funds
            - expired_card
            - incorrect_cvc
            - incorrect_number
            - card_not_supported
            - fraud_suspected
            - invalid_request
            - acquirer_error
            - processing_error
        message:
          type: string
          description: Texto técnico. Não exiba ao pagador
          example: O cartão não possui saldo suficiente para concluir o pagamento.
        customer_message:
          type: string
          description: Texto para exibir ao pagador
          example: >-
            Não foi possível concluir o pagamento. Revise os dados informados ou
            tente outro meio de pagamento.
        merchant_message:
          type: string
          description: Texto para você ou a sua equipe de atendimento
          example: >-
            O pagamento não foi concluído. Oriente o comprador a revisar os
            dados informados ou tentar outro meio de pagamento.
    V2Pix:
      type: object
      properties:
        qr_code:
          type: string
          description: Código PIX copia e cola
          example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
        qr_code_url:
          type: string
          description: Link do QR Code
          example: https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ
        expires_at:
          type: string
          description: Data e hora de expiração do QR Code
          example: '2026-09-14T16:00:00.000000Z'
  responses:
    V2Unauthorized:
      description: Chave de API ausente, inválida, revogada ou de outro ambiente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: authentication_error
              code: invalid_api_secret
              message: Invalid API secret.
    V2AccountBlocked:
      description: >-
        As requisições da conta estão bloqueadas. A resposta traz
        `customer_message`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: invalid_request_error
              code: account_requests_blocked
              message: As requisições desta conta estão bloqueadas.
              customer_message: >-
                Não foi possível concluir sua transação. Tente novamente mais
                tarde.
    V2SubscriptionNotFound:
      description: Assinatura não encontrada nesta conta
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              type: invalid_request_error
              code: resource_missing
              message: Recurso "subscription" não encontrado.
    V2ThrottleExceeded:
      description: >
        Limite geral de requisições excedido (120 por minuto por chave de API e
        por conta). Esta resposta não usa o envelope `error` da API v2.
      headers:
        X-RateLimit-Limit:
          description: Limite de requisições da janela
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requisições restantes na janela
          schema:
            type: integer
        Retry-After:
          description: Segundos até a próxima tentativa
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2ThrottleError'
          example:
            message: Too Many Attempts.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
        Bearer <token>`.
    secretKeyAuth:
      type: http
      scheme: bearer
      description: >
        Chave de API (secret key) da conta, no formato `sk_live_...` (produção)
        ou `sk_test_...` (Dev mode). Envie no header `Authorization: Bearer
        <chave>`. Autentica todas as rotas da API v2 e as rotas de Análise de
        Fraude. A chave identifica a conta, então a API v2 não usa o header
        `account`. Uma chave só é aceita no ambiente em que foi criada. Gere a
        sua no dashboard em Configurações → Chaves de API.

````