---
title: 'Políticas de resgate'
description: 'Como o loyalty decide quanto do saldo do cliente pode ser usado num pedido: quais políticas valem, o teto de cada uma, o modo de agrupamento e a disputa entre políticas.'
---

# Políticas de resgate

Quando um pedido pede resgate (por exemplo, no [Resgate por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)), o loyalty precisa decidir **quais cards** do cliente entram e **quanto** de cada um. Este guia explica essa decisão, passo a passo, com exemplos.

## Conceitos

- **Card** (`rewardCard`) — cada crédito que o cliente ganhou (cashback, bônus, pontos). Tem saldo e validade próprios.
- **Política de resgate** (também chamada de **carteira** ou `wallet`) — o conjunto de regras que diz **onde** e **quanto** desse saldo pode ser usado. Todo card pertence a uma política; o campo `wallet` do card é o id da política.

A campanha define em qual política nascem os cards que ela gera. Duas campanhas na mesma política geram saldo na mesma carteira.

## Passo 1 — Quais políticas valem neste pedido

Uma política só participa se **todas** as condições abaixo forem verdadeiras:

| Condição | O que é verificado |
|---|---|
| Loja | A loja do pedido está vinculada à política. |
| Resgate ativo | A política está com o resgate ligado. |
| Tags | O cliente tem todas as tags exigidas e não tem as tags excluídas. |
| Nível | O nível do cliente está entre os permitidos (ou fora dos excluídos). |
| Mínimo dinâmico | Se a política exige compra mínima proporcional ao saldo (`minOrderRate`), o pedido precisa atingi-la. Quando não atinge, a carteira fica de fora e o motivo vem em `redeemable.blocked`. |

Cards de uma política que não passou aqui não entram no resgate, mesmo com saldo.

## Passo 2 — O teto de cada política

Cada política calcula **o máximo de desconto que ela aceita neste pedido**, considerando só os itens que ela autoriza (categorias e coleções permitidas, sem as coleções excluídas):

- **Valor mínimo / máximo** (`minOrderTotal` / `maxOrderTotal`) — se o total dos itens autorizados ficar fora da faixa, a política não concede desconto.
- **Limite** (`maxOrderRate`) — até `1`, é um percentual: `0.3` = até 30% dos itens autorizados. Acima de `1`, é um valor fixo em centavos (veja [Valores monetários](/docs/{lang}/guides/monetary-values)): `5000` = até $50,00. Sem limite, vale o total dos itens autorizados.

O teto é **da política**: os cards dela, juntos, nunca passam desse valor.

## Passo 3 — Dentro da política: o modo de agrupamento

O modo de agrupamento da política define como **os cards dela** se combinam:

| Modo | Comportamento dentro da política |
|---|---|
| **Agregar** (`aggregate`) | Soma todos os cards da política, até o teto. |
| **Único** (`single`) | Usa **um** card só: o que dá o maior desconto. |
| **Misto** (`mixed`) | Igual a Agregar. Mantido para políticas já configuradas assim. |

O modo usado é o **atual** da política. Mudar o modo vale também para os cards que já existem.

## Passo 4 — Entre políticas: elas disputam, nunca somam

Se o cliente tem saldo em **mais de uma política válida** para o pedido, as políticas **disputam entre si**. O pedido usa **apenas uma**:

1. Vence a política que dá o **maior desconto** neste pedido (já aplicado o teto do passo 2 e o modo do passo 3).
2. Em caso de **empate**, vence a que tem o card com **vencimento mais próximo**, para o cliente não perder saldo.

Saldo de políticas diferentes **nunca é somado** no mesmo pedido. Para que dois saldos somem, os cards precisam estar na **mesma política**, ou seja, as campanhas que os geram devem apontar para a mesma política.

## Passo 5 — O valor solicitado

Quando a integração informa quanto quer resgatar (`amountToRedeem`), esse valor limita o resgate. Cada política é avaliada com o valor solicitado inteiro, e só depois a vencedora é escolhida, então uma política que perde a disputa não reduz o valor da que vence.

## Exemplos

Nos exemplos, os pedidos não têm teto de percentual, salvo quando indicado, e as políticas valem na loja do pedido.

| # | Saldo do cliente | Resultado | Por quê |
|---|---|---|---|
| 1 | Política A (agregar): cards de $100 e $50. Política B (agregar): card de $120. | **$150**, da A | A soma $150 e B soma $120. Políticas disputam: vence a maior. |
| 2 | Política A (agregar): $30 + $30. Política B (único): $50. | **$60**, da A | A soma $60; B usa um card de $50. Vence A. |
| 3 | Igual ao exemplo 2, com `amountToRedeem` = $60. | **$60**, da A | Cada política é avaliada com os $60 inteiros; A cobre os $60. |
| 4 | Política M (misto): $50. Política A (agregar): $100. | **$100**, da A | Misto não soma com outra política; vence o maior desconto. |
| 5 | Política M1 (misto): $40. Política M2 (misto): $70. | **$70**, da M2 | Mesmo com as duas em misto, políticas diferentes não somam. |
| 6 | Política A: $80, vence em dezembro. Política B: $80, vence em novembro. | **$80**, da B | Empate no desconto: vence o vencimento mais próximo. |
| 7 | Política A (agregar): $10 + $20 + $30. | **$60** | Dentro da mesma política, agregar soma todos os cards. |
| 8 | Política B (único): $10, $20 e $30. | **$30** | Dentro da mesma política, único usa só o melhor card. |
| 9 | Pedido de $1.000. Política A (agregar, máx. 30%): $500. Política B (agregar, sem teto): $200. | **$300**, da A | O teto da A limita a $300 (30% de $1.000), que ainda é maior que os $200 da B. |

## Perguntas frequentes

**O cliente tem mais saldo do que conseguiu resgatar. Por quê?**
As causas mais comuns são o saldo dividido em políticas diferentes (só uma é usada por pedido, passo 4), o teto da política (passo 2) ou o modo Único (passo 3). Se `redeemable.blocked` vier preenchido, uma carteira foi barrada pelo mínimo dinâmico (passo 1).

**Quero que o cashback de duas campanhas some no mesmo pedido.**
Coloque as duas campanhas na **mesma política** de resgate, em modo Agregar.

**Quero que o cliente use só o melhor crédito, um por pedido.**
Use o modo **Único** na política.

## Histórico

- **3 de outubro de 2026** — políticas diferentes passaram a disputar entre si. Antes, cards de políticas diferentes em modo Agregar ou Misto eram somados no mesmo pedido.

## Veja também

- [Resgate por pedido](/docs/{lang}/api-reference/loyalty/checkout/reward-by-order)
- [Confirmar pedido](/docs/{lang}/api-reference/loyalty/checkout/confirm-order-by-confirmtoken)
- [Atualizar transação](/docs/{lang}/api-reference/loyalty/checkout/update-transaction)
- [Cancelamento no loyalty](/docs/{lang}/guides/loyalty-cancellation)
