Using Policy Engine API on Promotion Alerts

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.

"actions": [
                    {
                        "id": "SendSlackMessage",
                        "metadata": {
                            "channel": "C01NJFF35R6",
                            "relatedUsers": [
                                "URUNDC2NB"
                            ]
                        }
                    }
                ]

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 valuesDefinition
SendSlackMessageIt sends a Slack message to a specific channel.
SendEmailIt sends an email.
DeactivatePromotionsIt 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

"actions": [
                    {
                        "id": "SendEmail",
                        "metadata": {
                            "emailList": [
                              "[email protected]"
                            ]
                        }
                    }
                ]

For deactivating the promotions

"actions": [
                    {
                        "id": "DeactivatePromotions",
                    }
                ]

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 the values 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.

{
  "conditions": [],
  "operation": "stringEquals",
  "key": "brandId",
  "values": [
    "2000001"
  ]
}

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.

{
  "conditions": [],
  "operation": "numericGreaterThan",
  "key": "discountPercentage",
  "values": [
    "40.00"
  ]
}

In the table below, you can see other possible values to key. It can affect SKUs, brands, and discounts.

The key parameter

key possible valuesDefinition
skuIdSKU ID
brandIdBrand ID
discountPercentageNumber 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.

"condition": {
                    "conditions": [
                        {
                            "conditions": [],
                            "operation": "stringEquals",
                            "key": "brandId",
                            "values": [
                                "2000001"
                            ]
                        },
                        {
                            "conditions": [],
                            "operation": "numericGreaterThan",
                            "key": "discountPercentage",
                            "values": [
                                "40.00"
                            ]
                        }
                    ],
                    "operation": "and"
                }

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 valuesDefinition
stringEqualsIt will check the first string inside values, being case sensitive, with the corresponding attribute within the context, when evaluating this policy.
stringEqualsIgnoreCaseIt will check the first string inside values, not being case sensitive, with the corresponding attribute within the context, when evaluating this policy.
numericEqualsIt will consist of the exact number inside values.
numericLessThanIt 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.
numericLessThanEqualsIt 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.
numericGreaterThanIt 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.
numericGreaterThanEqualsIt 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.
boolIt will determine if the condition is true or false, considering what is inside values.
notIt will negate a list of conditions inside the conditions array.
orFor the alert to be valid, at least one of the conditions should be satisfied.
andFor the alert to be valid, all of the conditions should be satisfied.
dateTimeUtcGreaterThanThe date should be greater than the one inside values.
dateTimeUtcLessThanThe date should be smaller than the one inside values.
betweenIt 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, and not are the most common ones to use when the operation parameter refers to a conditions array.

Check the request body below as an example of the scenario.

{
        "name": "alert-test",
        "description": "Alert Test",
        "statements": [
            {
                "actions": [
                    {
                        "id": "SendSlackMessage",
                        "metadata": {
                            "channel": "C01NJFF35R6",
                       "relatedUsers": [
                                "URUNDC2NB"
                            ],
                            "alertDescription": "Avoid selling products from Easy Cosmetics with a discount greater than 40%."
                        }
                    }
                ],
                "resource": "vrn:vtex.promotions-alert:aws-us-east-1:kamila:master:/_v/promotions_alert",
                "condition": {
                    "conditions": [
                        {
                            "conditions": [],
                            "operation": "stringEquals",
                            "key": "brandId",
                            "values": [
                                "2000001"
                            ]
                        },
                        {
                            "conditions": [],
                            "operation": "numericGreaterThan",
                            "key": "discountPercentage",
                            "values": [
                                "40.00"
                            ]
                        }
                    ],
                    "operation": "and"
                }
            }
        ]
    }
 }

📘

To fill the resource of your account, just use the following code vrn: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 return 200 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.

  1. Enter the Policy ID in the path.
  2. Change the desired information on the request body.
  3. Send the request.
  4. 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.

  1. Enter the Policy ID in the path.
  2. If the response to the request is 200 OK, the promotion alert was deleted.

Did this page help you?