Resumos

Assinaturas

Consulte o resumo da sua carteira de assinaturas e acompanhe assinaturas ativas, novas assinaturas, inadimplência, churn, recebidos, etc. Todas as métricas do resumo respondem ao filtro de data.

GET/v1/analytics/subscriptions/summary

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.

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

O que vem

Os parâmetros de início e fim (campos startDate e endDate) indicam o período da consulta. Sem as duas datas, será considerado o mês atual.
O período anterior e o respectivo crescimento relativo (campos previousPeriod e growth) apenas são retornados quando as datas de início e fim são enviadas; caso contrário, são null.
O campo growth.* = (atual − anterior) / anterior, com 4 casas, indica o crescimento em relação ao mesmo período anterior, ou null se o anterior for zero.

Para que serve

Resumo de assinaturas e KPIs de carteira
Comparar o período atual com o mês anterior via growth

Case de uso:

Como integrador, quero exibir o resumo da minha carteira de assinaturas sem montar agregações a partir dos ciclos e cobranças.

Resumos

Simulação de cards de assinaturas

A rota descrita nesta seção permite montar cards de resumos no seu painel, conforme a simulação abaixo.

Carregando resumo demo…

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

subscriptions/read

Query Parameters

startDateopcional

Início do período (YYYY-MM-DD). Envie junto com endDate

2026-09-01

endDateopcional

Fim do período (YYYY-MM-DD). Envie junto com startDate

2026-09-30

productIdopcional

Filtra cards de período/ciclos pelo produto

priceIdopcional

Filtra cards de período/ciclos pelo plano

paymentTypeopcional

PIX | BOLETO | CREDIT_CARD | PIX_AUTOMATICO

← Anterior

Desfazer cancelamento agendado

Cobranças

const url = 'https://api.validapay.com.br/v1/analytics/subscriptions/summary?startDate=2026-09-01&endDate=2026-09-30';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200▾

JSON

{
  "accountId": "474267606", 
  "startDate": "2026-09-01", 
  "endDate": "2026-09-30", 
  "asOfDate": "2026-09-30", 
  "totalPeriod": {
    "cycleCount": 85, 
    "netAmount": "42000.00" 
  },
  "received": {
    "cycleCount": 62,
    "netAmount": "38500.00"
  },
  "overdue": {
    "cycleCount": 12,
    "netAmount": "4800.00"
  },
  "dueToday": {
    "cycleCount": 5,
    "netAmount": "2100.00"
  },
  "upcoming": {
    "cycleCount": 38,
    "netAmount": "45200.00"
  },
  "activeSubscriptions": 156, 
  "mrr": "12345.67", 
  "arr": "148148.04", 
  "mrrAsOf": "2026-09-30", 
  "delinquentMrr": "2100.00", 
  "delinquentSubscriptions": 9,
  "newSubscriptions": 8,
  "canceledSubscriptions": 3,
  "churn": {
    "subscriptionCount": 1,
    "mrr": "149.79"
  },
  "previousPeriod": {
    "startDate": "2026-08-01",
    "endDate": "2026-08-30",
    "mrrAsOf": "2026-08-30",
    "mrr": "10000.00",
    "arr": "120000.00",
    "activeSubscriptions": 150,
    "newSubscriptions": 10,
    "churn": { "subscriptionCount": 2, "mrr": "100.00" },
    "delinquentMrr": "2000.00",
    "delinquentSubscriptions": 10
  },
  "growth": {
    "mrr": 0.2346,
    "activeSubscriptions": 0.04,
    "newSubscriptions": -0.2,
    "churn": { "subscriptionCount": -0.5, "mrr": 0.4979 },
    "delinquentMrr": 0.05,
    "delinquentSubscriptions": -0.1
  },
  "collectionRate": "0.72",
  "overdueAmount": "4800.00",
  "statusBreakdown": {
    "items": [
      {
        "status": "PAID",
        "cycleCount": 62,
        "netAmount": "38500.00",
        "percentage": "72.94"
      },
      {
        "status": "AWAITING_PAYMENT",
        "cycleCount": 23,
        "netAmount": "3500.00",
        "percentage": "27.06"
      }
    ]
  },
  "paymentMethodBreakdown": {
    "items": [
      { "paymentType": "PIX", "cycleCount": 52, "netAmount": "28000.00" },
      { "paymentType": "CREDIT_CARD", "cycleCount": 28, "netAmount": "11000.00" },
      { "paymentType": "BOLETO", "cycleCount": 5, "netAmount": "3000.00" }
    ]
  },
  "planBreakdown": {
    "items": [
      { "priceId": "price_pro", "planTitle": "Plano Pro", "cycleCount": 60, "netAmount": "32000.00" },
      { "priceId": "price_basic", "planTitle": "Plano Básico", "cycleCount": 25, "netAmount": "10000.00" }
    ]
  }
}

Campos da resposta

accountIdstring

Conta resolvida pelo token

startDatestring

Início do período pedido

endDatestring

Fim do período pedido

asOfDatestring

Referência dos snapshots de recebíveis

totalPeriodobject

receivedobject

overdueobject

dueTodayobject

upcomingobject

activeSubscriptionsnumber

Estoque ACTIVE em mrrAsOf

mrrstring

MRR ACTIVE em mrrAsOf

arrstring

mrr * 12

mrrAsOfstring

LEAST(endDate, hoje BRT)

delinquentMrrstring

Estoque overdue inteiro em mrrAsOf

delinquentSubscriptionsnumber

newSubscriptionsnumber

canceledSubscriptionsnumber

churnobject

previousPeriodobject

growthobject

collectionRatestring

overdueAmountstring

statusBreakdownobject

paymentMethodBreakdownobject

planBreakdownobject

400Intervalo 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"
  }
}

403Conta diferente do token▾

JSON

{
  "error": {
    "message": "accountId diferente da conta do token",
    "code": "ACCOUNT_OVERRIDE_FORBIDDEN",
    "details": null,
    "timestamp": "2026-10-10T18:00:00.000Z"
  }
}

← Anterior

Desfazer cancelamento agendado

Cobranças