[POST] Сreate Promotion
Request Description
POST /v1/promotionThe request allows you to create promotions and set discounts for your products. More details on how promotions work.
The request contains:
- Authorization data (token)
- Promotion basic properties
- Discount usage settings (one of the options):
- Properties of promotion codes
- Properties of instant discounts (without activating a promotion code)
Connection Data
- Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/promotion
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/promotion
- Request Method: POST
- Format: JSON
- Authorization: token-based
Authorization token
- Format:
Bearer [token] - Where [token] is substituted by the token, value obtained through the authentication API
Promotion type
Value options:
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.
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.
Promotion status
A promotion can only be applied if it is active.
Value options:
A promotion can only be applied if it is active.
Value options:
- true - active
- false - inactive
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
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).
Promotion code data
It is used for promotions having type coupon.
It is used for promotions having type coupon.
- * - Required, if "promotion_type":"coupon"
- Not transferred, if "promotion_type":"discount"
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:
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
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.
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.
Common discount (percentage)
It applies to the products that are transferred in the coupons.product_id или на все ваши продукты, если параметр coupons.product_id не передан. Скидка применяется к продукту после активации промокода в корзине.
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
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 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
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.
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.
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.
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.
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.
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
Discount data for promotions having type "discount"
- * - Required, if "promotion_type":"discount"
- The parameter must not be transferred, if "promotion_type":"coupon"
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.
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
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 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
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.
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.
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.
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.
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.
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
Examples of Request With Common Discount Applied to All Products
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:
- Transfer the parameter with the common discount value: coupons.discount_percent or discounts.discount_percent (according to the type of the promotion)
- The following parameters must not be present in the request:
- The list of the products with the common discount applied: coupons.product_id / discounts.product_id
- The individual discounts: coupons.products / discounts.products
Example for promotions having type "coupon" and common discount applied to all products
{
"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"
}
}Example for promotions having type " discount " and common discount applied to all products
{
"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"
}
}Examples of Request With Common Discount Applied to Specific Products
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:
- Transfer the following in the request:
- The parameter with the common discount value: coupons.discount_percent or discounts.discount_percent (according to the type of the promotion)
- The list of the products to which the common discount is to be applied: coupons.product_id or discounts.product_id (according to the type of the promotion)
- The following parameters must not be present in the request:
- The individual discounts: coupons.products / discounts.products
Example for promotions having type "coupon" and common discount applied to specific products
{
"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
]
}
}Example for promotions having type " discount " and common discount applied to specific products
{
"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
]
}
}Examples of Request With Individual Discounts
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:
- Transfer the following in the request:
- The array of individual discounts: coupons.products или discounts.products (according to the type of the promotion)
- The following parameters must not be present in the request:
- The parameter with the common discount value: coupons.discount_percent / discounts.discount_percent
- The list of the products to which the common discount is to be applied: coupons.product_id / discounts.product_id
Example for promotions having type "coupon" and individual discounts applied
{
"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"
}
]
}
}Example for promotions having type " discount " and individual discounts applied
{
"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"
}
]
}
}Response Description
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.
Successful Response
If processing is successful, the following will return in response server response code: HTTP/1.1 200 ОК and json with a promotion id.
Example of Successful Response
{
"id": 45566
}Error Response
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 Server Response Error Code
| 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. |
Additional Error Codes for HTTP 400
| 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_id, coupons.products.[object].product_id, discounts.product_id, discounts.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_from, date_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. |
Additional Error Codes for HTTP 401
The errors are the same for all the APIs that use token authorization.
Example of Error Response
{
"errors": [{
"error": 11010,
"message": "Invalid field value: date_from"
}, {
"error": 11010,
"message": "Invalid field value: product_id"
}
]
}