[POST] Сreate promotion

Request Description

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:

• 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

Header Parameters

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

Body Parameters

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:

• All your products

• Specific products

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:

• All your products

• Specific products

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.

discounts / 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.

discounts / products / [object] / discount_percent

string

required

Individual product discount
The discount is automatically applied to the product as soon as it is added to the checkout page if the following conditions are met:

• The discount is applicable to the product: the product ID is transferred in the current object through discounts.products.product_id.

• There is no individual zonal discount for this product: parameter discounts.products.discount_percent_currencies is either not transferred or does not contain the currency selected at checkout.

Filling guidelines.

• Format: Numerical digits, up to 6 decimal places, separator - dot.

• Fill-in rule: 0 < discount_percent ≤ 100

discounts / products / [object] / discount_percent_currencies

array [objects]

Individual zonal product discounts
This is an array of discount objects that replace the total discount (defined in discounts.products.discount_percent), if the checkout currency matches one of the currencies specified in this array.

See the example on how to use the individual zonal discount: Zonal Product Discounts

discounts / products / [object] / discount_percent_currencies / [object] / сurrency

string

required*

Individual zonal discount currency
The parameter specifies the checkout currency for which an individual zonal discount (discounts.products.discount_percent_currencies.discount_percent) is applied to the product (discounts.products.product_id) instead of the general individual discount (discounts.products.discount_percent).

• * - Required if array of individual zonal discounts (discounts.products.discount_percent_currencies) is transferred.

• Checkout currency code is ISO 4217 alpha-3.

• 3 characters max.

• Refer to reference guide for possible values: Currencies

• Currency codes must not be duplicated within same array (discounts.products.discount_percent_currencies).

discounts / products / [object] / discount_percent_currencies / [object] / discount_percent

string

required*

Individual zonal product discount (percent)
It is applied instead of the individual discount (discounts.products.discount_percent) to the product whose ID is transferred in discounts.products.product_id, if the checkout currency selected at checkout matches the currency from this object (discounts.products.discount_percent_currencies.сurrency).

• * - Required if array of individual zonal discounts (discounts.products.discount_percent_currencies) is transferred.

• Format: Numerical digits, up to 6 decimal places, separator - dot.

• Fill-in rule: 0 ≤ discount_percent ≤ 100.
  Please note that you can transfer value "0". In this case no discount having type Discounts from the promotion is applied. Use this feature to make an exception and not to apply the discount promotion to any specific checkout currency. Learn more about this feature.

See the example on how to use the individual zonal discount: Regional Product Discounts

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

• For any promotion having type Discounts, you can set zonal discounts that will apply only to the corresponding checkout currency selected at checkout.

To create a promotion with this discount type:

• Transfer the following in the request:

  • The array of individual discounts: coupons.products or 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"
   }
  ]
 }
}

Example for promotions having type " discount " and individual zonal 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.

Body Parameters

id

number

required

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

Additional Error Codes for HTTP 400

Additional Error Codes for HTTP 401

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

Body Parameters

errors

array [objects]

required

Error list

errors / [error object] / error

number

required

Error code

errors / [error object] / message

string

Error description

Example of Error Response

{
 "errors": [{
   "error": 11010,
   "message": "Invalid field value: date_from"
  }, {
   "error": 11010,
   "message": "Invalid field value: product_id"
  }
 ]
}

Noventiq Checkout