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

# Assinaturas Perdidas

> Acompanhe cancelamentos e assinaturas inativas para identificar padrões de perda, medir o impacto financeiro e tomar decisões que melhorem a retenção.

#### Escopo

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

## O que é este endpoint?

Lista todas as assinaturas canceladas ou inativas do seu negócio. A resposta inclui **métricas agregadas** com o valor financeiro em risco e a quantidade de clientes afetados.

***

## Casos de uso

<AccordionGroup>
  <Accordion title="Avaliar a retenção de clientes" icon="users">
    Compare períodos e veja se a taxa de cancelamento está caindo ou subindo. Se subiu após uma mudança no produto, é hora de rever o que foi feito.
  </Accordion>

  <Accordion title="Detectar picos de cancelamento" icon="triangle-exclamation">
    Um aumento repentino pode indicar problema técnico, insatisfação ou comunicação confusa. Quanto antes identificar, mais rápido você corrige.
  </Accordion>

  <Accordion title="Medir o impacto de reajustes de preço" icon="tags">
    Subiu o preço? Monitore este endpoint nos 30 dias seguintes para saber se a mudança afetou a permanência dos assinantes.
  </Accordion>

  <Accordion title="Comparar desempenho entre períodos" icon="chart-column">
    Filtre por mês ou trimestre para entender se o negócio recorrente está estável, crescendo ou perdendo fôlego.
  </Accordion>

  <Accordion title="Acompanhar a saúde da receita" icon="sack-dollar">
    O campo `total_at_risk_value` mostra o valor total das assinaturas canceladas e inativas. Isso ajuda a dimensionar o problema em dinheiro.
  </Accordion>

  <Accordion title="Descobrir sinais de insatisfação" icon="face-smile">
    Cancelamentos frequentes costumam preceder reclamações. Use os dados para investigar o que está errado antes que o churn se espalhe.
  </Accordion>
</AccordionGroup>

***

## Insights que podem ser obtidos

<AccordionGroup>
  <Accordion title="Identificar problemas de retenção" icon="magnifying-glass">
    Use os filtros de data para cruzar picos de cancelamento com mudanças recentes no produto, preço ou comunicação.
  </Accordion>

  <Accordion title="Avaliar mudanças no negócio" icon="arrows-rotate">
    Lançou uma nova funcionalidade ou campanha? Compare os cancelamentos antes e depois para medir o efeito real.
  </Accordion>

  <Accordion title="Antecipar quedas na receita" icon="circle-dollar-to-slot">
    Se o valor em risco cresce mês após mês, a receita recorrente vai cair em breve. Agir preventivamente é mais barato que recuperar clientes perdidos.
  </Accordion>

  <Accordion title="Planejar campanhas de recuperação" icon="clock-rotate-left">
    Analise a evolução dos cancelamentos ao longo do ano para identificar os melhores momentos para disparar ofertas de win-back.
  </Accordion>
</AccordionGroup>

***

## Filtros Disponíveis

<Tip>
  Filtros podem ser combinados para refinar os resultados.

  **Exemplo:** `?status=canceled&createdAt__gte=2025-01-01` — Filtra assinaturas canceladas desde janeiro de 2025.
</Tip>

<AccordionGroup>
  <Accordion title="Filtros por Status" icon="flag">
    * `status` — Status da assinatura (`canceled`, `inactive`, ou ambos separados por vírgula)

    **Exemplo:** `?status=canceled,inactive` — Traz tanto canceladas quanto inativas
  </Accordion>

  <Accordion title="Filtros por Período" icon="clock">
    * `current_period` — Período atual da assinatura (número inteiro)
    * `current_period__gt` — Período maior que
    * `current_period__lt` — Período menor que

    **Exemplo:** `?current_period__gt=3` — Assinaturas que já passaram do 3º período
  </Accordion>

  <Accordion title="Filtros por Data" icon="calendar">
    * `createdAt` — Data de criação (suporta `__gte`, `__lte`, `__gt`, `__lt`)
    * `canceledAt` — Data de cancelamento (suporta `__gte`, `__lte`, `__gt`, `__lt`)
    * `next_payment_date` — Próximo pagamento (suporta `__gte`, `__lte`, `__gt`, `__lt`)

    <Note>
      Formato de data: `YYYY-MM-DD` ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DDTHH:MM:SS±hh:mm`
    </Note>

    **Exemplo:** `?canceledAt__gte=2025-01-01&canceledAt__lt=2025-02-01` — Cancelamentos de janeiro de 2025
  </Accordion>

  <Accordion title="Paginação" icon="list-ol">
    * `limit` — Número de resultados por página (padrão: 100)
    * `offset` — Índice do primeiro resultado

    **Exemplo:** `?limit=50&offset=50` — Página 2 com 50 resultados por página
  </Accordion>
</AccordionGroup>

***

## Métricas Retornadas

A resposta inclui um objeto `metrics` com as seguintes informações financeiras e quantitativas:

| Métrica                    | Descrição                              |
| -------------------------- | -------------------------------------- |
| `at_risk_value`            | Valor total das assinaturas inativas   |
| `at_risk_count`            | Quantidade de assinaturas inativas     |
| `churned_value`            | Valor total das assinaturas canceladas |
| `churned_count`            | Quantidade de assinaturas canceladas   |
| `affected_customers_count` | Número de clientes únicos afetados     |
| `total_at_risk_value`      | Soma do valor inativo + cancelado      |

<Info>
  Dados sensíveis do cliente são limitados por padrão. Apenas `name` é retornado no objeto `customer`.
</Info>


## OpenAPI

````yaml GET /public_api/subscriptions/churn/
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/churn/:
    get:
      tags:
        - subscriptions
      description: Lista assinaturas canceladas e inativas com métricas agregadas
      operationId: subscriptions_churn_list
      parameters:
        - name: limit
          required: false
          in: query
          description: Número de resultados a serem retornados por página.
          schema:
            type: integer
        - name: offset
          required: false
          in: query
          description: Índice do primeiro resultado a ser retornado.
          schema:
            type: integer
        - name: status
          required: false
          in: query
          description: >-
            Filtra por status da assinatura (canceled, inactive, ou ambos
            separados por vírgula)
          schema:
            type: string
        - name: current_period
          required: false
          in: query
          description: Filtra pelo período atual da assinatura
          schema:
            type: integer
        - name: current_period__gt
          required: false
          in: query
          description: Filtra por período maior que
          schema:
            type: integer
        - name: current_period__lt
          required: false
          in: query
          description: Filtra por período menor que
          schema:
            type: integer
        - name: createdAt__gte
          required: false
          in: query
          description: Filtra por data de criação maior ou igual (formato ISO 8601)
          schema:
            type: string
            format: date-time
        - name: createdAt__lte
          required: false
          in: query
          description: Filtra por data de criação menor ou igual (formato ISO 8601)
          schema:
            type: string
            format: date-time
        - name: canceledAt__gte
          required: false
          in: query
          description: Filtra por data de cancelamento maior ou igual (formato ISO 8601)
          schema:
            type: string
            format: date-time
        - name: canceledAt__lte
          required: false
          in: query
          description: Filtra por data de cancelamento menor ou igual (formato ISO 8601)
          schema:
            type: string
            format: date-time
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSubscriptionChurnList'
              examples:
                Successo:
                  value:
                    count: 10
                    next: null
                    previous: null
                    results:
                      - id: b7475fda-fde2-4fcf-8bdf-d0fe569b4d9e
                        status: inactive
                        current_period: 1
                        recurrence_period: 7
                        quantity_recurrences: -1
                        trial_days: 0
                        max_retries: 3
                        amount: '300.00'
                        retry_interval: 1
                        paid_payments_quantity: 0
                        retention: '00:00:00'
                        paymentMethod: boleto
                        customer:
                          name: Mathias Silva
                        product: 210b2459-60ed-4b59-9e4f-d0f0abc5ad83
                        offer: 3exkqn4
                        orders:
                          - 5a6aea2f-3ccc-4e50-82f6-fb1489cc7d0b
                        next_payment_date: null
                        canceledAt: null
                      - id: 38d21232-4bf0-47fe-9ce6-617b2d9729fe
                        status: canceled
                        current_period: 1
                        recurrence_period: 7
                        quantity_recurrences: -1
                        trial_days: 0
                        max_retries: 3
                        amount: '300.99'
                        retry_interval: 1
                        paid_payments_quantity: 1
                        retention: '00:01:15.266048'
                        paymentMethod: credit_card
                        customer:
                          name: Mathias Silva
                        product: 210b2459-60ed-4b59-9e4f-d0f0abc5ad83
                        offer: 3exkqn4
                        orders:
                          - 4e4f6744-74b9-46da-aecd-ab3bd276b88b
                        next_payment_date: null
                        canceledAt: '2026-04-23T14:25:43.755035-03:00'
                    metrics:
                      at_risk_value: 300
                      at_risk_count: 1
                      churned_value: 901.98
                      churned_count: 3
                      affected_customers_count: 1
                      total_at_risk_value: 1201.98
          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'
        '403':
          description: Permissão negada. O token não possui o escopo `subscriptions`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                PermissãoNegada:
                  value:
                    detail: Você não tem permissão para realizar esta ação.
      security:
        - OAuth Token: []
components:
  schemas:
    PaginatedSubscriptionChurnList:
      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/SubscriptionChurn'
        metrics:
          $ref: '#/components/schemas/SubscriptionChurnMetrics'
      required:
        - count
        - results
        - metrics
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    SubscriptionChurn:
      type: object
      properties:
        id:
          type: string
          description: Id da assinatura
        status:
          type: string
          description: Status da assinatura (canceled ou inactive)
        current_period:
          type: integer
          description: Período atual da assinatura
        recurrence_period:
          type: integer
          description: Período de recorrência em dias
        quantity_recurrences:
          type: integer
          description: Quantidade de recorrências
        trial_days:
          type: integer
          description: Dias de teste
        max_retries:
          type: integer
          description: Número máximo de retentativas
        amount:
          type: string
          description: Valor da assinatura
        retry_interval:
          type: integer
          description: Intervalo entre retentativas em dias
        paid_payments_quantity:
          type: integer
          description: Quantidade de pagamentos efetuados
        retention:
          type: string
          description: Tempo de retenção da assinatura
        paymentMethod:
          type: string
          description: Método de pagamento
        customer:
          $ref: '#/components/schemas/SubscriptionChurnCustomer'
        product:
          type: string
          description: Id do produto
        offer:
          type: string
          description: Id da oferta
        orders:
          type: array
          items:
            type: string
          description: Lista de IDs dos pedidos associados
        next_payment_date:
          type: string
          format: date-time
          nullable: true
          description: Data do próximo pagamento
        canceledAt:
          type: string
          format: date-time
          nullable: true
          description: Data de cancelamento
      required:
        - id
        - status
        - amount
        - customer
    SubscriptionChurnMetrics:
      type: object
      properties:
        at_risk_value:
          type: number
          format: float
          description: Valor total das assinaturas inativas
        at_risk_count:
          type: integer
          description: Quantidade de assinaturas inativas
        churned_value:
          type: number
          format: float
          description: Valor total das assinaturas canceladas
        churned_count:
          type: integer
          description: Quantidade de assinaturas canceladas
        affected_customers_count:
          type: integer
          description: Número de clientes únicos afetados
        total_at_risk_value:
          type: number
          format: float
          description: Soma do valor inativo + cancelado
      required:
        - at_risk_value
        - at_risk_count
        - churned_value
        - churned_count
        - affected_customers_count
        - total_at_risk_value
    SubscriptionChurnCustomer:
      type: object
      properties:
        name:
          type: string
          description: Nome do cliente
      required:
        - name
  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).

````