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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# El objeto de promoción de suscripción

> Describe el objeto de promoción de una suscripción: el descuento, los ciclos usados, el comportamiento en pausa y cómo terminó la promoción

Cuando se aplica una promoción a una suscripción, Yuno guarda una copia en la suscripción. La copia es el objeto `promotion`. [Crear suscripción](https://docs.y.uno/es/reference/subscriptions/create-subscription.md) y [Actualizar suscripción](https://docs.y.uno/es/reference/subscriptions/update-subscription.md) lo devuelven. La copia nunca se edita: cambiar después la asociación del plan o la promoción no la modifica. Consulta [Promociones en planes de suscripción](https://docs.y.uno/es/docs/payment-features/subscriptions/promotions.md).

## Atributos

**id** `string`

El ID de la promoción (UUID).

Ejemplo: 8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10

**name** `string`

El nombre de la promoción.

Ejemplo: Welcome 20% x3

**discount** `object`

El descuento. Los campos dependen de `type`.

**propiedades**

**type** `enum`

`PERCENTAGE` o `FIXED`.

**value** `number`

Solo `PERCENTAGE`. El porcentaje, de 0 a 100, con un máximo de 2 decimales.

Ejemplo: 20

**amount** `number`

Solo `FIXED`. El monto, con los decimales de la moneda.

Ejemplo: 15.00

**currency** `string`

Solo `FIXED`. La moneda ISO 4217 de `amount`.

Ejemplo: USD

**cycles** `object`

El número de cobros que cubre el descuento.

**propiedades**

**total** `integer`

El número de ciclos que cubre la promoción, definido cuando se asoció al plan.

**used** `integer`

Ciclos contados desde que se aplicó: cobros aprobados, ciclos de prueba y ciclos al 100%. Un cobro rechazado no cuenta. Un reintento del mismo cobro cuenta una sola vez.

**remaining** `integer`

`total` menos `used`.

**on\_pause** `enum`

Qué efecto tiene una pausa sobre la promoción: `KEEP` (sus ciclos restantes continúan al reanudar) o `END` (la promoción termina con el motivo `PAUSE`). Se copia de la asociación del plan cuando se aplica la promoción.

**status** `enum`

`ACTIVE`, mientras queden ciclos. `COMPLETED`, cuando se usan todos los ciclos. `ENDED`, cuando la promoción termina antes de tiempo.

**applied\_at** `timestamp`

Cuándo se aplicó la promoción (ISO 8601).

Ejemplo: 2026-11-02T14:00:00Z

**ended\_at** `timestamp`

Cuándo terminó la promoción. `null` mientras está activa.

**end\_reason** `enum`

`null` mientras la promoción está activa. En otro caso, uno de estos: `REPLACED` (se aplicó otra promoción), `REMOVED` (se eliminó de la suscripción), `PLAN_CHANGE` (el plan cambió y la promoción terminó), `PAUSE` (la suscripción se pausó y `on_pause` es `END`) o `CANCELED` (la suscripción se canceló).

## Ejemplo

Una suscripción con una promoción de porcentaje, 2 de 3 ciclos usados:

```json Promotion object theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "id": "8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10",
  "name": "Welcome 20% x3",
  "discount": { "type": "PERCENTAGE", "value": 20 },
  "cycles": { "total": 3, "used": 2, "remaining": 1 },
  "on_pause": "KEEP",
  "status": "ACTIVE",
  "applied_at": "2026-11-02T14:00:00Z",
  "ended_at": null,
  "end_reason": null
}
```

Una promoción de monto fijo:

```json Fixed discount theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "discount": { "type": "FIXED", "amount": 15.00, "currency": "USD" }
}
```

## En webhooks

[`subscription.cycle_executed`](https://docs.y.uno/es/docs/webhooks/object-and-examples#subscription-cycle_executed) incluye un objeto `promotion` más corto en cada ciclo con descuento, con `id`, `discount_amount` y `cycles_remaining`.


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