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

Compras programadas

Lista as compras programadas, vê as entregas dos próximos dias e cancela, pausa, retoma, pula ou recobra uma compra.

Uma compra programada é a reposição agendada de um produto: o cliente escolhe a frequência (semanal, mensal...) e a cada data a plataforma gera um pedido, com o desconto da frequência. Diferente da assinatura, o foco é a entrega do pedido. Há duas origens, e a referência do item diz de qual:

Prefixo	Origem
`sch:<uuid>`	Compra programada criada pela vitrine da loja.
`app:<número>`	Compra programada criada pelo app do cliente.

Use sempre o id que as listagens devolvem. Exigem o módulo recurring-payments; ler exige manage_content ou view_content e agir exige manage_content. Os campos de cada linha são os mesmos de Assinaturas, com kind igual a scheduled.

Listar compras programadas

GET/api/v1/admin/recurring/scheduledAdmin

Lista as compras programadas 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 compras deste produto.

customer_iduuid

Só as compras deste cliente.

next_fromstring

Próxima entrega a partir desta data, YYYY-MM-DD.

next_tostring

Próxima entrega até esta data, YYYY-MM-DD.

overdueboolean

true1

Só as ativas com a próxima entrega já vencida.

sortstring

next

next ordena pela data da próxima entrega.

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

Resposta

200Compras programadas devolvidas

json

{
  "items": [
    {
      "id": "app:1482",
      "kind": "scheduled",
      "status": "active",
      "customer_name": "João Pereira",
      "customer_email": "joao.pereira@example.com",
      "product_name": "Ração Premium 10kg",
      "frequency": "mensal",
      "cycle_days": 30,
      "quantity": 2,
      "price_cents": 18900,
      "price_formatted": "R$ 189,00",
      "next_date": "2026-10-18",
      "retry_count": 0,
      "created_at": "2026-08-18T10:12:40Z",
      "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false }
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campos da resposta

itemsarray

Linhas da página, com os campos descritos em Assinaturas.

paginationobject

page, per_page, total e total_pages.

actions.skipboolean

true quando dá para pular a próxima entrega (só compras programadas ativas).

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

Ver as próximas entregas

Lista as compras programadas ativas com entrega nos próximos dias, da mais próxima para a mais distante. Serve para planejar separação e estoque.

GET/api/v1/admin/recurring/scheduled/upcomingAdmin

Lista as entregas programadas dos próximos dias

Parâmetros de consulta

daysintegerpadrão: 7

Janela a partir de hoje, de 1 a 90. Fora disso vale 7 (abaixo de 1) ou 90 (acima de 90).

Exemplo de requisição

bash

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

Resposta

200Entregas devolvidas

json

{
  "items": [
    {
      "id": "app:1482",
      "kind": "scheduled",
      "status": "active",
      "customer_name": "João Pereira",
      "product_name": "Ração Premium 10kg",
      "quantity": 2,
      "price_cents": 18900,
      "price_formatted": "R$ 189,00",
      "next_date": "2026-10-18"
    }
  ]
}

Campos da resposta

itemsarray

Até 100 linhas, no formato da listagem (o exemplo está abreviado).

Erros

Status	Quando	Corpo
500	Falha de consulta	`{"error":"failed to load recurring data"}`

Consultar uma compra programada

Devolve a linha, as cobranças relacionadas, a linha do tempo e, quando a compra gerou pedidos, o número e o id de cada um em charges.

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

Consulta uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra, com prefixo sch: ou app:.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra programada devolvida

json

{
  "id": "app:1482",
  "kind": "scheduled",
  "status": "active",
  "customer_name": "João Pereira",
  "product_name": "Ração Premium 10kg",
  "frequency": "mensal",
  "cycle_days": 30,
  "quantity": 2,
  "price_cents": 18900,
  "price_formatted": "R$ 189,00",
  "next_date": "2026-10-18",
  "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false },
  "charges": [
    {
      "id": "spc:3301",
      "ref": "app:1482",
      "kind": "scheduled",
      "amount_cents": 18900,
      "amount_formatted": "R$ 189,00",
      "status": "captured",
      "billing_date": "2026-09-18",
      "attempt": 1,
      "order_number": "VND-20260918-482113",
      "order_id": "a5d86a76-7d89-4646-8edc-29447aa2ec37",
      "created_at": "2026-09-18T05:00:09Z",
      "can_retry": false
    }
  ],
  "log": [
    { "at": "2026-08-18T10:12:40Z", "event": "created" },
    { "at": "2026-09-18T05:00:09Z", "event": "charge", "detail": "captured" }
  ]
}

Os campos são os de Assinaturas. Em compras programadas charges[].order_number e charges[].order_id ligam a tentativa ao pedido real que ela criou.

Erros

Status	Quando	Corpo
400	Referência com prefixo certo e sufixo malformado	`{"error":"invalid reference"}`
404	Prefixo diferente de `sch:` e `app:`, ou item inexistente	`{"error":"not found"}`

Cancelar uma compra programada

Encerra a compra. Pedidos já gerados não são afetados.

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

Cancela uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Corpo da requisição (opcional)

reasonstring

Motivo, até 500 bytes. É gravado só nas compras app:; nas sch: o campo é aceito mas descartado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente mudou de endereço" }'

Resposta

200Compra cancelada

json

{
  "id": "app:1482",
  "kind": "scheduled",
  "status": "cancelled",
  "cancellation_reason": "Cliente mudou de endereço",
  "actions": { "cancel": false, "pause": false, "resume": false, "skip": false, "retry": false }
}

Exemplo abreviado; a resposta é o detalhe completo, como na consulta. As demais ações desta página respondem do mesmo jeito.

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra já cancelada	`{"error":"action not allowed in the current status"}`

Pausar uma compra programada

Para as entregas sem cancelar. Só vale para compra active.

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

Pausa uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra pausada

json

{ "id": "app:1482", "kind": "scheduled", "status": "paused", "actions": { "cancel": true, "pause": false, "resume": true, "skip": false, "retry": false } }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `active`	`{"error":"action not allowed in the current status"}`

Retomar uma compra programada

Volta uma compra paused para active. Se a data da próxima entrega já passou, ela passa a ser hoje.

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

Retoma uma compra programada pausada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra retomada

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "next_date": "2026-10-18", "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false } }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `paused`	`{"error":"action not allowed in the current status"}`

Pular a próxima entrega

Empurra a próxima entrega em um ciclo inteiro (cycle_days dias a partir da data atual) sem cancelar nada. Útil quando o cliente avisa que ainda tem estoque em casa. Só vale para compra active; em compras app: o cliente precisa ter a opção de pular habilitada na compra.

POST/api/v1/admin/recurring/scheduled/{id}/skipAdmin

Pula a próxima entrega de uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/skip" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entrega adiada

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "next_date": "2026-11-17" }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `active`, ou `app:` sem permissão de pular	`{"error":"action not allowed in the current status"}`

Pedir nova tentativa de cobrança

Como em assinaturas: reenfileira a compra cuja cobrança falhou e roda o ciclo. Vale somente para compras app:; uma referência sch: nesta rota devolve 404. A compra precisa estar active ou suspended e ter ao menos uma falha (retry_count maior que zero).

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

Pede nova tentativa de cobrança de uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra, obrigatoriamente com prefixo app:.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nova tentativa feita

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "retry_count": 1, "last_charge_error": "card_declined" }

Exemplo abreviado; a resposta é o detalhe lido logo depois da tentativa.

Erros

Status	Quando	Corpo
404	Prefixo diferente de `app:`, ou item inexistente	`{"error":"not found"}`
409	Sem falha para recobrar, ou fora de `active` e `suspended`	`{"error":"action not allowed in the current status"}`

Veja também

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

Compras programadas

Lista as compras programadas, vê as entregas dos próximos dias e cancela, pausa, retoma, pula ou recobra uma compra.

Prefixo	Origem
`sch:<uuid>`	Compra programada criada pela vitrine da loja.
`app:<número>`	Compra programada criada pelo app do cliente.

Listar compras programadas

GET/api/v1/admin/recurring/scheduledAdmin

Lista as compras programadas 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 compras deste produto.

customer_iduuid

Só as compras deste cliente.

next_fromstring

Próxima entrega a partir desta data, YYYY-MM-DD.

next_tostring

Próxima entrega até esta data, YYYY-MM-DD.

overdueboolean

true1

Só as ativas com a próxima entrega já vencida.

sortstring

next

next ordena pela data da próxima entrega.

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

Resposta

200Compras programadas devolvidas

json

{
  "items": [
    {
      "id": "app:1482",
      "kind": "scheduled",
      "status": "active",
      "customer_name": "João Pereira",
      "customer_email": "joao.pereira@example.com",
      "product_name": "Ração Premium 10kg",
      "frequency": "mensal",
      "cycle_days": 30,
      "quantity": 2,
      "price_cents": 18900,
      "price_formatted": "R$ 189,00",
      "next_date": "2026-10-18",
      "retry_count": 0,
      "created_at": "2026-08-18T10:12:40Z",
      "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false }
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Campos da resposta

itemsarray

Linhas da página, com os campos descritos em Assinaturas.

paginationobject

page, per_page, total e total_pages.

actions.skipboolean

true quando dá para pular a próxima entrega (só compras programadas ativas).

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

Ver as próximas entregas

Lista as compras programadas ativas com entrega nos próximos dias, da mais próxima para a mais distante. Serve para planejar separação e estoque.

GET/api/v1/admin/recurring/scheduled/upcomingAdmin

Lista as entregas programadas dos próximos dias

Parâmetros de consulta

daysintegerpadrão: 7

Janela a partir de hoje, de 1 a 90. Fora disso vale 7 (abaixo de 1) ou 90 (acima de 90).

Exemplo de requisição

bash

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

Resposta

200Entregas devolvidas

json

{
  "items": [
    {
      "id": "app:1482",
      "kind": "scheduled",
      "status": "active",
      "customer_name": "João Pereira",
      "product_name": "Ração Premium 10kg",
      "quantity": 2,
      "price_cents": 18900,
      "price_formatted": "R$ 189,00",
      "next_date": "2026-10-18"
    }
  ]
}

Campos da resposta

itemsarray

Até 100 linhas, no formato da listagem (o exemplo está abreviado).

Erros

Status	Quando	Corpo
500	Falha de consulta	`{"error":"failed to load recurring data"}`

Consultar uma compra programada

Devolve a linha, as cobranças relacionadas, a linha do tempo e, quando a compra gerou pedidos, o número e o id de cada um em charges.

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

Consulta uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra, com prefixo sch: ou app:.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra programada devolvida

json

{
  "id": "app:1482",
  "kind": "scheduled",
  "status": "active",
  "customer_name": "João Pereira",
  "product_name": "Ração Premium 10kg",
  "frequency": "mensal",
  "cycle_days": 30,
  "quantity": 2,
  "price_cents": 18900,
  "price_formatted": "R$ 189,00",
  "next_date": "2026-10-18",
  "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false },
  "charges": [
    {
      "id": "spc:3301",
      "ref": "app:1482",
      "kind": "scheduled",
      "amount_cents": 18900,
      "amount_formatted": "R$ 189,00",
      "status": "captured",
      "billing_date": "2026-09-18",
      "attempt": 1,
      "order_number": "VND-20260918-482113",
      "order_id": "a5d86a76-7d89-4646-8edc-29447aa2ec37",
      "created_at": "2026-09-18T05:00:09Z",
      "can_retry": false
    }
  ],
  "log": [
    { "at": "2026-08-18T10:12:40Z", "event": "created" },
    { "at": "2026-09-18T05:00:09Z", "event": "charge", "detail": "captured" }
  ]
}

Os campos são os de Assinaturas. Em compras programadas charges[].order_number e charges[].order_id ligam a tentativa ao pedido real que ela criou.

Erros

Status	Quando	Corpo
400	Referência com prefixo certo e sufixo malformado	`{"error":"invalid reference"}`
404	Prefixo diferente de `sch:` e `app:`, ou item inexistente	`{"error":"not found"}`

Cancelar uma compra programada

Encerra a compra. Pedidos já gerados não são afetados.

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

Cancela uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Corpo da requisição (opcional)

reasonstring

Motivo, até 500 bytes. É gravado só nas compras app:; nas sch: o campo é aceito mas descartado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente mudou de endereço" }'

Resposta

200Compra cancelada

json

{
  "id": "app:1482",
  "kind": "scheduled",
  "status": "cancelled",
  "cancellation_reason": "Cliente mudou de endereço",
  "actions": { "cancel": false, "pause": false, "resume": false, "skip": false, "retry": false }
}

Exemplo abreviado; a resposta é o detalhe completo, como na consulta. As demais ações desta página respondem do mesmo jeito.

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra já cancelada	`{"error":"action not allowed in the current status"}`

Pausar uma compra programada

Para as entregas sem cancelar. Só vale para compra active.

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

Pausa uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra pausada

json

{ "id": "app:1482", "kind": "scheduled", "status": "paused", "actions": { "cancel": true, "pause": false, "resume": true, "skip": false, "retry": false } }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `active`	`{"error":"action not allowed in the current status"}`

Retomar uma compra programada

Volta uma compra paused para active. Se a data da próxima entrega já passou, ela passa a ser hoje.

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

Retoma uma compra programada pausada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Compra retomada

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "next_date": "2026-10-18", "actions": { "cancel": true, "pause": true, "resume": false, "skip": true, "retry": false } }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `paused`	`{"error":"action not allowed in the current status"}`

Pular a próxima entrega

POST/api/v1/admin/recurring/scheduled/{id}/skipAdmin

Pula a próxima entrega de uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra (sch:... ou app:...).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/skip" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entrega adiada

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "next_date": "2026-11-17" }

Erros

Status	Quando	Corpo
404	Prefixo errado ou item inexistente	`{"error":"not found"}`
409	Compra que não está `active`, ou `app:` sem permissão de pular	`{"error":"action not allowed in the current status"}`

Pedir nova tentativa de cobrança

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

Pede nova tentativa de cobrança de uma compra programada

Parâmetros de caminho

idstringobrigatório

Referência da compra, obrigatoriamente com prefixo app:.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/recurring/scheduled/app:1482/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nova tentativa feita

json

{ "id": "app:1482", "kind": "scheduled", "status": "active", "retry_count": 1, "last_charge_error": "card_declined" }

Exemplo abreviado; a resposta é o detalhe lido logo depois da tentativa.

Erros

Status	Quando	Corpo
404	Prefixo diferente de `app:`, ou item inexistente	`{"error":"not found"}`
409	Sem falha para recobrar, ou fora de `active` e `suspended`	`{"error":"action not allowed in the current status"}`