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

Painel e cobranças

Indicadores de assinatura do seller e o histórico das tentativas de cobrança.

O painel responde "como está minha receita recorrente?" e a lista de cobranças responde "o que foi cobrado e o que falhou?". Ambos são só leitura e limitados aos produtos do seller.

Painel de assinaturas

Reúne os números do painel de assinaturas: receita recorrente (MRR), ativas, pausadas, falhas, cancelamentos, novas por dia, próximas cobranças, atrasadas, produtos campeões, cobranças recentes, divisão por frequência e motivos de cancelamento. Conta só assinaturas, não compras programadas.

GET/api/v1/vendor/recurring/dashboardSeller

Indicadores de assinatura do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

periodstringpadrão: 30d

30d90d12m

Janela de comparação. Qualquer outro valor vale 30d.

product_iduuid

Restringe a um produto.

Exemplo de requisição

bash

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

Resposta

200Painel

json

{
  "available": true,
  "period": "90d",
  "from": "2026-07-13",
  "to": "2026-10-11",
  "cards": {
    "active_count": 12,
    "paused_count": 1,
    "past_due_count": 2,
    "suspended_count": 0,
    "overdue_count": 0,
    "mrr_cents": 59880,
    "mrr_formatted": "R$ 598,80",
    "month_charges": 9,
    "month_revenue_cents": 44910,
    "month_revenue_formatted": "R$ 449,10",
    "pending_charges": 1,
    "pending_amount_cents": 4990,
    "pending_amount_formatted": "R$ 49,90",
    "churn_percent": 6.25,
    "cancelled_in_period": 1,
    "new_subscriptions": 4,
    "new_previous_period": 3,
    "new_growth_percent": 33.3
  },
  "new_series": [
    {
      "bucket": "2026-10-05",
      "new": 1,
      "cancelled": 0
    }
  ],
  "upcoming": [],
  "upcoming_total": 0,
  "overdue": [],
  "overdue_total": 0,
  "top_products": [
    {
      "product_name": "Café em grãos 1 kg",
      "count": 8,
      "mrr_cents": 39920,
      "mrr_formatted": "R$ 399,20"
    }
  ],
  "recent_charges": [],
  "by_plan": [
    {
      "cycle_days": 30,
      "frequency": "mensal",
      "count": 10
    }
  ],
  "cancel_reasons": [
    {
      "reason": "",
      "count": 1
    }
  ]
}

Campos da resposta

availableboolean

false quando a loja nunca usou assinaturas (os demais campos vêm zerados).

periodstring

Janela aplicada.

fromstring

Início, YYYY-MM-DD.

tostring

Fim, YYYY-MM-DD.

cardsobject

Números principais.

active_countinteger

Assinaturas ativas.

paused_countinteger

Pausadas.

past_due_countinteger

Com cobrança falha em nova tentativa.

suspended_countinteger

Suspensas após esgotar as tentativas.

overdue_countinteger

Ativas com data de cobrança já vencida.

mrr_centsinteger

Receita mensal recorrente (MRR) das ativas, em centavos: valor x 30 / dias do ciclo.

mrr_formattedstring

MRR formatado.

month_chargesinteger

Cobranças deste mês.

month_revenue_centsinteger

Receita recebida este mês, em centavos.

month_revenue_formattedstring

Receita do mês formatada.

pending_chargesinteger

Cobranças pendentes.

pending_amount_centsinteger

Valor pendente, em centavos.

pending_amount_formattedstring

Valor pendente formatado.

churn_percentnumber

Cancelamentos do período sobre (ativas + cancelamentos), em %.

cancelled_in_periodinteger

Cancelamentos no período.

new_subscriptionsinteger

Novas no período.

new_previous_periodinteger

Novas no período anterior, do mesmo tamanho.

new_growth_percentnumber|null

Crescimento das novas sobre o período anterior, em %. null se o anterior foi zero.

new_seriesobject[]

Novas e canceladas por dia (por mês em 12m): bucket, new, cancelled.

upcomingobject[]

Próximas cobranças (mesmos campos de uma assinatura).

upcoming_totalinteger

Total de próximas.

overdueobject[]

Atrasadas.

overdue_totalinteger

Total de atrasadas.

top_productsobject[]

Produtos com mais assinaturas: product_name, count, mrr_cents, mrr_formatted.

recent_chargesobject[]

As 8 cobranças mais recentes.

idstring

Id da tentativa de cobrança.

refstring

Referência do registro cobrado (sub:..., sch:..., app:...).

kindstring

Tipo do registro cobrado.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor, em centavos.

amount_formattedstring

Valor formatado.

statusstring

Situação da tentativa: paid, failed, pending (compras programadas também usam captured).

billing_datestring

Dia da cobrança, YYYY-MM-DD.

attemptinteger

Número da tentativa.

order_numberstring

Pedido gerado (compras programadas). Omitido se não há.

order_iduuid

Id do pedido gerado. Omitido se não há.

created_atstring

Criação, RFC 3339.

can_retryboolean

Sempre false para o seller (repetir cobrança é da loja).

by_planobject[]

Ativas por frequência: cycle_days, frequency, count.

cancel_reasonsobject[]

Motivos de cancelamento: reason (vazio = não informado) e count.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Listar cobranças

Lista cada tentativa de cobrança (de assinaturas e de compras programadas) feita nos produtos do seller. O texto de erro do gateway e os ids do gateway ficam ocultos para o seller: só o status é visível.

GET/api/v1/vendor/recurring/chargesSeller

Tentativas de cobrança dos produtos do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring

paidfailedpendingcaptured

Filtra pela situação da tentativa.

refstring

Só tentativas desta referência (sub:..., sch:..., app:...).

product_iduuid

Só deste produto.

customer_iduuid

Só deste cliente.

qstring

Busca parcial em cliente e produto.

date_fromstring

Cobrança a partir de, YYYY-MM-DD.

date_tostring

Cobrança até, YYYY-MM-DD.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Padrão 25.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/recurring/charges?status=failed&date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobranças

json

{
  "items": [
    {
      "id": "c1",
      "ref": "sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11",
      "kind": "subscription",
      "customer_name": "Maria Souza",
      "product_name": "Café em grãos 1 kg",
      "amount_cents": 4990,
      "amount_formatted": "R$ 49,90",
      "status": "paid",
      "billing_date": "2026-10-05",
      "attempt": 1,
      "created_at": "2026-10-05T09:00:00Z",
      "can_retry": false
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Campos da resposta

itemsobject[]

Tentativas da página.

idstring

Id da tentativa de cobrança.

refstring

Referência do registro cobrado (sub:..., sch:..., app:...).

kindstring

Tipo do registro cobrado.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor, em centavos.

amount_formattedstring

Valor formatado.

statusstring

Situação da tentativa: paid, failed, pending (compras programadas também usam captured).

billing_datestring

Dia da cobrança, YYYY-MM-DD.

attemptinteger

Número da tentativa.

order_numberstring

Pedido gerado (compras programadas). Omitido se não há.

order_iduuid

Id do pedido gerado. Omitido se não há.

created_atstring

Criação, RFC 3339.

can_retryboolean

Sempre false para o seller (repetir cobrança é da loja).

paginationobject

Paginação: page, per_page, total, total_pages.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Veja também

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

Painel e cobranças

Indicadores de assinatura do seller e o histórico das tentativas de cobrança.

O painel responde "como está minha receita recorrente?" e a lista de cobranças responde "o que foi cobrado e o que falhou?". Ambos são só leitura e limitados aos produtos do seller.

Painel de assinaturas

GET/api/v1/vendor/recurring/dashboardSeller

Indicadores de assinatura do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

periodstringpadrão: 30d

30d90d12m

Janela de comparação. Qualquer outro valor vale 30d.

product_iduuid

Restringe a um produto.

Exemplo de requisição

bash

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

Resposta

200Painel

json

{
  "available": true,
  "period": "90d",
  "from": "2026-07-13",
  "to": "2026-10-11",
  "cards": {
    "active_count": 12,
    "paused_count": 1,
    "past_due_count": 2,
    "suspended_count": 0,
    "overdue_count": 0,
    "mrr_cents": 59880,
    "mrr_formatted": "R$ 598,80",
    "month_charges": 9,
    "month_revenue_cents": 44910,
    "month_revenue_formatted": "R$ 449,10",
    "pending_charges": 1,
    "pending_amount_cents": 4990,
    "pending_amount_formatted": "R$ 49,90",
    "churn_percent": 6.25,
    "cancelled_in_period": 1,
    "new_subscriptions": 4,
    "new_previous_period": 3,
    "new_growth_percent": 33.3
  },
  "new_series": [
    {
      "bucket": "2026-10-05",
      "new": 1,
      "cancelled": 0
    }
  ],
  "upcoming": [],
  "upcoming_total": 0,
  "overdue": [],
  "overdue_total": 0,
  "top_products": [
    {
      "product_name": "Café em grãos 1 kg",
      "count": 8,
      "mrr_cents": 39920,
      "mrr_formatted": "R$ 399,20"
    }
  ],
  "recent_charges": [],
  "by_plan": [
    {
      "cycle_days": 30,
      "frequency": "mensal",
      "count": 10
    }
  ],
  "cancel_reasons": [
    {
      "reason": "",
      "count": 1
    }
  ]
}

Campos da resposta

availableboolean

false quando a loja nunca usou assinaturas (os demais campos vêm zerados).

periodstring

Janela aplicada.

fromstring

Início, YYYY-MM-DD.

tostring

Fim, YYYY-MM-DD.

cardsobject

Números principais.

active_countinteger

Assinaturas ativas.

paused_countinteger

Pausadas.

past_due_countinteger

Com cobrança falha em nova tentativa.

suspended_countinteger

Suspensas após esgotar as tentativas.

overdue_countinteger

Ativas com data de cobrança já vencida.

mrr_centsinteger

Receita mensal recorrente (MRR) das ativas, em centavos: valor x 30 / dias do ciclo.

mrr_formattedstring

MRR formatado.

month_chargesinteger

Cobranças deste mês.

month_revenue_centsinteger

Receita recebida este mês, em centavos.

month_revenue_formattedstring

Receita do mês formatada.

pending_chargesinteger

Cobranças pendentes.

pending_amount_centsinteger

Valor pendente, em centavos.

pending_amount_formattedstring

Valor pendente formatado.

churn_percentnumber

Cancelamentos do período sobre (ativas + cancelamentos), em %.

cancelled_in_periodinteger

Cancelamentos no período.

new_subscriptionsinteger

Novas no período.

new_previous_periodinteger

Novas no período anterior, do mesmo tamanho.

new_growth_percentnumber|null

Crescimento das novas sobre o período anterior, em %. null se o anterior foi zero.

new_seriesobject[]

Novas e canceladas por dia (por mês em 12m): bucket, new, cancelled.

upcomingobject[]

Próximas cobranças (mesmos campos de uma assinatura).

upcoming_totalinteger

Total de próximas.

overdueobject[]

Atrasadas.

overdue_totalinteger

Total de atrasadas.

top_productsobject[]

Produtos com mais assinaturas: product_name, count, mrr_cents, mrr_formatted.

recent_chargesobject[]

As 8 cobranças mais recentes.

idstring

Id da tentativa de cobrança.

refstring

Referência do registro cobrado (sub:..., sch:..., app:...).

kindstring

Tipo do registro cobrado.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor, em centavos.

amount_formattedstring

Valor formatado.

statusstring

Situação da tentativa: paid, failed, pending (compras programadas também usam captured).

billing_datestring

Dia da cobrança, YYYY-MM-DD.

attemptinteger

Número da tentativa.

order_numberstring

Pedido gerado (compras programadas). Omitido se não há.

order_iduuid

Id do pedido gerado. Omitido se não há.

created_atstring

Criação, RFC 3339.

can_retryboolean

Sempre false para o seller (repetir cobrança é da loja).

by_planobject[]

Ativas por frequência: cycle_days, frequency, count.

cancel_reasonsobject[]

Motivos de cancelamento: reason (vazio = não informado) e count.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`

Listar cobranças

GET/api/v1/vendor/recurring/chargesSeller

Tentativas de cobrança dos produtos do seller

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).

Parâmetros de consulta

statusstring

paidfailedpendingcaptured

Filtra pela situação da tentativa.

refstring

Só tentativas desta referência (sub:..., sch:..., app:...).

product_iduuid

Só deste produto.

customer_iduuid

Só deste cliente.

qstring

Busca parcial em cliente e produto.

date_fromstring

Cobrança a partir de, YYYY-MM-DD.

date_tostring

Cobrança até, YYYY-MM-DD.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 25

Itens por página, de 1 a 100. Padrão 25.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/recurring/charges?status=failed&date_from=2026-10-01" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobranças

json

{
  "items": [
    {
      "id": "c1",
      "ref": "sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11",
      "kind": "subscription",
      "customer_name": "Maria Souza",
      "product_name": "Café em grãos 1 kg",
      "amount_cents": 4990,
      "amount_formatted": "R$ 49,90",
      "status": "paid",
      "billing_date": "2026-10-05",
      "attempt": 1,
      "created_at": "2026-10-05T09:00:00Z",
      "can_retry": false
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Campos da resposta

itemsobject[]

Tentativas da página.

idstring

Id da tentativa de cobrança.

refstring

Referência do registro cobrado (sub:..., sch:..., app:...).

kindstring

Tipo do registro cobrado.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor, em centavos.

amount_formattedstring

Valor formatado.

statusstring

Situação da tentativa: paid, failed, pending (compras programadas também usam captured).

billing_datestring

Dia da cobrança, YYYY-MM-DD.

attemptinteger

Número da tentativa.

order_numberstring

Pedido gerado (compras programadas). Omitido se não há.

order_iduuid

Id do pedido gerado. Omitido se não há.

created_atstring

Criação, RFC 3339.

can_retryboolean

Sempre false para o seller (repetir cobrança é da loja).

paginationobject

Paginação: page, per_page, total, total_pages.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido, expirado ou revogado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador), ou o usuário não está vinculado a nenhum seller.	`{"error":"insufficient permissions"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
403	O usuário não está vinculado a nenhum seller.	`{"error":"no vendor account"}`