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

Cobranças recorrentes

Lista as tentativas de cobrança de assinaturas e compras programadas, refaz uma que falhou e roda o ciclo de cobrança sob demanda.

Cada vez que a plataforma tenta cobrar um ciclo, ela registra uma tentativa de cobrança: quanto, de quem, se foi paga ou falhou e por quê. Estas rotas mostram esse histórico e deixam você refazer uma cobrança que falhou ou disparar o ciclo à mão. Exigem o módulo recurring-payments; ler exige manage_content ou view_content e agir exige manage_content.

Listar cobranças

Devolve as tentativas, das mais novas para as mais antigas, com paginação.

GET/api/v1/admin/recurring/chargesAdmin

Lista as tentativas de cobrança recorrente

Parâmetros de consulta

statusstring

paidcapturedfailedpending

Filtra pelo status da tentativa. paid é o status de assinatura e captured o de compra programada.

refstring

Só as tentativas de um item, pela referência dele (sub:..., sch:..., app:...).

product_iduuid

Só as tentativas deste produto.

customer_iduuid

Só as tentativas deste cliente.

qstring

Busca por nome do cliente, e-mail ou produto.

date_fromstring

Data da cobrança a partir de, YYYY-MM-DD.

date_tostring

Data da 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.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/charges?status=failed&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobranças devolvidas

json

{
  "items": [
    {
      "id": "hist:7c1d9e22-5b3a-4f68-8a10-2d4e6a3c1b99",
      "ref": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
      "kind": "subscription",
      "customer_name": "Maria Souza",
      "product_name": "Café Especial 500g",
      "amount_cents": 4200,
      "amount_formatted": "R$ 42,00",
      "status": "failed",
      "billing_date": "2026-10-20",
      "attempt": 2,
      "error": "card_declined",
      "gateway_charge_id": "ch_Z1dxXYKcNWcnw547",
      "gateway_order_id": "or_zOoLYy3HZf58m1Rj",
      "created_at": "2026-10-21T05:00:07Z",
      "can_retry": true
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campos da resposta

itemsarray

Tentativas da página.

paginationobject

page, per_page, total e total_pages.

idstring

Referência da tentativa. Prefixo hist: (assinatura) ou spc: (compra programada). É o que a nova tentativa recebe.

refstring

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

kindstring

subscriptionscheduled

Tipo do item.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor da tentativa, em centavos.

amount_formattedstring

Valor em reais (R$ 42,00).

statusstring

paidcapturedfailedpending

Resultado: paid e captured são dinheiro recebido.

billing_datestring

Data a que o ciclo se refere, YYYY-MM-DD.

attemptinteger

Número da tentativa dentro do ciclo (1, 2, 3...).

errorstring

Motivo da falha, como veio do gateway. Ausente quando não falhou.

order_numberstring

Número do pedido criado pela tentativa. Só em compra programada.

order_iduuid

Id do pedido criado. Só em compra programada.

gateway_charge_idstring

Cobrança no gateway (ch_...). Ausente quando a tentativa nem chegou ao gateway.

gateway_order_idstring

Pedido no gateway (or_...).

created_atstring

Quando a tentativa aconteceu, RFC 3339.

can_retryboolean

true quando dá para refazer esta cobrança.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio ou módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"failed to load recurring data"}`

Refazer uma cobrança que falhou

Reenfileira o item cobrado e roda o ciclo uma vez. Atenção ao que não acontece: a tentativa antiga não é reexecutada. O ciclo faz uma tentativa nova, com o número seguinte, e a antiga continua no histórico como failed. A tentativa informada precisa estar com status failed.

POST/api/v1/admin/recurring/charges/{id}/retryAdmin

Refaz uma cobrança recorrente que falhou

Parâmetros de caminho

idstringobrigatório

Referência da tentativa, como na listagem: hist:<uuid> (assinatura) ou spc:<número> (compra programada).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/charges/hist:7c1d9e22-5b3a-4f68-8a10-2d4e6a3c1b99/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobrança reenfileirada

json

{ "ok": true, "queued": true }

Campos da resposta

okboolean

true quando o pedido foi aceito.

queuedboolean

true: o item foi reenfileirado. O resultado da cobrança aparece depois na listagem, como uma tentativa nova.

Erros

Status	Quando	Corpo
400	Referência sem prefixo `hist:` ou `spc:`, ou com sufixo inválido	`{"error":"invalid reference"}`
404	A tentativa não existe	`{"error":"not found"}`
409	A tentativa não está `failed`, ou o item não tem falha para recobrar	`{"error":"action not allowed in the current status"}`

Rodar o ciclo de cobrança agora

Executa uma passada do mesmo processo automático que cobra o que venceu, só para esta loja. É seguro apertar duas vezes ou sobrepor ao agendamento: o ciclo usa travas por tentativa e no máximo uma nova tentativa por dia para itens com falha, então um ciclo nunca é cobrado em dobro.

POST/api/v1/admin/recurring/process-dueAdmin

Roda o ciclo de cobrança recorrente agora

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/process-due" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ciclo executado

json

{ "ok": true }

A resposta só confirma que a passada rodou. O resultado de cada cobrança aparece na listagem. A rota registra a ação no histórico de atividade da loja.

Erros

Status	Quando	Corpo
503	O processo de cobrança não está disponível neste servidor	`{"error":"cycle worker unavailable"}`
500	Falha na passada	`{"error":"failed to process"}`

Veja também

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

Cobranças recorrentes

Lista as tentativas de cobrança de assinaturas e compras programadas, refaz uma que falhou e roda o ciclo de cobrança sob demanda.

Listar cobranças

Devolve as tentativas, das mais novas para as mais antigas, com paginação.

GET/api/v1/admin/recurring/chargesAdmin

Lista as tentativas de cobrança recorrente

Parâmetros de consulta

statusstring

paidcapturedfailedpending

Filtra pelo status da tentativa. paid é o status de assinatura e captured o de compra programada.

refstring

Só as tentativas de um item, pela referência dele (sub:..., sch:..., app:...).

product_iduuid

Só as tentativas deste produto.

customer_iduuid

Só as tentativas deste cliente.

qstring

Busca por nome do cliente, e-mail ou produto.

date_fromstring

Data da cobrança a partir de, YYYY-MM-DD.

date_tostring

Data da 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.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/charges?status=failed&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobranças devolvidas

json

{
  "items": [
    {
      "id": "hist:7c1d9e22-5b3a-4f68-8a10-2d4e6a3c1b99",
      "ref": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
      "kind": "subscription",
      "customer_name": "Maria Souza",
      "product_name": "Café Especial 500g",
      "amount_cents": 4200,
      "amount_formatted": "R$ 42,00",
      "status": "failed",
      "billing_date": "2026-10-20",
      "attempt": 2,
      "error": "card_declined",
      "gateway_charge_id": "ch_Z1dxXYKcNWcnw547",
      "gateway_order_id": "or_zOoLYy3HZf58m1Rj",
      "created_at": "2026-10-21T05:00:07Z",
      "can_retry": true
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campos da resposta

itemsarray

Tentativas da página.

paginationobject

page, per_page, total e total_pages.

idstring

Referência da tentativa. Prefixo hist: (assinatura) ou spc: (compra programada). É o que a nova tentativa recebe.

refstring

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

kindstring

subscriptionscheduled

Tipo do item.

customer_namestring

Cliente.

product_namestring

Produto.

amount_centsinteger

Valor da tentativa, em centavos.

amount_formattedstring

Valor em reais (R$ 42,00).

statusstring

paidcapturedfailedpending

Resultado: paid e captured são dinheiro recebido.

billing_datestring

Data a que o ciclo se refere, YYYY-MM-DD.

attemptinteger

Número da tentativa dentro do ciclo (1, 2, 3...).

errorstring

Motivo da falha, como veio do gateway. Ausente quando não falhou.

order_numberstring

Número do pedido criado pela tentativa. Só em compra programada.

order_iduuid

Id do pedido criado. Só em compra programada.

gateway_charge_idstring

Cobrança no gateway (ch_...). Ausente quando a tentativa nem chegou ao gateway.

gateway_order_idstring

Pedido no gateway (or_...).

created_atstring

Quando a tentativa aconteceu, RFC 3339.

can_retryboolean

true quando dá para refazer esta cobrança.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio ou módulo desligado	`{"error":"module_disabled","module":"recurring-payments"}`
500	Falha de consulta	`{"error":"failed to load recurring data"}`

Refazer uma cobrança que falhou

POST/api/v1/admin/recurring/charges/{id}/retryAdmin

Refaz uma cobrança recorrente que falhou

Parâmetros de caminho

idstringobrigatório

Referência da tentativa, como na listagem: hist:<uuid> (assinatura) ou spc:<número> (compra programada).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/charges/hist:7c1d9e22-5b3a-4f68-8a10-2d4e6a3c1b99/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cobrança reenfileirada

json

{ "ok": true, "queued": true }

Campos da resposta

okboolean

true quando o pedido foi aceito.

queuedboolean

true: o item foi reenfileirado. O resultado da cobrança aparece depois na listagem, como uma tentativa nova.

Erros

Status	Quando	Corpo
400	Referência sem prefixo `hist:` ou `spc:`, ou com sufixo inválido	`{"error":"invalid reference"}`
404	A tentativa não existe	`{"error":"not found"}`
409	A tentativa não está `failed`, ou o item não tem falha para recobrar	`{"error":"action not allowed in the current status"}`

Rodar o ciclo de cobrança agora

POST/api/v1/admin/recurring/process-dueAdmin

Roda o ciclo de cobrança recorrente agora

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/process-due" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ciclo executado

json

{ "ok": true }

A resposta só confirma que a passada rodou. O resultado de cada cobrança aparece na listagem. A rota registra a ação no histórico de atividade da loja.

Erros

Status	Quando	Corpo
503	O processo de cobrança não está disponível neste servidor	`{"error":"cycle worker unavailable"}`
500	Falha na passada	`{"error":"failed to process"}`