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

Consultar orçamentos

Lista os orçamentos de desconto do seller com o consumo atual e detalha um orçamento.

Descontos custam dinheiro. Um orçamento de promoções é um teto: "no máximo R$ 5.000 de desconto neste mês" ou "no máximo 200 usos desta promoção". Quando o consumo chega ao teto, as promoções cobertas param de aplicar. Elas não são desativadas e voltam a aplicar sozinhas se um estorno liberar saldo ou a janela virar. O consumo não é um contador gravado: é calculado a cada leitura a partir das reservas (carrinho) e liquidações (pedido pago) e por isso já reflete cancelamentos e estornos.

O seller só enxerga os orçamentos que ele mesmo criou. O orçamento da loja inteira (escopo marketplace) e os de outros sellers não aparecem.

Listar orçamentos

GET/api/v1/vendor/promotion-budgetsSeller

Lista os orçamentos do seller com o consumo

Parâmetros de consulta

scopestring

promotiongroupcategorybrandsellermarketplace

Filtra por escopo.

scope_refuuid

Filtra pelo id do alvo do escopo.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/promotion-budgets?scope=promotion" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Orçamentos do seller

json

{
  "budgets": [
    {
      "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
      "scope": "promotion",
      "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "dimension": "discount_amount",
      "limit_cents": 500000,
      "window": "monthly",
      "enforcement": "stop_applying",
      "alert_threshold_pct": 80,
      "on_low_balance": "hard_stop",
      "funding_source": "seller",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "active",
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z",
      "spent": 125000,
      "usage_limit": 500000,
      "remaining": 375000,
      "unlimited": false,
      "exhausted": false,
      "alert_reached": false,
      "pct_used": 25
    }
  ]
}

Campos da resposta

budgetsarray

Orçamentos do seller. Sempre uma lista (vazia quando não há nenhum).

iduuid

Identificador do orçamento.

scopestring

promotiongroupcategorybrandseller

O que o teto limita. O escopo marketplace não existe para o seller.

scope_refuuid

Id do alvo do escopo (promoção, grupo, categoria, marca ou o próprio seller).

dimensionstring

discount_amountredemptions

O que é medido: centavos de desconto concedido ou número de usos.

limit_centsinteger | omitted

Teto em centavos, para discount_amount.

limit_countinteger | omitted

Teto em usos, para redemptions.

windowstring

lifetimedailyweeklymonthly

Janela de contagem. daily, weekly (semana ISO) e monthly zeram na virada, no fuso de São Paulo.

enforcementstring

Como reage ao esgotar. Hoje o único comportamento é stop_applying (parar de aplicar).

alert_threshold_pctinteger | omitted

Percentual do teto (1 a 100) a partir do qual alert_reached vira true.

on_low_balancestring

hard_stop ou partial. Só hard_stop tem efeito hoje.

funding_sourcestring

Quem paga o desconto. No seller é sempre seller.

funding_splitobject | omitted

Partição do custo. Informativa.

vendor_iduuid

Seller dono: sempre o seu.

statusstring

active participa do cálculo; qualquer outro valor deixa o orçamento fora.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

spentinteger

Consumo na janela corrente, na unidade da dimensão. Soma o que já virou pedido e o que está reservado em carrinhos que ainda não expiraram.

usage_limitinteger | null

O teto na mesma unidade de spent. null = sem teto.

remaininginteger

usage_limit menos spent. 0 quando não há teto.

unlimitedboolean

true quando não há teto: o orçamento só mede.

exhaustedboolean

true quando remaining chegou a zero: as promoções cobertas param de aplicar.

alert_reachedboolean

true quando o consumo passou de alert_threshold_pct.

pct_usedinteger

Consumo em percentual inteiro do teto. 0 sem teto.

Detalhar um orçamento

GET/api/v1/vendor/promotion-budgets/{id}Seller

Detalha um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Resposta: detalhar

200Orçamento encontrado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "dimension": "discount_amount",
  "limit_cents": 500000,
  "window": "monthly",
  "enforcement": "stop_applying",
  "alert_threshold_pct": 80,
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "active",
  "spent": 125000,
  "usage_limit": 500000,
  "remaining": 375000,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 25
}

Os campos são os de cada item de budgets.

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.	`{"error":"insufficient permissions"}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
404	No detalhe: o orçamento não existe ou é de outro seller (as duas situações são indistinguíveis de propósito).	`{"error":"promotion budget not found"}`
500	Falha ao ler.	`{"error":"failed to list promotion budgets","detail":"..."}`

Veja também

Consultar orçamentos

Lista os orçamentos de desconto do seller com o consumo atual e detalha um orçamento.

O seller só enxerga os orçamentos que ele mesmo criou. O orçamento da loja inteira (escopo marketplace) e os de outros sellers não aparecem.

Listar orçamentos

GET/api/v1/vendor/promotion-budgetsSeller

Lista os orçamentos do seller com o consumo

Parâmetros de consulta

scopestring

promotiongroupcategorybrandsellermarketplace

Filtra por escopo.

scope_refuuid

Filtra pelo id do alvo do escopo.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/promotion-budgets?scope=promotion" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Orçamentos do seller

json

{
  "budgets": [
    {
      "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
      "scope": "promotion",
      "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "dimension": "discount_amount",
      "limit_cents": 500000,
      "window": "monthly",
      "enforcement": "stop_applying",
      "alert_threshold_pct": 80,
      "on_low_balance": "hard_stop",
      "funding_source": "seller",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "status": "active",
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z",
      "spent": 125000,
      "usage_limit": 500000,
      "remaining": 375000,
      "unlimited": false,
      "exhausted": false,
      "alert_reached": false,
      "pct_used": 25
    }
  ]
}

Campos da resposta

budgetsarray

Orçamentos do seller. Sempre uma lista (vazia quando não há nenhum).

iduuid

Identificador do orçamento.

scopestring

promotiongroupcategorybrandseller

O que o teto limita. O escopo marketplace não existe para o seller.

scope_refuuid

Id do alvo do escopo (promoção, grupo, categoria, marca ou o próprio seller).

dimensionstring

discount_amountredemptions

O que é medido: centavos de desconto concedido ou número de usos.

limit_centsinteger | omitted

Teto em centavos, para discount_amount.

limit_countinteger | omitted

Teto em usos, para redemptions.

windowstring

lifetimedailyweeklymonthly

Janela de contagem. daily, weekly (semana ISO) e monthly zeram na virada, no fuso de São Paulo.

enforcementstring

Como reage ao esgotar. Hoje o único comportamento é stop_applying (parar de aplicar).

alert_threshold_pctinteger | omitted

Percentual do teto (1 a 100) a partir do qual alert_reached vira true.

on_low_balancestring

hard_stop ou partial. Só hard_stop tem efeito hoje.

funding_sourcestring

Quem paga o desconto. No seller é sempre seller.

funding_splitobject | omitted

Partição do custo. Informativa.

vendor_iduuid

Seller dono: sempre o seu.

statusstring

active participa do cálculo; qualquer outro valor deixa o orçamento fora.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

spentinteger

Consumo na janela corrente, na unidade da dimensão. Soma o que já virou pedido e o que está reservado em carrinhos que ainda não expiraram.

usage_limitinteger | null

O teto na mesma unidade de spent. null = sem teto.

remaininginteger

usage_limit menos spent. 0 quando não há teto.

unlimitedboolean

true quando não há teto: o orçamento só mede.

exhaustedboolean

true quando remaining chegou a zero: as promoções cobertas param de aplicar.

alert_reachedboolean

true quando o consumo passou de alert_threshold_pct.

pct_usedinteger

Consumo em percentual inteiro do teto. 0 sem teto.

Detalhar um orçamento

GET/api/v1/vendor/promotion-budgets/{id}Seller

Detalha um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Resposta: detalhar

200Orçamento encontrado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "dimension": "discount_amount",
  "limit_cents": 500000,
  "window": "monthly",
  "enforcement": "stop_applying",
  "alert_threshold_pct": 80,
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "active",
  "spent": 125000,
  "usage_limit": 500000,
  "remaining": 375000,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 25
}

Os campos são os de cada item de budgets.

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.	`{"error":"insufficient permissions"}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
404	No detalhe: o orçamento não existe ou é de outro seller (as duas situações são indistinguíveis de propósito).	`{"error":"promotion budget not found"}`
500	Falha ao ler.	`{"error":"failed to list promotion budgets","detail":"..."}`