Getting Started

Use Bold’s Price Rules API to create conditional pricing rules for your products. You manage and deploy pricing rules in collections called rulesets, which are the core resource of the Price Rules API.

In this guide, you will get started with the Price Rules API by accomplishing these tasks:

1. Install Bold Pricing in the Checkout app Marketplace.
2. Create an API access token that is scoped to access Price Rules.
3. Create a ruleset with the Price Rules API.

Install the Bold Pricing Plugin in the Checkout app Marketplace

To install and use Bold Price Rules, you must have Bold Checkout installed on your store. For installation instructions, refer to the Bold Checkout Getting Started guide.

To install the Bold Pricing Plugin through the Bold Checkout Marketplace, follow these steps:

1. Open the Checkout app and navigate to the Marketplace.
2. Click the Install button for Bold Pricing: A Bold Pricing dialog displays, requesting permission to modify your store.
3. To complete installation, click Allow.

The Bold Pricing Plugin is now installed. Next, contact Customer Success to install the Price Rules application.

Create an API access token to access Price Rules

An API access token provides you access to the Bold Price Rules API. The method of generating this token depends on the type of integration you build:

• For private integrations, which are installed on a single store and are not available in the Integrations Marketplace, create your API access token through the Bold Account Center. Complete the steps in Making API Calls to generate this token and make your first API calls.
• For public integrations, which can be made available in the Integrations Marketplace, create your API access token through an OAuth flow. Complete the steps in the Building Public Integrations guide to generate this token and make your first API calls.

When you create your API access token, enable these Price Rules access scopes:

• read_price_rulesets
• write_price_rulesets

To verify that the key or token is valid, use the Price Rules API Simple Communication Test. On a successful request, the API returns a "Hello world" message:

{
  "message": "Successfully reached Price Rules API",
  "data": {
    "hello": "world!"
  }
}

Create a ruleset with the Price Rules API

The core resource in the Price Rules API is the ruleset, which is a collection of rules for adjusting the prices of a selected set of products. Each ruleset requires these objects:

• a product_selection object that defines the products to which the ruleset applies
• a rules object that contains an array of pricing rules to apply to the selected products

For example, this simple ruleset selects the product with sku_id "1234" and applies a 50% discount when the customer is a member of the "Gold" customer group

{
  "ruleset": {
    "external_id": "Simple Ruleset",
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "sku_ids": ["1234"]
    },
    "rules": [
      {
        "type": "DISCOUNT",
        "conditions": [
          {
            "type": "CUSTOMER_GROUP",
            "value": "Gold"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_PERCENT",
            "value": -50
          }
        ]
      }
    ]
  }
}

To invoke the Create Ruleset operation with the Price Rules API, make a POST request to the /price_rules/rules/v2/shops/{shop_identifier}/rulesets endpoint.

note

Price Rules API operations typically require a {shop_identifier}. A shop identifier is a string that Bold generates to uniquely identify a store.

For instructions on how to retrieve a shop identifier, see Get your shop identifier.

When you make the request to create a ruleset, include your shop identifier in the request URL, supply your Bold API access token, and submit your ruleset in the request body:

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": "MY_FIRST_RULE_1234",
             "internal_name": "Example of adjusting product SKU:1234 price by a percentage",
             "product_selection": {
                 "type": "PRODUCT_SEARCH",
                 "sku_ids": [
                     "1234"
                 ]
             },
             "rules": [
                 {
                     "type": "DISCOUNT",
                     "conditions": [
                         {
                             "type": "CUSTOMER_GROUP",
                             "value": "gold"
                         }
                     ],
                     "actions": [
                         {
                             "type": "PRICE_ADJUST_PERCENT",
                             "value": -50
                         }
                     ]
                 }
             ]
         }
     }'

Every API request returns a response in JSON. The response gives information about the status of the request:

• If the request is successful, the API returns a code of "201" with the message "Created".
• If the request is unsuccessful, the API returns a specific error code and message. These error codes and messages further elaborate the reason of failure i.e., 400-Bad Request, 401-Unauthorized, 403-Forbidden, and several more.

Next steps

Now that you have created your first ruleset, you can learn how to integrate Price Rules with your storefront using Storefront Setup pages in the left-hand menu.

For more examples, see Create and Update Rulesets.

For a complete API reference, see the Price Rules API specification.

For troubleshooting help, see Developer tools and Errors.