Orçamentos e grupos de promoções

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. Um grupo de promoções é só um rótulo que reúne várias promoções (por exemplo "Campanha de verão") para que um orçamento possa limitá-las em conjunto.

Como funciona

Do carrinho ao pedido

1. Quando uma promoção entra num carrinho, o valor do desconto é reservado nos orçamentos aplicáveis, por 24 horas. Se o carrinho morrer, a reserva expira sozinha e o saldo volta.
2. Quando o pedido passa a pago, a reserva vira liquidada e passa a contar definitivamente. Um pedido que fica 24 horas sem pagar perde a reserva (ela expira e o saldo volta).
3. Se o pedido é cancelado ou reembolsado, o valor é liberado.

Escopos (scope)

Dimensão e janela

• discount_amount mede centavos de desconto concedido e usa limit_cents. redemptions mede número de usos e usa limit_count.
• A janela define quando o contador zera: lifetime nunca zera; daily, weekly (semana ISO) e monthly zeram na virada do dia, da semana ou do mês no fuso de São Paulo.
• Sem limit_cents/limit_count o orçamento é ilimitado: serve só para medir (unlimited: true).

Conceitos importantes

Alerta

alert_threshold_pct não bloqueia nada: ele só liga alert_reached quando o consumo passa daquele percentual do teto, para a loja ser avisada antes de esgotar.

Orçamento de seller

Um orçamento com vendor_id pertence a um seller; um sem vendor_id é da loja. O filtro ?vendor_id= da lista aceita valor vazio para pedir só os da loja.

Quem paga

funding_source (seller, operator, manufacturer, shared) e funding_split registram quem arca com o desconto, para a conciliação. Eles não mudam o bloqueio.

Endpoints

Erros comuns

• Esperar que o orçamento desative a promoção. Ele só faz a promoção parar de aplicar enquanto está esgotado.
• Esquecer o scope_ref. Qualquer escopo que não seja marketplace exige o id do alvo, em UUID. Um valor que não é UUID é recusado com 400, porque nunca casaria com nada.
• Trocar redemptions por limit_cents. Com dimension redemptions o teto é limit_count; mandar só limit_cents leva 400.
• Tentar mudar escopo, alvo, dimensão ou dono depois de criado. Esses campos são imutáveis: o PUT responde 400 immutable_field. Crie outro orçamento.
• Valores fora das listas. window, on_low_balance, funding_source e scope inválidos são barrados pelo banco e chegam como 500, não 400. Use só os valores documentados.
• Apagar um grupo em uso. A exclusão do grupo não é bloqueada: os orçamentos que apontavam para ele ficam órfãos e deixam de limitar qualquer coisa. Consulte /usage antes.

Próximos passos