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

Assinaturas

Cria, lista e cancela assinaturas de produtos.

Assinatura é o produto que o cliente recebe e paga a cada ciclo até cancelar (um plano de café, um refil). Exige o token do cliente e o módulo recurring-payments. Para uma recompra com desconto, sem cobrança automática, veja Compras programadas.

Listar minhas assinaturas

Devolve todas as assinaturas do cliente, inclusive canceladas, da mais nova para a mais antiga. Sem paginação.

GET/api/v1/storefront/recurring/subscriptionsCliente

Assinaturas do cliente logado

Exemplo de requisição

bash

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

Resposta

200Assinaturas

json

{
  "subscriptions": [
    {
      "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "status": "active",
      "cycle_days": 30,
      "price_cents": 2241,
      "next_billing_date": "2026-11-10T00:00:00Z"
    }
  ]
}

Campos da resposta

subscriptionsarray

Lista vazia se não há assinaturas.

iduuid

Id da assinatura.

user_iduuid

O cliente assinante.

vendor_iduuid

Seller do produto. Ausente se o produto não tem seller.

product_iduuid

Produto assinado.

statusstring

activepausedcancelled

Estado da assinatura.

cycle_daysinteger

Intervalo entre cobranças, em dias.

price_centsinteger

Preço de cada ciclo, em centavos, já com o desconto do ciclo.

next_billing_datestring

Próxima cobrança (RFC 3339). Ausente se não houver.

card_last_fourstring

Últimos 4 dígitos do cartão salvo da assinatura, quando há.

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

Assinar um produto

Uma assinatura cobra o cliente automaticamente a cada cycle_days. Ao criar, a plataforma confere se o produto aceita recorrência, calcula o preço do ciclo com o desconto da frequência, agenda a primeira cobrança para cycle_days dias depois e registra o aceite dos termos vigentes. Nada é cobrado nesta chamada.

POST/api/v1/storefront/recurring/subscriptionsCliente

Cria uma assinatura com cobrança a cada ciclo

Corpo da requisição

product_iduuidobrigatório

Produto a assinar.

cycle_daysintegerpadrão: 30

Intervalo em dias. Valores da tabela de frequências: 7, 14 (ou 15), 30, 60, 90, 120, 180, 365. Zero ou negativo vira 30.

price_centsinteger

Preço base por ciclo, em centavos, antes do desconto. Se omitido ou 0, usa o preço atual do produto. Prefira omitir.

Exemplo de requisição

bash

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

Resposta

201Assinatura criada

json

{
  "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "status": "active",
  "cycle_days": 30,
  "price_cents": 2241,
  "next_billing_date": "2026-11-10T00:00:00Z"
}

Campos da resposta

iduuid

Id da assinatura.

user_iduuid

O cliente assinante.

vendor_iduuid

Seller do produto. Ausente se o produto não tem seller.

product_iduuid

Produto assinado.

statusstring

activepausedcancelled

Estado da assinatura.

cycle_daysinteger

Intervalo entre cobranças, em dias.

price_centsinteger

Preço de cada ciclo, em centavos, já com o desconto do ciclo.

next_billing_datestring

Próxima cobrança (RFC 3339). Ausente se não houver.

card_last_fourstring

Últimos 4 dígitos do cartão salvo da assinatura, quando há.

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, desabilitada para o produto, ou dados faltando. A causa vem em `detail`.	`{"error":"failed to create subscription","detail":"recurringpayments: disabled for product"}`

Cancelar uma assinatura

Marca a assinatura como cancelled, com um motivo opcional, e para as cobranças futuras. Só atinge assinaturas do próprio cliente.

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

Encerra a assinatura do cliente

Parâmetros de caminho

iduuidobrigatório

Id da assinatura.

Corpo da requisição

reasonstring

Motivo do cancelamento. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/subscriptions/6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Estoque cheio, volto a pedir em dezembro"
  }'

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

Assinaturas

Cria, lista e cancela assinaturas de produtos.

Listar minhas assinaturas

Devolve todas as assinaturas do cliente, inclusive canceladas, da mais nova para a mais antiga. Sem paginação.

GET/api/v1/storefront/recurring/subscriptionsCliente

Assinaturas do cliente logado

Exemplo de requisição

bash

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

Resposta

200Assinaturas

json

{
  "subscriptions": [
    {
      "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
      "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "status": "active",
      "cycle_days": 30,
      "price_cents": 2241,
      "next_billing_date": "2026-11-10T00:00:00Z"
    }
  ]
}

Campos da resposta

subscriptionsarray

Lista vazia se não há assinaturas.

iduuid

Id da assinatura.

user_iduuid

O cliente assinante.

vendor_iduuid

Seller do produto. Ausente se o produto não tem seller.

product_iduuid

Produto assinado.

statusstring

activepausedcancelled

Estado da assinatura.

cycle_daysinteger

Intervalo entre cobranças, em dias.

price_centsinteger

Preço de cada ciclo, em centavos, já com o desconto do ciclo.

next_billing_datestring

Próxima cobrança (RFC 3339). Ausente se não houver.

card_last_fourstring

Últimos 4 dígitos do cartão salvo da assinatura, quando há.

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

Assinar um produto

POST/api/v1/storefront/recurring/subscriptionsCliente

Cria uma assinatura com cobrança a cada ciclo

Corpo da requisição

product_iduuidobrigatório

Produto a assinar.

cycle_daysintegerpadrão: 30

Intervalo em dias. Valores da tabela de frequências: 7, 14 (ou 15), 30, 60, 90, 120, 180, 365. Zero ou negativo vira 30.

price_centsinteger

Preço base por ciclo, em centavos, antes do desconto. Se omitido ou 0, usa o preço atual do produto. Prefira omitir.

Exemplo de requisição

bash

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

Resposta

201Assinatura criada

json

{
  "id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "user_id": "e0d4f8a1-5b2c-4d7e-9a31-6c8f0b2d4e6a",
  "vendor_id": "7c1e5d3a-2b4f-4a6e-9c8d-1f0a3b5c7d9e",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "status": "active",
  "cycle_days": 30,
  "price_cents": 2241,
  "next_billing_date": "2026-11-10T00:00:00Z"
}

Campos da resposta

iduuid

Id da assinatura.

user_iduuid

O cliente assinante.

vendor_iduuid

Seller do produto. Ausente se o produto não tem seller.

product_iduuid

Produto assinado.

statusstring

activepausedcancelled

Estado da assinatura.

cycle_daysinteger

Intervalo entre cobranças, em dias.

price_centsinteger

Preço de cada ciclo, em centavos, já com o desconto do ciclo.

next_billing_datestring

Próxima cobrança (RFC 3339). Ausente se não houver.

card_last_fourstring

Últimos 4 dígitos do cartão salvo da assinatura, quando há.

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, desabilitada para o produto, ou dados faltando. A causa vem em `detail`.	`{"error":"failed to create subscription","detail":"recurringpayments: disabled for product"}`

Cancelar uma assinatura

Marca a assinatura como cancelled, com um motivo opcional, e para as cobranças futuras. Só atinge assinaturas do próprio cliente.

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

Encerra a assinatura do cliente

Parâmetros de caminho

iduuidobrigatório

Id da assinatura.

Corpo da requisição

reasonstring

Motivo do cancelamento. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/recurring/subscriptions/6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Estoque cheio, volto a pedir em dezembro"
  }'

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