Skip to main content
POST
Promotions is enabled per organizationThis endpoint works only after Yuno enables Promotions for your organization. Until then it answers 404 PROMOTION_NOT_FOUND. Ask your Technical Account Manager or Key Account Manager. See Promotions.
Promotions can’t be editedThere’s no update endpoint and no delete. To change a discount, a date, a condition or the code, disable the promotion and create a new one.
This endpoint creates code promotions. A customer redeems one when your server sends its code on Create Payment. See Promotion codes for the whole flow.

What the request needs

  • The account comes from the X-Account-Code header. The promotion belongs to that account. A body that carries account_id is refused with 400 INVALID_PARAMETERS, and so is a body that repeats redemption or one of its members (names are compared without regard to case).
  • 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.
  • redemption.mode is CODE and you send exactly one of redemption.code and redemption.prefix. Neither answers 400 INVALID_REQUEST with redemption: CODE_OR_PREFIX_REQUIRED, and both answer redemption: CODE_AND_PREFIX_EXCLUSIVE. Each answer adds the message Send exactly one of redemption.code or redemption.prefix.. A null, an empty text and a text with only spaces count as not sent. A redemption.code that 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 answers redemption.code: CODE_CHARACTERS, and one of the wrong length redemption.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 from A-Z and 2-9, without 0, O, 1, I and L. For example, the prefix SUMMER can give SUMMERK7P2X. The 201 shows the code in redemption.code. A character outside A-Z, a-z and 0-9 answers redemption.prefix: FORMAT, and more than 8 characters answers redemption.prefix: LENGTH. Yuno never builds a code that another promotion of your account holds, whatever its status. A create with a prefix never answers 409 CODE_ALREADY_EXISTS. The same X-Idempotency-Key returns the same promotion with the same code. If Yuno can’t build a code, the create fails with 500 INTERNAL_ERROR and 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 countries and amounts. A code applies to the whole payment, whatever the payment method. A bins, payment_methods or card_types condition answers 400 INVALID_REQUEST with 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. A promotion with no limits has no cap, and its response shows limits: 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

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

X-Account-Code
string
required

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.").

X-Idempotency-Key
string
required

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

Required string length: 1 - 64

Body

application/json
name
string
required

The promotion name (1 to 255 characters).

Required string length: 1 - 255
schedule
object
required

The window in which the promotion runs. UTC.

redemption
object
required
discount
object
required

What the customer saves. For FIXED, when the promotion also has an amounts condition, discount.amounts and conditions.amounts.values must list the same currencies, or the request returns 400.

description
string

Optional. Up to 1000 characters.

Required string length: 1 - 1000
conditions
object

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.

limits
object

Optional. Without it the code has no cap.

Response

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

id
string<uuid>

The id of the promotion (UUID). Assigned by Yuno.

account_id
string<uuid>

The account the promotion belongs to.

name
string
description
string | null
schedule
object
redemption
object
discount
object
conditions
object

One key for each dimension, null when the promotion has no condition on it. A code promotion created with this API holds countries and amounts only.

limits
object | null

The cap of the code and the uses counted so far. null when the promotion has no cap.

status
enum<string>

Computed from schedule and from the disable at the moment you read the promotion.

Available options:
SCHEDULED,
ACTIVE,
EXPIRED,
DISABLED
created_at
string<date-time>
disabled_at
string<date-time> | null

null while the promotion is not disabled.