VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Checkout

Cupom e vale-presente no checkout

Aplica e remove um cupom de desconto ou um vale-presente na sessão de checkout e entende como o total é recalculado.

Duas formas de abater o total dentro da sessão de checkout:

  • Cupom (ou voucher): um código que dá desconto percentual, valor fixo, frete grátis ou "leve X pague Y". É o mesmo código do carrinho; se o carrinho já tinha um cupom gravado, ele entra na sessão sozinho ao abrir o checkout.
  • Vale-presente (gift certificate): um crédito pré-pago em dinheiro, com saldo, que o comprador gasta como forma de pagamento parcial ou total. O saldo só é descontado do vale quando o pedido é fechado.

Todas as quatro rotas devolvem a sessão inteira já recalculada e só têm efeito dentro dela; nada é cobrado aqui. Cada sessão guarda um cupom e um vale-presente: aplicar outro código troca o anterior.

Cupom

Aplicar um cupom

POST/api/v1/storefront/checkout/{sessionId}/couponAutenticada

Aplica um código de cupom à sessão de checkout

A API valida o código contra os itens da sessão e o cliente: validade, valor mínimo, limite de uso por cliente, grupos de cliente e produtos ou categorias exigidos. Se vale, o desconto entra em discount (somado ao de catálogo), o frete grátis do cupom é respeitado e o total é refeito, inclusive o desconto de PIX, que é calculado sobre o valor já abatido.

A loja pode desligar cupons por completo; nesse caso a rota responde 403 feature_not_available.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Corpo da requisição

coupon_codestringobrigatório
Código digitado pelo comprador.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/coupon" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "coupon_code": "BEMVINDO10"
}'

Resposta

200Cupom aplicado
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "step": "review",
  "subtotal": 30000,
  "catalog_discount": 7500,
  "discount": 9900,
  "coupon_code": "BEMVINDO10",
  "promotion_id": "01e3a0f3-5587-40d7-9915-b32832b70290",
  "free_shipping": false,
  "shipping_cost": 0,
  "pix_discount": 1005,
  "total": 19095
}

Campos que mudam na sessão

coupon_codestring
Código aplicado, como foi digitado.
discountinteger
Desconto total em centavos: catálogo + B2B + regional + cupom. O valor só do cupom é discount menos os outros três.
promotion_iduuid
Promoção que gerou o cupom. Ausente quando o código é um voucher avulso.
voucher_appliedboolean
true quando o código é um voucher avulso do seller ou da loja, e não uma promoção.
free_shippingboolean
true se o cupom dá frete grátis.
free_shipping_method_iduuid
Quando presente, o frete grátis vale só para este método.

Erros

StatusQuandoCorpo
400Sem coupon_code{"error":"coupon_code is required"}
400Código inexistente ou inativo{"error":"coupon not applicable: cupom não encontrado ou inativo"}
400Existe, mas não vale para este carrinho ou cliente{"error":"coupon not applicable: <motivo em português>"}
403A loja desligou cupons{"error":"feature_not_available","feature":"coupons","detail":"switched off for this store"}
404Sessão inexistente ou de outro dono{"error":"checkout session not found"}

O motivo depois de coupon not applicable: é uma frase em português escrita para o comprador (por exemplo, restrição de grupo de cliente). Pode ser mostrada como está.

Remover o cupom

DELETE/api/v1/storefront/checkout/{sessionId}/couponAutenticada

Remove o cupom da sessão de checkout

Tira o cupom da sessão, devolve o desconto e refaz o frete e o total. O desconto de catálogo é mantido, e um frete grátis vindo de promoção automática (sem cupom) continua valendo. Sem corpo. Chamar sem cupom aplicado não é erro: devolve a sessão como está.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/coupon" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Cupom removido
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "coupon_code": null,
  "catalog_discount": 7500,
  "discount": 7500,
  "free_shipping": false,
  "total": 22500
}

Os campos são os da sessão completa, aqui encurtados. Erros: 403 feature_not_available quando a loja desligou cupons, 404 checkout session not found e 400 com o texto do problema se o frete precisar ser cotado de novo (shipping_requote_required: ...).

Vale-presente

Aplicar um vale-presente

POST/api/v1/storefront/checkout/{sessionId}/gift-certificateAutenticada

Aplica um vale-presente à sessão de checkout

O vale é abatido do que sobra depois de descontos, frete e impostos. O valor usado é o menor entre o saldo do vale e o que falta pagar, e fica em gift_cert_amount. Se o saldo cobre tudo, total vira 0. Vales restritos a um seller não podem ser aplicados à sessão inteira e são recusados.

Se o total mudar depois (por exemplo, ao remover ou trocar um cupom), o valor abatido pelo vale é recalculado, sempre limitado ao que resta pagar.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Corpo da requisição

codestringobrigatório
Código do vale-presente.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/gift-certificate" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "VALE-ABCD-1234"
}'

Resposta

200Vale-presente aplicado
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "gift_cert_code": "VALE-ABCD-1234",
  "gift_cert_amount": 10000,
  "subtotal": 30000,
  "discount": 7500,
  "total": 12500
}

Campos que mudam na sessão

gift_cert_codestring
Código aplicado.
gift_cert_amountinteger
Valor abatido pelo vale, em centavos. Nunca passa do que falta pagar.
totalinteger
Total restante a pagar pela forma de pagamento escolhida.

Erros

StatusQuandoCorpo
400Sem code{"error":"gift certificate code is required"}
400Vale inexistente{"error":"invalid gift certificate: gift certificate not found"}
400Vale sem saldo, expirado ou inativo{"error":"invalid gift certificate: gift certificate has expired"} (ou has no remaining balance, ou is <status>)
400Vale restrito a um seller{"error":"invalid gift certificate: gift certificate is restricted to a specific vendor and cannot be applied to the whole cart"}
400A loja não usa vale-presente{"error":"gift certificates are not enabled"}
404Sessão inexistente ou de outro dono{"error":"checkout session not found"}

Remover o vale-presente

DELETE/api/v1/storefront/checkout/{sessionId}/gift-certificateAutenticada

Remove o vale-presente da sessão de checkout

Zera gift_cert_code e gift_cert_amount e recalcula o total. O saldo do vale nunca foi gasto, então nada precisa ser devolvido. Sem corpo.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/gift-certificate" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Vale-presente removido
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "gift_cert_amount": 0,
  "total": 22500
}

Erro possível: 404 checkout session not found. Remover sem vale aplicado devolve a sessão sem alterações.

Mostre o saldo usado, não o saldo do vale

Use gift_cert_amount para exibir "Vale-presente: - R$ 100,00". Ele já está limitado ao valor devido, então pode ser menor que o saldo total do vale. Como o saldo só é baixado ao fechar o pedido, aplicar o vale numa sessão não o reserva.

Veja também

  • Cupons no carrinho
  • Cupons automáticos
  • Validar e fechar o pedido
Anterior
Endereço, frete e pagamento
Próxima
Validar e fechar o pedido
Nesta página
  • Cupom
  • Aplicar um cupom
  • Remover o cupom
  • Vale-presente
  • Aplicar um vale-presente
  • Remover o vale-presente
  • Veja também