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

# Criar cupom

> Crie um cupom de desconto por porcentagem ou valor fixo, com vigência e escopo por filial.

**app\_id** `string` *required*

O ID da sua loja no Jelou Shop.

**code** `string` *required*

Código que o cliente insere no checkout (máx. 255 caracteres).

**name** `string` *required*

Nome interno do cupom (máx. 255 caracteres).

**description** `string`

Descrição opcional do cupom (máx. 1000 caracteres).

**discount\_type** `string` *required*

Tipo de desconto. Valores: `percentage` (porcentagem) ou `value` (valor fixo).

**discount\_value** `number` *required*

Valor do desconto. Para `percentage` é um valor entre `0` e `100`; para `value` é um valor fixo na moeda da loja.

**status** `boolean` (default: true)

Se o cupom está ativo. Um cupom inativo não pode ser aplicado.

**valid\_from** `string`

Data/hora de início da vigência (ISO 8601). Se omitido, o cupom é válido desde a criação.

**valid\_until** `string`

Data/hora de fim da vigência (ISO 8601). Deve ser igual ou posterior a `valid_from`. Se omitido, não expira.

**max\_uses** `integer`

Limite total de usos do cupom (mínimo `1`). Se omitido, os usos são ilimitados.

**once\_per\_client** `boolean` (default: false)

Se `true`, cada cliente pode usar o cupom apenas uma vez.

**applies\_to\_all\_branches** `boolean` (default: false)

Se `true`, o cupom aplica-se a todas as filiais e `branches` é ignorado. Se `false`, aplica-se apenas às filiais listadas em `branches`.

**branches** `object[]`

Filiais onde o cupom se aplica (apenas quando `applies_to_all_branches` é `false`).

**Propriedades de cada filial**

**id** `string` *required*

UUID da filial. Deve pertencer à mesma loja.

**max\_uses** `integer`

Limite de usos do cupom nessa filial (mínimo `1`). Se omitido, é ilimitado nessa filial.

**status** `boolean` (default: true)

Se o cupom está ativo nessa filial.

> [!NOTE]
>
> O `code` deve ser único dentro do seu escopo de filiais. Você não pode criar dois cupons com o mesmo código se compartilharem uma filial (ou se algum se aplicar a todas as filiais). Um desconto `percentage` não pode ultrapassar `100`.

```bash cURL theme={null}
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACKFRIDAY25",
    "name": "Black Friday 25%",
    "description": "25% de desconto em toda a loja",
    "discount_type": "percentage",
    "discount_value": 25,
    "status": true,
    "valid_from": "2026-11-25T00:00:00Z",
    "valid_until": "2026-11-30T23:59:59Z",
    "max_uses": 100,
    "once_per_client": true,
    "applies_to_all_branches": true
  }'
```

```json 201 Created theme={null}
{
  "data": {
    "id": "9e3f2c1a-8b7d-4e6f-a5c4-d3b2a1e0f9c8",
    "app_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "code": "BLACKFRIDAY25",
    "name": "Black Friday 25%",
    "description": "25% de desconto em toda a loja",
    "discount_type": "percentage",
    "discount_value": "25.000000",
    "status": true,
    "valid_from": "2026-11-25T00:00:00.000000Z",
    "valid_until": "2026-11-30T23:59:59.000000Z",
    "max_uses": 100,
    "once_per_client": true,
    "applies_to_all_branches": true,
    "state": "scheduled",
    "created_at": "2026-07-02T15:30:00.000000Z",
    "updated_at": "2026-07-02T15:30:00.000000Z"
  }
}
```

> [!TIP]
>
> **Cupom por filial:** envie `applies_to_all_branches: false` e uma lista `branches`. Cada filial pode ter seu próprio `max_uses` e `status`.
>
> ```json theme={null}
> {
>   "code": "CENTRO20",
>   "name": "Centro 20%",
>   "discount_type": "percentage",
>   "discount_value": 20,
>   "applies_to_all_branches": false,
>   "branches": [
>     { "id": "1a2b3c4d-...", "max_uses": 50, "status": true }
>   ]
> }
> ```


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