VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Orçamentos e grupos de promoções

Criar, alterar e excluir orçamento

Cria, ajusta e remove um teto de gasto em desconto.

Crie um orçamento para proteger o caixa de uma campanha. Ele vale a partir do momento em que é criado e só conta descontos concedidos depois disso. O PUT ajusta o teto, a janela, o alerta e o status; o que o orçamento limita (escopo, alvo, dimensão, dono) não muda. Para pausar sem perder o histórico de consumo, envie "status": "paused"; para voltar, "status": "active". Excluir apaga o orçamento e o razão de consumo dele.

Criar um orçamento

POST/api/v1/admin/promotion-budgetsAdmin

Cria um orçamento de promoções

Corpo da requisição

scopestringobrigatório
promotiongroupcategorybrandsellermarketplace
O que o teto limita.
scope_refuuid
Id do alvo. Obrigatório, em UUID, para todo escopo exceto marketplace (onde é ignorado). Vira minúsculo.
dimensionstringobrigatório
discount_amountredemptions
O que medir.
limit_centsinteger
Teto em centavos, para discount_amount.
limit_countinteger
Teto em usos, para redemptions.
windowstringpadrão: lifetime
lifetimedailyweeklymonthly
Janela de contagem.
alert_threshold_pctinteger
Percentual do teto que liga alert_reached.
enforcementstringpadrão: stop_applying
Comportamento ao esgotar. Deixe o padrão.
on_low_balancestringpadrão: hard_stop
hard_stoppartial
Gravado, mas só hard_stop tem efeito hoje.
funding_sourcestringpadrão: seller
selleroperatormanufacturershared
Quem paga (informativo).
funding_splitobject
Partição do custo, para shared.
vendor_iduuid
Seller dono. Omita para orçamento da loja.
statusstringpadrão: active
active ou outro valor para deixar o orçamento fora do cálculo.

Exemplo de requisição: criar

bash
curl -X POST "$BASE_URL/api/v1/admin/promotion-budgets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "group",
    "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
    "dimension": "discount_amount",
    "limit_cents": 999900,
    "window": "monthly",
    "alert_threshold_pct": 80
  }'

Resposta: criar

201Orçamento criado
json
{
  "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
  "scope": "group",
  "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "dimension": "discount_amount",
  "limit_cents": 999900,
  "window": "monthly",
  "alert_threshold_pct": 80,
  "enforcement": "stop_applying",
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "status": "active",
  "created_at": "2026-07-20T00:55:13.241665Z",
  "updated_at": "2026-07-20T01:32:33.732761Z",
  "spent": 0,
  "usage_limit": 999900,
  "remaining": 999900,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 0
}

Campos da resposta

(campos do orçamento)object
O orçamento criado, com os campos de consumo (zerados).

Erros: criar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo promotions está desligado na loja.{"error":"module_disabled","module":"promotions"}
403Falta o privilégio: view_promotions para ler, manage_promotions para gravar.{"error":"insufficient privileges","required":"manage_promotions"}
400Corpo inválido, scope ou dimension fora da lista, scope_ref ausente ou que não é UUID, ou redemptions com limit_cents e sem limit_count.{"error":"failed to create promotion budget","detail":"promotion budget validation: scope_ref is required for scope \"group\""}
500Valor fora da lista em window, on_low_balance ou funding_source (barrado pelo banco).{"error":"failed to create promotion budget","detail":"..."}

Alterar um orçamento

PUT/api/v1/admin/promotion-budgets/{id}Admin

Altera teto, janela, alerta ou status de um orçamento

Parâmetros de caminho

iduuidobrigatório
Id do orçamento.

Corpo da requisição

limit_centsinteger
Novo teto em centavos.
limit_countinteger
Novo teto em usos.
windowstring
lifetimedailyweeklymonthly
Nova janela.
alert_threshold_pctinteger
Novo percentual de alerta.
enforcementstring
Comportamento ao esgotar.
on_low_balancestring
hard_stoppartial
hard_stop ou partial.
funding_sourcestring
selleroperatormanufacturershared
Quem paga.
funding_splitobject
Partição do custo.
statusstring
active para ligar; outro valor para tirar do cálculo.

Exemplo de requisição: alterar

bash
curl -X PUT "$BASE_URL/api/v1/admin/promotion-budgets/c777e051-253e-4da0-a156-a1fe4032e8d1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_cents": 1500000,
    "alert_threshold_pct": 90
  }'

Resposta: alterar

200Orçamento alterado
json
{
  "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
  "scope": "group",
  "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "dimension": "discount_amount",
  "limit_cents": 1500000,
  "window": "lifetime",
  "enforcement": "stop_applying",
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "status": "active",
  "created_at": "2026-07-20T00:55:13.241665Z",
  "updated_at": "2026-07-20T01:32:33.732761Z",
  "spent": 120000,
  "usage_limit": 1500000,
  "remaining": 1380000,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 8
}

Campos da resposta

(campos do orçamento)object
O orçamento já alterado, com o consumo atual.

Erros: alterar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo promotions está desligado na loja.{"error":"module_disabled","module":"promotions"}
403Falta o privilégio: view_promotions para ler, manage_promotions para gravar.{"error":"insufficient privileges","required":"manage_promotions"}
400O corpo traz scope, scope_ref, dimension ou vendor_id: campos imutáveis. A mensagem diz para criar outro orçamento.{"error":"immutable_field","detail":"o campo \"scope\" não pode ser alterado por este endpoint: ..."}
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
404Não existe orçamento com esse id.{"error":"failed to get promotion budget","detail":"promotion budget not found"}
500O id não é um UUID válido. Hoje esta rota responde 500 (e não 400) nesse caso; a mensagem em detail explica o problema.{"error":"failed to get promotion budget","detail":"o valor \"xyz\" não é um uuid válido. ..."}

Excluir um orçamento

DELETE/api/v1/admin/promotion-budgets/{id}Admin

Exclui um orçamento e o razão de consumo

Parâmetros de caminho

iduuidobrigatório
Id do orçamento.

Exemplo de requisição: excluir

bash
curl -X DELETE "$BASE_URL/api/v1/admin/promotion-budgets/c777e051-253e-4da0-a156-a1fe4032e8d1" \
  -H "Authorization: Bearer $TOKEN"

Resposta: excluir

200Orçamento excluído
json
{
  "deleted": true
}

Erros: excluir

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo promotions está desligado na loja.{"error":"module_disabled","module":"promotions"}
403Falta o privilégio: view_promotions para ler, manage_promotions para gravar.{"error":"insufficient privileges","required":"manage_promotions"}
404Não existe orçamento com esse id.{"error":"failed to get promotion budget","detail":"promotion budget not found"}
500O id não é um UUID válido. Hoje esta rota responde 500 (e não 400) nesse caso; a mensagem em detail explica o problema.{"error":"failed to get promotion budget","detail":"o valor \"xyz\" não é um uuid válido. ..."}
Excluir é definitivo

A exclusão é física e leva junto o histórico de reservas e liquidações. As promoções cobertas voltam a aplicar sem teto na hora. Para suspender, use status.

`status` aceita qualquer texto

Só o valor active faz o orçamento participar. Qualquer outro (paused, inactive) o deixa fora do cálculo, mas o servidor não valida a grafia: um erro de digitação como activ também desliga o orçamento sem aviso.

Veja também

  • Orçamentos e grupos: visão geral
  • Consultar orçamentos
  • Consultar grupos
Anterior
Consultar orçamentos
Próxima
Consultar grupos
Nesta página
  • Criar um orçamento
  • Exemplo de requisição: criar
  • Resposta: criar
  • Erros: criar
  • Alterar um orçamento
  • Exemplo de requisição: alterar
  • Resposta: alterar
  • Erros: alterar
  • Excluir um orçamento
  • Exemplo de requisição: excluir
  • Resposta: excluir
  • Erros: excluir
  • Veja também