Promotions

Promotions let you offer discounts and incentives to customers through flexible rules-based campaigns. You can create automatic discounts that apply at checkout, promo codes customers enter manually, percentage or fixed-amount savings, and special offers like Buy X Get Y or free shipping.

Promotion types

CommerceBuild supports four promotion types, each designed for specific discount scenarios:

Order Promotion

Applies a discount to the entire order total when conditions are met. Use this when you want to reward customers for reaching a purchase threshold or to offer store-wide sales. Learn more →

Item Promotion

Applies a discount to specific products or product categories. Use this when you want to discount particular items, clear inventory, or promote a product line. Learn more →

Buy X Get Y

Rewards customers with a discounted or free product when they purchase qualifying items. Use this for bundle deals, "buy one get one" offers, or to encourage purchases of complementary products. Learn more →

Free Shipping

Removes shipping charges when conditions are met. Use this to incentivize larger orders or reward customer segments. Learn more →

Dimensions that apply to all promotions

Every promotion — regardless of type — has these configurable dimensions:

Method

Determines how customers access the promotion:

• Promo Code — Customer must enter a specific code at checkout
• Auto Promo — Automatically applies when conditions are met

Value type

Sets how the discount is calculated (not applicable to Free Shipping):

• Percentage — Discount as a percentage of the eligible amount
• Fixed Amount — Discount as a specific dollar amount

Minimum purchase

Controls when the promotion becomes available:

• Nothing — No minimum required
• Purchase Amount — Customer must reach a minimum order subtotal
• Quantity Of Item — Customer must purchase a minimum quantity of eligible items

Customer eligibility

Restricts who can use the promotion:

• Nothing — All customers are eligible
• Customer Code — Specific customer accounts by code
• Customer Group — All customers in selected groups
• User Group — All users in selected groups

Maximum discount use

Limits how many times the promotion can be applied:

• Unlimited — No limit on usage
• One Per User — Each customer can use it once
• X Amount Of Time — Total usage cap across all customers

Validity period

Every promotion has a start date/time and end date/time that define when it's active. The promotion will not apply outside this window, even if all other conditions are met.

Combination rules

You can specify which other promotion types can be combined with this promotion. This prevents over-discounting while allowing complementary offers to stack.

How to set it up

Where to find it: Admin → Promotions → Add Promotion

When you'd use this: You want to create a new discount campaign, seasonal sale, customer incentive, or any rules-based offer for your store.

What you need first:

• Admin access to Promotions
• Promotions enabled on your store
• For Promo Code promotions: a unique code to assign
• For item-specific promotions: product codes or category IDs
• For customer-restricted promotions: customer codes, customer group IDs, or user group IDs
• Start and end dates/times for the promotion validity period

Set it up:

1. Navigate to Promotions in the Admin interface
2. Click Add Promotion
3. Select the promotion type (Order Promotion, Item Promotion, Buy X Get Y, or Free Shipping)
4. Choose the method:
   • Promo Code — Enter a unique code customers will use
   • Auto Promo — Leave the code field empty
5. Enter a description that identifies this promotion in the admin (customers do not see this)
6. Set the validity period with start and end date/times
7. For Order Promotion, Item Promotion, and Buy X Get Y, configure:
   • Value type (Percentage or Fixed Amount)
   • The discount value (percentage number or dollar amount)
8. Configure minimum purchase requirements:
   • Select Nothing, Purchase Amount, or Quantity Of Item
   • If Purchase Amount: enter the minimum subtotal
   • If Quantity Of Item: enter the minimum quantity
9. For Item Promotion, define item eligibility:
   • Item List — Select specific products by code
   • Item Category — Select product categories
10. Configure customer eligibility:
    • Select Nothing, Customer Code, Customer Group, or User Group
    • If restricted: select or enter the qualifying customers/groups
11. Set maximum discount use:
    • Unlimited — No restrictions
    • One Per User — Each customer can use once
    • X Amount Of Time — Enter the total usage limit
12. For Buy X Get Y, configure the qualifying and reward items (see the Buy X Get Y page for details)
13. For Free Shipping, configure any excluded countries (see the Free Shipping page for details)
14. Select which promotion types can combine with this one
15. Set the promotion to Active if you want it to take effect immediately (within the validity period)
16. Click Save

Configuration options

Common fields (all promotion types)

Field	What it does	Allowed values	Required
Promotion Type	Determines the discount mechanism	Order Promotion, Item Promotion, Buy X Get Y, Free Shipping	Yes
Method	How customers access the promotion	Promo Code, Auto Promo	Yes
Code	The promo code customers enter	Any unique string	Required if Method is Promo Code
Description	Internal label for the promotion	Any text	Yes
Start Date/Time	When the promotion becomes active	Any future or current date/time	Yes
End Date/Time	When the promotion expires	Any date/time after start	Yes
Active	Whether the promotion is enabled	True or false	Yes

Discount value fields (Order Promotion, Item Promotion, Buy X Get Y)

Field	What it does	Allowed values	Required
Value Type	How the discount is calculated	Percentage, Fixed Amount	Yes
Value	The discount amount or percentage	Positive number	Yes

Minimum purchase

Field	What it does	Allowed values	Required
Minimum Purchase Type	Condition that must be met	Nothing, Purchase Amount, Quantity Of Item	Yes
Minimum Amount	Minimum order subtotal	Positive number	Required if type is Purchase Amount
Minimum Quantity	Minimum item quantity	Positive integer	Required if type is Quantity Of Item

Item eligibility (Item Promotion only)

Field	What it does	Allowed values	Required
Item Eligibility Type	How eligible items are defined	Item List, Item Category	Yes
Items	Specific product codes	List of product codes	Required if type is Item List
Categories	Product category IDs	List of category IDs	Required if type is Item Category

Customer eligibility

Field	What it does	Allowed values	Required
Customer Eligibility Type	Who can use the promotion	Nothing, Customer Code, Customer Group, User Group	Yes
Customer Codes	Specific customer account codes	List of customer codes	Required if type is Customer Code
Customer Groups	Customer group IDs	List of group IDs	Required if type is Customer Group
User Groups	User group IDs	List of group IDs	Required if type is User Group

Maximum discount use

Field	What it does	Allowed values	Required
Maximum Discount Use Type	Usage limit mechanism	Unlimited, One Per User, X Amount Of Time	Yes
Maximum Use Count	Total number of times the promotion can be used	Positive integer	Required if type is X Amount Of Time

Combination rules

Field	What it does	Allowed values	Required
Combinable With	Which other promotion types can be used with this one	Order Promotion, Item Promotion, Buy X Get Y, Free Shipping	No

Using it day-to-day

For customers

1. Auto Promo promotions apply automatically at checkout when all conditions are met — the customer sees the discount without needing to do anything
2. Promo Code promotions require the customer to enter the code in the promo code field during checkout
3. When multiple promotions are available, the system automatically applies the combination that provides the best discount
4. If two promotions offer exactly the same discount value, manually entered promo codes take priority over automatic promotions
5. The discount appears as a line item on the order, showing which promotion was applied and the discount amount

For admins

1. The Promotions list in the admin shows all promotions with their ID, description, code (if applicable), active status, promotion type, method, schedule status (Running, Scheduled, or Ended), date range, and usage count
2. Filter promotions using the All, Active, and Inactive tabs to see promotions by status
3. Each promotion type is marked with a color-coded label: Order Promotion (violet), Item Promotion (green), Buy X Get Y (amber), and Free Shipping (blue)
4. The schedule column shows whether a promotion is currently running, scheduled for the future, or has ended, along with the date range
5. The usage count shows how many times the promotion has been applied (for One Per User promotions, this tracks unique customers; for X Amount Of Time promotions, this tracks total uses)
6. Click any promotion to open the editor and view its full details, including all configured rules and historical usage
7. Edit a promotion to change its Start Date/Time, End Date/Time, or Active status — all other fields are locked after creation to maintain promotion integrity
8. A floating save bar appears when you make changes, allowing you to save or discard your edits
9. Delete promotions you no longer need by clicking the delete action in the row (this cannot be undone)
10. The admin interface is available in English, French, and Chinese
11. You can only view, edit, and delete promotions that belong to your store — promotion IDs from other stores will return a not found error
12. When the page is loading, you'll see placeholder content that mirrors the final layout; the page does not show a centered spinner or shift when data arrives

When the discount applies

1. The current date/time must fall within the promotion's validity period (between Start Date/Time and End Date/Time)
2. The promotion must be marked as Active
3. The promotion must not have reached its maximum use limit (if configured)
4. For customer-restricted promotions, the customer must match the eligibility criteria
5. For minimum purchase promotions, the cart must meet the minimum amount or quantity requirement
6. For item-specific promotions, eligible items must be in the cart
7. For Promo Code promotions, the customer must have entered the correct code

Where discounts are recorded

1. Discounts appear as line items on the order in CommerceBuild
2. For Sage 300 integrations, promotion discounts can be mapped to a specific ERP item (see the Map promotion discounts to Sage 300 section below)
3. The promotion ID and description are recorded with each order for reporting and audit purposes

Map promotion discounts to Sage 300 ERP items

Where to find it: Promotions settings in the Admin

When you'd use this: You're using Sage 300 as your ERP and need promotion discounts to appear as line items on orders synced to Sage 300.

What you need first:

• A store integrated with Sage 300
• Promotions enabled on your store
• Either Miscellaneous Items or Non-Stock Items configured in your Sage 300 system
• Admin access to Promotions settings

Set it up:

1. Navigate to the Promotions settings
2. Locate the promotion mapping configuration card
3. In the Item Type dropdown, select either:
   • Miscellaneous Item — for misc charges in Sage 300
   • Non-Stock Item — for non-inventory items in Sage 300
4. Once you've selected an Item Type, the ERP item dropdown becomes available
5. Select the specific item from Sage 300 that should represent all promotion discounts
6. Save your configuration

Using it day-to-day:

Once configured, promotion discounts automatically appear as line items when orders sync to Sage 300. The discount line uses the ERP item you mapped, with the discount amount shown as the extended amount on that line. This single mapping applies to all promotions on your store — you don't need to map each promotion individually.

Troubleshooting:

• ERP item dropdown is disabled — Select an Item Type first. The ERP item dropdown only activates after you choose Miscellaneous Item or Non-Stock Item.
• Discounts not appearing in Sage 300 orders — Verify that you've completed the mapping configuration and that the selected ERP item still exists in your Sage 300 system.

Troubleshooting

• Promotion not applying at checkout — Verify that the promotion is marked as Active, the current date falls within the validity period, the customer meets eligibility criteria, and any minimum purchase requirements are satisfied. For Promo Code promotions, ensure the customer entered the code correctly.
• "Unable to modify" error when editing a promotion — Only Start Date/Time, End Date/Time, and Active status can be changed after a promotion is created. The description, method, code, discount value, eligibility rules, and all other criteria are locked to maintain promotion integrity.
• Promotion reached maximum uses — For promotions configured with X Amount Of Time, check the usage count in the promotions list. If it has reached the maximum use count, the promotion will no longer apply. You can create a new promotion with updated settings or change the maximum use count by creating a replacement promotion (the original cannot be edited).
• One Per User promotion not working for repeat customer — Customers who have already used a One Per User promotion cannot use it again, even from a different device or after logging out and back in. The system tracks usage by customer account.
• Multiple promotions not combining as expected — Check the combination rules for each promotion. If a promotion doesn't allow combining with another type, only the better discount will apply. The system always applies the combination that provides the highest total discount.
• Promo code doesn't take priority over auto promo — Promo codes only take priority when the discount values are exactly equal. If an automatic promotion provides a better discount, it will be applied instead. The system prioritizes customer savings over promotion method.
• Item Promotion not applying to products — For Item List eligibility, verify the product codes are entered correctly and the products are in stock. For Item Category eligibility, verify the products are assigned to the selected categories. Product custom fields can also be used to define eligibility depending on your configuration.
• Customer eligibility not working — For Customer Code eligibility, ensure the customer is logged in and their account code matches one in the configured list. For Customer Group or User Group eligibility, verify the customer's account is assigned to the correct group.
• Minimum purchase requirement not recognized — For Purchase Amount minimums, ensure you're checking the order subtotal before shipping and tax, not the final total. For Quantity Of Item minimums, verify the quantity calculation includes all eligible items in the cart.
• "Promotion not found" error when viewing or editing — This error appears when the promotion ID doesn't exist or belongs to a different store. Verify you're using the correct promotion ID from your store's promotions list. You can only access promotions that belong to your store.