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

# Promotions on subscription plans

> Attach a discount to a plan for a set number of charges and apply it to its subscriptions, without creating a new plan or changing the amount of each subscription

A promotion on a plan is a time-limited discount on top of the plan's price. For example, "50% off the first 3 months" lets you offer a starter price without creating a new plan, or changing the amount of each subscription with a PATCH. The plan keeps its full price. A subscription that has the promotion gets the discount on its next charges, and pays the full price again once the promotion's cycles are used.

> [!NOTE]
>
> **Where it is available**
>
> Subscription promotions run in the US region only. Promotions are turned on per organization. Until your organization has them on, attaching or applying a promotion returns `422 PROMOTION_NOT_APPLICABLE` with the reason `PROMOTIONS_NOT_ENABLED`. Ask your Technical Account Manager or Key Account Manager to turn them on.

## How it works

1. **Attach the promotion to a plan.** Call [Attach Promotion to Plan](https://docs.y.uno/reference/plans/attach-plan-promotion.md) with the `promotion_id` and `cycles`, the number of charges the discount covers. A promotion can be attached to several plans, each with its own `cycles`.
2. **Apply it to a subscription.** Send `promotion` when you [create the subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md), or [update it](https://docs.y.uno/reference/subscriptions/update-subscription.md) later. You can apply by `id`, or by `code` for promotion codes. The discount takes effect from the next charge.
3. **Each charge gets the discount.** After `cycles` counted charges, the promotion becomes `COMPLETED` and the subscription is charged the full price.

> [!NOTE]
>
> **The subscription keeps its own copy**
>
> When you apply a promotion, the subscription stores a copy of it: the promotion's ID, the discount, the number of cycles and the pause behavior. The copy is never edited. Removing the promotion from the plan, disabling it or letting it expire does not change the subscriptions that already have a copy.

## Example: 20% off for 3 months

A gym sells a monthly plan for USD 100.00. It attaches the promotion "Welcome 20% x3" to the plan with `cycles` set to 3, and applies it to a subscription:

| Charge | Full price | Discount | Net charged | Count |
| :- | :- | :- | :- | :- |
| Cycle 1 | USD 100.00 | USD 20.00 | USD 80.00 | 1 of 3 |
| Cycle 2 | USD 100.00 | USD 20.00 | USD 80.00 | 2 of 3 |
| Cycle 3 | USD 100.00 | USD 20.00 | USD 80.00 | 3 of 3, the promotion becomes `COMPLETED` |
| Cycle 4 | USD 100.00 | none | USD 100.00 | Full price |

Each discounted charge carries the full price in `amount`, the discount in `discount_amount`, and a `SUBSCRIPTION_PROMOTION` discount line. Yuno adds the line; you don't send it. The customer pays the net amount. This is the cycle 2 charge:

```json Cycle 2 charge theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "amount": { "currency": "USD", "value": 100.00 },
  "discount_amount": 20.00,
  "additional_data": {
    "order": {
      "discounts": [
        {
          "type": "SUBSCRIPTION_PROMOTION",
          "id": "8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10",
          "name": "Welcome 20% x3",
          "unit_amount": 20.00
        }
      ]
    }
  }
}
```

## Attach a promotion to a plan

Attaching makes the promotion available to the subscriptions on that plan. The request takes:

* `promotion_id`: the ID of an existing promotion.
* `cycles`: the number of charges the discount covers. At least 1.
* `on_pause` (optional): `KEEP` (default) or `END`. It decides what a pause does to the promotion. See [Pause, cancellation and reactivation](#pause-cancellation-and-reactivation).

The attachment is not edited. To change `cycles`, remove the attachment with [Remove Promotion from Plan](https://docs.y.uno/reference/plans/remove-plan-promotion.md) and attach it again. Removing an attachment does not change the subscriptions that already have the promotion.

[Retrieve Plan](https://docs.y.uno/reference/plans/retrieve-plan.md) returns the attached promotions in a `promotions` list. Each entry has a `status` of `ENABLED` or `DISABLED`, read from the promotions engine. If the engine does not respond, the entry's `status` is `UNKNOWN`.

Attaching fails when the promotion does not exist, has expired, or is already attached to the plan. See [Subscription promotion error codes](https://docs.y.uno/reference/subscriptions/subscription-promotion-error-codes.md).

## Apply a promotion to a subscription

Apply a promotion when you create a subscription, or later with an update. Both take a `promotion` object with either an `id` or a `code`:

```json Apply by ID theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{ "promotion": { "id": "8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10" } }
```

```json Apply by code theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{ "promotion": { "code": "WELCOME50" } }
```

The subscription must meet these conditions:

* It is `ACTIVE` or `TRIALING`. Otherwise the request returns `409 SUBSCRIPTION_STATUS_NOT_ELIGIBLE`.
* It is on a plan. Otherwise the request returns `422 PROMOTION_NOT_APPLICABLE` with the reason `SUBSCRIPTION_NOT_ON_A_PLAN`.
* The plan has the promotion attached. Otherwise the request returns `422 PROMOTION_NOT_ATTACHED_TO_PLAN`.
* The subscription does not have `frequency.execution` set to `MERCHANT`. Subscriptions with that setting, which covers subscriptions that a provider manages such as Pix Automático, are rejected with `422 PROMOTION_NOT_APPLICABLE` and the reason `EXECUTION_TYPE_NOT_SUPPORTED`.

The promotion's conditions (country, currency and amount, payment method type, BIN, and the type of the stored card) are checked once, when you apply the promotion. They are not checked again on renewals. A promotion that does not meet them returns `422 PROMOTION_NOT_APPLICABLE` with the reason `CONDITIONS_NOT_MET`. A fixed-amount discount needs an amount in the subscription's currency, or the request returns the reason `CURRENCY_MISMATCH`.

The first time a promotion is applied to a subscription, it uses one of the promotion's uses. Applying it again to the same subscription does not use another. When no uses are left, applying fails with the reason `USAGE_LIMIT_REACHED`.

A request that applies a promotion carries nothing else. Combined with `plan_change`, it answers `400 INVALID_PARAMETERS`. Combined with any other field such as `name` or `metadata`, it answers `400 BAD_REQUEST`. Either way nothing is changed. Send the other changes in a separate request.

A successful apply returns the subscription with a `promotion` object. See [The subscription promotion object](https://docs.y.uno/reference/subscriptions/the-subscription-promotion-object.md).

### Applying again replaces the current promotion

If a promotion is already active, applying another one (or the same one again) ends the current copy with `end_reason` `REPLACED`. The new copy starts with 0 cycles used. This is how you give a subscription more discounted charges. For example, a subscription on a USD 100.00 plan has "Welcome 20% x3" applied. Cycles 1 and 2 are charged USD 80.00 each. The promotion is applied again after cycle 2 is charged. The new copy starts at 0 cycles used, so the count restarts:

| Charge | Net charged | Count |
| :- | :- | :- |
| Cycle 1 | USD 80.00 | 1 of 3, first copy |
| Cycle 2 | USD 80.00 | 2 of 3, first copy, then `REPLACED` |
| Cycle 3 | USD 80.00 | 1 of 3, new copy |
| Cycle 4 | USD 80.00 | 2 of 3, new copy |
| Cycle 5 | USD 80.00 | 3 of 3, new copy, `COMPLETED` |
| Cycle 6 | USD 100.00 | Full price |

After a promotion is `COMPLETED` or `ENDED`, you can apply the same promotion or another one. The new copy starts at 0.

## What each charge carries

While the counted cycles are below `cycles`, each renewal charges the plan price minus the discount. The discount is calculated for each charge and stored, so a retry of the same charge uses the same amount. Renewals are not quoted, so they carry no `quote_id`: Yuno adds the `SUBSCRIPTION_PROMOTION` line from the subscription's copy of the promotion.

A cycle counts toward `cycles` when:

* The charge is approved.
* The cycle is a trial cycle. A trial cycle counts even though it has no payment.
* The cycle is a 100% cycle (see below).

A declined charge does not count. An approved retry counts once, with the same discounted amount. A late approved result counts when it arrives.

Once the counted cycles reach `cycles`, the promotion becomes `COMPLETED`. The next charge, and the ones after it, are charged the full price with no discount line.

Renewals do not call the promotions engine. An engine outage, or a promotion that is disabled, expired or removed from the plan, does not change the discount of a renewal that is already in progress. Renewals also do not check whether promotions are turned on for your organization.

### Rounding and amount types

* Percentages have at most 2 decimals, for example `12.5`.
* Fixed amounts have the currency's decimals, for example `25.00`.
* The discount is calculated with exact decimals and rounded half up to the currency's minor units (2 for USD). For example, 33% of USD 19.99 is 6.5967, which rounds to 6.60, so the charge is USD 13.39.
* A fixed discount larger than the price leaves the charge at 0. The cycle is then a 100% cycle.

### Trial periods

A promotion that applies to a trial phase, or to any other \$0 phase, applies to that same phase. The promotion exists on the subscription from the moment it is created, at 0 of `cycles` used, and the trial cycle counts as the first promotional cycle (1 of `cycles`). The trial cycle has no discount to subtract: nothing is charged for it.

For example, a plan of USD 100.00 with a 1-month trial and "50% x3" charges USD 0.00 in month 1 (1 of 3), USD 50.00 in months 2 and 3 (2 and 3 of 3), and USD 100.00 from month 4. With "50% x1", the trial cycle is the only promotional cycle: the promotion becomes `COMPLETED` after it, and month 2 is charged at USD 100.00.

For a plan with phases, the `subscription.cycle_executed` event of the trial cycle carries the `promotion` object with `discount_amount` 0.

### 100% cycles

If the discount covers the whole price, the cycle is not charged. It is marked `EXECUTED` with the reason `FULL_DISCOUNT`, it counts as used, and the subscription receives a [`subscription.cycle_executed`](https://docs.y.uno/docs/webhooks/events) webhook. For example, "Free first month" (100% x1) gives a first cycle that is executed with no charge and counts as 1 of 1.

### Plans with several price phases

On a plan with several price phases, the discount applies to the price of each phase. See [Plans](https://docs.y.uno/docs/payment-features/subscriptions/plans.md) for phases.

### Usage-based billing

On a plan with usage charges (meters), a promotion discounts only the plan price. It never discounts usage. See [Usage-based billing](https://docs.y.uno/docs/payment-features/subscriptions/usage-based-billing).

### Only the subscription's own promotion applies

A subscription charge uses only the subscription's own promotion. No other promotion, automatic or with a code, is added on top. The discounted amount is the one Yuno's subscription service calculates.

## Automatic promotions

A promotion of type `AUTOMATIC` applies without a code. When an `AUTOMATIC` promotion is attached to a plan, it applies once, when a subscription is created on that plan. Renewals do not evaluate it again, and subscriptions that were already on the plan do not receive it.

If the request that creates the subscription also sends a `promotion`, the larger discount wins. The two promotions do not stack.

If the `AUTOMATIC` promotion cannot be applied when the subscription is created, because it is disabled, expired, or has no uses left, the subscription is created without it, and the request still succeeds. If the promotions service does not respond, the creation fails with `503` or `504`, nothing is created, and the request can be retried. See [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md).

A subscription created with `first_period_paid` set to `true` has its first period paid outside Yuno. That period does not count toward the promotion, so the discount applies from the first renewal, for the number of cycles the promotion allows. No `subscription.cycle_executed` event is sent for that first period. `first_period_paid` needs a `subscription_agreement_id` and is not accepted on a plan that starts with a trial (400 `BAD_REQUEST` in both cases).

> [!WARNING]
>
> **An automatic plan promotion can also discount one-off payments**
>
> An `AUTOMATIC` promotion attached to a plan may also discount the account's one-off payments, that is, payments that are not subscription charges. Attaching a promotion to a plan does not limit it to subscriptions. Subscription charges still use only the subscription's own discount, as described above. For how one-off promotions work, see [Promotions](https://docs.y.uno/docs/payment-features/promotions).

## Plan changes

When you change a subscription's plan with the `plan_change` object of [Update Subscription](https://docs.y.uno/reference/subscriptions/update-subscription.md), you choose what happens to the active promotion. The choice has two fields:

* `promotion_behavior`: `KEEP` (default) keeps the promotion, with its remaining cycles, on the new plan. `END` ends it with the reason `PLAN_CHANGE`. The field is ignored when the subscription has no active promotion.
* `apply_new_plan_promotion`: `true` (default) applies the new plan's `AUTOMATIC` promotion, if it has one. The current promotion ends with `PLAN_CHANGE`, and the new plan's promotion starts at 0. `false` leaves the new plan's promotion unapplied, and `promotion_behavior` decides what happens to the current one.

The result depends on when the change takes effect:

| When the change takes effect | `effective` | `billing_cycle_behavior` | `promotion_behavior: KEEP` (default) | `promotion_behavior: END` |
| :- | :- | :- | :- | :- |
| Now, same date | `IMMEDIATE` | `KEEP` (default) | The next charge is the new price minus the discount. A percentage is recalculated on the new price. A fixed amount stays the same. | The next charge is the full price. |
| Now, restarting the cycle | `IMMEDIATE` | `RESTART` | The first charge on the new plan has the discount, and it counts. | The first charge on the new plan is the full price. |
| At the next cycle | `NEXT_BILLING_CYCLE` (default) | Not applicable | The promotion moves to the effective date. | The promotion stays active until the effective date and ends there. |

For example, Basic at USD 10.00 changes to Pro at USD 20.00 in the middle of a cycle. The subscription has "Welcome 20% x6" with 3 cycles already used. With `KEEP`, the next three charges are USD 16.00 each (4 of 6, 5 of 6 and 6 of 6), and then USD 20.00. With `END`, the promotion ends at the change, and every charge is USD 20.00.

Other rules:

* A change to another billing frequency, for example from monthly to annual, does not end the promotion by default. With `KEEP`, the remaining cycles continue on the new plan's billing cycles.
* A trial period on the new plan that is not skipped counts toward the remaining cycles.
* Cancelling a scheduled change also undoes the `promotion_behavior` choice.
* A plan in another currency is rejected with `400`.

Example: a Monthly subscription with "Welcome 20%" (1 of 3 cycles used) moves to Plus at USD 150.00, which has an `AUTOMATIC` "Plus 30%" for 2 cycles. By default (`apply_new_plan_promotion: true`), the subscription pays USD 105.00 for each of those 2 cycles, and then USD 150.00. With `apply_new_plan_promotion: false` and `promotion_behavior: KEEP`, it pays USD 120.00 for each of those 2 cycles, and then USD 150.00.

Changing a subscription that is already on a plan to another plan with [Change Subscription Plan](https://docs.y.uno/reference/subscriptions/change-subscription-plan.md) creates a new subscription and cancels the original. The original's promotion ends with the reason `CANCELED`, and it is not carried over. The new subscription gets the new plan's `AUTOMATIC` promotion, if it has one. A subscription that is not on a plan is attached to the plan in place: nothing is replaced or canceled, and no automatic promotion is added. To keep the current promotion of a subscription that is already on a plan, use a plan change with `promotion_behavior` set to `KEEP` instead.

## Pause, cancellation and reactivation

The `on_pause` value you chose when you attached the promotion decides what a pause does:

| `on_pause` | What happens when the subscription is paused |
| :- | :- |
| `KEEP` (default) | The promotion stays active. Its remaining cycles continue when the subscription resumes. |
| `END` | The promotion ends with the reason `PAUSE`. When the subscription resumes, it is charged the full price. |

Cancelling a subscription ends its promotion with the reason `CANCELED`. Reactivating the subscription does not restart the promotion.

## Remove a promotion from a subscription

Call [Remove Promotion from Subscription](https://docs.y.uno/reference/subscriptions/remove-subscription-promotion.md) to remove the active promotion. The promotion ends with the reason `REMOVED`, and the next charge is the full price. If the subscription has no active promotion, the request returns `409 SUBSCRIPTION_PROMOTION_NOT_ACTIVE`.

## Promotion states

An applied promotion is `ACTIVE` until its cycles are used, which makes it `COMPLETED`, or until it ends early, which makes it `ENDED`. The `end_reason` field tells you why it ended early:

| `end_reason` | When it happens |
| :- | :- |
| `REPLACED` | Another promotion, or the same one, is applied to the subscription. |
| `REMOVED` | The promotion is removed from the subscription. |
| `PLAN_CHANGE` | The plan changes and the promotion ends, with `promotion_behavior: END` or `apply_new_plan_promotion: true`. |
| `PAUSE` | The subscription is paused and `on_pause` is `END`. |
| `CANCELED` | The subscription is cancelled. |

| Event | Effect on the active promotion |
| :- | :- |
| Charge approved, or trial cycle | One cycle counts. When the count reaches `cycles`, the promotion becomes `COMPLETED`. |
| Charge declined | Nothing. The cycle does not count. |
| Approved retry | The cycle counts once, with the same discounted amount. |
| Late approved result | The cycle counts when the result arrives. |
| Promotion removed from the plan, disabled, or expired | Nothing. The copy on the subscription continues. |
| Organization turned off | No new promotions can be applied. Promotions in progress continue. |

## Webhooks

| Event | When it is sent | Promotion data |
| :- | :- | :- |
| `subscription.promotion_applied` | A promotion is applied to a subscription: at creation (a promotion you send or the plan's `AUTOMATIC` promotion), when a payment link creates the subscription, with [Update Subscription](https://docs.y.uno/reference/subscriptions/update-subscription.md), including a re-apply that replaces the current promotion, and on a plan change with `apply_new_plan_promotion`. Select the `PROMOTION_APPLIED` trigger to receive it. | `promotion`, the [subscription promotion object](https://docs.y.uno/reference/subscriptions/the-subscription-promotion-object.md), in `data` and inside `data.subscription`. |
| `subscription.cycle_executed` | A cycle of a subscription with a promotion is charged or executed, including a 100% cycle. A full-price charge with no promotion does not send this event. | `promotion` with `id`, `discount_amount` and `cycles_remaining`. |

There is no event when a promotion ends. To see the state of a promotion, read the subscription. For the full list of events, see [Events and Triggers](https://docs.y.uno/docs/webhooks/events.md).

## Payment links and checkout

A subscription created from a payment link can carry a promotion on its first payment. In checkout and payment links, only `AUTOMATIC` promotions and the promotion the merchant sets on the link apply. The buyer cannot enter a code.

The promotion is copied to the subscription when the link creates it, before the buyer pays. Subscription payment links today are single-use, save the card, require an identified customer, and accept cards only. Promotions on these links follow the same conditions.

To attach a promotion to a link, send `promotion` inside the `subscription` object of [Create Payment Link](https://docs.y.uno/reference/payment-links/create-payment-link.md), with either an `id` or a `code`. The merchant sets it on the link, and the buyer has no code field.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{ "subscription": { "promotion": { "id": "8f2d6c1e-3b7a-4c55-9a1e-2f4d8b7c6a10" } } }
```

A promotion sent by `code` is counted when the link is created. A single-use code therefore cannot be used on a second link: that link answers `422 PROMOTION_NOT_APPLICABLE` with the reason `USAGE_LIMIT_REACHED`, and no subscription is created. A link that is never paid still uses up its code. A promotion sent by `id`, and an `AUTOMATIC` promotion, is counted when the subscription activates, so an unpaid link does not use it up.

On a link's first payment, Yuno checks the promotion before it charges anything. If the check cannot be completed, the payment is refused with `422 PROMOTION_ENGINE_UNAVAILABLE`. If the payment's amount or promotion does not match the subscription's first charge, it is refused with `422 PROMOTION_CONTEXT_MISMATCH`. In both cases nothing is charged.

## Not supported in this release

* Two promotions on the same subscription at once. Applying a new one replaces the current one.
* Proration. A plan change is not charged in proportion to the time used.
* Scheduling a promotion for a future date. A promotion applies from the next charge.
* Editing an attachment or the copy on a subscription. Remove and attach again instead.
* Subscriptions created with a single-step flow, such as a payment that creates the subscription, for example Pix Automático.
* Turning off all the promotions in progress for a merchant at once. Turning the feature off stops new applications only.
* Subscriptions with `frequency.execution` set to `MERCHANT`, which covers subscriptions that a provider manages, such as Pix Automático.

## Errors

The error codes, their HTTP statuses and the reasons for `PROMOTION_NOT_APPLICABLE` are listed in [Subscription promotion error codes](https://docs.y.uno/reference/subscriptions/subscription-promotion-error-codes.md).

## Related

* [Plans](https://docs.y.uno/docs/payment-features/subscriptions/plans.md)
* [Promotions](https://docs.y.uno/docs/payment-features/promotions) (promotions on one-off payments)
* [Attach Promotion to Plan](https://docs.y.uno/reference/plans/attach-plan-promotion.md)
* [Remove Promotion from Plan](https://docs.y.uno/reference/plans/remove-plan-promotion.md)
* [Remove Promotion from Subscription](https://docs.y.uno/reference/subscriptions/remove-subscription-promotion.md)
* [The Subscription Promotion Object](https://docs.y.uno/reference/subscriptions/the-subscription-promotion-object.md)


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