[POST] Сreate Promotion

POST /v1/promotion

The request allows you to create promotions and set discounts for your products. More details on how promotions work.

The request contains:

content-type
string
required
MIME-type

It must be equal to "application/json".
AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Where [token] is substituted by the token, value obtained through the authentication API
promotion_type
string
required
Promotion type

Value options:
  • coupon - in this case, a promotion is applied to a product automatically when adding the product to the shopping cart on the checkout page
  • discount - in this case, a promotion is applied to a product only after a promotion code gets activated in the shopping cart on the checkout page
promotion_name
string
required
Promotion name
Not displayed to customers. Use to organize your promotions. With this parameter, you can search for a promotion via the GET-request or the Merchant Portal.

Maximum of 255 characters.
status
boolean
Promotion status
A promotion can only be applied if it is active.

Value options:
  • true - active
  • false - inactive
It is true by default.
date_from
string
Promotion start date
  • Format: YYYY-MM-DDThh:mm:ss±hh:mm
    During processing, the date is recalculated according to the time zone of the server and saved into your promotion. When subsequent requests for getting the data of the promotion happen, the date returns being in the time zone of the server
  • If the parameter is transferred, the condition must be met: date_from ≤ date_to
  • If the parameter is not transferred, current date and time are saved as the start date
date_to
string
Promotion expiration date
  • Format: YYYY-MM-DDThh:mm:ss±hh:mm
    During processing, the date is recalculated according to the time zone of the server and saved into your promotion. When subsequent requests for getting the data of the promotion happen, the date returns being in the time zone of the server
  • If the parameter is transferred, the condition must be met: date_from ≤ date_to
  • If the parameter is not transferred, then "01.01.3000 00:00" is saved as the end date (equals to "unlimited" promotion).
coupons
object
required*
Promotion code data
It is used for promotions having type coupon.
  • * - Required, if "promotion_type":"coupon"
  • Not transferred, if "promotion_type":"discount"
See the examples of how to fill in the data in the object for different use cases of discounts.
coupons
/
coupon_type
string
Promotion code type
Determines the possibility of re-applying one promotion code. There can be only one type of promotional code in one promotion.
Value options:
  • one-time - in this case, the same promotion code can be applied only to the products of the same order. When managing a promotion through the portal, this type of promotional code is called "disposable"
  • reusable - in this case, the same promotion code can be applied to the products of several different orders
The default value is reusable.
coupons
/
coupon_code
array [strings]
required*
List of promotion codes
To get a discount amount, a promotion code must be activated on the checkout page. The customer must enter their promotion code into a special field to activate it.
  • * - Require, if "promotion_type":"coupon"
  • The list of promotion codes is transferred in the array format, each element of the array contains one promotional code
  • Array element format:
    • String, not more than 30 characters
    • Allowed: letters (Latin and Cyrillic), numerical digits, dashes, underscores, dots
    • Value is case insensitive
  • Unique value within a single promotion. Note that promotion codes from different promotions may be the same. If several promotions that meet the conditions of application are found when a promotion code is activated, the discount amount of only one of the promotions is applied to a product. More details on how discount amounts are applied in this case.
coupons
/
discount_percent
string
required*
Common discount (percentage)
It applies to the products that are transferred in the coupons.product_id или на все ваши продукты, если параметр coupons.product_id не передан. Скидка применяется к продукту после активации промокода в корзине.
  • * - Required, if a promotion does not use individual product discounts (parameter coupons.products) is not transferred); i.e. only one of the parameters can be transferred in the request: coupons.discount_percent or coupons.products
  • Format: Numerical digits, up to 6 decimal places, separator - dot
  • Fill-in rule: 0 < discount_percent ≤ 100
See the examples of the requests with the common discount applied to:
coupons
/
product_id
array [numbers]
List of product identifiers that are subject to the common discount (coupons.discount_percent)
The discount amount is applied to the product after the promotion code is activated on the checkout page. If you want the common discount to be applied to all your products, do not transfer this parameter.
  • The parameter must not be transferred if a promotion uses individual product discounts (parameter coupons.products); i.e. only one of the parameters can be transferred in the request: coupons.product_id or coupons.products
  • The list of product identifiers is transferred in the array format; each element of the array contains one identifier
  • Array element format: Numerical digits
  • Identifier values must not duplicate in an array
See the examples of the requests with the common discount applied to specific products.
coupons
/
products
object
List of individual product discounts
Use the parameter to transfer the list of the products participating in your promotion and to set individual discounts for each of these products. The discount amount is applied to the product after the promotion code is activated on the checkout page.

The parameter must not be transferred if the promotion uses the common discount (parameter coupons.discount_percent) is transferred); i.e. only one of the parameters can be transferred in the request: coupons.discount_percent or coupons.products.

See the examples of the requests with the individual discounts.
coupons / products / [object]
/
product_id
number
required
Product identifier that is subject to the individual discount activated by the promotion code.
The discount amount is applied to the product after the promotion code is activated on the checkout page.

The identifier value must be unique in the coupons.products aray.
coupons / products / [object]
/
discount_percent
string
required
Individual product discount
It applies to only the product the identifiers of which are transferred in the object in which the parameter is transferred. The discount amount is applied to the product after the promotion code is activated on the checkout page.
  • Format: Numerical digits, up to 6 decimal places, separator - dot.
  • Fill-in rule: 0 < discount_percent ≤ 100
discounts
object
required
Discount data for promotions having type "discount"
  • * - Required, if "promotion_type":"discount"
  • The parameter must not be transferred, if "promotion_type":"coupon"
See the examples of how to fill in the data in the object for different use cases of discounts.
discounts
/
discount_percent
string
required*
Common discount (percentage)
It applies to the products that are transferred in the discounts.product_id parameter or to all your products if the discounts.product_id parameter is not transferred. The discount amount is applied to the product after the product is added to the checkout page.
  • ⃰ - Required, if a promotion does not use individual product discounts (parameter discounts.products is not transferred); i.e. only one of the parameters can be transferred in the request: discounts.discount_percent or discounts.products.
  • Format: Numerical digits, up to 6 decimal places, separator - dot
  • Fill-in rule: 0 < discount_percent ≤ 100
See the examples of the requests with the common discount applied to:
discounts
/
product_id
array [numbers]
List of product identifiers that are subject to the common discount (discounts.discount_percent)
The discount amount is applied to the product after the product is added to the checkout page.
  • The parameter must not be transferred if a promotion uses individual product discounts (parameter discounts.products); i.e. only one of the parameters can be transferred in the request: discounts.product_id or discounts.products
  • The list of product identifiers is transferred in the array format; each element of the array contains one identifier
  • Array element format: Numerical digits
  • Identifier values must not duplicate in an array
See the examples of the requests with the common discount applied to specific products.
discounts
/
products
object
required*
List of individual product discounts
Use the parameter to transfer the list of the products participating in your promotion and to set individual discounts for each of these products. The discount amount is applied to the product after the product is added to the checkout page.

The parameter must not be transferred if the promotion uses the common discount (parameter discounts.discount_percent) is transferred); i.e. only one of the parameters can be transferred in the request: discounts.discount_percent or discounts.products.

See the examples of the requests with the individual discounts.
coupons / products / [object]
/
product_id
number
required
Product identifier that is subject to the individual discount
The discount amount is applied to the product after the product is added to the checkout page.

The identifier value must be unique in the discounts.products.
coupons / products / [object]
/
discount_percent
string
required
Individual product discount
It applies to only the product the identifiers of which are transferred in the object in which the parameter is transferred. The discount amount is applied to the product after the product is added to the checkout page.
  • Format: Numerical digits, up to 6 decimal places, separator - dot.
  • Fill-in rule: 0 < discount_percent ≤ 100

In this case:

  • The discount applies to all your products
  • The discount amount is the same for each product

To create a promotion with this discount type:

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10"
 }
}
{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "discount_percent": "10"
 }
}

In this case:

  • The discount amount applies only to the products selected for the promotion
  • The discount amount is the same for each of the participating products

To create a promotion with this discount type:

  •  
{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10",
  "product_id": [
   11111,
   22222
  ]
 }
}
{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "discount_percent": "10",
  "product_id": [
   11111,
   22222
  ]
 }
}

In this case:

  • The discount amount applies only to the products selected for the promotion
  • The discount amount is individual for each of the participating products

To create a promotion with this discount type:

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "coupons": {
  "coupon_type": "reusable",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "products": [{
    "product_id": 11111,
    "discount_percent": "10"
   }, {
    "product_id": 22222,
    "discount_percent": "20"
   }
  ]
 }
}
{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
  "products": [{
    "product_id": 11111,
    "discount_percent": "10"
   }, {
    "product_id": 22222,
    "discount_percent": "20"
   }
  ]
 }
}

In response to the request, you receive the server response code corresponding to the processing result. Depending on the code, the response body may contain additional parameters.

If processing is successful, the following will return in response server response code: HTTP/1.1 200 ОК and json with a promotion id.

id
number
required
Promotion ID
{
 "id": 45566
}

If an error occurs while processing the request, you receive a server response code corresponding to the result of processing. 
Depending on the code, the response body may contain additional parameters.

HTTP code Description
HTTP/1.1 400 Bad Request The request is not valid (error in parameters; necessary data is not transferred, etc.).
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 401 Unauthorized Unsuccessful authorization.
An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 404 Not found Invalid request URL. 
HTTP/1.1 500 Request Error Internal Server Error. Please try again later or contact support.
Error Message Description
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated.
110 JSON is not valid. The request cannot be processed. Request field structure is not valid. Check the fields in the request body against the JSON format.
111 Invalid data format (Content-type). The request cannot be processed. Invalid request header. Content-type must be equal to application/json.
11000 No access to promotion management. Please contact technical support. During processing, we could not identify your account setting unambiguously. Please contact support team.
If at least one error from the list below is found, then request validation is not interrupted. Several errors may return in response.
11010 Invalid field value: [parametr name] The request is not valid, e.g., the required parameter is not filled out, the parameter name is incorrect, the parameter value does not match with the data type provided, or the value format is incorrect. Moreover, the error will return if null is transferred in the parameter, and this value option is not set as valid in the parameter description.
11020
Product not found: [list of product identifiers] The request transferred contains the product that cannot be found or you do not have access to it. The error message contains the identifiers of the products that failed validation. Check the parameter value: coupons.product_idcoupons.products.[object].product_iddiscounts.product_iddiscounts.products.[object].product_id
11030
Same product can be listed only once ([product_id]) within one promotion. For the promotion having type "coupon", matching product identifiers are transferred in one of the request parameters (coupons.product_id, coupons.products.[object].product_id). Product identifiers must not match in the same parameter. 
11031 Same product can be listed only once ([product_id]) within one promotion. For the promotion having type "discount" , matching product identifiers are transferred in one of the request parameters (discounts.product_id, discounts.products.[object].product_id). Product identifiers must not match in the same parameter. 
11035 Product list has been sent twice. Transfer only one of the two options: coupons.product_id or coupons.products. For the promotion having type "coupon", the list of products is transferred twice in the request: for the common discount (coupons.product_id) and the array of individual discounts (coupons.products). You can use only one of these options for setting a discount amount. See the examples of the request for the promotions having type "coupon".
11036 Product list has been sent twice. Transfer only one of the two options: discounts.product_id or discounts.products. For the promotion having type "discount" , the list of products is transferred twice in the request: for the common discount (discounts.product_id) and the array of individual discounts (discounts.products). . You can use only one of these options for setting a discount amount. See the examples of the request for the promotions having type "discount".
11040 No discount is set. Provide values for parameters: coupons.discount_percent or coupons.products.discount_percent. For the promotion having type "coupon", no promotion discount is set. You must transfer one of the discount types: the common discount for all the participating products (coupons.discount_percent) or the individual discount for each of the participating products (coupons.products.[object].discount_percent). See the examples of the request for the promotions having type "coupon".
11041 No discount is set. Provide values for parameters: discounts.discount_percent or discounts.products.discount_percent. For the promotion having type "discount" no promotion discount is set. You must transfer one of the discount types: the common discount for all the participating products (discounts.discount_percent) or the individual discount for each of the participating products (discounts.products.[object].discount_percent). See the examples of the request for the promotions having type "discount".
11045 Discounts has been sent twice. Transfer only one of the two options: discount_percent or products.discount_percent. For the promotion having type "coupon", the discount amount is transferred twice in the request: the common discount (coupons.discount_percent) and the array of individual discounts (coupons.products). You can use only one of these options for setting a discount amount. See the examples of the request for the promotions having type "coupon".
11046 Discounts has been sent twice. Transfer only one of the two options: discount_percent or products.discount_percent. For the promotion having type "discount" , the discount amount is transferred twice in the request: the common discount (discounts.discount_percent) and the array of individual discounts (discounts.products). You can use only one of these options for setting a discount amount. See the examples of the request for the promotions having type "discount".
11050 Promotion validity period (date_from, date_to) is incorrect. The promotion validity dates (date_fromdate_to) not meeting the requirements are transferred in the request.
11070 No coupon code is set. Provide at least one value for coupons.coupon_code. For the promotion having type "coupon", no promotion code (coupons.coupon_code) is transferred. Transfer this parameter or change the type of the promotion.
11080 Coupons.coupon_code list must not contain duplicate values. For the promotion having type "coupon", matching promotion codes (coupons.coupon_code) are transferred. Promotion codes must not match in the same promotion.
11090 Request data and promotion type do not match (promotion_type). The data not related to the type of the promotion is transferred in the request.
E.g., for the promotion having type "coupon" ("promotion_type": "coupon"), the data about discounts (discounts) is transferred; or, for the promotion having type "discount" ("promotion_type": "discount") the data about promotion codes (coupons) is transferred.

The errors are the same for all the APIs that use token authorization.

errors
array [objects]
required
Error list
errors / [error object]
/
error
number
required
Error code
errors / [error object]
/
message
string
Error description
{
 "errors": [{
   "error": 11010,
   "message": "Invalid field value: date_from"
  }, {
   "error": 11010,
   "message": "Invalid field value: product_id"
  }
 ]
}