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

# The Subscription Promotion Object

> Documents the promotion object on a subscription: the discount, the cycles used, the pause behavior and how the promotion ended

When a promotion is applied to a subscription, Yuno stores a copy of it on the subscription. The copy is the `promotion` object. [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) and [Update Subscription](https://docs.y.uno/reference/subscriptions/update-subscription.md) return it. The copy is never edited: changing the plan's attachment or the promotion afterwards does not change it. See [Promotions on subscription plans](https://docs.y.uno/docs/payment-features/subscriptions/promotions.md).

## Attributes

**id** `string`

The ID of the promotion (UUID).

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

**name** `string`

The name of the promotion.

Example: Welcome 20% x3

**discount** `object`

The discount. The fields depend on `type`.

**properties**

**type** `enum`

`PERCENTAGE` or `FIXED`.

**value** `number`

`PERCENTAGE` only. The percentage, from 0 to 100, with at most 2 decimals.

Example: 20

**amount** `number`

`FIXED` only. The amount, with the currency's decimals.

Example: 15.00

**currency** `string`

`FIXED` only. The ISO 4217 currency of `amount`.

Example: USD

**cycles** `object`

The number of charges the discount covers.

**properties**

**total** `integer`

The number of cycles the promotion covers, set when it was attached to the plan.

**used** `integer`

Cycles counted since it was applied: approved charges, trial cycles and 100% cycles. A declined charge does not count. A retry of the same charge counts once.

**remaining** `integer`

`total` minus `used`.

**on\_pause** `enum`

What a pause does to the promotion: `KEEP` (its remaining cycles continue on resume) or `END` (the promotion ends with the reason `PAUSE`). It is copied from the plan's attachment when the promotion is applied.

**status** `enum`

`ACTIVE`, while cycles remain. `COMPLETED`, when all cycles are used. `ENDED`, when the promotion ends early.

**applied\_at** `timestamp`

When the promotion was applied (ISO 8601).

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

**ended\_at** `timestamp`

When the promotion ended. `null` while it is active.

**end\_reason** `enum`

`null` while the promotion is active. Otherwise one of: `REPLACED` (another promotion was applied), `REMOVED` (removed from the subscription), `PLAN_CHANGE` (the plan changed and the promotion ended), `PAUSE` (the subscription was paused and `on_pause` is `END`), or `CANCELED` (the subscription was canceled).

## Example

A subscription with a percentage promotion, 2 of 3 cycles used:

```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
}
```

A fixed-amount promotion:

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

## In webhooks

[`subscription.cycle_executed`](https://docs.y.uno/docs/webhooks/object-and-examples#subscription-cycle_executed) carries a shorter `promotion` object on each discounted cycle, with `id`, `discount_amount` and `cycles_remaining`.


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