Item Promotions

Item Promotions apply a discount to specific products or product categories when a customer adds them to their cart. The discount can be a percentage off or a fixed amount off the item's price, and you can optionally require a minimum purchase amount or quantity before the promotion applies.

How to set it up

Where to find it: Admin → Promotions → New Promotion → select "Item Promotion" as the promotion type.

When you'd use this: You want to discount particular products or entire categories, either automatically or via promo code, such as "20% off all Winter Jackets" or "$5 off Widget XYZ."

What you need first:

• The item codes or category names that should be eligible for the discount
• The discount value (percentage or fixed amount)
• Start and end dates for the promotion
• (Optional) A promo code if customers need to enter it manually
• (Optional) Minimum purchase requirements (cart subtotal or item quantity)
• (Optional) Customer eligibility rules (customer codes, customer groups, or user groups)

Set it up:

1. Navigate to Admin → Promotions and click New Promotion.
2. Set Promotion Type to "Item Promotion."
3. Enter a Description for internal reference (cannot be changed after creation).
4. Choose the Method:
   • Promo Code — customers must enter a code at checkout
   • Auto Promo — discount applies automatically when conditions are met
5. If you selected "Promo Code," enter the Code customers will use (cannot be changed after creation).
6. Set the Start Date Time and End Date Time for when the promotion is valid.
7. Configure Value:
   • Type: "Percentage" or "Fixed Amount"
   • Amount: the discount value (e.g., 20 for 20%, or 5.00 for $5 off)
8. Configure Item Eligibility to define which items qualify:
   • Type: "Item List" (specific products) or "Item Category" (all products in selected categories)
   • Value: list of item codes or category names
9. Configure Minimum Purchase requirements:
   • Type: "Nothing" (no minimum), "Purchase Amount" (minimum cart subtotal), or "Quantity Of Item" (minimum quantity of eligible items)
   • Amount: the threshold value if required
10. Configure Customer Eligibility to limit who can use the promotion:
    • Type: "Nothing" (all customers), "Customer Code" (specific customer accounts), "Customer Group" (named customer groups), or "User Group" (user permission groups)
    • Value: list of codes or group names if applicable
11. Configure Maximum Discount Use to limit redemption:
    • Type: "Unlimited" (no limit), "One Per User" (each customer can use it once), or "X Amount Of Time" (total redemption limit across all customers)
    • Amount: the redemption limit if "X Amount Of Time" is selected
12. Set Active to true to enable the promotion immediately (subject to start/end dates).
13. Click Save.

Configuration options

Field	What it does	Allowed values	Required
Description	Internal label for the promotion; appears in admin lists	Any text	Yes
Method	How customers activate the promotion	"Promo Code", "Auto Promo"	Yes
Code	The promo code customers enter (only for Promo Code method)	Alphanumeric string, unique per store	Yes (if Method = Promo Code)
Start Date Time	When the promotion becomes active	ISO 8601 timestamp	Yes
End Date Time	When the promotion expires	ISO 8601 timestamp	Yes
Value → Type	Whether the discount is a percentage or fixed dollar amount	"Percentage", "Fixed Amount"	Yes
Value → Amount	The discount value	Number ≥ 0	Yes
Item Eligibility → Type	How to select eligible items	"Item List", "Item Category"	Yes
Item Eligibility → Value	List of item codes or category names	Array of strings	Yes
Minimum Purchase → Type	Condition customers must meet to qualify	"Nothing", "Purchase Amount", "Quantity Of Item"	Yes
Minimum Purchase → Amount	Threshold for the minimum purchase requirement	Number ≥ 0	Yes (if Type ≠ "Nothing")
Customer Eligibility → Type	Who can use the promotion	"Nothing", "Customer Code", "Customer Group", "User Group"	Yes
Customer Eligibility → Value	List of customer codes or group names	Array of strings	Yes (if Type ≠ "Nothing")
Maximum Discount Use → Type	How many times the promotion can be redeemed	"Unlimited", "One Per User", "X Amount Of Time"	Yes
Maximum Discount Use → Amount	Total redemption limit	Integer ≥ 1	Yes (if Type = "X Amount Of Time")
Active	Whether the promotion is enabled	true, false	Yes

Using it day-to-day

1. Customer experience (Auto Promo): When a customer adds an eligible item to their cart, the discount appears automatically on the item line if all conditions are met (date range, minimum purchase, customer eligibility).

2. Customer experience (Promo Code): Customer enters the promo code at checkout; eligible items in their cart receive the discount if all conditions are met.

3. Admin visibility: Active promotions appear in the Promotions list. You can see redemption counts for "X Amount Of Time" promotions and track which orders used which codes.

4. Order records: The promotion discount appears as a line-item adjustment on the order, showing the original price, discount amount, and final price for each eligible item.

5. Expiry handling: Once the End Date Time passes, the promotion stops applying automatically, and promo codes return an "expired" message if entered.

6. Usage limits: For "One Per User" promotions, the system tracks each customer's redemptions and prevents reuse. For "X Amount Of Time" promotions, the system increments a counter with each order and stops accepting the promotion once the limit is reached.

Troubleshooting

• "Promotion not found" or promo code doesn't work: Check that the promotion is marked Active and that the current date/time falls between Start Date Time and End Date Time.

• Discount doesn't apply to some items in the cart: Verify that the items match the Item Eligibility configuration—check item codes or category assignments match exactly.

• "Minimum purchase not met" error: The cart subtotal (for "Purchase Amount") or quantity of eligible items (for "Quantity Of Item") is below the threshold configured in Minimum Purchase.

• Customer can't use the promotion: Check Customer Eligibility settings—the customer's account, customer group, or user group may not be in the allowed list.

• Promo code shows "maximum uses exceeded": The promotion has reached its redemption limit set in Maximum Discount Use. For "One Per User," that customer has already used it once. For "X Amount Of Time," the global limit has been reached.

• Discount amount is wrong: For "Percentage" discounts, verify the amount is the percentage value (e.g., 20 for 20%), not the decimal (0.20). For "Fixed Amount," ensure the amount doesn't exceed the item price, or the discount will cap at the item price.

• Cannot edit Description, Method, Code, or Criteria after saving: These fields are immutable once the promotion is created. You must create a new promotion with the desired settings and deactivate the old one.

• Promotion applies to a Resource instead of Charge Item: Ensure eligible items are configured as standard charge items in your catalog; promotions do not apply to resource-type items.