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

Compras programadas

Lista, antecipa a agenda, detalha e cancela as compras programadas dos produtos do seller.

Mesma lógica das assinaturas, para o outro tipo de recorrência. O módulo é o mesmo (recurring-payments) e o seller também só vê e cancela.

Estoque

upcoming com days=30 mostra o que vai sair nas próximas entregas. É a base para reabastecer.

Cartão

Compras programadas do tipo app: podem ter cartão salvo (card_last_four); as sch: não têm.

Listar compras programadas

Uma compra programada repete um pedido a cada ciclo, com desconto, sem cartão salvo: a plataforma gera um pedido novo na data. Lista as compras programadas dos produtos do seller.

GET/api/v1/vendor/recurring/scheduledSeller

Compras programadas 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
activepausedcancelled
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/scheduled?status=active&sort=next" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compras programadas
json
{
  "items": [
    {
      "id": "sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22",
      "kind": "scheduled",
      "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",
      "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[]

Compras programadas da página (mesmos campos das assinaturas).

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"}

Próximas entregas

Lista, da mais próxima para a mais distante, as compras programadas ativas com data de entrega entre hoje e daqui a days dias. Máximo de 100 itens, sem paginação. Use para planejar estoque.

GET/api/v1/vendor/recurring/scheduled/upcomingSeller

Compras programadas que vencem nos próximos dias

Cabeçalhos

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

Parâmetros de consulta

daysintegerpadrão: 7
Janela em dias. Menor que 1 vale 7; maior que 90 vale 90.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/recurring/scheduled/upcoming?days=14" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Próximas
json
{
  "items": [
    {
      "id": "sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22",
      "kind": "scheduled",
      "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",
      "retry_count": 0,
      "created_at": "2026-08-05T12:00:00Z",
      "actions": {
        "cancel": true,
        "pause": false,
        "resume": false,
        "skip": false,
        "retry": false
      }
    }
  ]
}

Campos da resposta

itemsobject[]

Compras programadas, mesmos campos da listagem.

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).

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 compra programada

Devolve a compra programada com as tentativas de cobrança (incluindo o pedido gerado em cada ciclo, quando houver) e a linha do tempo.

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

Compra programada 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 sch:<uuid> ou app:<número> obtida na listagem.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/recurring/scheduled/sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra programada
json
{
  "id": "sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22",
  "kind": "scheduled",
  "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",
  "retry_count": 0,
  "created_at": "2026-08-05T12:00:00Z",
  "actions": {
    "cancel": true,
    "pause": false,
    "resume": false,
    "skip": false,
    "retry": false
  },
  "charges": [],
  "log": [
    {
      "at": "2026-08-05T12:00:00Z",
      "event": "created"
    }
  ]
}

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 sub: na rota de compras programadas).{"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 compra programada

Cancela a compra programada. Pedidos já gerados não são afetados. Como nas assinaturas, é a única ação do seller.

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

Cancelar uma compra programada

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 sch:<uuid> ou app:<número> obtida na listagem.

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/scheduled/sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Produto descontinuado."
}'

Resposta

200Compra programada cancelada
json
{
  "id": "sch:8f0d5c32-2b8e-4b27-9a0d-4c4f5a9a7e22",
  "kind": "scheduled",
  "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",
  "retry_count": 0,
  "created_at": "2026-08-05T12:00:00Z",
  "actions": {
    "cancel": true,
    "pause": false,
    "resume": false,
    "skip": false,
    "retry": false
  },
  "charges": [],
  "log": []
}

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 sub: na rota de compras programadas).{"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

  • Assinaturas
  • Configuração
  • Visão geral
Anterior
Assinaturas recorrentes
Próxima
Painel e cobranças
Nesta página
  • Listar compras programadas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Próximas entregas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver compra programada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar compra programada
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também