The Promotion Alerts is a feature that sets alarms to trigger actions when certain products are sold with undesired prices and promotions. It will allow you to set conditions that check if the prices and the promotions are correct. If not, the system will also generate an alert with information about the product sold at unexpected prices.
This guide will describe all the steps to create, update, and delete a Promotion Alert.
Creating a Promotion Alert
To create a new promotion alert, you should use the Create Policy endpoint. Let us take a scenario: you want to be alert on Slack if products from the brand Easy Cosmetics are sold with a discount greater than 40%. To do so, you should create conditions to check unusual prices or promotions.
Setting up the actions
First, you should define the alert action. This array will define what action it should take when encountering products with the wrong discount or promotion. The alert can have multiple steps. See the code below as an example.
_11"actions": [_11 {_11 "id": "SendSlackMessage",_11 "metadata": {_11 "channel": "C01NJFF35R6",_11 "relatedUsers": [_11 "URUNDC2NB"_11 ]_11 }_11 }_11 ]
The id
parameter
Each object inside it contains an id
that establishes what the warning will be. Check the table below for its possible values.
id possible values | Definition |
---|---|
SendSlackMessage | It sends a Slack message to a specific channel. |
SendEmail | It sends an email. |
DeactivatePromotions | It deactivates the promotions. |
In the example case, you should define id
as SendSlackMessage
.
Other parameters
After setting the id
, you will determine the metadata
object that contains the details of the action. Inside it, you should define the channel
where the alert will notify, and the alertDescription
displayed when the alert is valid. You can also inform specific users by including their Slack IDs on the relatedUsers
field.
Other options examples
For sending emails
_10"actions": [_10 {_10 "id": "SendEmail",_10 "metadata": {_10 "emailList": [_10 "email@email.com"_10 ]_10 }_10 }_10 ]
_10"actions": [_10 {_10 "id": "DeactivatePromotions",_10 }_10 ]
After configuring the actions
, you should fill the condition
object with specific information to include the promotion alert context.
Creating the conditions
Every alert will be described by an object that has a condition
parameter. This will teach the VTEX platform how to know if the action should be executed or not. Conditions usually check a parameter described by the key
parameter against thevalues
by means of the operation
.
The condition
object contains a conditions
array, a key
string, a values
array of strings, and an operation
string. The condition
parameter allows recursiveness up to a limit of ten object levels inside it.
To create the alert in the example, you should create one condition to define the brand and another to restrict the discount. First, you create the condition for the brand Easy Cosmetics. To do so, fill your request body as the example below. You can use the Get Brand List to get the Brand ID of the brand.
_10{_10 "conditions": [],_10 "operation": "stringEquals",_10 "key": "brandId",_10 "values": [_10 "2000001"_10 ]_10}
After this, you will create the condition to restrict the discount for the brand. Fill your request body as the example below. In this case, values
contains the percentage discount.
_10{_10 "conditions": [],_10 "operation": "numericGreaterThan",_10 "key": "discountPercentage",_10 "values": [_10 "40.00"_10 ]_10}
In the table below, you can see other possible values to key
. It can affect SKUs, brands, and discounts.
The key
parameter
key possible values | Definition |
---|---|
skuId | SKU ID |
brandId | Brand ID |
discountPercentage | Number of the percentage discount |
Now you should establish a relation between the two created conditions. In this case, both conditions should be valid to the alert active, so you should set the operation
direct from the condition
object to and
. Check the example below.
_21"condition": {_21 "conditions": [_21 {_21 "conditions": [],_21 "operation": "stringEquals",_21 "key": "brandId",_21 "values": [_21 "2000001"_21 ]_21 },_21 {_21 "conditions": [],_21 "operation": "numericGreaterThan",_21 "key": "discountPercentage",_21 "values": [_21 "40.00"_21 ]_21 }_21 ],_21 "operation": "and"_21 }
In the table below, you can see other possible values to operation
. There are numerous ways to relate the conditions you create to the alarm.
The operation
parameter
operation possible values | Definition |
---|---|
stringEquals | It will check the first string inside values , being case sensitive, with the corresponding attribute within the context, when evaluating this policy. |
stringEqualsIgnoreCase | It will check the first string inside values , not being case sensitive, with the corresponding attribute within the context, when evaluating this policy. |
numericEquals | It will consist of the exact number inside values. |
numericLessThan | It will check if the first number is smaller than the one inside values with the corresponding attribute within the context when evaluating this policy. This is a string type. |
numericLessThanEquals | It will check if the first number is smaller than or equals the one inside values with the corresponding attribute within the context when evaluating this policy. This is a string type. |
numericGreaterThan | It will check if the first number is greater than the one inside values with the corresponding attribute within the context when evaluating this policy. This is a string type. |
numericGreaterThanEquals | It will check if the first number is greater than or equals to the one inside value with the corresponding attribute within the context when evaluating this policy. This is a string type. |
bool | It will determine if the condition is true or false , considering what is inside values. |
not | It will negate a list of conditions inside the conditions array. |
or | For the alert to be valid, at least one of the conditions should be satisfied. |
and | For the alert to be valid, all of the conditions should be satisfied. |
dateTimeUtcGreaterThan | The date should be greater than the one inside values . |
dateTimeUtcLessThan | The date should be smaller than the one inside values . |
between | It will check if the corresponding attribute within the context when evaluating this policy is between the other values inside values . The values array must have exactly two strings inside it. |
The values
and
,or
, andnot
are the most common ones to use when theoperation
parameter refers to aconditions
array. Check the request body below as an example of the scenario.
_43{_43 "name": "alert-test",_43 "description": "Alert Test",_43 "statements": [_43 {_43 "actions": [_43 {_43 "id": "SendSlackMessage",_43 "metadata": {_43 "channel": "C01NJFF35R6",_43 "relatedUsers": [_43 "URUNDC2NB"_43 ],_43 "alertDescription": "Avoid selling products from Easy Cosmetics with a discount greater than 40%."_43 }_43 }_43 ],_43 "resource": "vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert",_43 "condition": {_43 "conditions": [_43 {_43 "conditions": [],_43 "operation": "stringEquals",_43 "key": "brandId",_43 "values": [_43 "2000001"_43 ]_43 },_43 {_43 "conditions": [],_43 "operation": "numericGreaterThan",_43 "key": "discountPercentage",_43 "values": [_43 "40.00"_43 ]_43 }_43 ],_43 "operation": "and"_43 }_43 }_43 ]_43 }_43 }
To fill the
resource
of your account, just use the following codevrn:vtex.promotions-alert:aws-us-east-1:{accountName}:master:/_v/promotions_alert
, replacing{accountName}
with the name of your account. If your request is successful, it will return200 OK
.
Updating a Promotion Alert
To update an existing promotion alert, you should use the Update Policy endpoint. Follow the steps below to update a promotion alert.
- Enter the Policy ID in the path.
- Change the desired information on the request body.
- Send the request.
- If the response to the request is
200 OK
, the promotion alert was updated.
Deleting a Promotion Alert
To delete an existing promotion alert, you should use the Delete Policy endpoint. Follow the steps below to delete a promotion alert.
- Enter the Policy ID in the path.
- If the response to the request is
200 OK
, the promotion alert was deleted.