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

# The Promotion Object

> Documents the promotion object's attributes: discount, schedule, conditions, and status.

<Warning>
  **Promotions is enabled per organization**

  Promotions works only after Yuno enables it for your organization: the Promotions section of the Dashboard and the quote your payments use. Ask your Technical Account Manager or Key Account Manager. See [Promotions](/docs/payment-features/promotions#enable-promotions-for-your-organization).
</Warning>

## Attributes

A promotion is a discount with a date window and a set of conditions. You create, view and disable promotions in the Yuno Dashboard, and this page describes their attributes. A promotion can't be edited after you create it: the only change is to disable it.

<ParamField body="id" type="string">
  The unique identifier of the promotion (UUID). Assigned by Yuno.

  Example: b7c1a4f2-6e0d-4a3b-9c55-1f2e7d8a0b31
</ParamField>

<ParamField body="account_id" type="string">
  The account the promotion applies to (UUID). One promotion belongs to one account. If you run the same campaign on several accounts, create it once per account.

  Example: 493e9374-510a-4201-9e09-de669d75f256
</ParamField>

<ParamField body="name" type="string">
  The promotion name (1 to 255 characters). The checkout shows it as the title of the discount in the order summary.

  Example: 10% off with credit cards - Mother's Day
</ParamField>

<ParamField body="description" type="string">
  Shown with the name on the quote. Optional, up to 1000 characters. `null` when you don't set one.
</ParamField>

<ParamField body="schedule" type="object">
  The window in which the promotion runs. Always UTC.

  <Expandable title="properties">
    <ParamField body="starts_at" type="timestamp">
      When the promotion starts (ISO 8601). Any instant: a start in the past makes the promotion active at once, or expired at once if `ends_at` has also passed.

      Example: 2026-10-01T03:00:00Z
    </ParamField>

    <ParamField body="ends_at" type="timestamp">
      When the promotion ends (ISO 8601). `null` means no end date. Must be after `starts_at`.

      Example: 2026-11-01T02:59:59Z
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="redemption" type="object">
  How the promotion is redeemed.

  <Expandable title="properties">
    <ParamField body="mode" type="enum">
      Always `AUTOMATIC` today: the promotion applies by itself to every payment that meets the conditions, and the customer types nothing. Promotion codes aren't available yet: the Dashboard creates `AUTOMATIC` promotions only.
    </ParamField>

    <ParamField body="code" type="string">
      Reserved for promotion codes. Always `null` today.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="discount" type="object">
  What the customer saves.

  <Expandable title="properties">
    <ParamField body="type" type="enum">
      Possible values:

      * `PERCENTAGE` = A percentage of the payment amount, set in `value`.
      * `FIXED` = A fixed amount per currency, set in `amounts`.
    </ParamField>

    <ParamField body="value" type="number">
      `PERCENTAGE` only. Greater than 0 and up to 100, with up to two decimals. More decimals are rejected. `null` for a fixed discount.

      Example: 10.5
    </ParamField>

    <ParamField body="amounts" type="Array of objects">
      `FIXED` only: one `{ currency, value }` per currency (ISO 4217), each above zero. Required for fixed discounts. `null` for a percentage discount. A fixed promotion applies only to payments in the currencies it lists, and the discount is capped at the payment amount. When the promotion also has an `amounts` condition, `discount.amounts` and `conditions.amounts.values` must list the same currencies, or Yuno rejects the promotion.

      Example: `[{ "currency": "USD", "value": 30.00 }]`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="conditions" type="object">
  The conditions a payment must meet. **AND** across keys, **OR** inside each key's `values` list. Omit a key or send `null` for no condition on that dimension; an empty `values` list is rejected. An empty `conditions` object (`{}`) applies to every payment of the account.

  <Expandable title="properties">
    <ParamField body="bins" type="object">
      Card BIN condition. A card matches when its BIN starts with a prefix in `values` (a prefix covers its whole range) or falls in a `ranges` entry. A 6-digit BIN on the quote matches only the conditions that cover its whole 6-digit block, so send 8 digits to match an 8-digit prefix or a narrower range. When `bins` is present, at least one of `values` or `ranges` must be non-empty.

      <Expandable title="properties">
        <ParamField body="values" type="Array of strings">
          BIN prefixes (6 to 8 digits each).
        </ParamField>

        <ParamField body="ranges" type="Array of objects">
          Inclusive BIN ranges. Each entry has `start` and `end` (8 digits).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="payment_methods" type="object">
      <Expandable title="properties">
        <ParamField body="values" type="Array of strings">
          Payment method types, for example `CARD`. See [Payment type list](/reference/payment-type-list).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="card_types" type="object">
      <Expandable title="properties">
        <ParamField body="values" type="Array of strings">
          Card types, for example `CREDIT` or `DEBIT`. A card whose type is unknown never meets this condition.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="countries" type="object">
      <Expandable title="properties">
        <ParamField body="values" type="Array of strings">
          Payment countries ([ISO 3166-1](/reference/country-reference)).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="amounts" type="object">
      <Expandable title="properties">
        <ParamField body="values" type="Array of objects">
          Amount bounds per currency: `currency`, `min`, and `max` (both inclusive; `null` means no bound on that side). An entry with both `min` and `max` null filters by currency only.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status" type="enum">
  Computed from `schedule` at the moment you read the promotion.

  Possible values:

  * `SCHEDULED` = `starts_at` is in the future.
  * `ACTIVE` = Running now. Payments that meet the conditions get a quote.
  * `EXPIRED` = `ends_at` has passed.
  * `DISABLED` = You disabled it. Final.
</ParamField>

<ParamField body="created_at" type="timestamp">
  When the promotion was created (ISO 8601, UTC). When two promotions save the same amount, the oldest one applies.
</ParamField>

<ParamField body="disabled_at" type="timestamp">
  When you disabled the promotion (ISO 8601, UTC). `null` while the promotion is not disabled. The only field that changes after creation.
</ParamField>

## Limits

A promotion holds up to 500 BIN prefixes, 100 BIN ranges, 20 payment method types, 10 card types and 250 countries, and up to 50 currencies in the amount condition and in a fixed discount. Money amounts use the whole minor units of their currency.

## How a promotion is chosen

One payment gets one promotion. When two or more match, Yuno applies the one with the **biggest saving** for the customer, then the oldest, then the smallest `id`. A fixed discount is capped at the payment amount, but a promotion never makes a charge of zero: a quote whose charge would be zero answers `204`. A promotion whose discount is zero doesn't apply.

## Example

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "id": "b7c1a4f2-6e0d-4a3b-9c55-1f2e7d8a0b31",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "name": "10% off with credit cards - Mother's Day",
  "description": "Card deal, claimed monthly.",
  "schedule": { "starts_at": "2026-10-01T03:00:00Z", "ends_at": "2026-11-01T02:59:59Z" },
  "redemption": { "mode": "AUTOMATIC", "code": null },
  "discount": { "type": "PERCENTAGE", "value": 10, "amounts": null },
  "conditions": {
    "bins": {
      "values": ["457896", "40263412"],
      "ranges": [{ "start": "45780000", "end": "45789999" }]
    },
    "payment_methods": { "values": ["CARD"] },
    "card_types": { "values": ["CREDIT"] },
    "countries": { "values": ["AR"] },
    "amounts": { "values": [{ "currency": "USD", "min": 100.00, "max": 5000.00 }] }
  },
  "status": "SCHEDULED",
  "created_at": "2026-09-14T12:04:18Z",
  "disabled_at": null
}
```


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