> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# coupons.validate

> Validar cupom antes de aplicar no carrinho/checkout.

# storefront.coupons.validate(input)

Valida se um cupom pode ser usado **antes** de aplicar no checkout.

***

## Input

| Campo | Obrigatório | Descrição |
| - | - | - |
| `code` | ✅ | Código digitado pelo cliente |
| `document` | — | CPF/CNPJ (obrigatório para validar uso único por cliente) |

***

## Retorno

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  canUse: boolean;
  message: string;
  reason?: string;
  coupon?: CouponValidation | null;
}
```

### Motivos comuns (`reason`)

| Valor | Significado |
| - | - |
| `CouponNotFound` | Código inválido |
| `CouponInactive` | Cupom desativado |
| `CouponExpired` | Fora da vigência |
| `CouponExhausted` | Esgotou usos |
| `CouponAlreadyUsedByCustomer` | Cliente já usou (single use) |

***

## Exemplo

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function applyCoupon(code, document) {
  const result = await storefront.coupons.validate({ code, document });

  if (!result.canUse) {
    alert(result.message);
    return;
  }

  // aplicar no carrinho / checkout
}
```

***

## Hook / action

Use dentro de event handlers — **não** em `defineSectionData` (mutation).

Veja [coupons.list](https://docs-loja.usecorvex.com.br/data/queries/coupons-list.md) e [Coupon (resource)](https://docs-loja.usecorvex.com.br/data/resources/coupon.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.