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

# Subscription Promotion Error Codes

> Error codes and reasons for promotions on subscription plans: attaching, applying, removing and plan changes

Errors for promotions on subscription plans use the standard error format: a `code` and a `messages` array. Errors about the subscription's status also include `current_status`. A `422` with the code `PROMOTION_NOT_APPLICABLE` also includes a `reason`; the other `422` codes carry a `code` and `messages` only.

```json 422 Not Applicable theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "PROMOTION_NOT_APPLICABLE",
  "messages": [
    "The promotion cannot be applied to this subscription."
  ],
  "reason": "CONDITIONS_NOT_MET"
}
```

## Error codes

| HTTP | `code` | When |
| :- | :- | :- |
| `400` | `INVALID_PARAMETERS` | An update sends `promotion` together with `plan_change`. Nothing is changed. Send them in two requests. |
| `400` | `BAD_REQUEST` | An update sends `promotion` together with any other field, such as `name` or `metadata`. Nothing is changed. Send the other changes in a separate request. |
| `404` | `PROMOTION_NOT_FOUND` | The promotion ID or code is unknown, or belongs to another account. |
| `409` | `PROMOTION_ALREADY_ATTACHED` | The plan already has this promotion. |
| `422` | `PROMOTION_NOT_ATTACHED_TO_PLAN` | The promotion is applied to a subscription whose plan does not have it. |
| `422` | `PROMOTION_NOT_APPLICABLE` | The promotion cannot be attached or applied. The `reason` says why (see below). |
| `409` | `SUBSCRIPTION_STATUS_NOT_ELIGIBLE` | The subscription is not `ACTIVE` or `TRIALING`. The response includes `current_status`. |
| `409` | `SUBSCRIPTION_PROMOTION_NOT_ACTIVE` | The request removes a promotion, but the subscription has no active promotion. The response includes `current_status`: the status of the latest promotion (`COMPLETED` or `ENDED`), or `null` if there was none. |
| `422` | `PROMOTION_ENGINE_UNAVAILABLE` | On a payment link's first payment, the promotion could not be checked. The payment is refused, and nothing is charged. |
| `422` | `PROMOTION_CONTEXT_MISMATCH` | On a payment link's first payment, the payment's amount or promotion does not match the subscription's first charge. The payment is refused, and nothing is charged. |
| `503` | `PROMOTION_ENGINE_UNAVAILABLE` | The promotions engine did not respond when the promotion was attached or applied. |
| `504` | `PROMOTION_ENGINE_TIMEOUT` | The promotions engine did not respond in time when the promotion was attached or applied. |

## Reasons for `PROMOTION_NOT_APPLICABLE`

| `reason` | Meaning |
| :- | :- |
| `EXPIRED` | The promotion has expired. |
| `DISABLED` | The promotion is disabled. |
| `NOT_STARTED` | The promotion's start date has not arrived yet. |
| `USAGE_LIMIT_REACHED` | The promotion has no uses left. |
| `CONDITIONS_NOT_MET` | The subscription does not meet the promotion's conditions: country, currency and amount, payment method type, BIN, or the type of the stored card. Conditions are checked only when the promotion is applied, not on renewals. |
| `CURRENCY_MISMATCH` | A fixed-amount promotion has no amount in the subscription's currency. |
| `PROMOTIONS_NOT_ENABLED` | Promotions are not turned on for your organization, or the region does not support them. Subscription promotions run in the US region only. |
| `EXECUTION_TYPE_NOT_SUPPORTED` | The subscription has `frequency.execution` set to `MERCHANT`. This covers subscriptions that a provider manages, such as Pix Automático. |
| `SUBSCRIPTION_NOT_ON_A_PLAN` | The subscription is not on a plan. Promotions apply only to subscriptions on a plan. |
| `ZERO_DISCOUNT` | The promotion gives no discount on the subscription's price. |
| `IDEMPOTENCY_KEY_REUSED` | The subscription already used this promotion with a different code. |

## Related

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


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