[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")
Restriction: You can access only promotions created by the API user (username) that sends the PATCH request.
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:
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
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.
If the transferred value doesn't match the current promotion type, the promotion type will be modified accordingly. See examples of changes in a separate guide.
promotion_name
string
Promotion name
Maximum of 255 characters.
If the parameter is not transferred, the current name will not change
status
boolean
Promotion status
Value options:
true - active
false - inactive
If the parameter is not transferred, the current activity will not change.
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 serverIf the parameter is transferred, the condition must be met: date_from ≤ date_to
If the parameter is not transferred, the current promotion start date will not change
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 serverIf the parameter is transferred, the condition must be met: date_from ≤ date_to
If the parameter is not transferred, the current promotion end date will not change
coupons
object
required*
Promotion code data
If "promotion_type":"discount", this parameter must not be transferred.
If "promotion_type":"coupon":
If you change the promotion type from "discount" to "coupon" in this request, this parameter is required - *.
If the current promotion type is "coupon" and the parameter is not transferred, the promotion code data for the current promotion will not change.
If the current promotion type is "coupon" and the parameter is transferred, all the values within the nested parameters will be completely updated with the new values. If any of the nested parameters is not transferred, its value will revert to default one if specified.
If the parameter is transferred, the requirements for filling nested parameters are the same as when creating a promotion
discounts
object
required*
Discount data
If "promotion_type":"coupon", this parameter must not be transferred.
If "promotion_type":"discount":
If you change the promotion type from "coupon" to "discount" in this request, this parameter is required - *.
If the current promotion type is "discount" and the parameter is not transferred, the discount data for the current promotion will change.
If the current promotion type is "discount" and the parameter is transferred, all the values within the nested parameters will be completely updated with the new values. If any of the nested parameters is not transferred, its value will revert to default one if specified.
If the parameter is transferred, the requirements for filling nested parameters are the same as when 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
HTTP code | Description |
HTTP/1.1 400 Bad Request | The request is not valid (error in parameters; necessary data is not transferred, etc.). |
HTTP/1.1 401 Unauthorized | Unsuccessful authorization. |
HTTP/1.1 404 Not found | Invalid request URL or no promotion having the identifier transferred is found. If no promotion is found, an additional additional error code will return in the response body. |
HTTP/1.1 500 Request Error | Internal Server Error. Please try again later or contact support. |
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
Error | Message | Description |
11200 | Promotion not found: [promotion id] | No promotion with the identifier transferred is found, or you do not have the rights to get the data (incl. If a different API user created the promotion). |
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
Support | |
Our resources |