Documentation

Discount Codes and Cart Predicates

Elevate, May 20-22-2025, Miami Beach, Florida

Learn about the features of Discount Codes and the best practices for using them effectively.

  • After completing this page, you should be able to:

    • Identify the purpose and function of Discount Codes and Cart Predicates in Composable Commerce.
    • Apply best practices for creating and managing Discount Codes and Cart Predicates.
    • Discount Codes—also known as promo codes or coupon codes—are unique alphanumeric strings that customers can enter at checkout to receive a discount. They are a powerful tool in Composable Commerce that act as triggers for predefined Cart Discounts, allowing you to offer targeted discounts to drive sales, reward customer loyalty, and clear inventory.

    How Discount Codes work

    Businesses can offer targeted discounts by distributing unique codes to eligible customers. When a customer applies a Discount Code on a Cart, Composable Commerce applies the associated Cart Discount.

    Some key points to consider when using Discount Codes:

    • Multiple Discount Codes per Cart Discount: you can associate many Discount Codes with a single Cart Discount—for example, you could set up an email promotion and send unique codes to multiple Customers, all linked to the same Cart Discount.
    • Usage limits: a single Cart can have a maximum of 10 Discount Codes applied. A Discount Code can apply up to 10 Cart Discounts.
    • Validity: Discount Codes can have defined validity dates, specifying the time range during which they can be used—for example, a Valentine’s Day promotion from February 1 to February 14.
    • Case sensitivity and length: Discount Codes are case-sensitive and are limited to 64 characters.
    • Activation: Discount Codes must be activated before they can be used.

    How Discount Codes relate to Cart Discounts

    Discount Codes and Cart Discounts are related but distinct. Cart Discounts define the discount logic, specifying what is discounted (total cart price, specific items, shipping) and how (percentage off, fixed amount off, free item), while Discount Codes trigger the application of the Cart Discounts.

    In other words, think of Cart Discounts as the engine that powers the discount and Discount Codes as the key that activates the engine.

    To learn how to set up a Discount Code in the Merchant Center, see Apply Discount Codes.

    Cart Predicates

    When talking about Discount Codes, we need to distinguish between two types of Cart Predicates:
    • A Cart Predicate applied at a Cart Discount level defines if a Cart Discount can apply on a Cart, regardless of whether a Discount Code is used. If the Cart Predicate condition is met, the Cart Discount applies on the Cart; otherwise, the Cart Discount is ignored for that Cart.
    • A Cart Predicate applied at a Discount Code level adds an additional filtering layer. For the discount to apply, the Cart Predicate conditions of both the Cart Discount and Discount Code must be met. Essentially, the DiscountCode cartPredicate acts as a gatekeeper, controlling whether the associated Cart Discounts can even be considered for that Cart.
    The key takeaway is that different Cart Predicates at the Cart Discount and Discount Code levels allow for independent and conditional discount applications. A Cart Discount with requiresDiscountCode = true will still require a valid and linked Discount Code on the Cart for the Cart Discount to apply on the Cart.

    The benefits of using Cart Predicates are:

    • Flexibility: supports complex discount scenarios.
    • Targeted promotions: limits promotions to specific customer segments, cart values, or products.
    • Efficiency: reduces code duplication by allowing Cart Discounts to be reused with different Discount Codes.

    How Cart Predicates affect discount application

    Due to having two levels of Cart Predicates available, we have a number of combinations possible:

    Cart Discount PredicateDiscount Code PredicateScenario Description
    YesNoThe Discount Code enables the Cart Discount. The Cart Discount applies only if its own cartPredicate condition is met.
    YesYesThis enables more granular discount targeting. Both conditions must be met for the discount to apply. You can create scenarios where the Discount Code is only valid for a subset of Carts (for example, Carts from a specific Customer Group or Carts containing a specific Line Item) or where the discount is only applied when both conditions are met.
    NoYesThe Discount Code determines eligibility. If the Discount Code's cartPredicate condition is met, the unrestricted Cart Discount applies.

    Let’s look at a quick example of the third scenario, where we have a Cart Discount with no Cart Predicate, but we have a Discount Code with a Cart Predicate.

    A retailer has created a Cart Discount offering 10% off all Line Items in a Cart, without any restrictions (no CartDiscount cartPredicate). In addition, they have created a Discount Code, VIPCUSTOMER, designed specifically for VIP customers. This is set by a DiscountCode cartPredicate (customer.customerGroup.key = "VIP").

    When a VIP customer enters "VIPCUSTOMER" at checkout, they receive the 10% discount that exists on the Cart Discount level. However, regular customers who attempt to use the same code do not receive any discount.

    Using Cart Predicates in this way allows for a high degree of flexibility and precision when generating discounts.

    Best practices

    1. Implement case normalization (essential): Discount Codes are case-sensitive—for example, if customers use summer20 instead of SUMMER20, an error will be thrown as the code is invalid. We suggest enforcing a consistent case (uppercase is recommended) and then normalizing the input in your frontend or middleware to allow customers to enter codes without error.
    2. Define concise codes: use short codes that are easy to remember that are relevant—for example, "FREESHIPPING," "SUMMER20," "WELCOME10."
    3. Set a validity period: set DiscountCode validFrom and validUntil to control the promotion's duration.
    4. Limit usage: use DiscountCode maxApplications and maxApplicationsPerCustomer to avoid abuse and control discount allocation.
    5. Target specific customers: use DiscountCode cartPredicate to restrict code usage to certain customer segments or cart conditions.
    6. Organize with groups: use DiscountCode groups to categorize Discount Codes for easier management.
    7. Test thoroughly: test Discount Codes in various scenarios to ensure they work as expected, before launch.

    Test your knowledge