API atual/Referência completa/Promoções e cupons

Alterar e excluir promoção

Altera campos de uma promoção existente e a exclui de forma lógica.

O PUT é parcial: envie só os campos que mudam. Campo ausente, null ou vazio quer dizer "não mexer". A exceção é "code": null, que remove o código. Para pausar uma promoção envie {"status":"inactive"}; para reativá-la, {"status":"active"} (a reativação confere de novo se produtos e categorias citados ainda existem).

O DELETE é lógico: a promoção sai da lista e deixa de descontar, mas o registro de pedidos antigos que a usaram continua intacto, e o código dela volta a ficar livre para outra promoção. Uma promoção já excluída não é restaurada por edição.

Alterar uma promoção

PUT/api/v1/admin/promotions/{id}Admin

Altera campos de uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Cabeçalhos

X-Margin-Overridestring

Token de exceção do Protetor de Margem, quando a oferta foi aprovada fora do piso.

Parâmetros de consulta

confirm_store_widebooleanpadrão: false

Envie true para confirmar que uma promoção de catálogo sem produto nem categoria deve valer para a loja toda.

Corpo da requisição

namestring

Novo nome.

typestring

Novo tipo. Mesma lista da criação.

discountinteger

Pontos-base em percentage (1000 = 10%, máximo 10000), centavos em fixed. Nunca negativo. Pode ser 0 em free_shipping e buy_x_get_y.

descriptionstring

Descrição livre.

codestring

Novo código (vira maiúsculo). Envie null para remover o código e tornar a promoção automática.

max_discountinteger

Teto do desconto em centavos.

priorityinteger

Ordem de avaliação; menor primeiro.

stop_other_rulesboolean

Interrompe a avaliação das promoções seguintes.

stackableboolean

Pode se combinar com outras acumuláveis.

conditionsobject

Condições simples. Veja a home da seção.

condition_groupsobject

Condições aninhadas E/OU.

bonusesarray

Lista de bônus: [{"bonus_type":"order_discount","config":{"discount_type":"by_percentage","discount_value":1000}}].

bonus_typestring

Bônus único (formato antigo).

bonus_configobject

Configuração do bônus único (formato antigo).

free_shipping_method_iduuid

Forma de envio que recebe frete grátis (tipo free_shipping).

usage_limitinteger

Máximo de usos no total. 0 = sem limite.

per_user_limitinteger

Máximo de usos por cliente.

valid_fromstring (RFC 3339)

Início da vigência. Se omitido, vale a partir de agora.

valid_untilstring (RFC 3339)

Fim da vigência. Se omitido, não expira.

statusstring

activeinactivedisabledexpireddraftADE

active, inactive/disabled, expired, draft (vira inativa) ou a letra. Vazio vira ativa.

zonestring

cartcatalog

cart ou catalog. Veja como o padrão é escolhido na home da seção.

vendor_iduuid

Atribui a promoção a um seller. Omita para promoção da loja.

descriptionsobject

Textos por idioma: mapa de código de idioma (pt-BR, en) para um objeto com o nome e a descrição traduzidos. Idiomas ausentes herdam name e description.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": 1500,
    "valid_until": "2026-12-01T23:59:59-03:00"
  }'

Resposta: alterar

200Promoção alterada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "name": "Black Friday 10% nas camisas",
  "description": "",
  "type": "percentage",
  "code": "BLACK10",
  "discount": 1500,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 0,
  "valid_from": "2026-11-27T03:00:00Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "condition_groups": null,
  "bonus_type": null,
  "bonus_config": null,
  "bonuses": [],
  "free_shipping_method_id": null,
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z",
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "coupon_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "bonus_value": 1500,
  "from_date": 1795748400,
  "expiry_date": 1796007599,
  "users": 0,
  "timestamp": 1791727330,
  "updated_timestamp": 1791727330
}

Campos da resposta

(campos da promoção)object

Devolve a promoção inteira, igual ao detalhe, mais ignored_fields e warning quando o corpo trouxe chaves que não viraram alteração.

Erros: alterar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	O corpo não altera nada: sem chaves conhecidas, ou só `null`/vazio. Nada foi gravado e a mensagem lista os campos aceitos.	`{"error":"o corpo não altera nada nesta promoção","detail":"nada foi gravado; campos aceitos: ..."}`
400	Id não é UUID completo; ou regra de validação (tipo, desconto, status, condição); ou `store_wide_unconfirmed`.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente.	`{"error":"promotion not found"}`
409	O novo código já pertence a outra promoção.	`{"error":"coupon_code_in_use","detail":"..."}`
422	A alteração leva a oferta abaixo do piso de margem.	`{"ok":false,"reason":"below_floor",...}`

Excluir uma promoção

DELETE/api/v1/admin/promotions/{id}Admin

Exclui (de forma lógica) uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Exemplo de requisição: excluir

bash

curl -X DELETE "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN"

Resposta: excluir

200Promoção excluída

json

{
  "message": "promotion deleted"
}

Erros: excluir

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	Id não é UUID completo.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente ou já excluída.	`{"error":"promotion not found"}`

Veja também

Alterar e excluir promoção

Altera campos de uma promoção existente e a exclui de forma lógica.

Alterar uma promoção

PUT/api/v1/admin/promotions/{id}Admin

Altera campos de uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Cabeçalhos

X-Margin-Overridestring

Token de exceção do Protetor de Margem, quando a oferta foi aprovada fora do piso.

Parâmetros de consulta

confirm_store_widebooleanpadrão: false

Envie true para confirmar que uma promoção de catálogo sem produto nem categoria deve valer para a loja toda.

Corpo da requisição

namestring

Novo nome.

typestring

Novo tipo. Mesma lista da criação.

discountinteger

Pontos-base em percentage (1000 = 10%, máximo 10000), centavos em fixed. Nunca negativo. Pode ser 0 em free_shipping e buy_x_get_y.

descriptionstring

Descrição livre.

codestring

Novo código (vira maiúsculo). Envie null para remover o código e tornar a promoção automática.

max_discountinteger

Teto do desconto em centavos.

priorityinteger

Ordem de avaliação; menor primeiro.

stop_other_rulesboolean

Interrompe a avaliação das promoções seguintes.

stackableboolean

Pode se combinar com outras acumuláveis.

conditionsobject

Condições simples. Veja a home da seção.

condition_groupsobject

Condições aninhadas E/OU.

bonusesarray

Lista de bônus: [{"bonus_type":"order_discount","config":{"discount_type":"by_percentage","discount_value":1000}}].

bonus_typestring

Bônus único (formato antigo).

bonus_configobject

Configuração do bônus único (formato antigo).

free_shipping_method_iduuid

Forma de envio que recebe frete grátis (tipo free_shipping).

usage_limitinteger

Máximo de usos no total. 0 = sem limite.

per_user_limitinteger

Máximo de usos por cliente.

valid_fromstring (RFC 3339)

Início da vigência. Se omitido, vale a partir de agora.

valid_untilstring (RFC 3339)

Fim da vigência. Se omitido, não expira.

statusstring

activeinactivedisabledexpireddraftADE

active, inactive/disabled, expired, draft (vira inativa) ou a letra. Vazio vira ativa.

zonestring

cartcatalog

cart ou catalog. Veja como o padrão é escolhido na home da seção.

vendor_iduuid

Atribui a promoção a um seller. Omita para promoção da loja.

descriptionsobject

Textos por idioma: mapa de código de idioma (pt-BR, en) para um objeto com o nome e a descrição traduzidos. Idiomas ausentes herdam name e description.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": 1500,
    "valid_until": "2026-12-01T23:59:59-03:00"
  }'

Resposta: alterar

200Promoção alterada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "name": "Black Friday 10% nas camisas",
  "description": "",
  "type": "percentage",
  "code": "BLACK10",
  "discount": 1500,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 0,
  "valid_from": "2026-11-27T03:00:00Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "condition_groups": null,
  "bonus_type": null,
  "bonus_config": null,
  "bonuses": [],
  "free_shipping_method_id": null,
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z",
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "coupon_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "bonus_value": 1500,
  "from_date": 1795748400,
  "expiry_date": 1796007599,
  "users": 0,
  "timestamp": 1791727330,
  "updated_timestamp": 1791727330
}

Campos da resposta

(campos da promoção)object

Devolve a promoção inteira, igual ao detalhe, mais ignored_fields e warning quando o corpo trouxe chaves que não viraram alteração.

Erros: alterar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	O corpo não altera nada: sem chaves conhecidas, ou só `null`/vazio. Nada foi gravado e a mensagem lista os campos aceitos.	`{"error":"o corpo não altera nada nesta promoção","detail":"nada foi gravado; campos aceitos: ..."}`
400	Id não é UUID completo; ou regra de validação (tipo, desconto, status, condição); ou `store_wide_unconfirmed`.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente.	`{"error":"promotion not found"}`
409	O novo código já pertence a outra promoção.	`{"error":"coupon_code_in_use","detail":"..."}`
422	A alteração leva a oferta abaixo do piso de margem.	`{"ok":false,"reason":"below_floor",...}`

Excluir uma promoção

DELETE/api/v1/admin/promotions/{id}Admin

Exclui (de forma lógica) uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Exemplo de requisição: excluir

bash

curl -X DELETE "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN"

Resposta: excluir

200Promoção excluída

json

{
  "message": "promotion deleted"
}

Erros: excluir

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	Id não é UUID completo.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente ou já excluída.	`{"error":"promotion not found"}`