> ## 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.

<ParamField path="app_id" type="string" required>
  O ID da sua loja no Jelou Shop.
</ParamField>

<ParamField body="code" type="string" required>
  Código que o cliente insere no checkout (máx. 255 caracteres).
</ParamField>

<ParamField body="name" type="string" required>
  Nome interno do cupom (máx. 255 caracteres).
</ParamField>

<ParamField body="description" type="string">
  Descrição opcional do cupom (máx. 1000 caracteres).
</ParamField>

<ParamField body="discount_type" type="string" required>
  Tipo de desconto. Valores: `percentage` (porcentagem) ou `value` (valor fixo).
</ParamField>

<ParamField body="discount_value" type="number" required>
  Valor do desconto. Para `percentage` é um valor entre `0` e `100`; para `value` é um valor fixo na moeda da loja.
</ParamField>

<ParamField body="status" type="boolean" default="true">
  Se o cupom está ativo. Um cupom inativo não pode ser aplicado.
</ParamField>

<ParamField body="valid_from" type="string">
  Data/hora de início da vigência (ISO 8601). Se omitido, o cupom é válido desde a criação.
</ParamField>

<ParamField body="valid_until" type="string">
  Data/hora de fim da vigência (ISO 8601). Deve ser igual ou posterior a `valid_from`. Se omitido, não expira.
</ParamField>

<ParamField body="max_uses" type="integer">
  Limite total de usos do cupom (mínimo `1`). Se omitido, os usos são ilimitados.
</ParamField>

<ParamField body="once_per_client" type="boolean" default="false">
  Se `true`, cada cliente pode usar o cupom apenas uma vez.
</ParamField>

<ParamField body="applies_to_all_branches" type="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`.
</ParamField>

<ParamField body="branches" type="object[]">
  Filiais onde o cupom se aplica (apenas quando `applies_to_all_branches` é `false`).

  <Expandable title="Propriedades de cada filial">
    <ParamField body="id" type="string" required>
      UUID da filial. Deve pertencer à mesma loja.
    </ParamField>

    <ParamField body="max_uses" type="integer">
      Limite de usos do cupom nessa filial (mínimo `1`). Se omitido, é ilimitado nessa filial.
    </ParamField>

    <ParamField body="status" type="boolean" default="true">
      Se o cupom está ativo nessa filial.
    </ParamField>
  </Expandable>
</ParamField>

<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`.
</Note>

<RequestExample>
  ```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
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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"
    }
  }
  ```
</ResponseExample>

<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 }
    ]
  }
  ```
</Tip>