The Promotion Object

Promotions is enabled per organizationPromotions 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.

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.

string

The unique identifier of the promotion (UUID). Assigned by Yuno.Example: b7c1a4f2-6e0d-4a3b-9c55-1f2e7d8a0b31

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

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

string

Shown with the name on the quote. Optional, up to 1000 characters. null when you don’t set one.

object

The window in which the promotion runs. Always UTC.

Show properties

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

timestamp

When the promotion ends (ISO 8601). null means no end date. Must be after starts_at.Example: 2026-11-01T02:59:59Z

object

How the promotion is redeemed.

Show properties

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.

string

Reserved for promotion codes. Always null today.

object

What the customer saves.

Show properties

enum

Possible values:

PERCENTAGE = A percentage of the payment amount, set in value.
FIXED = A fixed amount per currency, set in amounts.

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

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

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.

Show properties

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.

Show properties

Array of strings

BIN prefixes (6 to 8 digits each).

Array of objects

Inclusive BIN ranges. Each entry has start and end (8 digits).

object

Show properties

Array of strings

Payment method types, for example CARD. See Payment type list.

object

Show properties

Array of strings

Card types, for example CREDIT or DEBIT. A card whose type is unknown never meets this condition.

object

Show properties

Array of strings

Payment countries (ISO 3166-1).

object

Show properties

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.

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.

timestamp

When the promotion was created (ISO 8601, UTC). When two promotions save the same amount, the oldest one applies.

timestamp

When you disabled the promotion (ISO 8601, UTC). null while the promotion is not disabled. The only field that changes after creation.

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

{
  "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
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Attributes

Limits

How a promotion is chosen

Example

​Attributes

​Limits

​How a promotion is chosen

​Example

Attributes

Limits

How a promotion is chosen

Example