VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Cupons, vales, pagamentos e NF-e

Cupons do seller

Cria e gerencia cupons de desconto que valem apenas para os produtos do seller.

Cada seller cria os próprios cupons sem depender do administrador. O cupom nunca desconta itens de outro seller no mesmo carrinho. Não há módulo a ligar: é uma capacidade nativa do seller, mas sub-contas precisam de um privilégio de configurações.

Porcentagem em pontos-base

Para 15% envie value: 1500, não 15. Um value: 15 cria um desconto de 0,15%. Em fixed o valor é em centavos (1200 = R$ 12,00).

Código único na loja inteira

Dois sellers não podem ter o mesmo código. A colisão volta como 400 voucher code ... already exists.

Listar cupons

Um cupom (voucher) é um código que o cliente digita no carrinho para ganhar desconto. Os cupons do seller valem só para os itens dele no carrinho; os da loja inteira são do administrador. Lista todos os cupons do seller, sem paginação.

GET/api/v1/vendor/vouchersSeller

Cupons de desconto do seller

Cabeçalhos

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

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/vouchers" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupons
json
{
  "vouchers": [
    {
      "id": 51,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "code": "BEMVINDO10",
      "type": "fixed",
      "value": 1200,
      "min_order": 5000,
      "max_uses": 10,
      "used_count": 0,
      "max_per_user": 1,
      "starts_at": "2026-10-01T03:00:00Z",
      "expires_at": "2026-12-05T02:59:59Z",
      "is_active": true,
      "description": "Primeira compra",
      "created_at": "2026-10-01T09:17:47Z",
      "updated_at": "2026-10-01T09:21:55Z"
    }
  ],
  "total": 1
}

Campos da resposta

vouchersobject[]

Cupons.

idinteger
Id do cupom (inteiro).
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código que o cliente digita, em maiúsculas. Único em toda a loja.
typestring
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
fixed: centavos. percentage: pontos-base (1500 = 15%). free_shipping: ignorado.
min_orderinteger
Pedido mínimo, em centavos, medido só nos itens deste seller. 0 = sem mínimo.
max_usesinteger
Usos totais permitidos. 0 = ilimitado.
used_countinteger
Quantas vezes já foi usado.
max_per_userinteger
Usos por cliente. 0 = ilimitado.
starts_atstring|null
Início da validade, RFC 3339. null = já vale.
expires_atstring|null
Fim da validade, RFC 3339. null = sem fim.
is_activeboolean
Se o cupom pode ser usado.
descriptionstring
Descrição interna.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Quantidade.

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"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Criar cupom

Cria um cupom do seller. O vendor_id do corpo é ignorado: o cupom é sempre do seller do token.

POST/api/v1/vendor/vouchersSeller

Criar um cupom

Cabeçalhos

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

Corpo da requisição

codestring
Código desejado. Vazio gera um automático. É convertido para maiúsculas.
typestringobrigatório
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
Centavos (fixed, positivo) ou pontos-base (percentage, 1 a 10000). Ignorado em free_shipping.
min_orderintegerpadrão: 0
Pedido mínimo em centavos.
max_usesintegerpadrão: 0
Usos totais.
max_per_userintegerpadrão: 0
Usos por cliente.
starts_atstring
Início, RFC 3339.
expires_atstring
Fim, RFC 3339.
is_activebooleanpadrão: true
Ativo.
descriptionstring
Descrição interna.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/vouchers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "BEMVINDO10",
  "type": "fixed",
  "value": 1200,
  "min_order": 5000,
  "max_uses": 10,
  "max_per_user": 1,
  "expires_at": "2026-12-05T02:59:59Z",
  "description": "Primeira compra"
}'

Resposta

201Cupom criado
json
{
  "id": 51,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "BEMVINDO10",
  "type": "fixed",
  "value": 1200,
  "min_order": 5000,
  "max_uses": 10,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-01T03:00:00Z",
  "expires_at": "2026-12-05T02:59:59Z",
  "is_active": true,
  "description": "Primeira compra",
  "created_at": "2026-10-01T09:17:47Z",
  "updated_at": "2026-10-01T09:21:55Z"
}

Campos da resposta

idinteger
Id do cupom (inteiro).
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código que o cliente digita, em maiúsculas. Único em toda a loja.
typestring
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
fixed: centavos. percentage: pontos-base (1500 = 15%). free_shipping: ignorado.
min_orderinteger
Pedido mínimo, em centavos, medido só nos itens deste seller. 0 = sem mínimo.
max_usesinteger
Usos totais permitidos. 0 = ilimitado.
used_countinteger
Quantas vezes já foi usado.
max_per_userinteger
Usos por cliente. 0 = ilimitado.
starts_atstring|null
Início da validade, RFC 3339. null = já vale.
expires_atstring|null
Fim da validade, RFC 3339. null = sem fim.
is_activeboolean
Se o cupom pode ser usado.
descriptionstring
Descrição interna.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400Regra violada. O texto do error diz qual: tipo inválido, valor fixed não positivo, percentage fora de 1 a 10000, código já existente. Textos em inglês.{"error":"voucher code 'BEMVINDO10' already exists"}
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"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Ver cupom

Devolve um cupom do seller.

GET/api/v1/vendor/vouchers/{id}Seller

Detalhe de um cupom

Cabeçalhos

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

Parâmetros de caminho

idintegerobrigatório
Id do cupom (inteiro). Texto dá 400 invalid voucher id.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/vouchers/51" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupom
json
{
  "id": 51,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "BEMVINDO10",
  "type": "fixed",
  "value": 1200,
  "min_order": 5000,
  "max_uses": 10,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-01T03:00:00Z",
  "expires_at": "2026-12-05T02:59:59Z",
  "is_active": true,
  "description": "Primeira compra",
  "created_at": "2026-10-01T09:17:47Z",
  "updated_at": "2026-10-01T09:21:55Z"
}

Campos da resposta

idinteger
Id do cupom (inteiro).
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código que o cliente digita, em maiúsculas. Único em toda a loja.
typestring
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
fixed: centavos. percentage: pontos-base (1500 = 15%). free_shipping: ignorado.
min_orderinteger
Pedido mínimo, em centavos, medido só nos itens deste seller. 0 = sem mínimo.
max_usesinteger
Usos totais permitidos. 0 = ilimitado.
used_countinteger
Quantas vezes já foi usado.
max_per_userinteger
Usos por cliente. 0 = ilimitado.
starts_atstring|null
Início da validade, RFC 3339. null = já vale.
expires_atstring|null
Fim da validade, RFC 3339. null = sem fim.
is_activeboolean
Se o cupom pode ser usado.
descriptionstring
Descrição interna.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400id não é inteiro.{"error":"invalid voucher id"}
404O cupom não existe ou não é seu.{"error":"voucher 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"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Atualizar cupom

Altera só os campos enviados. Você não consegue apagar starts_at nem expires_at por aqui (enviar nada mantém o valor) nem mudar o dono. Se mandar type, mande também value: sem ele o valor é tratado como zero e a validação recusa.

PUT/api/v1/vendor/vouchers/{id}Seller

Alterar um cupom

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

idintegerobrigatório
Id do cupom (inteiro). Texto dá 400 invalid voucher id.

Corpo da requisição

codestring
Novo código. Não envie vazio: o código ficaria vazio. É convertido para maiúsculas.
typestring
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
Centavos (fixed, positivo) ou pontos-base (percentage, 1 a 10000). Ignorado em free_shipping.
min_orderinteger
Pedido mínimo em centavos.
max_usesinteger
Usos totais.
max_per_userinteger
Usos por cliente.
starts_atstring
Início, RFC 3339.
expires_atstring
Fim, RFC 3339.
is_activeboolean
Ativo.
descriptionstring
Descrição interna.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/vouchers/51" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "is_active": false
}'

Resposta

200Cupom atualizado
json
{
  "id": 51,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "code": "BEMVINDO10",
  "type": "fixed",
  "value": 1200,
  "min_order": 5000,
  "max_uses": 10,
  "used_count": 0,
  "max_per_user": 1,
  "starts_at": "2026-10-01T03:00:00Z",
  "expires_at": "2026-12-05T02:59:59Z",
  "is_active": false,
  "description": "Primeira compra",
  "created_at": "2026-10-01T09:17:47Z",
  "updated_at": "2026-10-01T09:21:55Z"
}

Campos da resposta

idinteger
Id do cupom (inteiro).
vendor_iduuid
Seller dono. Sempre o seu.
codestring
Código que o cliente digita, em maiúsculas. Único em toda a loja.
typestring
fixedpercentagefree_shipping
Tipo do desconto.
valueinteger
fixed: centavos. percentage: pontos-base (1500 = 15%). free_shipping: ignorado.
min_orderinteger
Pedido mínimo, em centavos, medido só nos itens deste seller. 0 = sem mínimo.
max_usesinteger
Usos totais permitidos. 0 = ilimitado.
used_countinteger
Quantas vezes já foi usado.
max_per_userinteger
Usos por cliente. 0 = ilimitado.
starts_atstring|null
Início da validade, RFC 3339. null = já vale.
expires_atstring|null
Fim da validade, RFC 3339. null = sem fim.
is_activeboolean
Se o cupom pode ser usado.
descriptionstring
Descrição interna.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo de exemplo
400id não inteiro, JSON inválido ou regra violada (mesmos textos da criação).{"error":"fixed voucher value must be positive (in centavos)"}
404O cupom não existe ou não é seu.{"error":"voucher 42 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"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Excluir cupom

Apaga o cupom de vez. Pedidos já feitos com ele não mudam. Para só parar de aceitar, use PUT com is_active: false.

DELETE/api/v1/vendor/vouchers/{id}Seller

Excluir um cupom

Cabeçalhos

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

Parâmetros de caminho

idintegerobrigatório
Id do cupom (inteiro). Texto dá 400 invalid voucher id.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/vouchers/51" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cupom excluído
json
{
  "message": "voucher deleted"
}

Erros

StatusQuandoCorpo de exemplo
400id não é inteiro.{"error":"invalid voucher id"}
404O cupom não existe ou não é seu.{"error":"voucher 42 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"}
403Sub-conta do seller sem nenhum dos privilégios de configurações (a lista completa vem em privilege_required_any; o exemplo está cortado). O dono da loja passa sempre.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings"]}
403O usuário não está vinculado a nenhum seller.{"error":"no vendor account associated with this user"}

Veja também

  • Vales-presente
  • Visão geral
Anterior
Cupons, vales, pagamentos e NF-e
Próxima
Vales-presente do seller
Nesta página
  • Listar cupons
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar cupom
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver cupom
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar cupom
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir cupom
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também