[PATCH] Modify promotion

Request Description

PATCH /v1/promotion/[promotion id]

The request allows you to modify the properties of promotion.
This also includes:

• Promotion type

• Discount model

• List of linked promotion codes and their type (for promotions having type "coupon")

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: PATCH

• Format: JSON

• Authorization: token-based

URL Parameters

[promotion id]

required

Promotion identifier.
You can get it from:

• Request for creating promotions

• Request for getting lists of IDs of promotions

Example: /v1/promotion/123456

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

[...]

The list of valid parameters is the same as in the request for creating promotions. The parameter requirements are the same, except:

• promotion_type - required parameter
  If the value transferred does not match the current promotion type, it will change

• promotion_name - optional parameter

• coupons, discounts - optional parameters:

  • If the object is not transferred, the previously set promotion code/discount data is not updated

  • If the object is transferred, all the nested parameter values are fully updated with the new values. If any of the parameters is not transferred, the value changes to the default one, if provided.
    All the requirements for the parameters in the object are the same as those in the request for creating a promotion

Request Example

Let us assume that you have created a lifetime promotion. This promotion has type "discounts" and a common discount amount applied to all of your products.

Request for creation: POST /v1/promotion/

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "discounts": {
  "discount_percent": "50"
 }
}

To limit the validity period of the promotion and make the promotion applicable only to a specific product, transfer the request for modification:

PATCH /v1/promotion/123456

{
 "promotion_type": "discount",
 "date_to": "2022-01-10T09:16:35+03:00",
 "discounts": {
  "product_id": [22222],
  "discount_percent": "50"
 }
}

NOTE:

• The request must include the parameter containing the type of the promotion (promotion_type).

• All the parameters must be transferred in object "discounts", including the discount amount that does not change. Since, if there is object “discounts” (or “coupons”) present in the request, all the nested parameters are updated. If any of the optional parameters is not transferred, it is resaved having the default value.

See the additional examples of promotion modification.

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 ОК.

The successful response returns only if the request is fully complete. In addition:

• If the promotion uses promotional codes and the list of these codes has been modified, then:

  • All the new promotion codes have been successfully created.

  • All the previously present promotion codes have been successfully updated.

  • All the promotion codes not included in the request have been deleted. 
    If the deleted promotion code has already been applied to an order, then it is not deleted from the order (regardless of the status of this order).
    E.g., if an order was created and a discount activated by a promotion code was used, but no payment was made for the order, and the promotion code was deleted from the promotion afterwards, the discount in the order would not change. The orders having deleted promotion codes are recorded into the promotion statistics.

• If a promotion must apply only to specific products, they all can be found and belong to you.

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

The errors are the same as the errors you get in response to the request for creating a promotion.

Additional Error Codes for HTTP 401

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

Additional Error Codes for HTTP 404

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