Promotions Builder API Overview

The Promotions Builder helps users create various types of promotions based on customizable conditions and actions. Through flexible rules and strategies, the Promotions Builder allows merchants to build complex promotions tailored to specific business needs.

The Promotions Builder Object

Name	Type	Required	Description
type	string	Required	Specifies the type of the resource. The type of resource for this promotion is rule_promotion.
name	string	Required	Specifies a name for the promotion.
description	string	Optional	Specifies a description for the promotion. If not provided, you can update the description using the Update endpoint.
enabled	boolean	Required	Specifies whether the promotion is enabled. The options are true or false, and the default setting is false.
automatic	boolean	Optional	Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.
priority	integer	Optional	Specifies the priority of the promotion. Priorities are represented as integers, with higher numbers indicating higher priority. Each priority value must be unique, so no two promotions can have the same priority number. If there is no priority set, the most recently created promotion will be applied. Expired or inactive promotions can have duplicate priorities, but they must be changed to unique when reactived. To remove the priority, pass the null value in the update a Promotions Builder. For example, see Create a Promotion with Priority.
stackable	boolean	Optional	Specifies whether multiple promotions can be stacked to the same cart. By default, it is set to true. If set to false, the promotions cannot be stacked with other promotions. To create a Promotion Builder, for example, see Create a Promotion with Stackable Flag.
start	string	Required	Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. For example, "start": "2000-01-01 12:00". If no time is specified, the default start and end time is set to 00:00.
end	string	Required	Specifies the end date and time of the promotion or the end date of the promotion.

The rule_set Object

Name	Type	Required	Description
rule_set.catalog_ids	string	Optional	Specifies the catalogs that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when rule_set.catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion.
rule_set.currencies	string	Optional	Specifies currencies that are applied for the promotion.
rule_set.rules.strategy	string	Required	Specifies strategies for the rule. Strategy decides how the rules are applied. The following strategies provide different criteria for applying rules, allowing for flexible and customizable promotion management: cart_total: Considers the total value of items in the shopping cart. cart_custom_attribute: Represents custom attributes associated with the entire shopping cart. item_price: Indicates the price of individual items. item_quantity: Considers the quantity of individual items. item_sku: Pertains to specific item SKUs. Supports multiple SKUs separated by a comma. For example, [sku1,sku2]. item_category: Relates to item categories. Supports multiple unique identifiers of categories separated by a comma. For example, [cat1,cat2]. item_attribute: Involves item attributes, which include; Arguments: [productTemplate, field slug value, field type, field value]. For example, "Example: [template-1, brand, string, Adidas, Nike]". The maximum number of attribute values is 20. item_product_id: Displays the product ID. It can be used for items without SKU, like skuless bundles. See Handling both Item SKU and Product ID together When using these strategies, you can combine and or or as needed to specify the criteria. The and strategy is applied when multiple conditions must all be met. The or strategy is applied when at least one of the multiple conditions must be met.
rule_set.rules.children	string[array]	Optional	Specifies an array of rules within a rule set, particularly used when multiple rules are involved in defining a promotion. This structure allows for incorporating several rules within the same rule_set, where each rule establishes the criteria necessary for discount eligibility. Additionally, you can include sub conditions within the rule_set.rules.childrento add additional criteria or conditions that must be met for a particular promotion to be applied. This is helpful for configuring complex promotions that require multiple, layered criteria. For configuring promotions with sub conditions, See Create a Cart Percent Discount with Sub Conditions and Create an Item Promotion with Sub Condition.
rule_set.rules.operator	string	Required	Specifies the operators used for the rule strategy. The eq, gt,lt,gte, and lte operators are supported in the following rule strategies: cart_total item_price item_quantity The in and nin operators are supported in the following rule strategies: item_sku item_category cart_custom_attribute
rule_set.rules.args	string / number	Required	Represents the condition value associated with each rule within the rule set. The number of supported arguments varies based on the rule strategy: For cart_total, item_price, and item_quantity strategies, only one argument is supported. For item_sku and item_category strategies, the args field supports a minimum of 1 and a maximum of 400 arguments. See Arguments

The actions object

Name	Type	Required	Description
rule_set.actions.strategy	string	Required	Defines how the discount is applied. The available options are: cart_discount item_discount shipping_discount shipping_discount applies to shipping groups and can use percentage, fixed discount, or fixed price discounts. See Create a Shipping Discount.
rule_set.actions.args	string/number	Required	The first argument specifies the format for the discount value. The available options are: fixed percent fixed_price The second argument indicates the value associated with the first argument. For example, ["percent", 20]. In the case of fixed_price, the second argument indicates the multiplier, for example, X for amount, and the third argument is the price. For example, ["fixed_price", 4, 100]. See Arguments
rule_set.actions.condition	object	Optional	Defines how to apply discounts based on specified conditions. It supports multiple conditions and utilizes various strategies, operators, and arguments to determine when to apply the discount. See Create a Promotion with Conditions. Additionally, you can also include sub condition under actions object. A sub condition is an additional condition that further refines or restricts when the action associated with the rule should be executed. It provides more granularity and specificity to the rule, ensuring that the action is applied only under certain circumstances. See Create a Cart Percent Discount with Sub Conditions and Create an Item Promotion with Sub Condition
rule_set.actions.condition.strategy	string	Required	Strategy specifies the condition strategy to be used. Available options include: cart_total item_price item_quantity item_sku item_category The and strategy is applied when multiple conditions must all be met. For shipping_discount, the only supported value is shipping_type.
rule_set.actions.condition.operator	string	Required	Supported operators depend on the strategy used. For example: eq, gt, lt, gte, and lte operators:Supported for item_price and item_quantity in and nin operators: Supported for item_sku, item_category, and other strategies. For shipping_discount, only the in operator is supported.
rule_set.actions.condition.args	string	Required	Arguments for the condition are specified. This could be a single value or a list of values depending on the strategy and operator used. For example, for the item_quantity strategy with the gte operator, the argument [4] means that the condition is met if the quantity of the item is greater than or equal to 4. For shipping_discount, an array of shipping types can be specified, for example, ["FEDEX", "UPS"]. The maximum number of values is 400.
rule_set.actions.limitations	object	Optional	Defines how limitiations are applied to promotions. These limitations dictate how the promotion can be used and what criteria must be met for it to be applied. For more information, see Action Limitations.

Sample Response

{
    "data": {
        "type": "rule_promotion",
        "id": "e42ec2df-5682-4047-bc22-9e5eb932ca4a",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "$5 off cart with custom attribute",
        "description": "$5 off cart with custom attribute",
        "enabled": true,
        "automatic": true,
        "priority": 100,
        "rule_set": {
            "catalog_ids": null,
            "currencies": null,
            "rules": {
                "strategy": "cart_custom_attribute",
                "operator": "in",
                "args": [
                    "member_status",
                    "string",
                    "gold",
                    "platinum"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        500
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-26T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-01-24T21:27:13.1Z",
                "updated_at": "2024-01-24T21:27:13.1Z"
            }
        }
    }
}

The Promotions Builder Custom Fields

Promotion builder object supports one or more custom fields where a user can create custom fields attached to the promotion object. See Flows on how to create custom fields.