Create Promotion
Creates a code promotion: a code you send or one Yuno builds from your prefix, a discount, a date window, the conditions a payment must meet and, optionally, the most uses.
What the request needs
- The account comes from the
X-Account-Codeheader. The promotion belongs to that account. A body that carriesaccount_idis refused with400 INVALID_PARAMETERS, and so is a body that repeatsredemptionor one of its members (names are compared without regard to case). 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.redemption.modeisCODEand you send exactly one ofredemption.codeandredemption.prefix. Neither answers400 INVALID_REQUESTwithredemption: CODE_OR_PREFIX_REQUIRED, and both answerredemption: CODE_AND_PREFIX_EXCLUSIVE. Each answer adds the messageSend exactly one of redemption.code or redemption.prefix.. Anull, an empty text and a text with only spaces count as not sent. Aredemption.codethat is not valid, sent with a prefix, counts as both.- A code you send has 3 to 32 characters: letters, digits,
_and-, in any case. Yuno trims the spaces around it and stores it in upper case. A code with a character outside that set answersredemption.code: CODE_CHARACTERS, and one of the wrong lengthredemption.code: CODE_LENGTH. - A prefix builds the code. The prefix has 1 to 8 letters or digits (
A-Z,a-z,0-9). Yuno converts it to upper case and builds the code as the prefix and a random suffix of 5 characters fromA-Zand2-9, without0,O,1,IandL. For example, the prefixSUMMERcan giveSUMMERK7P2X. The201shows the code inredemption.code. A character outsideA-Z,a-zand0-9answersredemption.prefix: FORMAT, and more than 8 characters answersredemption.prefix: LENGTH. Yuno never builds a code that another promotion of your account holds, whatever its status. A create with a prefix never answers409 CODE_ALREADY_EXISTS. The sameX-Idempotency-Keyreturns the same promotion with the same code. If Yuno can’t build a code, the create fails with500 INTERNAL_ERRORand Yuno stores nothing: retry the request. - A code is unique per account. Another promotion of the account that is not disabled, with a schedule that overlaps the new 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
countriesandamounts. A code applies to the whole payment, whatever the payment method. Abins,payment_methodsorcard_typescondition answers400 INVALID_REQUESTwithconditions.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. A promotion with nolimitshas no cap, and its response showslimits: null. Yuno counts a use when a payment takes the code. See Uses and limits.- The body is at most 256 KiB. A larger body answers
413 REQUEST_ENTITY_TOO_LARGE.
What the answer holds
201 returns the promotion, as The Promotion Object describes it, with status computed from schedule and limits.used at 0. Every member is present, with null for an absent value. redemption.code holds the code, whether you sent it or Yuno built it from your prefix.
Two kinds of 400 exist. INVALID_PARAMETERS comes from the checks Yuno makes before it reads the promotion: the headers, account_id, redemption.mode. INVALID_REQUEST comes from the rules of the promotion itself, with one path: RULE message for each failed path, in the order of the checks. Promotion Error Codes lists them.Authorizations
Headers
The account_id found in your Yuno Dashboard (UUID). Required. A promotion belongs to one account, and this header names it. Omitting it returns 400 INVALID_PARAMETERS ("x-account-code header is required.").
Body
The conditions a payment must meet. AND across keys, OR inside each key's values list. A code applies to the whole payment, whatever the payment method, so only countries and amounts are accepted. A bins, payment_methods or card_types condition returns 400 INVALID_REQUEST with the messages conditions.bins: FORBIDDEN, conditions.payment_methods: FORBIDDEN or conditions.card_types: FORBIDDEN.
Response
- The promotion. The same answer returns when the account repeats the
X-Idempotency-Key.
A promotion. Every member is present, with null for an absent value.