Saleor Promotions and Discounts
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io promotions catalog order rules for promotion types and rule configuration
- Web-search
site:docs.saleor.io vouchers voucher codes for voucher creation and usage patterns
- Web-search
site:docs.saleor.io gift cards for gift card creation, activation, and redemption
- Fetch
https://docs.saleor.io/docs/developer/discounts and review the promotion model, rules, and conditions
- Web-search
site:docs.saleor.io manual discount order staff for staff-applied manual discounts
- Fetch
https://docs.saleor.io/docs/developer/gift-cards and review gift card as product and as payment method
Promotion Types
Saleor distinguishes between two promotion types that apply at different stages:
| Type | When Applied | Effect |
|---|
| Catalog promotion | At product display time | Reduces the visible price on product listings and detail pages |
| Order promotion | At checkout time | Applies discount to the order total or specific lines during checkout |
Catalog Promotions
| Aspect | Description |
|---|
| Timing | Applied before the product reaches the cart |
| Visibility | Customers see the discounted price on product pages |
| Price display | undiscountedPrice and pricing.discount show the original and savings |
| Stacking | Multiple catalog promotions can apply to the same product |
Order Promotions
| Aspect | Description |
|---|
| Timing | Applied when conditions are met in the checkout |
| Visibility | Discount shown as a line discount or order-level discount |
| Conditions | Based on cart contents, order total, or specific products |
| Application | Automatic when conditions match -- no code required |
Promotion Rules and Conditions
Each promotion contains one or more rules:
Rule Structure
| Field | Description |
|---|
name | Rule display name |
channels | Channels where this rule applies |
cataloguePredicate | Conditions based on product, category, collection, or variant |
orderPredicate | Conditions based on order total or checkout lines |
rewardValue | Discount amount (fixed or percentage) |
rewardValueType | FIXED or PERCENTAGE |
rewardType | For order promotions: SUBTOTAL_DISCOUNT or GIFT |
Catalogue predicate conditions: productPredicate, categoryPredicate, collectionPredicate, variantPredicate. Order predicate conditions: discountedObjectPredicate (minimum subtotal), totalPrice (order total threshold).
Promotion Management
Key Mutations
| Operation | Mutation | Notes |
|---|
| Create promotion | promotionCreate | Set name, type, start/end dates, rules |
| Update promotion | promotionUpdate | Modify promotion settings |
| Delete promotion | promotionDelete | Remove promotion |
| Create rule | promotionRuleCreate | Add rule to existing promotion |
| Update rule | promotionRuleUpdate | Modify rule conditions and rewards |
| Delete rule | promotionRuleDelete | Remove rule from promotion |
Promotion Fields
| Field | Description |
|---|
name | Promotion display name |
type | CATALOGUE or ORDER |
startDate | When the promotion becomes active |
endDate | When the promotion expires (optional) |
rules | Array of promotion rules |
metadata | Custom key-value metadata |
Voucher Codes
Vouchers are code-based discounts that customers enter at checkout:
Voucher Types
| Type | Description |
|---|
ENTIRE_ORDER | Discount applied to the entire order |
SHIPPING | Free or discounted shipping |
SPECIFIC_PRODUCT | Discount on specific products only |
Voucher Configuration
| Field | Description |
|---|
code | The voucher code customers enter |
type | Voucher type (see above) |
discountValueType | FIXED or PERCENTAGE |
discountValue | Discount amount or percentage |
minCheckoutItemsQuantity | Minimum items required in checkout |
minSpent | Minimum order amount (per channel) |
usageLimit | Total number of times the voucher can be used |
applyOncePerCustomer | Whether each customer can use it only once |
applyOncePerOrder | Whether the discount applies to one item or all matching items |
onlyForStaff | Restrict to staff-created orders |
startDate | Activation date |
endDate | Expiration date |
Key Voucher Mutations
| Operation | Mutation |
|---|
| Create voucher | voucherCreate |
| Update voucher | voucherUpdate |
| Delete voucher | voucherDelete |
| Add products | voucherCataloguesAdd |
| Remove products | voucherCataloguesRemove |
Manual Staff Discounts
Staff users can apply manual discounts to orders:
| Operation | Mutation | Scope |
|---|
| Add order discount | orderDiscountAdd | Entire order |
| Update order discount | orderDiscountUpdate | Modify existing discount |
| Delete order discount | orderDiscountDelete | Remove discount |
| Add line discount | orderLineDiscountAdd (draft orders) | Specific line item |
Manual discounts are only available for draft orders and through staff-facing operations. They cannot be combined with automatic promotions on the same order line.
Gift Cards
Gift cards function both as a product type and as a payment method:
Gift Card as Product
| Aspect | Description |
|---|
| Product type | Create a product type with isDigital: true for gift cards |
| Variants | Each variant represents a gift card denomination |
| Purchase | Customer buys a gift card like any other product |
| Activation | Gift card is automatically created and code sent to buyer |
Gift Card as Payment
| Aspect | Description |
|---|
| Application | Customer enters gift card code at checkout |
| Balance | Gift card has a remaining balance that decreases with each use |
| Partial use | Gift card can be used for partial payment; remainder stays as balance |
| Multiple cards | Multiple gift cards can be applied to one checkout |
Gift Card Mutations
| Operation | Mutation | Notes |
|---|
| Create gift card | giftCardCreate | Staff-created gift card |
| Update gift card | giftCardUpdate | Modify balance, expiry |
| Deactivate | giftCardDeactivate | Disable without deleting |
| Activate | giftCardActivate | Re-enable a deactivated card |
| Resend code | giftCardResend | Resend gift card code via email |
| Bulk create | giftCardBulkCreate | Generate multiple cards at once |
| Add note | giftCardAddNote | Add staff note to gift card |
Discount Stacking Rules
| Scenario | Behavior |
|---|
| Multiple catalog promotions | All matching promotions apply; discounts stack |
| Catalog promotion + voucher | Both apply; catalog discount reduces base price, voucher applies on top |
| Catalog promotion + order promotion | Both can apply; catalog reduces price, order promotion discounts checkout |
| Multiple vouchers | Only one voucher code per checkout |
| Voucher + manual discount | Voucher applies first; manual discount applies on remaining amount |
| Gift card + other discounts | Gift card applies after all other discounts as a payment method |
Best Practices
- Use catalog promotions for sale prices visible on product pages; order promotions for cart-level discounts
- Use vouchers when a code-based redemption experience is required
- Set
startDate and endDate on promotions to automate sale periods
- Use
usageLimit and applyOncePerCustomer on vouchers to control distribution
- Test promotion stacking behavior in a staging environment before going live
- Use gift cards with expiration dates to manage liability
- Always specify channels on promotion rules to prevent unintended cross-channel di
