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

Compras programadas

Cria, lista e cancela recompras programadas com desconto.

A compra programada é mais leve que a assinatura: o cliente escolhe uma frequência e ganha desconto por recomprar. Exige o token do cliente e o módulo recurring-payments.

Listar minhas compras programadas

Devolve todas as compras programadas do cliente, inclusive canceladas. Sem paginação e sem ordem garantida.

GET/api/v1/storefront/recurring/scheduledCliente

Compras programadas do cliente logado

Exemplo de requisição

bash

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

Resposta

200Compras programadas

json

{
  "scheduled": [
    {
      "id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "status": "active",
      "frequency_type": "mensal",
      "cycle_days": 30,
      "discount_bps": 0,
      "next_delivery_date": "2026-11-10T00:00:00Z"
    }
  ]
}

Campos da resposta

scheduledarray

Lista vazia se não há.

iduuid

Id da compra programada.

user_iduuid

O cliente.

product_iduuid

Produto recomprado.

statusstring

activepausedcancelled

Estado.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência.

cycle_daysinteger

Intervalo entre entregas, em dias.

discount_bpsinteger

Desconto registrado na linha, em pontos-base. Pode vir 0 mesmo havendo desconto no preço: não use este campo para calcular valores.

next_delivery_datestring

Próxima entrega (RFC 3339). Ausente se não houver.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`

Programar uma compra

Uma compra programada é a recompra de um produto com desconto, numa frequência escolhida ("receber todo mês"). A primeira entrega fica para cycle_days dias depois. Nada é cobrado nesta chamada.

POST/api/v1/storefront/recurring/scheduledCliente

Cria uma compra programada de um produto

Corpo da requisição

product_iduuidobrigatório

Produto.

cycle_daysintegerpadrão: 30

Intervalo em dias. Zero ou negativo vira 30.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência. Se omitido, é deduzido de cycle_days.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/scheduled" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
    "cycle_days": 30,
    "frequency_type": "mensal"
  }'

Resposta

201Compra programada criada

json

{
  "id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "status": "active",
  "frequency_type": "mensal",
  "cycle_days": 30,
  "discount_bps": 0,
  "next_delivery_date": "2026-11-10T00:00:00Z"
}

Campos da resposta

iduuid

Id da compra programada.

user_iduuid

O cliente.

product_iduuid

Produto recomprado.

statusstring

activepausedcancelled

Estado.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência.

cycle_daysinteger

Intervalo entre entregas, em dias.

discount_bpsinteger

Desconto registrado na linha, em pontos-base. Pode vir 0 mesmo havendo desconto no preço: não use este campo para calcular valores.

next_delivery_datestring

Próxima entrega (RFC 3339). Ausente se não houver.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON válido.	`{"error":"invalid json","detail":"..."}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
400	Produto sem recorrência habilitada ou dados faltando. A causa vem em `detail`.	`{"error":"failed to create scheduled purchase","detail":"recurringpayments: disabled for product"}`

Cancelar uma compra programada

Marca a compra programada como cancelled. O corpo é opcional.

POST/api/v1/storefront/recurring/scheduled/{id}/cancelCliente

Encerra a compra programada do cliente

Parâmetros de caminho

iduuidobrigatório

Id da compra programada.

Corpo da requisição

reasonstring

Aceito, mas não é gravado nas compras programadas.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/scheduled/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Não preciso mais"
  }'

Resposta

200Cancelada

json

{
  "ok": true
}

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
500	`id` que não é um UUID válido, ou falha de gravação.	`{"error":"failed to cancel","detail":"..."}`

Veja também

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

Compras programadas

Cria, lista e cancela recompras programadas com desconto.

A compra programada é mais leve que a assinatura: o cliente escolhe uma frequência e ganha desconto por recomprar. Exige o token do cliente e o módulo recurring-payments.

Listar minhas compras programadas

Devolve todas as compras programadas do cliente, inclusive canceladas. Sem paginação e sem ordem garantida.

GET/api/v1/storefront/recurring/scheduledCliente

Compras programadas do cliente logado

Exemplo de requisição

bash

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

Resposta

200Compras programadas

json

{
  "scheduled": [
    {
      "id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "status": "active",
      "frequency_type": "mensal",
      "cycle_days": 30,
      "discount_bps": 0,
      "next_delivery_date": "2026-11-10T00:00:00Z"
    }
  ]
}

Campos da resposta

scheduledarray

Lista vazia se não há.

iduuid

Id da compra programada.

user_iduuid

O cliente.

product_iduuid

Produto recomprado.

statusstring

activepausedcancelled

Estado.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência.

cycle_daysinteger

Intervalo entre entregas, em dias.

discount_bpsinteger

Desconto registrado na linha, em pontos-base. Pode vir 0 mesmo havendo desconto no preço: não use este campo para calcular valores.

next_delivery_datestring

Próxima entrega (RFC 3339). Ausente se não houver.

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`

Programar uma compra

POST/api/v1/storefront/recurring/scheduledCliente

Cria uma compra programada de um produto

Corpo da requisição

product_iduuidobrigatório

Produto.

cycle_daysintegerpadrão: 30

Intervalo em dias. Zero ou negativo vira 30.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência. Se omitido, é deduzido de cycle_days.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/scheduled" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
    "cycle_days": 30,
    "frequency_type": "mensal"
  }'

Resposta

201Compra programada criada

json

{
  "id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "status": "active",
  "frequency_type": "mensal",
  "cycle_days": 30,
  "discount_bps": 0,
  "next_delivery_date": "2026-11-10T00:00:00Z"
}

Campos da resposta

iduuid

Id da compra programada.

user_iduuid

O cliente.

product_iduuid

Produto recomprado.

statusstring

activepausedcancelled

Estado.

frequency_typestring

semanalquinzenalmensalbimestraltrimestralquadrimestralsemestralanual

Nome da frequência.

cycle_daysinteger

Intervalo entre entregas, em dias.

discount_bpsinteger

Desconto registrado na linha, em pontos-base. Pode vir 0 mesmo havendo desconto no preço: não use este campo para calcular valores.

next_delivery_datestring

Próxima entrega (RFC 3339). Ausente se não houver.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON válido.	`{"error":"invalid json","detail":"..."}`
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
400	Produto sem recorrência habilitada ou dados faltando. A causa vem em `detail`.	`{"error":"failed to create scheduled purchase","detail":"recurringpayments: disabled for product"}`

Cancelar uma compra programada

Marca a compra programada como cancelled. O corpo é opcional.

POST/api/v1/storefront/recurring/scheduled/{id}/cancelCliente

Encerra a compra programada do cliente

Parâmetros de caminho

iduuidobrigatório

Id da compra programada.

Corpo da requisição

reasonstring

Aceito, mas não é gravado nas compras programadas.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/scheduled/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Não preciso mais"
  }'

Resposta

200Cancelada

json

{
  "ok": true
}

Erros

Status	Quando	Corpo de exemplo
401	Sem token de cliente no cabeçalho `Authorization`.	`{"error":"missing authorization header"}`
403	O módulo `recurring-payments` está desligado nesta loja.	`{"error":"module_disabled","module":"recurring-payments"}`
500	`id` que não é um UUID válido, ou falha de gravação.	`{"error":"failed to cancel","detail":"..."}`