Skip to main content
A promotion code is a promotion that applies only when a payment carries its code, for example 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.
Promotions is enabled per organizationUntil Yuno enables Promotions for your organization, the promotions endpoints answer 404 PROMOTION_NOT_FOUND, and a payment that carries a code is refused with 422 PROMOTION_NOT_APPLICABLE and the reason PROMOTIONS_NOT_ENABLED. No payment is created. Ask your Technical Account Manager or Key Account Manager to enable it. See Promotions.

How it works

  1. Create the promotion. Call Create Promotion with redemption.mode set to CODE. 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.
  2. Collect the code. Your customer gives you the code in your own checkout.
  3. Send the code on the payment. Add { "code": "SUMMER10" } to additional_data.order.discounts on Create Payment, with the original amount.
  4. 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.
A payment that carries no code is charged in full, as before.

Create a code promotion

Send the promotion to POST /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)
What to know before you create one:
  • X-Idempotency-Key is required. It is any text of 1 to 64 characters. The same key on the same account returns the first promotion with 201, and Yuno does not compare the body. A request with no valid key is refused with 400 before the body is read.
  • The mode is CODE. Any other redemption.mode is refused with 400 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 with 400 INVALID_REQUEST and the message redemption.code: CODE_LENGTH, and a code with another character with redemption.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 countries and amounts only. A code applies to the whole payment, whatever the payment method. A bins, payment_methods or card_types condition is refused with 400 INVALID_REQUEST and the messages conditions.bins: FORBIDDEN, conditions.payment_methods: FORBIDDEN or conditions.card_types: FORBIDDEN.
  • limits.total is 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 shows limits: 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.
To read a promotion, call Retrieve Promotion. To list the promotions of the account, newest first, call List Promotions. The list also returns the account’s AUTOMATIC promotions. The Promotion Object describes every field.

Let Yuno build the code from a prefix

Send exactly one of redemption.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_REQUEST with the messages redemption: CODE_OR_PREFIX_REQUIRED and Send exactly one of redemption.code or redemption.prefix.. A body with both answers redemption: CODE_AND_PREFIX_EXCLUSIVE with the same second message. A null, an empty text and a text with only spaces count as not sent. A code that is not valid, sent with a prefix, counts as both.
  • A wrong prefix is refused. A character outside A-Z, a-z and 0-9 answers redemption.prefix: FORMAT. More than 8 characters answers redemption.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-Key on the same account returns the first promotion with 201 and 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 the X-Account-Code and X-Idempotency-Key headers, both required, and a body with quantity and prefix:
Request body
  • quantity is required. It is the number of codes in the batch, a whole number from 1 to 1000. A missing value answers quantity: REQUIRED, and a value outside that range answers quantity: RANGE. Both are 400 INVALID_REQUEST.
  • prefix is required. It has 1 to 8 letters or digits (A-Z and 0-9), in any case, and Yuno converts it to upper case. A missing or blank prefix answers prefix: REQUIRED. A character outside A-Z and 0-9 answers prefix: FORMAT, and more than 8 characters answer prefix: LENGTH.
  • uses_per_code is 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 answers uses_per_code: RANGE.
  • A full code is refused. Yuno makes every code of a batch from the prefix, so a body with a code answers 400 INVALID_REQUEST with code: NOT_ALLOWED.
Each code is the prefix and a random suffix, with nothing between them. The suffix uses 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-Key on the same promotion returns the first batch with 201, 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_APPLICABLE with the reason BATCH_LIMIT_REACHED, and stores nothing.
  • Only a code promotion holds a batch. An AUTOMATIC promotion has no code, and it answers 422 PROMOTION_NOT_APPLICABLE with the reason NOT_CODE_PROMOTION. A disabled promotion answers DISABLED, and an ended one answers EXPIRED.
  • 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
This is the part of the request that matters here; the rest is the Create Payment body you already send. Send 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:
  1. It checks the rules above. A break is a 400.
  2. 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.
  3. It asks the promotions service for a quote with your account, the payment amount, the country and the code. It sends the X-Idempotency-Key of your payment, so the service counts one use for the payment.
  4. 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.
  5. 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_PROMOTION line carries a code. A code on a MERCHANT line is ignored (see the note after the rules table).
Other facts about the line:
  • payment_method.type is 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-Key is required. Create Payment requires it on every payment: without the header the answer is 400 INVALID_PARAMETERS and The 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 with 400 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 header X-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)
Yuno refuses the payment before it asks for a quote, tokenizes a card or reaches a provider, so it counts no use. The message never repeats your code. Only the value 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 the code. 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-Key of 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_APPLICABLE and the reason IDEMPOTENCY_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_APPLICABLE and the reason ZERO_CHARGE before 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 answers ZERO_CHARGE, not USAGE_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.used equals limits.total, a payment with the code is refused with 422 PROMOTION_NOT_APPLICABLE and the reason USAGE_LIMIT_REACHED. No payment is created.
  • limits.used counts the uses of a code that has a limit. A code with no limit shows limits: 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 used count of the code and, when the promotion has limits.total, one to limits.used. Both counts happen or neither does. A code at its limit, or a promotion at its total limit, refuses the payment with 422 PROMOTION_NOT_APPLICABLE and the reason USAGE_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 code is a preview: Yuno signs, stores and counts nothing. A payment with a code counts the use.
  • A quote request answers ZERO_CHARGE too. A quote request for a code that wins and leaves a charge of zero gets 422 PROMOTION_NOT_APPLICABLE and the reason ZERO_CHARGE, as a payment does. It counts nothing, and the reason comes before USAGE_LIMIT_REACHED there too.
  • ZERO_CHARGE belongs to a code that wins. When an automatic promotion wins the selection and its quote would charge zero, the payment is not refused with ZERO_CHARGE: Yuno refuses it with 422 PROMOTION_NOT_APPLICABLE and the reason ENGINE_UNAVAILABLE. No payment is created. A quote request in that case gets 204.

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 (earliest created_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 on POST /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.
The message says 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)
Promotion Error Codes lists every answer of the promotions endpoints and of a payment with a code, with the text of each message.