# Churn

**Área:** Séries temporais

Série de perda de MRR no período, fatiada por dia ou por mês. Esta série temporal considera assinaturas canceladas ou expiradas (status `CANCELED` ou `EXPIRED`) que já pagaram pelo menos um ciclo. Deste modo, assinaturas canceladas ou expiradas que nunca tiveram um ciclo pago não são consideradas no cálculo do churn.

`GET /v1/analytics/churn`

**Base URL Produção:** `https://api.validapay.com.br`

> Disponível apenas em produção. Esta rota não existe no sandbox: use credenciais e a URL de produção.

## Simulação de consumo de rotas

A página HTML traz o gráfico interativo com as séries MRR, Churn, MRRM, Inadimplência e Assinantes e os filtros Semanal, Mensal, Semestral, Anual e Personalizado.
Os dados vêm das rotas públicas `GET /v1/analytics/demo/...` em `https://api.validapay.com.br`, sem token.
Assinantes usa `activeSubscriptions` de `GET /v1/analytics/demo/mrr`.


**Scopes necessários:** `subscriptions/read`

Valores monetários vêm como string decimal em reais (ex.: `"12345.67"`).

Dias/meses sem evento **não** geram linha. A soma dos dias do mês fecha com o ponto mensal e com `churn.mrr` do summary no mesmo recorte.

Case de uso:

_Como integrador, quero a curva de evolução do churn no tempo e poder cruzar com as demais séries temporais de assinaturas._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `granularity` | não | month (default) ou day |
| `startDate` | não | Início diário YYYY-MM-DD |
| `endDate` | não | Fim diário YYYY-MM-DD |
| `startMonth` | não | Início mensal YYYY-MM |
| `endMonth` | não | Fim mensal YYYY-MM |

### Resposta 200: 200 Diário

```json
{
  "accountId": "460851686",
  "items": [
    { "period": "2026-08-10", "mrr": "149.79", "subscriptionCount": 1, "currency": "BRL" },
    { "period": "2026-08-13", "mrr": "896.98", "subscriptionCount": 2, "currency": "BRL" }
  ]
}
```


### Resposta 200: 200 Mensal

```json
{
  "accountId": "460851686",
  "items": [
    { "period": "2026-08", "mrr": "1046.77", "subscriptionCount": 3, "currency": "BRL" }
  ]
}
```


### Resposta 400: 400 Intervalo de datas inválido

```json
{
  "error": {
    "message": "startDate e endDate devem ser informados juntos",
    "code": "INVALID_DATE_RANGE",
    "details": null,
    "timestamp": "2026-10-10T18:00:00.000Z"
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/get-churn  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json