Discount Code Promotions

Use Price Rules discount codes or coupon codes to provide a customer with a discount on checkout. Discount codes are short texts that are entered on a Discount code field on the checkout page, for example BLACKFRIDAY.

note

Discount codes are unique to each shop
Duplicate discount code names are not allowed

Prerequisites

Before you get started, complete the following steps:

Install Bold's Price Rules Engine.
Must have write_discount_codes and read_discount_codes scopes
Read and understand the following guides:

Create a Discount Code

Sample discount code schema

{
  "discount_code": {
    "codes": ["BLACKFRIDAY"],
    "limits": [
      {
        "limit_type": "per_shop",
        "limit_amount": 1000
      }
    ],
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["1234567890123", "1234567890456"]
    },
    "conditions": [
      {
        "type": "CART_SUBTOTAL_MIN",
        "value": 5000
      }
    ],
    "action": {
      "type": "PRICE_ADJUST_PERCENT",
      "value": -15
    },
    "restrict_by_emails": ["[email protected]", "[email protected]"],
    "start_date": "2021-11-25T18:00:00.000Z",
    "expiry_date": "2022-11-27T06:00:00.000Z"
  }
}

Unlike Price Rules rulesets, discount codes are created using the object discount_code. Here are the basic requirements to create a discount code in Price Rules

Attribute	Description
`codes`	One or more discount code names to create. All discount code names listed here will have the same eligibility requirements and pricing actions. Example, `BLACKFRIDAY`, `BACK_TO_SCHOOL`.
`product_selection`	Describes which products, variants or collections are eligible for this discount code. See more below.
`action`	Describes the discount you want to provide and the discount value. See more below.

Product Selection

The product selection object allows you to define which items qualify a cart for the discount code and in some cases which items are eligible to receive the discount. It is very similar to the product selection used on rulesets.

For general discount code actions, a selection determines that at least one of the selected items must be present in the cart for the discount code to be applicable.

Value	Description	Use case
`PRODUCTS_SEARCH`	The discount code applies to products that satisfy a specified product search filter.	Discount code only applies to collection `t-shirts`
`PRODUCTS_EXCEPT`	The discount code applies to any and all products not specified in this product search filter	Discount code applies to all products except those in collection `t-shirts`

Visit Product search filters for more information.

Action

The discount code action is used to affect the price of either the cart subtotal, the shipping rate or an individual item in some way when the discount code is applicable and eligible. The action used to describe the discount type and value are similar to the actions used when creating rulesets.

Type	Description	Child properties	Example use case
`PRICE_ADJUST_PERCENT`	Adjusts the price of each selected item by a percentage.	`type`, `value`	Discount code takes 10% off the price of selected items.
`PRICE_ADJUST_RELATIVE`	Adjusts the price of each selected item by a fixed amount.	`type`, `value`	Discount code takes $1.00 off the price of selected items.
`FREE_SHIPPING`	Adjusts the shipping rate by the exact amount needed to make it zero.	`type`	Discount code discounts the full shipping rate.
`SHIPPING_ADJUST_RELATIVE`	Adjusts the shipping rate by a fixed amount.	`type`, `value`	Discount code discounts the shipping rate by $10.00.
`CART_ADJUST_PERCENT`	Adjusts the cart subtotal by a percentage.	`type`, `value`	Discount code takes 15% off the entire cart's subtotal.

Optional Attributes

You can also specify additional attributes that will limit the usage or the availability of the discount code you create.

Attribute	Description	Use case
`limits`	Describes the usage limit for the discount code.	First 50 customers who use discount code `SPRINGSALE` on checkout receive a 25% discount.
`conditions`	Describes additional conditions that must match for the discount code to be applicable.	Customers who spend $100 or more and use discount code `FREESHIPPING` receive free shipping.
`restrict_by_emails`	Describes a list of customer email addresses who are eligible to use this discount code. Limit of 50 email addresses.	Discount code is only eligible for `[email protected]`, `[email protected]` and `[email protected]`
`start_date`	Describes when the discount code is active and enabled for use. All date and times are UTC.	Discount code `BLACKFRIDAY` is effective starting November 25 2021 18:00 UTC
`expiry_date`	Describes when the discount code expires and is no longer active to be used. All date and times are UTC.	Discount code `BLACKFRIDAY` expires on November 27 2021 05:00 UTC

Usage Limits

A discount code can be limited to a certain number of uses for each customer or it can have a fixed amount of usages for the shop as a whole. By default, a discount code will have no usage limits unless specified.

Property	Description
`limit_type`	Options here are `per_shop` or `per_customer`
`limit_amount`	Amount for the `limit_type`

Conditions

Conditions can set additional restrictions for a discount code to be considered applicable. The conditions used for discount codes are similar to the conditions used on rulesets.

However, there are specific condition types that are available for discount codes.

Type	Description	Child properties	Example use case
`CART_SUBTOTAL_MIN`	The discount code will only apply if the cart subtotal is above a certain minimum value.	`type`, `value`	Spend a minimum of $50.00 and use discount code `FREESHIPPING` for free shipping on checkout.
`QTY_ON_CART`	The discount code will only apply if the total quantity of items in the cart are equal to or greater than the given value.	`type`, `value`	Use discount code `FREESHIPPING` when you purchase 5 items from collection `t-shirts`.
`SHIPPING_RATE_RANGE`	The discount code will only apply if the order's shipping rate is equal to or greater than the minimum value and equal to or lower than the maximum value. Both values are not required, however, at least one must be set when using this condition.	`type`, `min_value`, `max_value`	Discount code promotions for customers whose shipping rates are greater than $25.00
`CUSTOMER_IN_ANY_GROUP_FROM_LIST`	The discount code targets customers based on their membership in groups created on your storefront's ecommerce platform.	`type`, `list`	Discount code promotions for `VIP` customers.
`CUSTOMER_COUNTRY`	The discount code targets customers based on their shipping address country. Note: only ISO-3166 alpha-2 country codes are accepted.	`type`, `list`	Discount code promotions for `US` customers.
`BUY_X_GET_Y_DISCOUNT_CODE`	Configures discounts in a "Buy X, Get Y" style promotion. The discount code targets customers who purchase X and provides them with discount Y. `uses_per_order` limits how many times the same promotion can be applied per order. The `requirement_selection` is similar to the product selection and specifies which X products are required to get the Y discount.	`type`, `buy_quantity`, `get_quantity`, `uses_per_order`, `requirement_selection`	Discount code targets customers who buy 2 of Product A to receive 1 of Product B for free.

Example of a Buy X Get Y discount code condition

{
  "type": "BUY_X_GET_Y_DISCOUNT_CODE",
  "buy_quantity": 3,
  "get_quantity": 2,
  "uses_per_order": 5,
  "requirement_selection": {
    "type": "PRODUCT_SEARCH",
    "variant_ids": ["8888888888888", "9999999999999"]
  }
}

Using Discount Codes

After the discount code is created it is available to be used by customers on the Bold Checkout page.

Currently, the shop must have Bold Checkout enabled:

the Bold Discount Codes plugin must be installed on the Bold Checkout Marketplace
Discount codes must be enabled in Bold Checkout Payment Options

This will enable the "Discount code" text input box on the checkout page. The customer enters their email address and the discount code name and upon clicking the "Apply" button for the discount code, Price Rules API evaluates the eligibility of the customer, the cart items and the discount code entered.

Only one discount code can be applied per order even if there are multiple discount codes applicable for the same checkout context. The discounted amount is shown right below the subtotal for the cart.

After "Complete Order" is clicked, the discount code usage will be registered and the order will be created in the shop platform.

Prerequisites​

Create a Discount Code​

Product Selection​

Action​

Optional Attributes​

Usage Limits​

Conditions​

Using Discount Codes​