Rulesets and Rules

With Price Rules, you can create rulesets that dynamically manage the pricing of products on your ecommerce store. Each ruleset defines a collection of pricing rules that apply to a selection of products.

Rulesets

Rulesets are the core resource of the Price Rules API. To create a ruleset, you define it as a JSON object and then publish the ruleset via the API.

A ruleset has these basic elements and structure:

Element	Description
Start and expiry dates	Define when a ruleset takes effect. Use for scheduling promotions.
Product selection	Defines the set of product items to which the ruleset applies.
Rules list	A list of pricing rules that apply to the product selection.
Rule	Defines the pricing actions to take when a set of conditions are satisfied.
Conditions	A list of conditions that define criteria for applying a rule to the product selection.
Actions	A list of pricing actions to take when a rule's conditions are satisfied.

The following JSON example schedules a seasonal promotion for product items with SKU IDs 1234-001 and 3329-001. The promotion has two rules that target customer groups — Gold and Silver, respectively. During the promotion, customers who are members of the Gold customer group get a 50% discount while members of the Silver group get 30%:

{
  "ruleset": {
    "external_id": "MY_FIRST_RULE_1234",
    "internal_name": "Example of adjusting product SKU:1234 and SKU:3329 price by a percentage",
    "active": true,
    "start_date": "2022-11-23T00:00:00Z",
    "expiry_date": "2022-11-30T23:59:00Z",
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "sku_ids": ["1234-001", "3329-001"]
    },
    "rules": [
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "CUSTOMER_GROUP",
            "value": "gold"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -50
          }
        ]
      },
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "CUSTOMER_GROUP",
            "value": "silver"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -30
          }
        ]
      }
    ]
  }
}

Price Rules always returns the best available price, so if a customer is a member of multiple customer groups — Gold and Silver in this example — the customer gets the best price, 50% off in this case.

In the above example, the active property is set to true, which is the default value. To deactivate a ruleset, set active to false. While a ruleset is inactive, so are all of its rules.

To examine the JSON schema for rulesets, visit Create Ruleset in the Price Rules API documentation. In the Request body section, click Schema.

Start and expiry dates

Set the start and expiry dates of a ruleset when you want to schedule a promotion for a limited time. Without a start date, the ruleset takes effect as soon as it is published. Without an end date, the ruleset is in effect until deactivated or deleted.

Both the start_date and expiry_date properties take UTC-formatted strings. When a ruleset is not time bound, you can leave these properties out of the request body.

Product selection

The product selection defines which product items the ruleset applies to. You can think of product selection as a search that ranges over your product catalog. Your ruleset applies to the results.

Price Rules allows you to create product selections using these properties:

• Collection
• Product ID
• Product title
• Product type
• SKU ID
• Variant
• Vendor

The following JSON example searches the store by product type for items that are "Tops" or "Ties":

"product _selection": {
    "type": "PRODUCT_SEARCH",
    "product_types": [
        "Tops",
        "Ties"
    ]
}

For more detail and a guide to usage, see Product selection.

Rules

Rules are the basic unit of price adjustment in a ruleset. Each rule is tested against each selected product item in the customer's cart. When a rule's conditions are satisfied, Price Rules applies the rule's pricing actions to the product items.

The following JSON example of a discount rule lowers prices in the product selection by 30% when the customer is a member of the Silver group:

{
  "type": "DISCOUNT",
  "conditions": [
    {
      "type": "CUSTOMER_GROUP",
      "value": "silver"
    }
  ],
  "actions": [
    {
      "type": "PRICE_ADJUST_PERCENT",
      "value": -30
    }
  ]
}

note

The maximum number of rules you can include in a single API request is 500. When an API request exceeds this limit, Price Rules returns one of the following errors: 400 Bad Request or TooManyRulesException.

To avoid this limitation, use multiple requests to publish your ruleset. For example, send the first 500 rules when you Create Ruleset with the Price Rules API, then use the Update Ruleset operation to send the rest of your rules in batches.

Rule type and priority

Each rule has a type, which influences the order in which Price Rules resolves the rule. The example rule in the previous section uses the rule type DISCOUNT, which is also the default when no type is provided.

Rule types map to layers, ranging from layer 0 (the base price) to layer 3. You can think of these layers as a stack, and the Price Rules engine resolves rules starting at layer 0 and works "up" the stack to layer 3.

Rules can also have priority, which orders rules of the same type (within the same layer).

For more on rule types, layers, and priority, see Priority and stacking.

Conditions

Conditions define the criteria for triggering a rule's actions. Each condition is essentially a type:value pair. When a property of a customer's cart satisfies the value defined in a condition, that condition is satisfied. When all of the conditions associated with a rule are satisfied, Price Rules applies the rule's pricing actions to the selected items in the customer's cart.

Price Rules allows you to conditionally trigger a pricing rule based on these attributes:

• Customer ID
• Customer group
• Reference URL
• Traffic from a specific source
• Number of variants
• Number of products
• Custom Order Conditions
• Line item property
• Quantity of line item

Some condition types support comparison operators.

The following JSON example uses an operator to define a condition that is satisfied when the customer is not a member of the Wholesale group:

{
  "type": "CUSTOMER_GROUP",
  "operator": "!=",
  "value": "wholesale"
}

For a guide to usage see Customer-targeted pricing.

For a complete reference, see Conditions.

Actions

Actions define how to adjust the prices of items in the product selection. Each action is essentially a type:value pair. The type defines what kind of adjustment to make, and the value determines the amount.

Price Rules allows you to make these price adjustments:

• Absolute
• Relative
• Percentage
• Case pricing
• Charm pricing
• Fees
• Cart fees

The following JSON example defines an action that sets the price of each case of 20 items to $300.00:

{
  "type": "CASE_PRICING",
  "case_price": 30000,
  "case_size": 20
}

For a guide to usage, see Price adjustments.

For a complete reference, see Actions.