Cupons: escrita

Cria, altera e apaga cupons de desconto, com as regras de valor, validade e margem mínima.

Use estas operações para publicar uma campanha vinda de um sistema de marketing, ligar ou desligar um código ou remover um cupom que não vale mais. As três mexem direto no que o cliente enxerga no checkout, então a alteração vale na hora.

Antes de gravar, a plataforma confere o tipo e o valor. Se a loja tem uma margem mínima configurada, também confere se o desconto não leva os produtos de menor margem abaixo dela: nesse caso responde 422 margin_floor.

POST/api/v2/couponsAdmin

Criar um cupom

Cria um cupom. Se code vier vazio, a plataforma gera um código aleatório. O código é guardado em maiúsculas e sem espaços nas pontas.

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT de administrador>.

Content-Typestringobrigatório

application/json.

X-Margin-Overridestring

Token de exceção da margem mínima, emitido pela loja. Sem ele, um desconto que fere a margem é recusado.

Corpo da requisição

typestringobrigatório

fixedpercentagefree_shipping

Tipo do desconto.

valueintegerobrigatório

Em fixed, centavos, maior que zero. Em percentage, pontos-base de 1 a 10000 (1500 = 15%). Em free_shipping é ignorado.

codestring

Código do cupom. Vazio gera um automático. Repetido responde 409.

min_orderintegerpadrão: 0

Pedido mínimo em centavos. 0 é sem mínimo.

max_usesintegerpadrão: 0

Limite total de usos. 0 é ilimitado.

max_per_userintegerpadrão: 0

Limite por cliente. 0 é ilimitado.

starts_atstring

Início da validade (RFC 3339). Omitido vale desde já.

expires_atstring

Fim da validade (RFC 3339). Omitido nunca expira.

is_activebooleanpadrão: true

Se o cupom já nasce ligado.

descriptionstring

Nota interna.

vendor_iduuid

Seller dono do cupom. Omitido cria um cupom da loja inteira.

PUT/api/v2/coupons/{id}Admin

Alterar um cupom

Alteração parcial: só os campos enviados mudam. Os campos têm o mesmo significado da criação.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom.

Corpo da requisição

codestring

Novo código. Repetido responde 409.

typestring

fixedpercentagefree_shipping

Novo tipo. Quando enviado, o par type e value é validado e, se os dois vierem, conferido contra a margem mínima.

valueinteger

Novo valor. Envie sempre junto com type, veja o aviso abaixo.

min_orderinteger

Pedido mínimo em centavos.

max_usesinteger

Limite total de usos.

max_per_userinteger

Limite por cliente.

starts_atstring

Início da validade (RFC 3339).

expires_atstring

Fim da validade (RFC 3339).

is_activeboolean

Liga ou desliga o cupom.

descriptionstring

Nota interna.

vendor_iduuid

Passa o cupom para outro seller.

DELETE/api/v2/coupons/{id}Admin

Apagar um cupom

Apaga o cupom de vez (não há lixeira). Para só impedir novos usos, prefira PUT com "is_active": false.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v2/coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "INVERNO10",
  "type": "percentage",
  "value": 1000,
  "min_order": 5000,
  "max_uses": 100,
  "max_per_user": 1,
  "expires_at": "2026-12-31T23:59:59Z",
  "description": "Campanha de inverno"
}'

Para ligar ou desligar um código:

bash

curl -X PUT "$BASE_URL/api/v2/coupons/79" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "percentage",
  "value": 1000,
  "is_active": false
}'

Resposta

201Cupom criado

json

{
  "data": {
    "id": 80,
    "vendor_id": null,
    "code": "INVERNO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 5000,
    "max_uses": 100,
    "used_count": 0,
    "max_per_user": 1,
    "starts_at": null,
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": true,
    "description": "Campanha de inverno",
    "created_at": "2026-10-11T21:09:59.968204Z",
    "updated_at": "2026-10-11T21:09:59.968204Z"
  }
}

200Cupom alterado

json

{
  "data": {
    "id": 80,
    "vendor_id": null,
    "code": "INVERNO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 5000,
    "max_uses": 100,
    "used_count": 0,
    "max_per_user": 1,
    "starts_at": null,
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": false,
    "description": "Campanha de inverno",
    "created_at": "2026-10-11T21:09:59.968204Z",
    "updated_at": "2026-10-11T21:10:04.318101Z"
  }
}

204Cupom apagado

Sem corpo.

Os campos da resposta são os mesmos de Cupons: consulta.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
400	`type` inválido	`{"error":{"code":"bad_request","message":"invalid voucher type: x (must be fixed, percentage, or free_shipping)"}}`
400	`fixed` com valor zero ou negativo	`{"error":{"code":"bad_request","message":"fixed voucher value must be positive (in centavos)"}}`
400	`percentage` fora de 1 a 10000	`{"error":{"code":"bad_request","message":"percentage voucher value must be 1-10000 basis points (0.01%-100%)"}}`
404	Cupom inexistente (`PUT`, `DELETE`)	`{"error":{"code":"not_found","message":"coupon not found"}}`
409	Código já existe	`{"error":{"code":"conflict","message":"coupon code already exists"}}`
422	Desconto fere a margem mínima	`{"error":{"code":"margin_floor","message":"...","details":{...}}}`

As mensagens de erro desta tabela voltam em inglês, como no servidor.

Veja também

Cupons: escrita

Cria, altera e apaga cupons de desconto, com as regras de valor, validade e margem mínima.

POST/api/v2/couponsAdmin

Criar um cupom

Cria um cupom. Se code vier vazio, a plataforma gera um código aleatório. O código é guardado em maiúsculas e sem espaços nas pontas.

Cabeçalhos

Authorizationstringobrigatório

Bearer <JWT de administrador>.

Content-Typestringobrigatório

application/json.

X-Margin-Overridestring

Token de exceção da margem mínima, emitido pela loja. Sem ele, um desconto que fere a margem é recusado.

Corpo da requisição

typestringobrigatório

fixedpercentagefree_shipping

Tipo do desconto.

valueintegerobrigatório

Em fixed, centavos, maior que zero. Em percentage, pontos-base de 1 a 10000 (1500 = 15%). Em free_shipping é ignorado.

codestring

Código do cupom. Vazio gera um automático. Repetido responde 409.

min_orderintegerpadrão: 0

Pedido mínimo em centavos. 0 é sem mínimo.

max_usesintegerpadrão: 0

Limite total de usos. 0 é ilimitado.

max_per_userintegerpadrão: 0

Limite por cliente. 0 é ilimitado.

starts_atstring

Início da validade (RFC 3339). Omitido vale desde já.

expires_atstring

Fim da validade (RFC 3339). Omitido nunca expira.

is_activebooleanpadrão: true

Se o cupom já nasce ligado.

descriptionstring

Nota interna.

vendor_iduuid

Seller dono do cupom. Omitido cria um cupom da loja inteira.

PUT/api/v2/coupons/{id}Admin

Alterar um cupom

Alteração parcial: só os campos enviados mudam. Os campos têm o mesmo significado da criação.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom.

Corpo da requisição

codestring

Novo código. Repetido responde 409.

typestring

fixedpercentagefree_shipping

Novo tipo. Quando enviado, o par type e value é validado e, se os dois vierem, conferido contra a margem mínima.

valueinteger

Novo valor. Envie sempre junto com type, veja o aviso abaixo.

min_orderinteger

Pedido mínimo em centavos.

max_usesinteger

Limite total de usos.

max_per_userinteger

Limite por cliente.

starts_atstring

Início da validade (RFC 3339).

expires_atstring

Fim da validade (RFC 3339).

is_activeboolean

Liga ou desliga o cupom.

descriptionstring

Nota interna.

vendor_iduuid

Passa o cupom para outro seller.

DELETE/api/v2/coupons/{id}Admin

Apagar um cupom

Apaga o cupom de vez (não há lixeira). Para só impedir novos usos, prefira PUT com "is_active": false.

Parâmetros de caminho

idintegerobrigatório

Id numérico do cupom.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v2/coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "INVERNO10",
  "type": "percentage",
  "value": 1000,
  "min_order": 5000,
  "max_uses": 100,
  "max_per_user": 1,
  "expires_at": "2026-12-31T23:59:59Z",
  "description": "Campanha de inverno"
}'

Para ligar ou desligar um código:

bash

curl -X PUT "$BASE_URL/api/v2/coupons/79" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "percentage",
  "value": 1000,
  "is_active": false
}'

Resposta

201Cupom criado

json

{
  "data": {
    "id": 80,
    "vendor_id": null,
    "code": "INVERNO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 5000,
    "max_uses": 100,
    "used_count": 0,
    "max_per_user": 1,
    "starts_at": null,
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": true,
    "description": "Campanha de inverno",
    "created_at": "2026-10-11T21:09:59.968204Z",
    "updated_at": "2026-10-11T21:09:59.968204Z"
  }
}

200Cupom alterado

json

{
  "data": {
    "id": 80,
    "vendor_id": null,
    "code": "INVERNO10",
    "type": "percentage",
    "value": 1000,
    "min_order": 5000,
    "max_uses": 100,
    "used_count": 0,
    "max_per_user": 1,
    "starts_at": null,
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": false,
    "description": "Campanha de inverno",
    "created_at": "2026-10-11T21:09:59.968204Z",
    "updated_at": "2026-10-11T21:10:04.318101Z"
  }
}

204Cupom apagado

Sem corpo.

Os campos da resposta são os mesmos de Cupons: consulta.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}`
400	`type` inválido	`{"error":{"code":"bad_request","message":"invalid voucher type: x (must be fixed, percentage, or free_shipping)"}}`
400	`fixed` com valor zero ou negativo	`{"error":{"code":"bad_request","message":"fixed voucher value must be positive (in centavos)"}}`
400	`percentage` fora de 1 a 10000	`{"error":{"code":"bad_request","message":"percentage voucher value must be 1-10000 basis points (0.01%-100%)"}}`
404	Cupom inexistente (`PUT`, `DELETE`)	`{"error":{"code":"not_found","message":"coupon not found"}}`
409	Código já existe	`{"error":{"code":"conflict","message":"coupon code already exists"}}`
422	Desconto fere a margem mínima	`{"error":{"code":"margin_floor","message":"...","details":{...}}}`

As mensagens de erro desta tabela voltam em inglês, como no servidor.