Skip to main content
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.
Where it is availableSubscription 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 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, or update it 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.
The subscription keeps its own copyWhen 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: 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:
Cycle 2 charge

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.
The attachment is not edited. To change cycles, remove the attachment with Remove Promotion from Plan and attach it again. Removing an attachment does not change the subscriptions that already have the promotion. Retrieve Plan 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.

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:
Apply by ID
Apply by code
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.

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

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. 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).
An automatic plan promotion can also discount one-off paymentsAn 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.

Plan changes

When you change a subscription’s plan with the plan_change object of Update Subscription, 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: 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 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: 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 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:

Webhooks

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. 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, with either an id or a code. The merchant sets it on the link, and the buyer has no code field.
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.