Calcule e reserve o desconto

O cálculo valida o código no contexto atual, aplica as regras por produto e frete e cria uma cotação temporária.

Um cupom

Use POST /v1/coupon/discount/single com coupon_code, um identificador opcional do carrinho e o contexto completo.

{
  "cart_id": "cart-001",
  "coupon_code": "BEMVINDO15",
  "context": {
    "user": { "id": "user-001" },
    "cart": [
      { "id": "product-001", "quantity": 2, "unitary_price": 100 }
    ],
    "shipping": { "amount": 25 }
  }
}

Vários cupons

Use POST /v1/coupon/discount/multiple quando a operação permite combinar códigos. Envie de dois a dez códigos e escolha a estratégia de seleção documentada no contrato.

Use a resposta como fonte de verdade

Apresente os totais retornados e guarde quote_id durante o checkout. Se o contexto mudar, gere uma nova cotação. Não replique no frontend as regras configuradas no painel.

Falhas esperadas

Trate código inválido, regra não satisfeita, limite esgotado e budget indisponível como resultados comerciais. Erros de autenticação, permissão ou validação indicam problema de integração e devem seguir uma estratégia diferente de observabilidade e retry.