API atual/Referência completa/Promoções do seller

Criar, alterar e excluir promoção

Cadastra uma promoção do seller com cupom, ajusta seus campos e a exclui de forma lógica.

Crie uma promoção quando o seller quer dar desconto aos clientes que digitarem um código: 10% acima de R$ 200, frete grátis, compre 3 leve 4. A promoção nasce ativa e começa a valer na hora, se valid_from for omitido. O dono (vendor_id) é sempre o seller do token. O desconto incide só sobre os itens dele e só funciona por código: sem code a promoção fica cadastrada e nunca é aplicada.

A plataforma recusa de antemão promoções que nasceriam "mortas" (tipo desconhecido, desconto negativo, condição inexistente na zona escolhida). Leia a mensagem do 400: ela diz o que corrigir.

Criar uma promoção

POST/api/v1/vendor/promotionsSeller

Cria uma promoção do seller

Corpo da requisição

namestringobrigatório

Nome interno da promoção.

typestringobrigatório

percentagefixedfree_shippingbuy_x_get_yto_percentageto_fixedorder_discountproduct_discountcategory_discountfree_productsgive_usergroupgive_couponfree_productassign_usergroup

Tipo da promoção. Os quatro primeiros cobrem quase todos os casos; os demais existem por compatibilidade com a plataforma antiga.

discountinteger

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

codestring

Código do cupom, gravado em maiúsculas. Obrigatório na prática: sem ele a promoção não é aplicada.

descriptionstring

Descrição livre.

max_discountinteger

Teto do desconto em centavos.

priorityintegerpadrão: 0

Ordem de avaliação; menor primeiro.

stop_other_rulesbooleanpadrão: false

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

stackablebooleanpadrão: false

Pode se combinar com outras acumuláveis.

conditionsobject

Condições simples: min_cart_total (centavos, medido sobre os itens do seller), product_ids, category_ids, exclude_product_ids, user_group_ids, vendor_ids (listas de UUID) e buy_x_get_y (buy_product_ids, buy_quantity, get_product_ids, get_quantity, discount_percent).

condition_groupsobject

Condições aninhadas E/OU: {"set":"all","set_value":true,"conditions":[{"type":"subtotal","operator":"gte","value":20000}]}.

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_limitintegerpadrão: 0

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

draft vira inativa. Vazio vira ativa.

zonestring

cartcatalog

cart ou catalog. Sem valor, promoção com código vira cart.

descriptionsobject

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

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inverno 10% nas camisas",
    "type": "percentage",
    "discount": 1000,
    "code": "INVERNO10",
    "zone": "cart",
    "conditions": { "min_cart_total": 20000 },
    "usage_limit": 500,
    "per_user_limit": 1,
    "valid_until": "2026-11-30T23:59:59-03:00"
  }'

Resposta: criar

201Promoção criada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "description": "",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1000,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 0,
  "valid_from": "2026-10-11T14:02:10Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "bonuses": [],
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z"
}

201Criada, mas com campos ignorados

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "name": "Inverno 10% nas camisas",
  "...": "demais campos como acima",
  "ignored_fields": ["end_at", "title"],
  "warning": "a promoção foi criada, mas estes campos do corpo não entraram nela: end_at, title. Campos aceitos: vendor_id, name, ..."
}

Campos da resposta

iduuid

Identificador da promoção.

vendor_iduuid

Seller dono: sempre o do token.

(demais campos)mixed

Os mesmos da promoção em Consultar promoções.

ignored_fieldsarray of string | omitted

Só aparece quando o corpo trouxe chaves desconhecidas, que foram descartadas.

warningstring | omitted

Texto, em português, que lista as chaves descartadas e as aceitas.

Alterar uma promoção

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

Altera campos de uma promoção do seller

O PUT é parcial: envie só o que muda. Para pausar, envie {"status":"inactive"}; para reativar, {"status":"active"}. O corpo aceita os mesmos campos da criação, todos opcionais, e ignora vendor_id.

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Corpo da requisição

namestring

Novo nome.

typestring

Novo tipo. Mesma lista da criação.

discountinteger

Novo desconto (pontos-base ou centavos, conforme o tipo).

codestring

Novo código (vira maiúsculo). Enviar null não remove o código nesta rota.

statusstring

activeinactivedisabledexpireddraftADE

Novo status.

valid_fromstring (RFC 3339)

Novo início de vigência.

valid_untilstring (RFC 3339)

Novo fim de vigência.

(demais campos)mixed

description, max_discount, priority, stop_other_rules, stackable, conditions, condition_groups, bonuses, bonus_type, bonus_config, free_shipping_method_id, usage_limit, per_user_limit, zone, descriptions, como na criação.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/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",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1500,
  "valid_until": "2026-12-02T02:59:59Z",
  "status": "A",
  "updated_at": "2026-10-11T15:10:00.120000Z"
}

A resposta é a promoção inteira, como na criação (trimada aqui).

Excluir uma promoção

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

Exclui (logicamente) uma promoção do seller

A exclusão é lógica: a promoção vai para o status D, sai da lista e deixa de descontar. Os pedidos antigos que a usaram continuam intactos.

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Resposta: excluir

200Promoção excluída

json

{ "message": "promotion deleted" }

Excluir de novo uma promoção que já foi excluída também responde 200: a rota só falha com 404 quando o id não é de uma promoção sua.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou o seller não tem privilégio de configurações.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}`
400	`name` ou `type` ausente na criação.	`{"error":"name is required","detail":"..."}`
400	Corpo que não é JSON, ou valor com formato errado (data sem hora, por exemplo). A mensagem diz o campo e o formato.	`{"error":"invalid request body","detail":"..."}`
400	Regra de validação: tipo, desconto, status, condição ou zona inválidos. A mensagem, em português, traz as opções aceitas.	`{"error":"invalid promotion type: percent; tipos aceitos: percentage, fixed, ...","detail":""}`
404	Alterar ou excluir uma promoção que não existe ou é de outro seller.	`{"error":"promotion not found"}`
422	A oferta fica abaixo do piso de margem da loja. O corpo é o detalhamento da conta.	`{"ok":false,"floor_bps":1500,"reason":"below_floor","worst":{},"violations":[]}`
500	Falha inesperada ao gravar. Um código de cupom repetido também chega como `500`, não como `409`.	`{"error":"failed to create promotion","detail":"..."}`

Veja também

API atual/Referência completa/Promoções do seller

Criar, alterar e excluir promoção

Cadastra uma promoção do seller com cupom, ajusta seus campos e a exclui de forma lógica.

A plataforma recusa de antemão promoções que nasceriam "mortas" (tipo desconhecido, desconto negativo, condição inexistente na zona escolhida). Leia a mensagem do 400: ela diz o que corrigir.

Criar uma promoção

POST/api/v1/vendor/promotionsSeller

Cria uma promoção do seller

Corpo da requisição

namestringobrigatório

Nome interno da promoção.

typestringobrigatório

percentagefixedfree_shippingbuy_x_get_yto_percentageto_fixedorder_discountproduct_discountcategory_discountfree_productsgive_usergroupgive_couponfree_productassign_usergroup

Tipo da promoção. Os quatro primeiros cobrem quase todos os casos; os demais existem por compatibilidade com a plataforma antiga.

discountinteger

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

codestring

Código do cupom, gravado em maiúsculas. Obrigatório na prática: sem ele a promoção não é aplicada.

descriptionstring

Descrição livre.

max_discountinteger

Teto do desconto em centavos.

priorityintegerpadrão: 0

Ordem de avaliação; menor primeiro.

stop_other_rulesbooleanpadrão: false

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

stackablebooleanpadrão: false

Pode se combinar com outras acumuláveis.

conditionsobject

condition_groupsobject

Condições aninhadas E/OU: {"set":"all","set_value":true,"conditions":[{"type":"subtotal","operator":"gte","value":20000}]}.

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_limitintegerpadrão: 0

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

draft vira inativa. Vazio vira ativa.

zonestring

cartcatalog

cart ou catalog. Sem valor, promoção com código vira cart.

descriptionsobject

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

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inverno 10% nas camisas",
    "type": "percentage",
    "discount": 1000,
    "code": "INVERNO10",
    "zone": "cart",
    "conditions": { "min_cart_total": 20000 },
    "usage_limit": 500,
    "per_user_limit": 1,
    "valid_until": "2026-11-30T23:59:59-03:00"
  }'

Resposta: criar

201Promoção criada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "description": "",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1000,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 0,
  "valid_from": "2026-10-11T14:02:10Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "bonuses": [],
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z"
}

201Criada, mas com campos ignorados

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "name": "Inverno 10% nas camisas",
  "...": "demais campos como acima",
  "ignored_fields": ["end_at", "title"],
  "warning": "a promoção foi criada, mas estes campos do corpo não entraram nela: end_at, title. Campos aceitos: vendor_id, name, ..."
}

Campos da resposta

iduuid

Identificador da promoção.

vendor_iduuid

Seller dono: sempre o do token.

(demais campos)mixed

Os mesmos da promoção em Consultar promoções.

ignored_fieldsarray of string | omitted

Só aparece quando o corpo trouxe chaves desconhecidas, que foram descartadas.

warningstring | omitted

Texto, em português, que lista as chaves descartadas e as aceitas.

Alterar uma promoção

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

Altera campos de uma promoção do seller

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Corpo da requisição

namestring

Novo nome.

typestring

Novo tipo. Mesma lista da criação.

discountinteger

Novo desconto (pontos-base ou centavos, conforme o tipo).

codestring

Novo código (vira maiúsculo). Enviar null não remove o código nesta rota.

statusstring

activeinactivedisabledexpireddraftADE

Novo status.

valid_fromstring (RFC 3339)

Novo início de vigência.

valid_untilstring (RFC 3339)

Novo fim de vigência.

(demais campos)mixed

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/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",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1500,
  "valid_until": "2026-12-02T02:59:59Z",
  "status": "A",
  "updated_at": "2026-10-11T15:10:00.120000Z"
}

A resposta é a promoção inteira, como na criação (trimada aqui).

Excluir uma promoção

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

Exclui (logicamente) uma promoção do seller

A exclusão é lógica: a promoção vai para o status D, sai da lista e deixa de descontar. Os pedidos antigos que a usaram continuam intactos.

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Resposta: excluir

200Promoção excluída

json

{ "message": "promotion deleted" }

Excluir de novo uma promoção que já foi excluída também responde 200: a rota só falha com 404 quando o id não é de uma promoção sua.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller, ou o seller não tem privilégio de configurações.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}`
400	`name` ou `type` ausente na criação.	`{"error":"name is required","detail":"..."}`
400	Corpo que não é JSON, ou valor com formato errado (data sem hora, por exemplo). A mensagem diz o campo e o formato.	`{"error":"invalid request body","detail":"..."}`
400	Regra de validação: tipo, desconto, status, condição ou zona inválidos. A mensagem, em português, traz as opções aceitas.	`{"error":"invalid promotion type: percent; tipos aceitos: percentage, fixed, ...","detail":""}`
404	Alterar ou excluir uma promoção que não existe ou é de outro seller.	`{"error":"promotion not found"}`
422	A oferta fica abaixo do piso de margem da loja. O corpo é o detalhamento da conta.	`{"ok":false,"floor_bps":1500,"reason":"below_floor","worst":{},"violations":[]}`
500	Falha inesperada ao gravar. Um código de cupom repetido também chega como `500`, não como `409`.	`{"error":"failed to create promotion","detail":"..."}`