Skip to main content
GET
/
public_api
/
subscriptions
/
{id}
/
billing-cycles
/
cURL
curl --request GET \
  --url https://api.cakto.com.br/public_api/subscriptions/{id}/billing-cycles/ \
  --header 'Authorization: Bearer <token>'
{
  "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"
        }
      ]
    }
  ]
}

​
Escopo

    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.

Visão histórica

Veja todos os ciclos de uma assinatura em ordem cronológica, do mais recente ao mais antigo.

Identifique inadimplência

Descubra se o cliente tem ciclos pendentes, atrasados ou com múltiplas tentativas de cobrança.

Acompanhe receita recorrente

Entenda se a assinatura está gerando receita de forma previsível ou se há interrupções.

Base para decisões

Use os dados de ciclo para decidir sobre retenção, cobrança manual ou cancelamento.

​
Quando usar cada endpoint

EndpointAçãoQuando usar
GET /subscriptions/{id}/billing-cycles/Listar ciclosPara ver todo o histórico de cobrança de uma assinatura.
GET /subscriptions/{id}/billing-cycles/{cycle_id}/Consultar cicloPara obter os detalhes de um ciclo específico, incluindo tentativas.
GET /subscriptions/{id}/billing-cycles/{cycle_id}/attempts/Listar tentativasPara analisar apenas as tentativas de cobrança de um ciclo.

​
Casos de uso

Verifique se o cliente pagou todos os ciclos em dia ou se há atrasos recorrentes. Isso ajuda a identificar assinaturas em risco de cancelamento.
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.
Analise a regularidade dos pagamentos ao longo dos ciclos para projetar a receita recorrente e identificar churn antes que aconteça.
Quando um cliente questiona uma cobrança, consulte o ciclo específico para verificar status, valor e tentativas de forma rápida e precisa.

​
Como interpretar a resposta

A resposta é uma lista paginada de ciclos. Cada ciclo contém:
CampoDescrição
cycle_numberNúmero sequencial do ciclo (1, 2, 3…)
due_dateData de vencimento da cobrança
amountValor do ciclo
statusStatus atual: paid, pending, failed, etc.
total_attemptsQuantidade de tentativas de cobrança realizadas
completed_atData em que o ciclo foi concluído (pago ou falhou definitivamente)
attemptsLista aninhada com o detalhe de cada tentativa
Ciclos com status: paid e poucas tentativas indicam assinatura saudável. Ciclos com status: pending e muitas tentativas merecem atenção para retenção.
Os ciclos são retornados ordenados por data de vencimento decrescente. O primeiro item da lista é sempre o ciclo mais recente.

Authorizations

​
Authorization
string
header
required

Token de autenticação do tipo Bearer {access_token}, onde {access_token} é o token obtido no fluxo de autenticação.

Path Parameters

​
id
string<uuid>
required

ID da assinatura

Response

Corpo da resposta status 200

​
count
integer
required

Total de resultados

​
results
object[]
required

Lista de ciclos de cobrança

​
next
string<uri> | null

URL da próxima página

​
previous
string<uri> | null

URL da página anterior