Skip to main content
POST
Create Promotion Codes
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.
This endpoint makes a batch of codes on a code promotion of your account. The guide Create a batch of codes explains the whole flow, and List Promotion Codes reads the codes back.

What the request needs

  • The account comes from the X-Account-Code header. The promotion must belong to that account. Without the header the answer is 400 INVALID_PARAMETERS.
  • X-Idempotency-Key is required. It is any text of 1 to 64 characters. The same key on the same promotion returns the first batch with 201, and Yuno does not compare the body.
  • The promotion id is a UUID v4 in the path. An id that is not one answers 400 INVALID_PARAMETERS. An id that is not on the account answers 404 PROMOTION_NOT_FOUND.
  • quantity is required, a whole number from 1 to 1000. prefix is required, 1 to 8 letters or digits. uses_per_code is optional, a whole number from 1 to 1000000, and each code accepts one payment without it.
  • A full code is refused. A body with a code answers 400 INVALID_REQUEST with code: NOT_ALLOWED. Yuno makes every code of the batch.
  • The body is at most 256 KiB. A larger body answers 413 REQUEST_ENTITY_TOO_LARGE.

What the answer holds

201 returns the batch: batch_id, promotion_id, quantity and codes. Each entry of codes holds the code and its uses_per_code. The suffix of each code is 5 characters for up to 28 codes, 6 characters for 29 to 887 codes, and 7 characters for 888 to 1000 codes. The codes come back only in this answer and in List Promotion Codes. Keep them secret. Yuno does not write them to its logs.

Errors

Two kinds of 400 exist, as for Create Promotion. INVALID_PARAMETERS comes from the headers, the path and the check of the body as an object. INVALID_REQUEST comes from the rules of the batch: quantity, uses_per_code, prefix and code, with one path: RULE message for each failed path. A promotion that can’t hold a batch answers 422 PROMOTION_NOT_APPLICABLE with a reason. Promotion Error Codes lists every answer.

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 promotion returns the first batch with 201. Yuno does not compare the body.

Required string length: 1 - 64

Path Parameters

promotion_id
string<uuid>
required

The promotion id (UUID v4). The promotion must belong to the account of X-Account-Code and must be a code promotion (redemption.mode is CODE). An id that is not a UUID v4 answers 400 INVALID_PARAMETERS.

Body

application/json
quantity
integer
required

The number of codes in the batch, from 1 to 1000. A missing value answers quantity: REQUIRED, and a value outside that range answers quantity: RANGE. Both are 400 INVALID_REQUEST.

Required range: 1 <= x <= 1000
prefix
string
required

Required. 1 to 8 letters or digits (A-Z, 0-9), in any case. Yuno converts it to upper case and builds each code from it: the prefix, then a random suffix. A missing or blank prefix answers prefix: REQUIRED. A body with a code is refused with code: NOT_ALLOWED.

Required string length: 1 - 8
uses_per_code
integer
default:1

How many payments each code accepts, from 1 to 1000000. Optional: without it each code accepts one payment. A value outside that range answers uses_per_code: RANGE.

Required range: 1 <= x <= 1000000

Response

  1. The batch, with its codes. The same key on the same promotion returns the same batch with 201.

A batch of codes.

batch_id
string<uuid>

The id of the batch. It is derived from the account, the promotion and the key.

promotion_id
string<uuid>
quantity
integer

The number of codes in the answer.

codes
object[]