Xsolla-logo

Create promo code promotionServer-sideAdmin

post/v2/project/{project_id}/admin/promocode

Creates a promo code promotion.

SecuritybasicAuth
Request
path Parameters
project_id
required
integer

Project ID. You can find this parameter in your Publisher Account next to the name of the project.

Example: 44056
Request Body schema: application/json
external_id
required
string
Default: "coupon_external_id"

Unique promotion ID. The external_id may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores.

required
object
Default: {"en-US":"Coupon title","de-DE":"Gutscheintitel"}

Name of promotion. Should contain key/value pairs where key is a locale with "^[a-z]{2}-[A-Z]{2}$" format, value is string.

property name*
additional property
string
date_start
string or null <date-time>
Default: "2020-04-15T18:16:00+05:00"

Date when your promotion will be started.

date_end
string or null <date-time>
Default: "2020-04-15T18:16:00+05:00"

Date when your promotion will be finished. Can be null. If date_end is null, promotion will be unlimited by time.

Array of objects or null
Array
sku
string
Default: "elven_shield"

Item SKU.

quantity
number
Default: 1

Item quantity.

redeem_total_limit
integer or null
Default: 10

Limits total numbers of coupons.

redeem_user_limit
integer or null
Default: 10

Limits total numbers of coupons redeemed by single user.

redeem_code_limit
integer or null
Default: 10

Number of redemptions per code.

object or null
percent
string or null
Default: "10.00"

Percent discount. The price of cart will be decreased using a value calculated by using this percent and then rounded to 2 decimal places.

Array of objects or null

List of items that are discounted by a promo code.

Array
sku
required
string
Default: "elven_shield"

Item SKU.

required
object
percent
required
string
Default: "10.00"

Percent discount.

The price of cart item will be decreased using a value calculated by using this percent and then rounded to 2 decimal places.

Array of type = string (objects) or Array of type = date (objects) or Array of type = number (objects)

Conditions which are compared to user attribute values. All conditions must be met for the action to take an effect.

One of:

Conditions which are compared to user attribute values. All conditions must be met for the action to take an effect.

[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
attribute
required
string [ 1 .. 255 ] characters ^[-_.\\d\\w]+$

User attribute code.

operator
required
string

Type of operation performed by condition. For string attribute type.

Enum: Description
eq

Equals

ne

Not equals

value
required
string <= 255 characters

Condition value which user attribute value will be compared to. Type depends on attribute type.

type
required
string

User attribute type.

Value: "string"
can_be_missing
boolean

Indicates that the condition is met even if attribute is missing from user attributes. Pass true to show the item to users who don't have this attribute. Users who have the attribute, but the value does not match that specified in the condition, will not see the item. false — users who have the attribute, but the value does not match that specified in the condition, or the attribute is missing, will not see the item.

Array of objects or null

Array of objects with conditions that set the price range for applying the promotion to the entire cart.
The total price of all items in the user's cart is compared with the price range specified in the condition. Bonuses and discounts are applied to all items in the cart if the price of the cart meets the specified condition.
If you pass this array, set the value of the discounted_items array to null.

Array
operator
required
string

Comparison operator for setting the price range for applying the promotion.

Enum: Description
ge

Greater or equal

gt

Greater than

le

Less or equal

lt

Less than

eq

Equals

ne

Not equals

value
required
string^\\d+(\\.\\d{1,4})?$

Value for determining the price range for applying the promotion.

Array of objects or null

Array of objects with conditions that set the price range for applying the promotion to certain items in the cart.
The price of each item in the user's cart is compared with the price range specified in the condition. Bonuses and discounts are applied only to those items in the cart whose price meets the condition.
If you pass this array, set the value of the discounted_items array to null.

Array
operator
required
string

Comparison operator for setting the price range for applying the promotion.

Enum: Description
ge

Greater or equal

gt

Greater than

le

Less or equal

lt

Less than

eq

Equals

ne

Not equals

value
required
string^\\d+(\\.\\d{1,4})?$

Value for determining the price range for applying the promotion.

excluded_promotions
Array of integers

List of promotion IDs to exclude when applying this promotion.
Example: [12, 789]

Responses
201

Promo code was successfully created.

401

Basic authentication not passed or wrong. Make sure you used basic authentication or correct credentials.

422

Invalid request.

Request samples
application/json
{
  • "external_id": "promo_code_external_id",
  • "date_start": "2020-04-15T18:16:00+05:00",
  • "date_end": "2020-04-25T18:16:00+05:00",
  • "name": {
    },
  • "redeem_total_limit": 100,
  • "redeem_user_limit": 1,
  • "redeem_code_limit": 1,
  • "bonus": [
    ]
}
Response samples
application/json
{
  • "external_id": "coupon_external_id"
}
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.