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
- Attach the promotion to a plan. Call Attach Promotion to Plan with the
promotion_idandcycles, the number of charges the discount covers. A promotion can be attached to several plans, each with its owncycles. - Apply it to a subscription. Send
promotionwhen you create the subscription, or update it later. You can apply byid, or bycodefor promotion codes. The discount takes effect from the next charge. - Each charge gets the discount. After
cyclescounted charges, the promotion becomesCOMPLETEDand 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 withcycles 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) orEND. It decides what a pause does to the promotion. See Pause, cancellation and reactivation.
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 apromotion object with either an id or a code:
Apply by ID
Apply by code
- It is
ACTIVEorTRIALING. Otherwise the request returns409 SUBSCRIPTION_STATUS_NOT_ELIGIBLE. - It is on a plan. Otherwise the request returns
422 PROMOTION_NOT_APPLICABLEwith the reasonSUBSCRIPTION_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.executionset toMERCHANT. Subscriptions with that setting, which covers subscriptions that a provider manages such as Pix Automático, are rejected with422 PROMOTION_NOT_APPLICABLEand the reasonEXECUTION_TYPE_NOT_SUPPORTED.
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 withend_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 belowcycles, 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).
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 ofcycles 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 markedEXECUTED 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 typeAUTOMATIC 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).
Plan changes
When you change a subscription’s plan with theplan_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.ENDends it with the reasonPLAN_CHANGE. The field is ignored when the subscription has no active promotion.apply_new_plan_promotion:true(default) applies the new plan’sAUTOMATICpromotion, if it has one. The current promotion ends withPLAN_CHANGE, and the new plan’s promotion starts at 0.falseleaves the new plan’s promotion unapplied, andpromotion_behaviordecides what happens to the current one.
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_behaviorchoice. - A plan in another currency is rejected with
400.
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
Theon_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 reasonREMOVED, 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 isACTIVE 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.
Payment links and checkout
A subscription created from a payment link can carry a promotion on its first payment. In checkout and payment links, onlyAUTOMATIC 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.
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.executionset toMERCHANT, which covers subscriptions that a provider manages, such as Pix Automático.
Errors
The error codes, their HTTP statuses and the reasons forPROMOTION_NOT_APPLICABLE are listed in Subscription promotion error codes.
Related
- Plans
- Promotions (promotions on one-off payments)
- Attach Promotion to Plan
- Remove Promotion from Plan
- Remove Promotion from Subscription
- The Subscription Promotion Object