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

Assinaturas recorrentes

Lista, exporta, detalha e cancela as assinaturas dos produtos do seller.

Estas quatro rotas dão ao seller a visão de suas assinaturas (o módulo de pagamentos recorrentes). O seller só vê e cancela: pausar, retomar e repetir cobrança são ações da loja. Para o painel com totais, veja Painel e cobranças.

Referências, não UUIDs

O id devolvido é uma referência com prefixo (sub:...). Guarde-a inteira e use-a no caminho. O prefixo diz de que tabela o registro vem.

Dois sistemas de assinatura

Existe também o sistema mais antigo em /vendor/subscriptions (veja Assinaturas (painel antigo)). São bases diferentes: uma assinatura aparece em apenas um dos dois.

Listar assinaturas

Uma assinatura cobra o cartão salvo do cliente a cada ciclo até ele cancelar. Lista as assinaturas dos produtos do seller com filtros e paginação.

GET/api/v1/vendor/recurring/subscriptionsSeller

Assinaturas 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
activepausedpast_duesuspendedcancelled
Filtra por situação, texto exato.
qstring
Busca parcial em nome ou e-mail do cliente e nome do produto.
product_iduuid
Só deste produto.
customer_iduuid
Só deste cliente.
next_fromstring
Próxima data a partir de, YYYY-MM-DD.
next_tostring
Próxima data até, YYYY-MM-DD.
overdueboolean
1 ou true: só ativas cuja próxima data já passou.
sortstring
next
next ordena pela próxima data; sem isso, mais novas primeiro.
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/subscriptions?status=active&page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinaturas
json
{
  "items": [
    {
      "id": "sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11",
      "kind": "subscription",
      "status": "active",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Café em grãos 1 kg",
      "frequency": "mensal",
      "cycle_days": 30,
      "quantity": 1,
      "price_cents": 4990,
      "price_formatted": "R$ 49,90",
      "next_date": "2026-11-05",
      "last_date": "2026-10-05",
      "card_last_four": "4242",
      "retry_count": 0,
      "created_at": "2026-08-05T12:00:00Z",
      "actions": {
        "cancel": true,
        "pause": false,
        "resume": false,
        "skip": false,
        "retry": false
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Campos da resposta

itemsobject[]

Assinaturas da página.

idstring
Referência opaca do registro: sub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.
kindstring
subscriptionscheduled
Tipo do registro.
statusstring
Situação: assinatura active, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.
customer_namestring
Nome do cliente.
customer_emailstring
E-mail do cliente.
product_namestring
Produto.
frequencystring
Frequência por extenso (semanal, quinzenal, mensal...).
cycle_daysinteger
Dias entre cobranças ou entregas.
quantityinteger
Quantidade por ciclo.
price_centsinteger
Valor do ciclo, em centavos.
price_formattedstring
O mesmo valor formatado, R$ 49,90.
next_datestring
Próxima cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
last_datestring
Última cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
card_last_fourstring
Final do cartão salvo. Omitido se não houver.
cancellation_reasonstring
Motivo do cancelamento. Omitido se vazio.
retry_countinteger
Tentativas de cobrança que falharam no ciclo atual.
last_attempt_atstring
Última tentativa de cobrança, RFC 3339. Omitido se não houve.
suspended_atstring
Quando foi suspensa por falhas seguidas. Omitido se não foi.
created_atstring
Criação, RFC 3339.
actionsobject

Quais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.

cancelboolean
Pode cancelar.
pauseboolean
Pode pausar (só a loja).
resumeboolean
Pode retomar (só a loja).
skipboolean
Pode pular a próxima entrega (só a loja).
retryboolean
Pode repetir a cobrança (só a loja).
paginationobject
Paginação: page, per_page, total, total_pages.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Exportar assinaturas em CSV

Mesmos filtros da listagem (sem page/per_page), até 5.000 linhas. Devolve um arquivo CSV em UTF-8 com BOM, nome assinaturas-AAAAMMDD.csv. Células que começam com =, +, - ou @ recebem um apóstrofo na frente para evitar execução de fórmula no Excel.

GET/api/v1/vendor/recurring/subscriptions/export.csvSeller

Baixar as assinaturas filtradas em CSV

Cabeçalhos

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

Parâmetros de consulta

statusstring
activepausedpast_duesuspendedcancelled
Filtra por situação, texto exato.
qstring
Busca parcial em nome ou e-mail do cliente e nome do produto.
product_iduuid
Só deste produto.
customer_iduuid
Só deste cliente.
next_fromstring
Próxima data a partir de, YYYY-MM-DD.
next_tostring
Próxima data até, YYYY-MM-DD.
overdueboolean
1 ou true: só ativas cuja próxima data já passou.

Exemplo de requisição

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

Resposta

200Arquivo CSV
http
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="assinaturas-20261011.csv"

Cliente,E-mail,Produto,Status,Frequencia,Valor,Proxima cobranca,Ultima cobranca,Criada em
Maria Souza,maria.souza@example.com,Café em grãos 1 kg,active,mensal,"R$ 49,90",2026-11-05,2026-10-05,2026-08-05

Colunas do arquivo

Cliente, E-mail, Produto, Status, Frequencia, Valor, Proxima cobranca, Ultima cobranca, Criada emcsv
Nove colunas, com estes cabeçalhos em português, sem acento. Valor já vem formatado (R$ 49,90).

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Ver assinatura

Devolve a assinatura e, junto, as tentativas de cobrança, a linha do tempo e o termo que o cliente aceitou. Só sub:... serve nesta rota.

GET/api/v1/vendor/recurring/subscriptions/{id}Seller

Assinatura com cobranças e linha do tempo

Cabeçalhos

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

Parâmetros de caminho

idstringobrigatório
Referência sub:<uuid> obtida na listagem. Os dois pontos podem ir como estão.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/recurring/subscriptions/sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Assinatura
json
{
  "id": "sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11",
  "kind": "subscription",
  "status": "active",
  "customer_name": "Maria Souza",
  "customer_email": "maria.souza@example.com",
  "product_name": "Café em grãos 1 kg",
  "frequency": "mensal",
  "cycle_days": 30,
  "quantity": 1,
  "price_cents": 4990,
  "price_formatted": "R$ 49,90",
  "next_date": "2026-11-05",
  "last_date": "2026-10-05",
  "card_last_four": "4242",
  "retry_count": 0,
  "created_at": "2026-08-05T12:00:00Z",
  "actions": {
    "cancel": true,
    "pause": false,
    "resume": false,
    "skip": false,
    "retry": false
  },
  "charges": [
    {
      "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
    }
  ],
  "log": [
    {
      "at": "2026-08-05T12:00:00Z",
      "event": "created"
    }
  ],
  "terms": {
    "name": "Termos de assinatura",
    "version": 2,
    "accepted_at": "2026-08-05T12:00:00Z",
    "ip_address": "203.0.113.10"
  }
}

Campos da resposta

idstring
Referência opaca do registro: sub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.
kindstring
subscriptionscheduled
Tipo do registro.
statusstring
Situação: assinatura active, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.
customer_namestring
Nome do cliente.
customer_emailstring
E-mail do cliente.
product_namestring
Produto.
frequencystring
Frequência por extenso (semanal, quinzenal, mensal...).
cycle_daysinteger
Dias entre cobranças ou entregas.
quantityinteger
Quantidade por ciclo.
price_centsinteger
Valor do ciclo, em centavos.
price_formattedstring
O mesmo valor formatado, R$ 49,90.
next_datestring
Próxima cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
last_datestring
Última cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
card_last_fourstring
Final do cartão salvo. Omitido se não houver.
cancellation_reasonstring
Motivo do cancelamento. Omitido se vazio.
retry_countinteger
Tentativas de cobrança que falharam no ciclo atual.
last_attempt_atstring
Última tentativa de cobrança, RFC 3339. Omitido se não houve.
suspended_atstring
Quando foi suspensa por falhas seguidas. Omitido se não foi.
created_atstring
Criação, RFC 3339.
actionsobject

Quais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.

cancelboolean
Pode cancelar.
pauseboolean
Pode pausar (só a loja).
resumeboolean
Pode retomar (só a loja).
skipboolean
Pode pular a próxima entrega (só a loja).
retryboolean
Pode repetir a cobrança (só a loja).
chargesobject[]

Tentativas de cobrança do registro.

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).
logobject[]
Linha do tempo montada pela plataforma: at, event, detail.
termsobject
Termo aceito na adesão: name, version, accepted_at, ip_address. Omitido se não há.

Erros

StatusQuandoCorpo de exemplo
400Referência malformada (por exemplo sub: com UUID inválido).{"error":"invalid reference"}
404Registro inexistente, de outro seller ou de outro tipo (um sch: na rota de assinaturas).{"error":"not found"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Cancelar assinatura

Cancela a assinatura (cancelled), grava motivo e data, e devolve o registro atualizado. É a única ação que o seller pode fazer sobre assinaturas. Não há reativação por aqui. A cobrança em andamento não é desfeita.

POST/api/v1/vendor/recurring/subscriptions/{id}/cancelSeller

Cancelar uma assinatura do seller

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

idstringobrigatório
Referência sub:<uuid> obtida na listagem. Os dois pontos podem ir como estão.

Corpo da requisição

reasonstring
Motivo do cancelamento, opcional. Cortado em 500 caracteres. Um corpo ausente ou inválido é ignorado.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/recurring/subscriptions/sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Pedido do cliente por telefone."
}'

Resposta

200Assinatura cancelada
json
{
  "id": "sub:5d6b0a4e-7a3a-4a8e-b8b6-2e1f9d0a1c11",
  "kind": "subscription",
  "status": "cancelled",
  "customer_name": "Maria Souza",
  "customer_email": "maria.souza@example.com",
  "product_name": "Café em grãos 1 kg",
  "frequency": "mensal",
  "cycle_days": 30,
  "quantity": 1,
  "price_cents": 4990,
  "price_formatted": "R$ 49,90",
  "next_date": "2026-11-05",
  "last_date": "2026-10-05",
  "card_last_four": "4242",
  "retry_count": 0,
  "created_at": "2026-08-05T12:00:00Z",
  "actions": {
    "cancel": false,
    "pause": false,
    "resume": false,
    "skip": false,
    "retry": false
  },
  "charges": [
    {
      "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
    }
  ],
  "log": [
    {
      "at": "2026-08-05T12:00:00Z",
      "event": "created"
    }
  ],
  "terms": {
    "name": "Termos de assinatura",
    "version": 2,
    "accepted_at": "2026-08-05T12:00:00Z",
    "ip_address": "203.0.113.10"
  },
  "cancellation_reason": "Pedido do cliente por telefone."
}

Campos da resposta

idstring
Referência opaca do registro: sub:<uuid> (assinatura), sch:<uuid> ou app:<número> (compra programada). Use-a como está nas rotas de detalhe e cancelamento.
kindstring
subscriptionscheduled
Tipo do registro.
statusstring
Situação: assinatura active, paused, past_due, suspended, cancelled; compra programada active, paused, cancelled.
customer_namestring
Nome do cliente.
customer_emailstring
E-mail do cliente.
product_namestring
Produto.
frequencystring
Frequência por extenso (semanal, quinzenal, mensal...).
cycle_daysinteger
Dias entre cobranças ou entregas.
quantityinteger
Quantidade por ciclo.
price_centsinteger
Valor do ciclo, em centavos.
price_formattedstring
O mesmo valor formatado, R$ 49,90.
next_datestring
Próxima cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
last_datestring
Última cobrança ou entrega, YYYY-MM-DD. Omitido se não houver.
card_last_fourstring
Final do cartão salvo. Omitido se não houver.
cancellation_reasonstring
Motivo do cancelamento. Omitido se vazio.
retry_countinteger
Tentativas de cobrança que falharam no ciclo atual.
last_attempt_atstring
Última tentativa de cobrança, RFC 3339. Omitido se não houve.
suspended_atstring
Quando foi suspensa por falhas seguidas. Omitido se não foi.
created_atstring
Criação, RFC 3339.
actionsobject

Quais botões fazem sentido. No escopo do seller só cancel pode ser true; pause, resume, skip e retry vêm sempre false.

cancelboolean
Pode cancelar.
pauseboolean
Pode pausar (só a loja).
resumeboolean
Pode retomar (só a loja).
skipboolean
Pode pular a próxima entrega (só a loja).
retryboolean
Pode repetir a cobrança (só a loja).
chargesobject[]

Tentativas de cobrança do registro.

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).
logobject[]
Linha do tempo montada pela plataforma: at, event, detail.
termsobject
Termo aceito na adesão: name, version, accepted_at, ip_address. Omitido se não há.

Erros

StatusQuandoCorpo de exemplo
400Referência malformada.{"error":"invalid reference"}
404Registro inexistente, de outro seller ou de outro tipo (um sch: na rota de assinaturas).{"error":"not found"}
409Já está cancelada.{"error":"action not allowed in the current status"}
401Token ausente, inválido, expirado ou revogado.{"error":"missing authorization header"}
403O 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"}
403O módulo recurring-payments está desligado nesta loja.{"error":"module_disabled","module":"recurring-payments"}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account"}

Veja também

  • Compras programadas
  • Painel e cobranças
  • Visão geral
Anterior
Configuração de compra programada
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
  • Ver assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar assinatura
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também