Promotion Codes
Create and manage discount codes that customers can apply at checkout for percentage, monetary, or free shipping discounts.
Promotion Codes lets you create discount codes that customers enter during checkout to receive a price reduction or free shipping. Each code can be configured with a specific discount type, value, expiration date, usage limits, and restrictions by product category, order minimum, or item quantity.
You can manage codes individually through the admin interface or bulk import/export them via Excel spreadsheets.
View Promotion Codes
Navigate to Pricing > Promotion Codes in the admin sidebar. The page displays a paginated grid of all promotion codes for the current store.
Grid Columns
| Column | Description |
|---|---|
| Active | Checkbox indicating whether the code is currently active and redeemable. |
| Code | The promotion code string that customers enter at checkout. |
| Description | A brief description of what the promotion offers. |
| Value | The discount value, formatted by type: a dollar amount (e.g., "$5.00") for monetary value, a percentage (e.g., "25%") for percentage discounts, or "Free Shipping" for free shipping codes. |
| Expiration | The date the code expires. Blank if the code has no expiration. |
| Action | Edit or Delete the promotion code. |
Additional columns (Id, Type, Usage Limit, MinSubTotal, FreeShippingAddon, MinQuantity, MaxQuantity) are available but hidden by default.
Use the search panel to filter the grid by any visible column. The three-dot menu at the top provides Export (download all codes as an Excel file) and Import (bulk upload codes from a spreadsheet).
Add or Edit a Promotion Code
Click Add Promotion Code to create a new code, or click Edit on an existing row. The form is divided into three sections.
Promotion Info
| Field | Description |
|---|---|
| Code | The text string customers type at checkout. Maximum 25 characters. Must be unique within the store. |
| Description | Internal description of the promotion. Maximum 50 characters. Not shown to customers. |
| Active | Checkbox. Only active codes can be redeemed. Inactive codes are ignored at checkout. |
Promotion Details
| Field | Description |
|---|---|
| Discount Type | The type of discount applied. Options: Free Shipping — waives shipping for a specific method. Monetary Value — subtracts a fixed dollar amount from the order. Percentage — subtracts a percentage of the order subtotal. |
| Discount Value | The discount amount or percentage. Shown only when Discount Type is Monetary Value or Percentage. For example, enter 10 for a $10 discount or 10% off. |
| Category | Restrict the promotion to items in a specific product category. Select "None" to apply to all categories. |
| Shipping | Shown only when Discount Type is Free Shipping. Select which shipping method is made free when this code is applied. |
| Free Shipping Add-on | Shown only when Discount Type is Monetary Value or Percentage. When checked, the discount also includes free shipping in addition to the price reduction. |
| Restrict to category | Shown only when Discount Type is Free Shipping. When checked, the free shipping offer applies only if the cart contains items from the selected category. |
Requirements / Expiration
| Field | Description |
|---|---|
| Usage Limit | Maximum number of times a single customer can use this code. Leave blank or set to 0 for unlimited use. |
| Min. SubTotals | Minimum order subtotal required to apply this code. Leave blank or set to 0 for no minimum. |
| End Date | Expiration date for the code (date picker). After this date, the code is automatically rejected at checkout. Leave blank for no expiration. |
| Min Quantity | Minimum item quantity in the cart required to use this code. |
| Max Quantity | Maximum item quantity allowed in the cart for this code to apply. |
Click Save to create or update the code. Click Cancel to return to the list without saving.
Import Promotion Codes
Click the three-dot menu and select Import to open the three-step import wizard.
Step 1: Upload
Upload an Excel file (.xlsx format) with a worksheet named "Promotions" containing these columns: Code, Description, Type, Value, Expiration, UsageLimit, MinSubTotal, Active, FreeShippingAddon, MinQuantity, MaxQuantity.
Rules for the spreadsheet:
- Type values must be
MV(Monetary Value),PC(Percentage), orFS(Free Shipping). - Expiration format:
mm/dd/yyyyor blank for no expiration. - UsageLimit: blank, non-numeric, or less than 1 means unlimited use.
- MinSubTotal: blank, non-numeric, or not greater than 0 means no minimum.
- Active and FreeShippingAddon:
TrueorFalse. - Rows with a blank Code column are skipped.
- All columns should be formatted as text in Excel.
Click Verify to validate the file before proceeding.
Step 2: Verify
Review the parsed promotion codes in a preview grid. Verify that codes, values, and expiration dates were read correctly. Duplicate codes within the file are ignored.
Step 3: Confirm Import
A warning is displayed: importing will completely overwrite all existing promotion codes for the current store. Check the confirmation checkbox and click Finish to execute the import. This action cannot be undone.
Category and shipping method assignments cannot be set via import and must be configured individually after the import completes.
Associations
Print Store
| Area | Effect |
|---|---|
| Checkout promo code entry | Customers enter a promotion code during checkout. The storefront looks up the code via PromotionRepository.FindPromotion() (case-insensitive) and validates it through PromotionHelper.ValidatePromotion(), which checks: active status, expiration, usage limit per customer, minimum subtotal, category match, shipping method match, and quantity range. |
| Discount calculation | When a valid code is applied, the discount is calculated and stored as PromotionTotal in the checkout state. The grand total becomes SubTotal + ShippingTotal + TaxTotal - PromotionTotal. |
| Free shipping validation | For Free Shipping codes, the storefront verifies that the customer's selected shipping method matches the RateRuleId configured on the promotion. If the shipping method does not match, the code is rejected. |
| Order records | When an order is placed with a promotion code, the code and discount amount are saved to the order's promotionCode and promotionTotal fields. This data feeds into the Promotion Codes report. |
| Usage tracking | Usage count is calculated by querying orders placed by the same customer with the same promotion code. When the count reaches the usage limit, the code is rejected for that customer. |
Related Pages
- Checkout Settings — overview of all checkout configuration options
- Orders — view which promotion codes were applied to completed orders
- Reports — analyze promotion code usage and discount totals