Skip to main content

Discount Codes

Introduction​

Discount codes can be added to an order, on the checkout page, to provide the customer with a discount. Discount codes are unique to each shop; you cannot have two discount codes named “BLACKFRIDAY” for the same store.

Prerequisites​

Like Price Rules, Discount Codes are composed of Conditions and Actions. Review these documents before proceeding.

Discount Codes created using Price Rules API are only able to be used with Bold Checkout. Review Getting Started for more information on installing and configuring Bold Checkout.

Customizing a Discount Code​

When creating a discount code, some fields are required, and others are optional depending on the desired behavior.

Required fields:

  • A unique name
  • An action that describes what kind of discount you want to provide, and the value
  • A product selection that describes which products or variants are eligible for the discount

You can also provide optional parameters:

  • Limit amounts for how many times that code can be used
  • How above limits should be applied (per customer and/or for the entire shop)
  • Extra conditions that must be matched for the discount code to be eligible

One example of a possible payload to create a discount code is included below. Each piece of the payload will be explained in the next sections.

{
  "discount_code": {
    "codes": ["BLACKFRIDAY"],
    "limits": [
      {
        "limit_type": "per_shop",
        "limit_amount": 1000
      }
    ],
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["9876543210987", "9876543210111"]
    },
    "conditions": [
      {
        "type": "CART_SUBTOTAL_MIN",
        "value": 5000
      }
    ],
    "action": {
      "type": "PRICE_ADJUST_PERCENT",
      "value": -25
    },
    "restrict_by_emails": ["[email protected]", "[email protected]"]
  }
}

Discount Code Name​

The discount code name can be any combination of letters, numbers and characters until the max length of 128. It needs to be unique for that store, but different stores can have discount codes with the same name (e.g.: "BOXING-DAY-2020"). They are completely different entities since each one only affects its own shop.

You can also delete an old discount code and release the name to be used again with a different configuration, there's no restrictions on how many times a code can be deleted and then reused.

Usage Limit​

A discount code will be limitless by default, so to create usage restrictions, a limit must be specified. A discount code can be limited to a certain amount of uses for each customer, or it can have a fixed amount of usages for the shop as a whole. You can also have both limits simultaneously, since "limits" is a list that accepts multiple objects.

Limiting the discount code for the entire shop:

{
  "limit_type": "per_shop",
  "limit_amount": 1000
}

Limiting a discount code per customer:

{
  "limit_type": "per_customer",
  "limit_amount": 1
}

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, but the selections available for discount codes are slightly different than the ruleset default ones. They will be described in detail later on.

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

If you use PRODUCTS_EXCEPT, any product that is not explicitly listed at the selection will be enough to make the cart eligible to the discount code. However, having a product that is listed on PRODUCTS_EXCEPT inside your cart does not disqualify the cart.

When using the actions PRICE_ADJUST_PERCENT or PRICE_ADJUST_RELATIVE, the price adjustment will only be applied to the products included in the selection (or if you are using PRODUCTS_EXCEPT, to the products that are not explicitly listed there).

Product search can match items by their product IDs, variant IDs, SKUs (stock-keeping units) or collection IDs. The product ids are the unique identifiers for the shop platform, and variant IDs are the identifiers for each option that a product might have (like different sizes or colors). In some platforms the products can be grouped in larger collections, in this case the collection identifier can also be used to select a set of products.

Selection using variant IDs:

{
  "type": "PRODUCT_SEARCH",
  "variant_ids": ["6543210123456", "4567890123456"]
}

Selection using product IDs:

{
  "type": "PRODUCT_SEARCH",
  "product_ids": ["9876543210123", "9876543210987", "9876543210111"]
}

Selection using collection IDs:

{
  "type": "PRODUCT_SEARCH",
  "collection_ids": ["12345678901"]
}

Selection using SKUs:

{
  "type": "PRODUCT_SEARCH",
  "sku_ids": ["BLU-TXT-120", "RED-TXT-109"]
}

PRODUCTS_EXCEPT​

PRODUCTS_EXCEPT will include any products that don't have their identifiers listed in the selection. For variants, it will accept all options except for the ones explicitly listed. For collections, it will consider as qualifying any product that doesn’t belong to the selected collection.

Selection using variant IDs:

{
  "type": "PRODUCTS_EXCEPT",
  "variant_ids": ["6543210123456", "4567890123456"]
}

Selection using product IDs:

{
  "type": "PRODUCTS_EXCEPT",
  "product_ids": ["9876543210123", "9876543210987", "9876543210111"]
}

Selection using collection IDs:

{
  "type": "PRODUCTS_EXCEPT",
  "collection_ids": ["12345678901"]
}

PRODUCTS_ALL​

This option defines a discount code that applies to the entire store. It might be especially useful for shipping discounts.

No extra information is required in the selection besides the type.

{
  "type": "PRODUCTS_ALL"
}

Conditions​

You can set some extra restrictions for a discount code to be considered eligible; they are expressed as conditions. You can have several conditions, or omit the conditions parameter entirely (it is optional).

The available conditions are:

CART_SUBTOTAL_MIN​

{
  "type": "CART_SUBTOTAL_MIN",
  "value": 5000
}

Ensures that the discount code will only be applied if the cart subtotal (without shipping rate) is above a certain minimum value. The amount should be provided as an integer, so $50.00 should be given as 5000.

QTY_ON_CART​

{
  "type": "QTY_ON_CART",
  "value": 8
}

Ensures that the discount code will only be applied if the cart contains a quantity of items equal or higher than the given value (they can be different products or copies of the same variant, the condition doesn't check for specific products/variants).

SHIPPING_RATE_RANGE​

{
  "type": "SHIPPING_RATE_RANGE",
  "min_value": 500,
  "max_value": 5000
}

Ensures that the discount code will only be applied if the shipping rate for the current cart is equal or higher than the min_value, and equal or lower than the max_value. It is possible to specify only the minimum or only the maximum limit, they’re both optional. The amount should be provided as an integer, so $50.00 should be given as 5000.

CUSTOMER_IN_ANY_GROUP_FROM_LIST​

{
  "type": "CUSTOMER_IN_ANY_GROUP_FROM_LIST",
  "list": ["VIP", "gold", "wholesale"]
}

Ensures that the discount code will only be applied if the customer belongs to one (or more) of the groups given in the list.

CUSTOMER_COUNTRY​

{
  "type": "CUSTOMER_COUNTRY",
  "list": ["US", "CA", "JP"]
}

Ensures that the discount code will only be applied if the customer shipping address belongs to one of the countries in the list (Please use country codes instead of names, the proper code for each country can be obtained here: https://www.iso.org/obp/ui/#search).

BUY_X_GET_Y_DISCOUNT_CODE​

{
  "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"]
  }
}

This is a special type of condition. It allows you to configure discounts in a "Buy X, Get Y" style. You can set as a requirement for the discount a list of variant_ids (like in the above example), a list of product_ids, a list of sku_ids or a list of collection_ids.

The field buy_quantity says how many items of the required type you need to buy to qualify for the discount.

The field get_quantity defines how many items in your product selection will receive the price discount action if the order qualifies for it.

The field uses_per_order sets a limit on how many times the same "Buy X, Get Y" promotion can be applied per order.

For example: if you configure a "Buy 3 products A, get 2 products B" discount code, and someone adds to their cart 9 products A and 6 products B, uses_per_order will define if the promotion happens 3 times - giving a discount to all 6 products of type B - or if it should apply only once.

note

The BUY_X_GET_Y_DISCOUNT_CODE condition only works with the PRICE_ADJUST_PERCENT action. The percent discount can be 100% (producing a true "Buy 2 Get 1" behaviour) or a smaller percentage, for a "Buy X, Get 25% off in Y" kind of situation.

Actions​

Actions are used to affect the price of one item, the cart subtotal or the shipping rate in some way, when a discount code is considered valid and eligible for a certain checkout scenario.

The actions used to describe the discount type and value are the same actions that can be used to create rulesets.

However, for discount codes not all types of actions are supported, and some shipping actions are exclusive for discount codes. Below there’s a list of examples for all the supported actions.

PRICE_ADJUST_PERCENT​

{
  "type": "PRICE_ADJUST_PERCENT",
  "value": -20
}

Adjusts the price of each selected item by a percentage.

PRICE_ADJUST_RELATIVE​

{
  "type": "PRICE_ADJUST_RELATIVE",
  "value": -500
}

Adjusts the price of each selected item by a relative amount. The amount should be provided as an integer, so $10.00 should be given as 1000. Also, this action has the potential to reduce the price below 0. If that happens this action will be ignored and the discount code will be considered invalid.

FREE_SHIPPING​

{
  "type": "FREE_SHIPPING"
}

Adjusts the shipping rate by the exact amount needed to make it zero. For this action, value is not needed since it’s calculated automatically.

SHIPPING_ADJUST_RELATIVE​

{
  "type": "SHIPPING_ADJUST_RELATIVE",
  "value": -500
}

Adjusts the shipping rate by a relative amount. The value should be always an integer, following the same criteria that is used for PRICE_ADJUST_RELATIVE to represent cents or other fractional money units. If the discount value is bigger than the current shipping rate, the shipping will be free instead of resulting in a negative value.

CART_ADJUST_RELATIVE​

{
  "type": "CART_ADJUST_RELATIVE",
  "value": -4999
}

Adjusts the value of the entire cart by a relative amount. The value should always be an integer, following the same criteria that is used for PRICE_ADJUST_RELATIVE to represent cents or other fractional money units.

CART_ADJUST_PERCENT​

{
  "type": "CART_ADJUST_PERCENT",
  "value": -25
}

Adjust the value of the entire cart by a percentage.

Customer Restrictions​

You can make the discount code eligible only to specific customers by adding the optional field restrict_by_emails.

This field is used to define a list of email addresses, identifying the customers that are allowed to use that discount code. Without the use of restrict_by_emails, the discount code will be applied to any customer whose checkout cart qualifies for it (as long as they haven’t exceeded the code usage limit yet, in case there’s one in place).

The field restrict_by_emails accepts a maximum amount of 50 email addresses. For restricting a code to a larger set of customers, the use of customer groups/tags is recommended instead.

What happens after the discount code is created?​

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

The shop must have Bold Checkout enabled for the Price Rules discount code mechanism to operate.

Once the customer is at the checkout page, an email address must be provided, and then the code can be typed into the "Discount code" text input. When the button "Apply" is clicked, Price Rules API is contacted with the code and some basic information, and it evaluates if that discount code is eligible considering the items in the cart, the customer email address, etc...

Even if multiple codes are eligible for the same checkout context, only one discount code can be applied per order. 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. The order total will already include the adjustments related to the applied discount code.

Depending on the platform, you can see the applied discount code directly in the order details. If your platform does not show the discount code in the order data, you can still see it inside Bold Checkout, navigating to the "Orders" menu and selecting the option "View order details" on the row that corresponds to the order you’re analyzing.