Skip to main content

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.

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


  • Install Bold's Price Rules Engine.
  • Must have write_discount_codes and read_discount_codes scopes

Before using discount codes, 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": {
"product_ids": ["1234567890123", "1234567890456"]
"conditions": [
"value": 5000
"action": {
"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

codesOne 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_selectionDescribes which products, variants or collections are eligible for this discount code. See more below.
actionDescribes 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.

ValueDescriptionUse case
PRODUCTS_SEARCHThe discount code applies to products that satisfy a specified product search filter.Discount code only applies to collection t-shirts
PRODUCTS_EXCEPTThe discount code applies to any and all products not specified in this product search filterDiscount code applies to all products except those in collection t-shirts

Visit Product search filters for more information.


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.

TypeDescriptionChild propertiesExample use case
PRICE_ADJUST_PERCENTAdjusts the price of each selected item by a percentage.type, valueDiscount code takes 10% off the price of selected items.
PRICE_ADJUST_RELATIVEAdjusts the price of each selected item by a fixed amount.type, valueDiscount code takes $1.00 off the price of selected items.
FREE_SHIPPINGAdjusts the shipping rate by the exact amount needed to make it zero.typeDiscount code discounts the full shipping rate.
SHIPPING_ADJUST_RELATIVEAdjusts the shipping rate by a fixed amount.type, valueDiscount code discounts the shipping rate by $10.00.
CART_ADJUST_PERCENTAdjusts the cart subtotal by a percentage.type, valueDiscount 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.

AttributeDescriptionUse case
limitsDescribes the usage limit for the discount code.First 50 customers who use discount code SPRINGSALE on checkout receive a 25% discount.
conditionsDescribes 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_emailsDescribes 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_dateDescribes 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_dateDescribes 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.

limit_typeOptions here are per_shop or per_customer
limit_amountAmount for the limit_type


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.

TypeDescriptionChild propertiesExample use case
CART_SUBTOTAL_MINThe discount code will only apply if the cart subtotal is above a certain minimum value.type, valueSpend a minimum of $50.00 and use discount code FREESHIPPING for free shipping on checkout.
QTY_ON_CARTThe discount code will only apply if the total quantity of items in the cart are equal to or greater than the given value.type, valueUse discount code FREESHIPPING when you purchase 5 items from collection t-shirts.
SHIPPING_RATE_RANGEThe 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_valueDiscount code promotions for customers whose shipping rates are greater than $25.00
CUSTOMER_IN_ANY_GROUP_FROM_LISTThe discount code targets customers based on their membership in groups created on your storefront's ecommerce platform.type, listDiscount code promotions for VIP customers.
CUSTOMER_COUNTRYThe discount code targets customers based on their shipping address country. Note: only ISO-3166 alpha-2 country codes are accepted.type, listDiscount code promotions for US customers.
BUY_X_GET_Y_DISCOUNT_CODEConfigures 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_selectionDiscount 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

"buy_quantity": 3,
"get_quantity": 2,
"uses_per_order": 5,
"requirement_selection": {
"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.