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

# Obter Ciclo de Cobrança

> Consulte os detalhes completos de um ciclo de cobrança específico, incluindo todas as tentativas de pagamento.

#### Escopo

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

## Quando usar

* Para investigar uma cobrança específica que o cliente questionou
* Para analisar o histórico de tentativas de um ciclo pendente
* Para confirmar se um pagamento foi processado corretamente

## O que a resposta inclui

A resposta traz o ciclo completo com o array `attempts` aninhado. Cada tentativa mostra:

| Campo            | Descrição                           |
| ---------------- | ----------------------------------- |
| `attempt_number` | Número da tentativa (1ª, 2ª, 3ª...) |
| `result`         | `success` ou `failure`              |
| `failure_reason` | Motivo da falha, quando houver      |
| `scheduled_for`  | Data agendada para a tentativa      |
| `started_at`     | Quando a tentativa iniciou          |
| `completed_at`   | Quando a tentativa finalizou        |

<Tip>
  Compare `scheduled_for` com `completed_at` para identificar atrasos no processamento da cobrança.
</Tip>

<Note>
  O `cycle_id` deve ser o identificador retornado pelo endpoint de listagem de ciclos.
</Note>


## OpenAPI

````yaml GET /public_api/subscriptions/{id}/billing-cycles/{cycle_id}/
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/{cycle_id}/:
    get:
      tags:
        - subscriptions
      description: Public API to retrieve a single billing cycle for a subscription.
      operationId: subscriptions_billing_cycle_retrieve
      parameters:
        - in: path
          name: cycle_id
          schema:
            type: string
            format: uuid
          required: true
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCycle'
              examples:
                Successo:
                  value:
                    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 ou ciclo de cobrança não encontrado.
      security:
        - OAuth Token: []
components:
  schemas:
    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
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    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).

````