API atual/Referência completa/Assinaturas e compras programadas

Painel de assinaturas

Indicadores das assinaturas da loja: receita mensal recorrente, cancelamentos, próximas cobranças, atrasos e produtos que mais assinam.

O painel resume a saúde da recorrência em uma chamada: quantas assinaturas estão ativas, quanto elas rendem por mês (MRR, receita mensal recorrente), quantas foram canceladas (churn), o que vence nos próximos dias e o que está atrasado. Os números do painel contam assinaturas; as compras programadas aparecem nas listas próprias. Exige o módulo recurring-payments e o privilégio manage_content ou view_content.

Ler o painel

GET/api/v1/admin/recurring/dashboardAdmin

Indicadores das assinaturas da loja

Parâmetros de consulta

periodstringpadrão: 30d

30d90d12m

Janela de comparação para novos e cancelamentos e para a série. Qualquer outro valor vira 30d.

product_iduuid

Restringe todos os números a um produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/dashboard?period=30d" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Painel devolvido

json

{
  "available": true,
  "period": "30d",
  "from": "2026-09-11",
  "to": "2026-10-11",
  "cards": {
    "active_count": 42,
    "paused_count": 3,
    "past_due_count": 2,
    "suspended_count": 1,
    "overdue_count": 1,
    "mrr_cents": 189900,
    "mrr_formatted": "R$ 1.899,00",
    "month_charges": 18,
    "month_revenue_cents": 98400,
    "month_revenue_formatted": "R$ 984,00",
    "pending_charges": 4,
    "pending_amount_cents": 21600,
    "pending_amount_formatted": "R$ 216,00",
    "churn_percent": 4.5,
    "cancelled_in_period": 2,
    "new_subscriptions": 9,
    "new_previous_period": 6,
    "new_growth_percent": 50
  },
  "new_series": [
    { "bucket": "2026-10-01", "new": 2, "cancelled": 0 }
  ],
  "upcoming": [],
  "upcoming_total": 0,
  "overdue": [],
  "overdue_total": 0,
  "top_products": [
    { "product_name": "Café Especial 500g", "count": 14, "mrr_cents": 58800, "mrr_formatted": "R$ 588,00" }
  ],
  "recent_charges": [],
  "by_plan": [
    { "cycle_days": 30, "frequency": "mensal", "count": 30 }
  ],
  "cancel_reasons": [
    { "reason": "Preço", "count": 1 }
  ],
  "by_vendor": [
    {
      "vendor_name": "Torrefação Serra Azul",
      "active_count": 20,
      "paused_count": 1,
      "mrr_cents": 90000,
      "mrr_formatted": "R$ 900,00",
      "month_revenue_cents": 48000,
      "month_revenue_formatted": "R$ 480,00"
    }
  ]
}

Campos da resposta

availableboolean

false quando a loja nunca usou assinaturas (as tabelas ainda não existem). Nesse caso os demais campos vêm zerados ou vazios.

periodstring

30d90d12m

Janela aplicada.

fromstring

Início da janela, YYYY-MM-DD.

tostring

Fim da janela (hoje), YYYY-MM-DD.

cards.active_countinteger

Assinaturas ativas.

cards.paused_countinteger

Assinaturas pausadas.

cards.past_due_countinteger

Ativas com cobrança que falhou e em nova tentativa.

cards.suspended_countinteger

Suspensas depois de esgotar as tentativas.

cards.overdue_countinteger

Ativas com a data de cobrança já vencida.

cards.mrr_centsinteger

Receita mensal recorrente, em centavos: cada assinatura ativa normalizada para 30 dias (price_cents * 30 / cycle_days).

cards.mrr_formattedstring

mrr_cents formatado em reais.

cards.month_chargesinteger

Cobranças com data neste mês.

cards.month_revenue_centsinteger

Valor cobrado e pago neste mês, em centavos.

cards.month_revenue_formattedstring

month_revenue_cents formatado.

cards.pending_chargesinteger

Cobranças pendentes.

cards.pending_amount_centsinteger

Soma das pendentes, em centavos.

cards.pending_amount_formattedstring

Soma das pendentes formatada.

cards.churn_percentnumber

Cancelados no período divididos por (ativas + cancelados no período), em porcentagem.

cards.cancelled_in_periodinteger

Cancelamentos na janela.

cards.new_subscriptionsinteger

Assinaturas criadas na janela.

cards.new_previous_periodinteger

Criadas na janela anterior de mesmo tamanho.

cards.new_growth_percentnumber

Crescimento de novas assinaturas sobre a janela anterior, em porcentagem. null quando a janela anterior teve zero.

new_seriesarray

Série de novas e canceladas: bucket (YYYY-MM-DD, o dia, ou o primeiro dia do mês quando o período é 12m), new e cancelled.

upcomingarray

Até 8 assinaturas ativas com cobrança nos próximos 7 dias, no formato de linha das listas.

upcoming_totalinteger

Total de assinaturas nessa condição.

overduearray

Até 8 assinaturas ativas com a cobrança vencida.

overdue_totalinteger

Total de vencidas.

top_productsarray

Até 5 produtos com mais assinaturas ativas: product_name, count, mrr_cents, mrr_formatted.

recent_chargesarray

Até 8 tentativas de cobrança mais recentes, no formato de Cobranças.

by_planarray

Assinaturas ativas por ciclo: cycle_days, frequency e count.

cancel_reasonsarray

Até 8 motivos de cancelamento na janela, com reason (vazio quando não informado) e count.

by_vendorarray

Por seller (só no painel do administrador): vendor_name, active_count, paused_count, mrr_cents, mrr_formatted, month_revenue_cents e month_revenue_formatted.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio	`{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}`
403	Módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"failed to load recurring data"}`

Veja também

Painel de assinaturas

Indicadores das assinaturas da loja: receita mensal recorrente, cancelamentos, próximas cobranças, atrasos e produtos que mais assinam.

Ler o painel

GET/api/v1/admin/recurring/dashboardAdmin

Indicadores das assinaturas da loja

Parâmetros de consulta

periodstringpadrão: 30d

30d90d12m

Janela de comparação para novos e cancelamentos e para a série. Qualquer outro valor vira 30d.

product_iduuid

Restringe todos os números a um produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/dashboard?period=30d" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Painel devolvido

json

{
  "available": true,
  "period": "30d",
  "from": "2026-09-11",
  "to": "2026-10-11",
  "cards": {
    "active_count": 42,
    "paused_count": 3,
    "past_due_count": 2,
    "suspended_count": 1,
    "overdue_count": 1,
    "mrr_cents": 189900,
    "mrr_formatted": "R$ 1.899,00",
    "month_charges": 18,
    "month_revenue_cents": 98400,
    "month_revenue_formatted": "R$ 984,00",
    "pending_charges": 4,
    "pending_amount_cents": 21600,
    "pending_amount_formatted": "R$ 216,00",
    "churn_percent": 4.5,
    "cancelled_in_period": 2,
    "new_subscriptions": 9,
    "new_previous_period": 6,
    "new_growth_percent": 50
  },
  "new_series": [
    { "bucket": "2026-10-01", "new": 2, "cancelled": 0 }
  ],
  "upcoming": [],
  "upcoming_total": 0,
  "overdue": [],
  "overdue_total": 0,
  "top_products": [
    { "product_name": "Café Especial 500g", "count": 14, "mrr_cents": 58800, "mrr_formatted": "R$ 588,00" }
  ],
  "recent_charges": [],
  "by_plan": [
    { "cycle_days": 30, "frequency": "mensal", "count": 30 }
  ],
  "cancel_reasons": [
    { "reason": "Preço", "count": 1 }
  ],
  "by_vendor": [
    {
      "vendor_name": "Torrefação Serra Azul",
      "active_count": 20,
      "paused_count": 1,
      "mrr_cents": 90000,
      "mrr_formatted": "R$ 900,00",
      "month_revenue_cents": 48000,
      "month_revenue_formatted": "R$ 480,00"
    }
  ]
}

Campos da resposta

availableboolean

false quando a loja nunca usou assinaturas (as tabelas ainda não existem). Nesse caso os demais campos vêm zerados ou vazios.

periodstring

30d90d12m

Janela aplicada.

fromstring

Início da janela, YYYY-MM-DD.

tostring

Fim da janela (hoje), YYYY-MM-DD.

cards.active_countinteger

Assinaturas ativas.

cards.paused_countinteger

Assinaturas pausadas.

cards.past_due_countinteger

Ativas com cobrança que falhou e em nova tentativa.

cards.suspended_countinteger

Suspensas depois de esgotar as tentativas.

cards.overdue_countinteger

Ativas com a data de cobrança já vencida.

cards.mrr_centsinteger

Receita mensal recorrente, em centavos: cada assinatura ativa normalizada para 30 dias (price_cents * 30 / cycle_days).

cards.mrr_formattedstring

mrr_cents formatado em reais.

cards.month_chargesinteger

Cobranças com data neste mês.

cards.month_revenue_centsinteger

Valor cobrado e pago neste mês, em centavos.

cards.month_revenue_formattedstring

month_revenue_cents formatado.

cards.pending_chargesinteger

Cobranças pendentes.

cards.pending_amount_centsinteger

Soma das pendentes, em centavos.

cards.pending_amount_formattedstring

Soma das pendentes formatada.

cards.churn_percentnumber

Cancelados no período divididos por (ativas + cancelados no período), em porcentagem.

cards.cancelled_in_periodinteger

Cancelamentos na janela.

cards.new_subscriptionsinteger

Assinaturas criadas na janela.

cards.new_previous_periodinteger

Criadas na janela anterior de mesmo tamanho.

cards.new_growth_percentnumber

Crescimento de novas assinaturas sobre a janela anterior, em porcentagem. null quando a janela anterior teve zero.

new_seriesarray

Série de novas e canceladas: bucket (YYYY-MM-DD, o dia, ou o primeiro dia do mês quando o período é 12m), new e cancelled.

upcomingarray

Até 8 assinaturas ativas com cobrança nos próximos 7 dias, no formato de linha das listas.

upcoming_totalinteger

Total de assinaturas nessa condição.

overduearray

Até 8 assinaturas ativas com a cobrança vencida.

overdue_totalinteger

Total de vencidas.

top_productsarray

Até 5 produtos com mais assinaturas ativas: product_name, count, mrr_cents, mrr_formatted.

recent_chargesarray

Até 8 tentativas de cobrança mais recentes, no formato de Cobranças.

by_planarray

Assinaturas ativas por ciclo: cycle_days, frequency e count.

cancel_reasonsarray

Até 8 motivos de cancelamento na janela, com reason (vazio quando não informado) e count.

by_vendorarray

Por seller (só no painel do administrador): vendor_name, active_count, paused_count, mrr_cents, mrr_formatted, month_revenue_cents e month_revenue_formatted.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio	`{"error":"insufficient privileges","privilege_required_any":["manage_content","view_content"]}`
403	Módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"failed to load recurring data"}`