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

# Listar Ciclos de Cobrança

> Acompanhe o histórico completo de cobranças de uma assinatura. Entenda o que foi pago, o que está pendente e o padrão de inadimplência ao longo do tempo.

#### Escopo

```bash theme={null}
    read subscriptions
```

## O que são ciclos de cobrança?

Cada assinatura gera ciclos de cobrança periódicos. Um ciclo representa uma fatura com valor, vencimento, status e o histórico de tentativas de pagamento.

<CardGroup cols={2}>
  <Card title="Visão histórica" icon="clock-rotate-left">
    Veja todos os ciclos de uma assinatura em ordem cronológica, do mais recente ao mais antigo.
  </Card>

  <Card title="Identifique inadimplência" icon="triangle-exclamation">
    Descubra se o cliente tem ciclos pendentes, atrasados ou com múltiplas tentativas de cobrança.
  </Card>

  <Card title="Acompanhe receita recorrente" icon="chart-line">
    Entenda se a assinatura está gerando receita de forma previsível ou se há interrupções.
  </Card>

  <Card title="Base para decisões" icon="scale-balanced">
    Use os dados de ciclo para decidir sobre retenção, cobrança manual ou cancelamento.
  </Card>
</CardGroup>

***

## Quando usar cada endpoint

| Endpoint                                                      | Ação                  | Quando usar                                                          |
| ------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------- |
| `GET /subscriptions/{id}/billing-cycles/`                     | **Listar ciclos**     | Para ver todo o histórico de cobrança de uma assinatura.             |
| `GET /subscriptions/{id}/billing-cycles/{cycle_id}/`          | **Consultar ciclo**   | Para obter os detalhes de um ciclo específico, incluindo tentativas. |
| `GET /subscriptions/{id}/billing-cycles/{cycle_id}/attempts/` | **Listar tentativas** | Para analisar apenas as tentativas de cobrança de um ciclo.          |

***

## Casos de uso

<AccordionGroup>
  <Accordion title="Auditar o histórico de pagamentos" icon="list-check">
    Verifique se o cliente pagou todos os ciclos em dia ou se há atrasos recorrentes. Isso ajuda a identificar assinaturas em risco de cancelamento.
  </Accordion>

  <Accordion title="Investigar cobranças recusadas" icon="magnifying-glass">
    Um ciclo com status pendente e múltiplas tentativas pode indicar problema no cartão, limite insuficiente ou questão no gateway. Use os dados para tomar ação.
  </Accordion>

  <Accordion title="Prever receita futura" icon="chart-column">
    Analise a regularidade dos pagamentos ao longo dos ciclos para projetar a receita recorrente e identificar churn antes que aconteça.
  </Accordion>

  <Accordion title="Suporte ao cliente" icon="headset">
    Quando um cliente questiona uma cobrança, consulte o ciclo específico para verificar status, valor e tentativas de forma rápida e precisa.
  </Accordion>
</AccordionGroup>

***

## Como interpretar a resposta

A resposta é uma lista paginada de ciclos. Cada ciclo contém:

| Campo            | Descrição                                                          |
| ---------------- | ------------------------------------------------------------------ |
| `cycle_number`   | Número sequencial do ciclo (1, 2, 3...)                            |
| `due_date`       | Data de vencimento da cobrança                                     |
| `amount`         | Valor do ciclo                                                     |
| `status`         | Status atual: `paid`, `pending`, `failed`, etc.                    |
| `total_attempts` | Quantidade de tentativas de cobrança realizadas                    |
| `completed_at`   | Data em que o ciclo foi concluído (pago ou falhou definitivamente) |
| `attempts`       | Lista aninhada com o detalhe de cada tentativa                     |

<Tip>
  Ciclos com `status: paid` e poucas tentativas indicam assinatura saudável. Ciclos com `status: pending` e muitas tentativas merecem atenção para retenção.
</Tip>

<Info>
  Os ciclos são retornados ordenados por data de vencimento decrescente. O primeiro item da lista é sempre o ciclo mais recente.
</Info>


## OpenAPI

````yaml GET /public_api/subscriptions/{id}/billing-cycles/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/subscriptions/{id}/billing-cycles/:
    get:
      tags:
        - subscriptions
      description: Public API to list billing cycles for a subscription.
      operationId: subscriptions_billing_cycles_list
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBillingCycleList'
              examples:
                Successo:
                  value:
                    count: 1
                    next: null
                    previous: null
                    results:
                      - id: f15d1962-bba0-4e66-a147-f59a48935f29
                        cycle_number: 1
                        due_date: '2026-05-18T19:14:17.677041Z'
                        amount: '100.00'
                        status: paid
                        total_attempts: 2
                        completed_at: '2026-05-18T19:15:02.123456Z'
                        created_at: '2026-05-18T19:14:17.677041Z'
                        attempts:
                          - id: d9abeb29-6c7d-46fa-938a-4fbce40be05d
                            attempt_number: 1
                            amount: '100.00'
                            result: failure
                            failure_reason: Insufficient funds
                            scheduled_for: '2026-05-18T19:14:17.677041Z'
                            started_at: '2026-05-18T19:14:18.123456Z'
                            completed_at: '2026-05-18T19:14:20.789012Z'
                            created_at: '2026-05-18T19:14:17.677041Z'
                          - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                            attempt_number: 2
                            amount: '100.00'
                            result: success
                            failure_reason: null
                            scheduled_for: '2026-05-19T19:14:17.677041Z'
                            started_at: '2026-05-19T19:14:18.000000Z'
                            completed_at: '2026-05-19T19:14:22.000000Z'
                            created_at: '2026-05-18T19:14:17.677041Z'
          description: Corpo da resposta status 200
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                NaoEncontrado:
                  value:
                    detail: Não encontrado.
          description: Assinatura não encontrada.
      security:
        - OAuth Token: []
components:
  schemas:
    PaginatedBillingCycleList:
      type: object
      properties:
        count:
          type: integer
          description: Total de resultados
        next:
          type: string
          format: uri
          nullable: true
          description: URL da próxima página
        previous:
          type: string
          format: uri
          nullable: true
          description: URL da página anterior
        results:
          type: array
          items:
            $ref: '#/components/schemas/BillingCycle'
          description: Lista de ciclos de cobrança
      required:
        - count
        - results
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    BillingCycle:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID do ciclo de cobrança
        cycle_number:
          type: integer
          description: Número do ciclo
        due_date:
          type: string
          format: date-time
          description: Data de vencimento
        amount:
          type: string
          description: Valor do ciclo
        status:
          type: string
          description: Status do ciclo (paid, pending, etc.)
        total_attempts:
          type: integer
          description: Total de tentativas de cobrança
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Data de conclusão
        created_at:
          type: string
          format: date-time
          description: Data de criação
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/Attempt'
          description: Lista de tentativas de cobrança
      required:
        - amount
        - attempts
        - created_at
        - cycle_number
        - due_date
        - id
        - status
        - total_attempts
    Attempt:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID da tentativa
        attempt_number:
          type: integer
          description: Número da tentativa
        amount:
          type: string
          description: Valor tentado
        result:
          type: string
          description: Resultado (success ou failure)
        failure_reason:
          type: string
          nullable: true
          description: Motivo da falha, se houver
        scheduled_for:
          type: string
          format: date-time
          description: Data agendada
        started_at:
          type: string
          format: date-time
          nullable: true
          description: Data de início
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Data de conclusão
        created_at:
          type: string
          format: date-time
          description: Data de criação
      required:
        - amount
        - attempt_number
        - completed_at
        - created_at
        - id
        - result
        - scheduled_for
        - started_at
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````