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

# Crear cupón

> Crea un cupón de descuento por porcentaje o monto fijo, con vigencia y alcance por sucursal.

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

ID de tu tienda en Jelou Shop.

**code** `string` *required*

Código que el cliente ingresa en el checkout (máx. 255 caracteres).

**name** `string` *required*

Nombre interno del cupón (máx. 255 caracteres).

**description** `string`

Descripción opcional del cupón (máx. 1000 caracteres).

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

Tipo de descuento. Valores: `percentage` (porcentaje) o `value` (monto fijo).

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

Valor del descuento. Para `percentage` es un porcentaje entre `0` y `100`; para `value` es un monto fijo en la moneda de la tienda.

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

Si el cupón está activo. Un cupón inactivo no se puede aplicar.

**valid\_from** `string`

Fecha/hora de inicio de vigencia (ISO 8601). Si se omite, el cupón es válido desde su creación.

**valid\_until** `string`

Fecha/hora de fin de vigencia (ISO 8601). Debe ser igual o posterior a `valid_from`. Si se omite, no expira.

**max\_uses** `integer`

Límite total de usos del cupón (mínimo `1`). Si se omite, los usos son ilimitados.

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

Si es `true`, cada cliente puede usar el cupón una sola vez.

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

Si es `true`, el cupón aplica en todas las sucursales y se ignora `branches`. Si es `false`, solo aplica en las sucursales listadas en `branches`.

**branches** `object[]`

Sucursales donde aplica el cupón (solo cuando `applies_to_all_branches` es `false`).

**Propiedades de cada sucursal**

**id** `string` *required*

UUID de la sucursal. Debe pertenecer a la misma tienda.

**max\_uses** `integer`

Límite de usos del cupón en esa sucursal (mínimo `1`). Si se omite, es ilimitado en esa sucursal.

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

Si el cupón está activo en esa sucursal.

> [!NOTE]
>
> El `code` debe ser único dentro de su alcance de sucursales. No puedes crear dos cupones con el mismo código si comparten sucursal (o si alguno aplica a todas las sucursales). Un descuento `percentage` no puede superar `100`.

```bash cURL theme={null}
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/coupons" \
  -H "x-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACKFRIDAY25",
    "name": "Black Friday 25%",
    "description": "25% de descuento en toda la tienda",
    "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 descuento en toda la tienda",
    "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]
>
> **Cupón por sucursal:** envía `applies_to_all_branches: false` y una lista `branches`. Cada sucursal puede tener su propio `max_uses` y `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.