VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Assinaturas e compras programadas

Assinaturas

Lista, exporta e consulta assinaturas e as cancela, pausa, retoma ou recobra quando a cobrança falhou.

Uma assinatura é a cobrança recorrente de um produto para um cliente, a cada cycle_days dias. Estas rotas mostram todas as assinaturas da loja e permitem agir sobre cada uma. Todas identificam o item pela referência com prefixo sub: (por exemplo sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10), exatamente como vem no campo id das listagens. Exigem o módulo recurring-payments; ler exige manage_content ou view_content e agir exige manage_content.

Listar assinaturas

Devolve as assinaturas, das mais novas para as mais antigas (ou pela próxima cobrança, com sort=next), com paginação.

GET/api/v1/admin/recurring/subscriptionsAdmin

Lista as assinaturas da loja

Parâmetros de consulta

statusstring
activepausedsuspendedcancelled
Filtra pelo status exato.
qstring
Busca por trecho do nome ou e-mail do cliente ou do nome do produto.
product_iduuid
Só as assinaturas deste produto.
customer_iduuid
Só as assinaturas deste cliente.
next_fromstring
Próxima cobrança a partir desta data, YYYY-MM-DD. Data inválida é ignorada.
next_tostring
Próxima cobrança até esta data, YYYY-MM-DD. Data inválida é ignorada.
overdueboolean
true1
Só as ativas com a próxima cobrança já vencida.
sortstring
next
next ordena pela data da próxima cobrança (mais próxima primeiro).
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 25
Itens por página, de 1 a 100. Acima de 100 vale 100.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/recurring/subscriptions?status=active&sort=next&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinaturas devolvidas
json
{
  "items": [
    {
      "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
      "kind": "subscription",
      "status": "active",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Café Especial 500g",
      "vendor_name": "Torrefação Serra Azul",
      "frequency": "mensal",
      "cycle_days": 30,
      "quantity": 1,
      "price_cents": 4200,
      "price_formatted": "R$ 42,00",
      "next_date": "2026-10-20",
      "last_date": "2026-09-20",
      "card_last_four": "4242",
      "retry_count": 0,
      "created_at": "2026-06-20T14:05:11Z",
      "actions": { "cancel": true, "pause": true, "resume": false, "skip": false, "retry": false }
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campos da resposta

itemsarray
Linhas da página.
paginationobject
page, per_page, total e total_pages.
idstring
Referência com prefixo. Use-a nas demais rotas.
kindstring
subscriptionscheduled
Tipo da linha. Aqui sempre subscription.
statusstring
activepausedsuspendedcancelled
Estado da assinatura.
customer_namestring
Nome do cliente.
customer_emailstring
E-mail do cliente.
product_namestring
Produto assinado.
vendor_namestring
Seller do produto. Só no painel do administrador.
frequencystring
Chave da frequência (mensal, semanal...), derivada de cycle_days.
cycle_daysinteger
Dias entre cobranças.
quantityinteger
Unidades por ciclo.
price_centsinteger
Valor de cada cobrança, em centavos, já com o desconto contratado.
price_formattedstring
price_cents em reais (R$ 42,00).
next_datestring
Próxima cobrança, YYYY-MM-DD. Ausente quando não há.
last_datestring
Última cobrança, YYYY-MM-DD. Ausente quando ainda não houve.
card_last_fourstring
Últimos 4 dígitos do cartão guardado. Ausente quando não há.
cancellation_reasonstring
Motivo informado ao cancelar. Ausente quando não há.
retry_countinteger
Quantas tentativas de cobrança já falharam seguidas.
last_attempt_atstring
Quando foi a última tentativa, RFC 3339.
last_charge_errorstring
Motivo da última falha de cobrança (texto do gateway).
suspended_atstring
Quando foi suspensa, RFC 3339.
created_atstring
Criação, RFC 3339.
actionsobject
Quais ações fazem sentido agora: cancel, pause, resume, skip e retry. Use para ligar ou desligar botões.

Erros

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

Loja que nunca usou assinaturas devolve 200 com items vazio, não erro.

Exportar assinaturas em CSV

Baixa até 5.000 assinaturas que casam com os mesmos filtros da listagem (sem paginação), para planilha.

GET/api/v1/admin/recurring/subscriptions/export.csvAdmin

Exporta as assinaturas em CSV

Parâmetros de consulta

statusstring
activepausedsuspendedcancelled
Filtra pelo status.
qstring
Busca por cliente ou produto.
product_iduuid
Só este produto.
customer_iduuid
Só este cliente.
next_fromstring
Próxima cobrança a partir de, YYYY-MM-DD.
next_tostring
Próxima cobrança até, YYYY-MM-DD.
overdueboolean
true1
Só as vencidas.
sortstring
next
Ordena pela próxima cobrança.

Exemplo de requisição

bash
curl -o assinaturas.csv "$BASE_URL/api/v1/admin/recurring/subscriptions/export.csv?status=active" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivo CSV
text
Cliente,E-mail,Produto,Status,Frequencia,Valor,Proxima cobranca,Ultima cobranca,Criada em
Maria Souza,maria.souza@example.com,Café Especial 500g,active,mensal,R$ 42,00,2026-10-20,2026-09-20,2026-06-20

O arquivo é UTF-8 com BOM, separado por vírgula, com Content-Disposition: attachment; filename="assinaturas-AAAAMMDD.csv". Células que começam com =, +, - ou @ recebem um apóstrofo na frente para não virarem fórmula na planilha. O cabeçalho é em português, sem acentos.

Erros

StatusQuandoCorpo
500Falha de consulta{"error":"failed to load recurring data"}
Valor com vírgula dentro do CSV

A coluna Valor vem como R$ 42,00, que contém vírgula; ela vem entre aspas no arquivo, e qualquer leitor de CSV a interpreta certo. Se você mesmo corta as linhas por vírgula, use um leitor de CSV de verdade.

Consultar uma assinatura

Devolve a linha da assinatura mais o histórico de cobranças, uma linha do tempo e o termo que o cliente aceitou.

GET/api/v1/admin/recurring/subscriptions/{id}Admin

Consulta uma assinatura

Parâmetros de caminho

idstringobrigatório
Referência da assinatura, com o prefixo sub:.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/recurring/subscriptions/sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinatura devolvida
json
{
  "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
  "kind": "subscription",
  "status": "active",
  "customer_name": "Maria Souza",
  "customer_email": "maria.souza@example.com",
  "product_name": "Café Especial 500g",
  "frequency": "mensal",
  "cycle_days": 30,
  "quantity": 1,
  "price_cents": 4200,
  "price_formatted": "R$ 42,00",
  "next_date": "2026-10-20",
  "last_date": "2026-09-20",
  "card_last_four": "4242",
  "retry_count": 0,
  "created_at": "2026-06-20T14:05:11Z",
  "actions": { "cancel": true, "pause": true, "resume": false, "skip": false, "retry": false },
  "charges": [
    {
      "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": "paid",
      "billing_date": "2026-09-20",
      "attempt": 1,
      "created_at": "2026-09-20T05:00:07Z",
      "can_retry": false
    }
  ],
  "log": [
    { "at": "2026-06-20T14:05:11Z", "event": "created" },
    { "at": "2026-09-20T05:00:07Z", "event": "charge", "detail": "paid" }
  ],
  "terms": { "name": "Termo de assinatura", "version": 2, "accepted_at": "2026-06-20T14:05:11Z", "ip_address": "203.0.113.10" }
}

Campos da resposta

chargesarray
Até 100 tentativas de cobrança desta assinatura. Veja os campos em Cobranças.
logarray
Linha do tempo montada a partir dos dados: at, event (created, charge, suspended, cancelled) e detail. Não é um registro de auditoria: o evento cancelled usa a data de criação da assinatura.
termsobject
Termo aceito: name, version, accepted_at e ip_address. Ausente quando não há aceite registrado.

Os demais campos são os da linha da listagem.

Erros

StatusQuandoCorpo
400Referência malformada (sufixo que não é UUID){"error":"invalid reference"}
404Prefixo diferente de sub:, ou assinatura que não existe{"error":"not found"}
Codifique os dois pontos no caminho

A referência contém :. Servidores e bibliotecas aceitam, mas se o seu cliente reclamar, codifique o id (sub%3A5f0c...): a plataforma decodifica antes de usar.

Cancelar uma assinatura

Encerra a assinatura. Cobranças futuras deixam de acontecer; o que já foi cobrado não é devolvido por aqui.

POST/api/v1/admin/recurring/subscriptions/{id}/cancelAdmin

Cancela uma assinatura

Parâmetros de caminho

idstringobrigatório
Referência da assinatura (sub:...).

Corpo da requisição (opcional)

reasonstring
Motivo do cancelamento, até 500 bytes (o excedente é cortado). Aparece em cancellation_reason e nos motivos do painel.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/recurring/subscriptions/sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Pedido do cliente por telefone" }'

Resposta

200Assinatura cancelada
json
{
  "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
  "kind": "subscription",
  "status": "cancelled",
  "cancellation_reason": "Pedido do cliente por telefone",
  "customer_name": "Maria Souza",
  "product_name": "Café Especial 500g",
  "frequency": "mensal",
  "cycle_days": 30,
  "price_cents": 4200,
  "price_formatted": "R$ 42,00",
  "actions": { "cancel": false, "pause": false, "resume": false, "skip": false, "retry": false },
  "charges": [],
  "log": [
    { "at": "2026-06-20T14:05:11Z", "event": "created" },
    { "at": "2026-06-20T14:05:11Z", "event": "cancelled", "detail": "Pedido do cliente por telefone" }
  ]
}

A resposta é o detalhe da assinatura já atualizado, no formato da consulta (abreviado no exemplo). As ações de pausar, retomar e cancelar seguem o mesmo formato de resposta e de erros.

Erros

StatusQuandoCorpo
400Referência malformada{"error":"invalid reference"}
404Prefixo errado ou assinatura inexistente{"error":"not found"}
409Assinatura já cancelada{"error":"action not allowed in the current status"}

Pausar uma assinatura

Para as cobranças sem cancelar. Só vale para assinatura active.

POST/api/v1/admin/recurring/subscriptions/{id}/pauseAdmin

Pausa uma assinatura

Parâmetros de caminho

idstringobrigatório
Referência da assinatura (sub:...).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/recurring/subscriptions/sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinatura pausada
json
{
  "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
  "kind": "subscription",
  "status": "paused",
  "next_date": "2026-10-20",
  "actions": { "cancel": true, "pause": false, "resume": true, "skip": false, "retry": false }
}

Exemplo abreviado; a resposta traz o detalhe completo.

Erros

StatusQuandoCorpo
404Prefixo errado ou assinatura inexistente{"error":"not found"}
409Assinatura que não está active{"error":"action not allowed in the current status"}

Retomar uma assinatura

Volta uma assinatura paused para active. Se a data da próxima cobrança já passou, ela passa a ser hoje, para não cobrar retroativamente vários ciclos.

POST/api/v1/admin/recurring/subscriptions/{id}/resumeAdmin

Retoma uma assinatura pausada

Parâmetros de caminho

idstringobrigatório
Referência da assinatura (sub:...).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/recurring/subscriptions/sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinatura retomada
json
{
  "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
  "kind": "subscription",
  "status": "active",
  "next_date": "2026-10-11",
  "actions": { "cancel": true, "pause": true, "resume": false, "skip": false, "retry": false }
}

Exemplo abreviado; a resposta traz o detalhe completo.

Erros

StatusQuandoCorpo
404Prefixo errado ou assinatura inexistente{"error":"not found"}
409Assinatura que não está paused{"error":"action not allowed in the current status"}

Pedir nova tentativa de cobrança

Reenfileira uma assinatura cuja cobrança falhou e já roda o ciclo de cobrança uma vez, então a tentativa acontece na hora. A assinatura precisa estar active ou suspended e ter ao menos uma falha (retry_count maior que zero). Uma assinatura suspended volta a active só para essa tentativa. O contador de falhas não é zerado: se falhar de novo e o limite já estava esgotado, ela é suspensa outra vez.

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

Pede nova tentativa de cobrança de uma assinatura

Parâmetros de caminho

idstringobrigatório
Referência da assinatura (sub:...).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/recurring/subscriptions/sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nova tentativa feita
json
{
  "id": "sub:5f0c1a52-8d7e-4c1b-9a64-2b5e7d9c1a10",
  "kind": "subscription",
  "status": "active",
  "retry_count": 2,
  "last_charge_error": "card_declined",
  "actions": { "cancel": true, "pause": true, "resume": false, "skip": false, "retry": true }
}

Exemplo abreviado. A resposta é o detalhe lido logo depois da tentativa; veja charges e retry_count para saber se deu certo.

Erros

StatusQuandoCorpo
404Prefixo errado ou assinatura inexistente{"error":"not found"}
409Sem falha para recobrar, ou fora de active e suspended{"error":"action not allowed in the current status"}
A tentativa pode não ser imediata

A chamada reenfileira o item e tenta rodar o ciclo na hora. Se o ciclo de cobrança não estiver disponível no servidor que atendeu a chamada, a cobrança acontece no próximo ciclo automático, e a resposta 200 só confirma que o item foi reenfileirado. Confira charges e retry_count depois de alguns instantes antes de repetir.

Veja também

  • Cobranças
  • Compras programadas
  • Painel
Anterior
Painel de assinaturas
Próxima
Compras programadas
Nesta página
  • Listar assinaturas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar assinaturas em CSV
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar uma assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pausar uma assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Retomar uma assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Pedir nova tentativa de cobrança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também