Skip to main content

Create and Update Rulesets

Introduction​

Within Price Rules, price rules are created (scoped on specific variants, products, or collections) that influence base prices in order to facilitate offering sales or promotions or to enforce other price adjustments. Where competing rules exist, Price Rules always resolves for the best price for the customer.

Price Rules pricing capabilities include:

  • Scheduling offers
  • Discounting (percentage, fixed dollar amount)
  • Setting absolute prices (decrease or increase)
  • Quantity break and limit discounts
  • Customer specific pricing
  • Regulatory fees
  • Location-based pricing
  • Buy/Get offers

Prerequisites​

Price Rules API endpoints that create and update price rules require you to obtain a Bold API authentication key (OAuth Token). To obtain your Bold API authentication key, please refer to the instructions found in Building Public Integrations.

Access Scopes for PRE API

When generating the API authentication token you will be asked to specify the scopes (permissions) you need. Please use the following scopes for PRE:

  • read_price_rulesets - access to read price rule sets
  • write_price_rulesets - access to create, update and delete price rule sets

Once you have received your Bold API token you can review the Price Rules API reference document.

You will also need your shop’s shop_identifier which can be obtained from calling Get Shop Info:

curl --request GET 'https://api.boldcommerce.com/shops/v1/info' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

Creating Rulesets​

Price Rules can accept rules for $-off discounts, %-off discounts, fixed price changes as well as handling pricing for specific customer groups.

note

Currently, Price Rules Headless only works with SKU-based products (using sku_id as the main product identifier) so the remainder of this guide will use SKU-based instructions and examples.

A basic Price Rule contains product selection, a condition, and an action:

{
  "ruleset": {
    "external_id": "MY_FIRST_RULE_1234",
    "internal_name": "Example of adjusting product SKU:1234 and SKU:3329 price by a percentage",
    "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
          }
        ]
      }
    ]
  }
}

In this example, we have a price ruleset for SKU IDs 1234-001 and 3329-001 with specific price rules for 2 customer groups: Gold and Silver. Customers who are members of the Gold customer group get a 50% discount for these products while customers who are members of the Silver customer group get a 30% discount.

Price Rules always returns the best available price, so if a specific customer is a member of multiple customer groups (example: customer is member of both Gold and Silver customer group) the customer will get the best price of 50% off.

To create the above ruleset for your store in Price Rules use the Create Ruleset endpoint with your Bold API token as the OAuth Bearer token in the request:

curl --request POST 'https://api.boldcommerce.com/price_rules/rules/v2/shops/{shop_identifier}/rulesets' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "ruleset": {
             "external_id": "example ruleset",
             "internal_name": "example ruleset",
             "start_date": "2021-11-23T00:00:00Z",
             "expiry_date": "2021-11-30T23:59:00Z",
             "product_selection": {
                 "type": "PRODUCT_SEARCH",
                 "product_ids": [
                     "1234567890123"
                 ]
             },
             "rules": [
                 {
                     "type": "DISCOUNT",
                     "conditions": [
                         {
                             "type": "CUSTOMER_GROUP",
                             "value": "gold"
                         }
                     ],
                     "actions": [
                         {
                             "type": "PRICE_ADJUST_PERCENT",
                             "value": -10
                         }
                     ]
                 }
             ]
         }
     }'

Start and end dates can also be added to a ruleset. The start_date is configured in UTC and notes the date these discounts should begin to apply. If not provided they will apply as soon as possible. The expiry_date is also configured in UTC and notes the date these discounts should expire. If not provided they will apply until they are deleted.

Updating Rulesets​

For any recurring pricing updates for your store, Price Rules API has available endpoints for updating and maintaining your existing rulesets and rules, such as:

Price Rules provides the ability for you to use an external_id for tracking rulesets and rules. This external_id can be the identifier you can use, maintain and track to easily find the ruleset or rule you need to update. This can match an identifier in your inventory system or admin tool. For external_id attributes, visit 4.1 Attributes.

For more information please refer the Price Rules API specifications.