SUMMER10 for “10% off in summer”. You create the promotion with the API, your customer gives you the code, and your server sends the code on Create Payment. Yuno prices the payment with the code and charges the discounted amount.
How it works
- Create the promotion. Call Create Promotion with
redemption.modeset toCODE. You set the discount, the dates, the conditions, and, if you want a cap, the most uses (limits.total). You also send exactly one of two things: a code of your own (redemption.code), or a prefix (redemption.prefix). With a prefix, Yuno builds the code from it. - Collect the code. Your customer gives you the code in your own checkout.
- Send the code on the payment. Add
{ "code": "SUMMER10" }toadditional_data.order.discountson Create Payment, with the originalamount. - Yuno charges the discounted price. Yuno exchanges the code for a quote, counts one use of the code when the code applies, and charges the quoted amount. The answer is the one in What the payment carries.
Create a code promotion
Send the promotion toPOST /v1/promotions. The promotion belongs to the account in the X-Account-Code header. A body that carries account_id is refused with 400 INVALID_PARAMETERS.
Request
Response (201)
X-Idempotency-Keyis required. It is any text of 1 to 64 characters. The same key on the same account returns the first promotion with201, and Yuno does not compare the body. A request with no valid key is refused with400before the body is read.- The mode is
CODE. Any otherredemption.modeis refused with400 INVALID_PARAMETERS. - A code you send has 3 to 32 characters: letters, digits,
_and-, in any case. Yuno trims the spaces around it, stores it in upper case and matches the code of a payment without regard to case. A code with another length is refused with400 INVALID_REQUESTand the messageredemption.code: CODE_LENGTH, and a code with another character withredemption.code: CODE_CHARACTERS. - A code is unique per account. Another promotion of the account that is not disabled and whose schedule overlaps this one cannot hold the same code, and no batch code of the account can hold it either: the request answers
409 CODE_ALREADY_EXISTS. A code is free again when the earlier promotion is disabled, or when its schedule ends at or before the start of the new one. - Conditions are
countriesandamountsonly. A code applies to the whole payment, whatever the payment method. Abins,payment_methodsorcard_typescondition is refused with400 INVALID_REQUESTand the messagesconditions.bins: FORBIDDEN,conditions.payment_methods: FORBIDDENorconditions.card_types: FORBIDDEN. limits.totalis optional. It is the most uses the code accepts, a whole number from 1 to 2147483647. Without it the code has no cap and the response showslimits: null. See Uses and limits.- Promotions can’t be edited, and there is no delete. The only change is Disable Promotion, and it is final. To change a discount, disable the promotion and create a new one.
AUTOMATIC promotions. The Promotion Object describes every field.
Let Yuno build the code from a prefix
Send exactly one ofredemption.code and redemption.prefix. The prefix has 1 to 8 letters or digits (A-Z, a-z, 0-9), in any case, and Yuno converts it to upper case. Yuno builds the code from it: the prefix, then a random suffix of 5 characters from ABCDEFGHJKMNPQRSTUVWXYZ23456789 (the letters and digits without 0, O, 1, I and L), with nothing between them. The code is not linked to the promotion id. The answer holds the code in redemption.code, and Retrieve Promotion returns the same code. This request sends a prefix:
Request body, with a prefix
Response (201), with the code Yuno built
- Send a code or a prefix, not both and not none. A body with neither answers
400 INVALID_REQUESTwith the messagesredemption: CODE_OR_PREFIX_REQUIREDandSend exactly one of redemption.code or redemption.prefix.. A body with both answersredemption: CODE_AND_PREFIX_EXCLUSIVEwith the same second message. Anull, an empty text and a text with only spaces count as not sent. Acodethat is not valid, sent with a prefix, counts as both. - A wrong prefix is refused. A character outside
A-Z,a-zand0-9answersredemption.prefix: FORMAT. More than 8 characters answersredemption.prefix: LENGTH. - A create with a prefix never answers
409 CODE_ALREADY_EXISTS. That answer is for a code you send. Yuno never builds a code that another promotion of your account holds, whatever its status: active, scheduled, ended or disabled, and no batch code of your account holds it. If the code Yuno draws is taken, Yuno draws another, up to six draws. If none of the six is free, the create fails (see below). - A replay returns the same code. The same
X-Idempotency-Keyon the same account returns the first promotion with201and the code Yuno built for it. The replay keeps that code and stores nothing, also when its prefix is different. - You can’t change the code. A promotion can’t be edited, so its code can’t change, whether Yuno built the code or you sent it. To get another code, disable the promotion and create a new one.
- If Yuno can’t build a code, the create fails. The answer is
500 INTERNAL_ERROR, and Yuno stores nothing. The failure is on Yuno’s side: retry the request.
Create a batch of codes
A batch gives one code promotion many codes at once, for example one code for each customer of a campaign. Each code of the batch has its own limit of uses, and the promotion keeps its total limit. Create Promotion Codes makes the batch, and List Promotion Codes reads the codes back. The request sends theX-Account-Code and X-Idempotency-Key headers, both required, and a body with quantity and prefix:
Request body
quantityis required. It is the number of codes in the batch, a whole number from 1 to 1000. A missing value answersquantity: REQUIRED, and a value outside that range answersquantity: RANGE. Both are400 INVALID_REQUEST.prefixis required. It has 1 to 8 letters or digits (A-Zand0-9), in any case, and Yuno converts it to upper case. A missing or blank prefix answersprefix: REQUIRED. A character outsideA-Zand0-9answersprefix: FORMAT, and more than 8 characters answerprefix: LENGTH.uses_per_codeis optional. It is how many payments each code accepts, a whole number from 1 to 1000000. Without it, each code accepts one payment. A value outside that range answersuses_per_code: RANGE.- A full code is refused. Yuno makes every code of a batch from the prefix, so a body with a
codeanswers400 INVALID_REQUESTwithcode: NOT_ALLOWED.
ABCDEFGHJKMNPQRSTUVWXYZ23456789, the letters and digits without 0, O, 1, I and L. Its length depends on the quantity of the request: Yuno takes the shortest suffix that has at least one million possible values for each code. That is 5 characters for up to 28 codes, 6 characters for 29 to 887 codes, and 7 characters for 888 to 1000 codes.
Response, 201
- The same key returns the same batch. A repeated
X-Idempotency-Keyon the same promotion returns the first batch with201, with the same codes. Yuno does not compare the body. - Every code is unique in the account. No code of the batch is a code that a promotion of your account holds, whatever the status of that promotion, and no code of another batch. A code you send, and a code Yuno builds from a prefix, can’t be a batch code either.
- A promotion holds up to 10,000 batch codes. A batch that would take the promotion past 10,000 codes answers
422 PROMOTION_NOT_APPLICABLEwith the reasonBATCH_LIMIT_REACHED, and stores nothing. - Only a code promotion holds a batch. An
AUTOMATICpromotion has no code, and it answers422 PROMOTION_NOT_APPLICABLEwith the reasonNOT_CODE_PROMOTION. A disabled promotion answersDISABLED, and an ended one answersEXPIRED. - Keep the codes secret. Each code works as a credential. The codes come back only in this answer and in List Promotion Codes, and Yuno does not write them to its logs.
Read the codes
List Promotion Codes returns the codes of a promotion, oldest first.limit takes 1 to 500 and defaults to 100, and next_cursor is null on the last page. Each code shows its uses_per_code and its used count. A disabled promotion lists its codes too.
Send the code on the payment
Put the code on a discount line of Create Payment (POST /v1/payments). Send the original amount, never the discounted one.
Request
X-Idempotency-Key on the request, as on every payment.
The discount line follows these rules. A line that breaks one is refused with 400 INVALID_PARAMETERS before anything else happens, and no payment is created.
A code on a
MERCHANT line is ignored. Yuno reads a line as MERCHANT when its type is MERCHANT, or when it has no type and carries an id or a name. Yuno drops the code of such a line without an error: no promotion is applied, and the payment goes on without that discount. To redeem a code, send it on a line with no id, name or unit_amount, and with type left out or set to YUNO_PROMOTION.
No answer repeats your code. Where the promotions service quotes it back in a message, Yuno replaces it with ***.
What Yuno does with the code
Yuno handles the line before it creates the payment and before it tokenizes the card:- It checks the rules above. A break is a
400. - It checks that Promotions is enabled for your organization, and that the payment can carry a code. See Payments that can’t carry a code.
- It asks the promotions service for a quote with your account, the payment
amount, thecountryand the code. It sends theX-Idempotency-Keyof your payment, so the service counts one use for the payment. - When the service gives a quote, Yuno replaces the code with the quote on the discount line, and the payment goes on as a payment with a quote. Yuno does not send the code on with the payment.
- When the service gives no quote, Yuno refuses the payment, and the answer says why (see Answers). No payment is created. Yuno never charges the full price for a payment whose
YUNO_PROMOTIONline carries a code. A code on aMERCHANTline is ignored (see the note after the rules table).
payment_method.typeis not required for a code. A code applies to the whole payment, whatever the payment method. Yuno sends the type to the promotions service only when your payment has one.- A card number or token goes to the quote as the payment carries it. Yuno sends the BIN (the first 8 digits at most) of a card number sent in the clear, never the number. A token or vaulted token goes as it is.
- The
X-Idempotency-Keyis required. Create Payment requires it on every payment: without the header the answer is400 INVALID_PARAMETERSandThe header 'x-idempotency-key' is required.Yuno also trims the key before it counts a use, and a key that is empty after the trim is refused with400 INVALID_PARAMETERS:The header 'x-idempotency-key' is required to apply a promotion code.
Dry run
A dry run takes no promotion code. A payment with the headerX-Dry-Run: true that carries a code on a YUNO_PROMOTION line is refused with 400 INVALID_PARAMETERS, and no payment is created:
Dry run with a code (400)
true, in any case, makes a dry run. A dry run without a code, or with a quote_id line, is not affected. To try a promotion code, use the sandbox environment.
Show the price before the payment
To show the discounted price before your customer pays, call Create Promotion Quote with thecode. That endpoint sends no idempotency key, so the answer is a preview: the promotion, original_amount, discount_amount and charge_amount, with no quote_id and no expires_at. Yuno signs, stores and counts nothing.
A preview can’t be paid: there is no quote_id to put on a discount line. The payment carries the code itself, as described in Send the code on the payment.
Uses and limits
- A use is counted when Yuno accepts the code for a payment. The count happens at the payment attempt, before the payment reaches a provider, and it is keyed by the
X-Idempotency-Keyof the payment. - The same key again counts no second use. A retry of a payment with the same key and the same code is priced from the first use. This holds even if the promotion was disabled, ended or reached its limit after the first attempt.
- A key belongs to one code. The same key with another code is refused with
422 PROMOTION_NOT_APPLICABLEand the reasonIDEMPOTENCY_KEY_REUSED. - A code that leaves a charge of zero counts no use. When the code is the promotion that applies and the payment would be charged zero or less (a 100% discount, or a fixed discount at or above the amount), Yuno refuses the payment with
422 PROMOTION_NOT_APPLICABLEand the reasonZERO_CHARGEbefore it counts a use. This holds for a code with a limit and for one without. A code at its limit that also leaves a charge of zero answersZERO_CHARGE, notUSAGE_LIMIT_REACHED. - A declined payment keeps its use. Yuno gives no use back. The count only grows. A new attempt after a decline needs a new
X-Idempotency-Key, and it counts a new use. - The limit stops the next use. When
limits.usedequalslimits.total, a payment with the code is refused with422 PROMOTION_NOT_APPLICABLEand the reasonUSAGE_LIMIT_REACHED. No payment is created. limits.usedcounts the uses of a code that has a limit. A code with no limit showslimits: null.- Only the promotion that applies counts a use. When an automatic promotion gives the customer a bigger discount than the code, that promotion applies and the code counts no use. See When a code and an automatic promotion both apply.
- A batch code counts against its own limit and the total limit, in one step. A payment that takes a batch code adds one to the
usedcount of the code and, when the promotion haslimits.total, one tolimits.used. Both counts happen or neither does. A code at its limit, or a promotion at its total limit, refuses the payment with422 PROMOTION_NOT_APPLICABLEand the reasonUSAGE_LIMIT_REACHED. See Create a batch of codes. - A quote request counts no use. Create Promotion Quote sends no key, so a quote made with a
codeis a preview: Yuno signs, stores and counts nothing. A payment with a code counts the use. - A quote request answers
ZERO_CHARGEtoo. A quote request for a code that wins and leaves a charge of zero gets422 PROMOTION_NOT_APPLICABLEand the reasonZERO_CHARGE, as a payment does. It counts nothing, and the reason comes beforeUSAGE_LIMIT_REACHEDthere too. ZERO_CHARGEbelongs to a code that wins. When an automatic promotion wins the selection and its quote would charge zero, the payment is not refused withZERO_CHARGE: Yuno refuses it with422 PROMOTION_NOT_APPLICABLEand the reasonENGINE_UNAVAILABLE. No payment is created. A quote request in that case gets204.
When a code and an automatic promotion both apply
One payment gets one promotion. Promotions don’t add up. When a payment carries a code, the promotion of the code and the account’s automatic promotions that match the payment compete in one selection. The one that saves the customer the most wins. If two save the same amount, the oldest one (earliestcreated_at) wins; if that also ties, the smallest id wins. The code has no advantage.
In this example the payment is charged USD 220. The code counts no use, and the payment is not refused.
A code that fails is refused with its own reason, and no automatic promotion takes its place. For example, a code that reached its limit and would have won answers
USAGE_LIMIT_REACHED; Yuno does not apply the automatic promotion instead.
An automatic promotion that has a payment method condition competes only when the payment carries payment_method.type: without it the payment has no method to meet the condition.
Payments that can’t carry a code
A code applies to one-time payments onPOST /v1/payments. These payments are refused, and no payment is created:
Yuno refuses all three before it asks for the quote, so the refusal counts no use. These bodies have a
code and messages, and no reason.
Every other route that takes additional_data.order.discounts refuses a code line exactly as it refuses a YUNO_PROMOTION quote line: the same status, the same code and the same messages. This covers checkout sessions, payment links, subscriptions, capture, and POST /v2/payments. See What’s not included yet.
Answers
When a code does not become a quote, no payment is created and the answer says why.ENGINE_UNAVAILABLE covers two causes, and the answer does not say which one it is. Both come back with the same reason and the same message.
- Transient: retry later. The promotions service did not answer in time, answered with an error, or Promotions is temporarily disabled by Yuno. Retry the same payment later.
- Not transient: a retry gets the same answer. An automatic promotion wins the selection for this payment and would leave a charge of zero. Send the payment without the code. A payment with no code is charged in full, and the promotion check does not refuse it.
Try again. for both causes, so it does not tell you which one to retry. If the same payment still gets ENGINE_UNAVAILABLE after you retry later, send it without the code. The customer then pays the full price and loses the discount of that code for that payment.
Code that reached its limit (422)
Unknown code (404)
Code that leaves a charge of zero (422)