Examples of Promotion Modifications

You can modify promotions created earlier using the request for modification. This documentation provides you with the examples of different modifications.

You can activate or deactivate a promotion and/or modify its validity period without changing the rest of its properties.

Transfer the following in the request for modification:

  • The promotion_type parameter (using the same value as it was).
  • The parameters that change activity and/or validity periods (status, date_from, date_to).

Example:
Request for creation: POST /v1/promotion/

{
 "promotion_type": "discount",
 "status": false,
 "date_from": "2021-08-13T09:16:35+03:00",
 "date_to": "2023-08-13T09:16:35+03:00"
 "promotion_name": "Black Friday",
 "discounts": {
  "discount_percent": "50"
 }
}

Request for modification: PATCH /v1/promotion/123456

{
 "promotion_type": "discount",
 "status": true,
 "date_from": "2022-01-01T09:16:35+03:00",
 "date_to": "2022-01-10T09:16:35+03:00"
}

After you run the request:

  • Your promotion becomes active
  • The promotion expiration date is updated according to the values transferred

You can modify the list of the promotion codes that are used in your promotion.

At the same time, if you delete any promotion code from the promotion, the orders that have already been created and have the deleted promotion code applied remain unaffected (order status is ignored). Moreover, these orders are recorded into the statistics of the promotion.

To modify the list of promotion codes, transfer the following in the request for modification:

  • The parameter containing the type of your promotion: promotion_type (using the same value as it was)
  • The coupons object with the full set of the parameters nested
    • In the coupons.coupon_code parameter, list only the promotion codes that must participate in the promotion
    • Transfer the rest of the nested parameters. They must have the same values as they have in your current promotion. These parameters do not require any modification.
      Note: You must transfer the full set of parameters (not only the modified list of promotion codes), because all the nested parameters of the object will be updated. If any of the optional parameters is not transferred, it is resaved having the default value

Example:

Let us assume that you have created a promotion (id 123456) with promotion codes PROMO-001 and PROMO-002.

Request for creation: POST /v1/promotion/

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "coupons": {
  "coupon_type": "one-time",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10"
 }
}

To make the promotion applicable only to promotion codes PROMO-002 (already included in the promotion) and PROMO-003 (new promotion code), transfer the request for modification:

PATCH /v1/promotion/123456

{
 "promotion_type": "coupon",
 "coupons": {
  "coupon_type": "one-time",
  "coupon_code": [
   "PROMO-002",
   "PROMO-003"
  ],
  "discount_percent": "10"
 }
}

After you run the request:

  • Promotion code PROMO-003 is added to the promotion
  • Promotion code PROMO-001 is removed from the promotion because it was not transferred in the request
  • The remaining properties of the promotion and the promotion codes in it remain unchanged

You can modify the list of the products that are used in your promotion.

At the same time, if you delete any product from the promotion, the orders that have already been created and have the promotion applied remain unaffected (order status is ignored). Moreover, these orders are recorded into the statistics of the promotion.

To modify the list of products, transfer the following in the request for modification:

  • The parameter containing the type of your promotion: promotion_type (using the same value as it was)
  • One of the objects: coupons or discounts (according to the type of the promotion). The object must contain the full set of the parameters nested.
    • In the parameter containing the list of products, list only the product identifiers that must participate in the promotion
    • Transfer the rest of the nested parameters. They must have the same values as they have in your current promotion. These parameters do not require any modification
      Note: You must transfer the full set of parameters (not only the modified list of products), because all the nested parameters of the object will be updated. If any of the optional parameters is not transferred, it is resaved having the default value

Example:

Let us assume that you have created a promotion (id 123456) having a common discount activated by promotion codes. The discount applies to products 11111 and 22222.

Request for creation: POST /v1/promotion/

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "coupons": {
  "coupon_type": "one-time",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10",
  "product_id": [11111, 22222]
 }
}

To make the promotion applicable only to products 22222 and 33333, transfer the request for modification:

PATCH /v1/promotion/123456

{
 "promotion_type": "coupon",
 "coupons": {
  "coupon_type": "one-time",
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10",
  "product_id": [22222, 33333]
 }
}

Note that the request for modification uses the same parameters in the coupons object as when creating the promotion. In this case, the type and the amount of the discount will not change.

After you run the request:

  • The promotion applies to products 22222 and 33333
  • The promotion does not apply to product 11111
  • The remaining properties of the promotion remain unchanged

For promotions using individual discounts, as well as for promotions having type "discounts", the modifications are executed in a similar way.

You can change the type of your promotion. E.g., if a promotion used a discount that is applied after a promotion code is activated, you can make this discount be applied immediately after a product is added to checkout page (without using promotion codes).

At the same time, if the promotional discount has already been applied to any orders, they remain unaffected (order status is ignores). These orders are recorded into the promotion statistics.

To modify the type of your promotion, transfer the following in the request for modification:

  • The parameter containing the type of your promotion: promotion_type, according to the type you require.
  • One of the objects: coupons or discounts (according to the new type of the promotion):
    • If you want the discount in the promotion to be applied immediately when adding a product to the checkout page, you need to change promotion_type to discount. At the same time, the discounts object and all the required nested parameters must be transferred in the request. The coupons object must not be present. 
    • If you want the discount in the promotion to be applied after a promotion code is activated, you need to change promotion_type to coupon. At the same time, the coupons object and all the required nested parameters must be transferred in the request. The discounts object must not be present. 

Let us assume that you have created a promotion (id 123456) having a common discount activated by promotion codes. The discount applies to all your products.

Request for creation: POST /v1/promotion/

{
 "promotion_type": "coupon",
 "promotion_name": "Black Friday",
 "coupons": {
  "coupon_code": [
   "PROMO-001",
   "PROMO-002"
  ],
  "discount_percent": "10"
 }
}

To make the promotional discount be applied to a product immediately after the product is added to the checkout page (without using a promotional code), transfer the request for modification:

PATCH /v1/promotion/123456

{
 "promotion_type": "discount",
 "discounts": {
  "discount_percent": "10"
 }
}

You can modify the discount model of your promotion. E.g., you can set individual discounts for the promotion that provided a common discount to specific products.

Transfer the following in the request for modification:

  • The parameter containing the type of your promotion: promotion_type (using the same value as it was)
  • One of the objects: coupons or discounts (according to the type of the promotion). The object must contain the full set of the parameters nested
    • The nested parameters must match the discount model to be used in the promotion. The set of parameters is the same as when creating the promotion. See the examples for different discount models

Let us assume that you have created a promotion (id 123456) having a common discount. The discount applies to specific products.

Request for creation: POST /v1/promotion/

{
 "promotion_type": "discount",
 "discounts": {
  "product_id": [22222, 33333, 44444],
  "discount_percent": "10"
 }
}

To add the individual 20% discount to product 44444, you need to change the discount model of the promotion to individual discounts. In addition, you must:

  • Transfer the individual 20% discount for product 44444.
  • Transfer the individual discounts for the rest of the products: products 22222 and 33333. The individual discounts must be the same as the common discount that was valid before (10%). Note that, you cannot set one individual discount for product 44444, and make the rest of the products have the common discount. The set of parameters must fully comply with one of the discount models.
  • The parameter containig the common discount (discounts.discount_percent) and the parameter containig the list of products for which the common discount is applied (discounts.product_id) must not be present in the request.

Transfer the request for modification:

PATCH /v1/promotion/123456

{
 "promotion_type": "discount",
 "discounts": {
  "products": [{
    "product_id": 22222,
    "discount_percent": "10"
   }, {
    "product_id": 33333,
    "discount_percent": "10"
   }, {
    "product_id": 44444,
    "discount_percent": "20"
   }
  ]
 }
}