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/developer/discounts/overview 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/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 discounts
Fetch the Saleor promotions and voucher documentation for exact mutation inputs, predicate syntax, and discount stacking behavior before implementing.
1---2name: saleor-promotions-23description: Configure Saleor promotions — catalog promotions, order promotions, vouchers, manual discounts, gift cards, and discount stacking. Use when setting up pricing rules.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-promotions-27---89# Saleor Promotions and Discounts1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io promotions catalog order rules` for promotion types and rule configuration152. Web-search `site:docs.saleor.io vouchers voucher codes` for voucher creation and usage patterns163. Web-search `site:docs.saleor.io gift cards` for gift card creation, activation, and redemption174. Fetch `https://docs.saleor.io/developer/discounts/overview` and review the promotion model, rules, and conditions185. Web-search `site:docs.saleor.io manual discount order staff` for staff-applied manual discounts196. Fetch `https://docs.saleor.io/developer/gift-cards` and review gift card as product and as payment method2021## Promotion Types2223Saleor distinguishes between two promotion types that apply at different stages:2425| Type | When Applied | Effect |26|------|-------------|--------|27| Catalog promotion | At product display time | Reduces the visible price on product listings and detail pages |28| Order promotion | At checkout time | Applies discount to the order total or specific lines during checkout |2930### Catalog Promotions3132| Aspect | Description |33|--------|-------------|34| Timing | Applied before the product reaches the cart |35| Visibility | Customers see the discounted price on product pages |36| Price display | `undiscountedPrice` and `pricing.discount` show the original and savings |37| Stacking | Multiple catalog promotions can apply to the same product |3839### Order Promotions4041| Aspect | Description |42|--------|-------------|43| Timing | Applied when conditions are met in the checkout |44| Visibility | Discount shown as a line discount or order-level discount |45| Conditions | Based on cart contents, order total, or specific products |46| Application | Automatic when conditions match -- no code required |4748## Promotion Rules and Conditions4950Each promotion contains one or more rules:5152### Rule Structure5354| Field | Description |55|-------|-------------|56| `name` | Rule display name |57| `channels` | Channels where this rule applies |58| `cataloguePredicate` | Conditions based on product, category, collection, or variant |59| `orderPredicate` | Conditions based on order total or checkout lines |60| `rewardValue` | Discount amount (fixed or percentage) |61| `rewardValueType` | `FIXED` or `PERCENTAGE` |62| `rewardType` | For order promotions: `SUBTOTAL_DISCOUNT` or `GIFT` |6364Catalogue predicate conditions: `productPredicate`, `categoryPredicate`, `collectionPredicate`, `variantPredicate`. Order predicate conditions: `discountedObjectPredicate` (minimum subtotal), `totalPrice` (order total threshold).6566## Promotion Management6768### Key Mutations6970| Operation | Mutation | Notes |71|-----------|----------|-------|72| Create promotion | `promotionCreate` | Set name, type, start/end dates, rules |73| Update promotion | `promotionUpdate` | Modify promotion settings |74| Delete promotion | `promotionDelete` | Remove promotion |75| Create rule | `promotionRuleCreate` | Add rule to existing promotion |76| Update rule | `promotionRuleUpdate` | Modify rule conditions and rewards |77| Delete rule | `promotionRuleDelete` | Remove rule from promotion |7879### Promotion Fields8081| Field | Description |82|-------|-------------|83| `name` | Promotion display name |84| `type` | `CATALOGUE` or `ORDER` |85| `startDate` | When the promotion becomes active |86| `endDate` | When the promotion expires (optional) |87| `rules` | Array of promotion rules |88| `metadata` | Custom key-value metadata |8990## Voucher Codes9192Vouchers are code-based discounts that customers enter at checkout:9394### Voucher Types9596| Type | Description |97|------|-------------|98| `ENTIRE_ORDER` | Discount applied to the entire order |99| `SHIPPING` | Free or discounted shipping |100| `SPECIFIC_PRODUCT` | Discount on specific products only |101102### Voucher Configuration103104| Field | Description |105|-------|-------------|106| `code` | The voucher code customers enter |107| `type` | Voucher type (see above) |108| `discountValueType` | `FIXED` or `PERCENTAGE` |109| `discountValue` | Discount amount or percentage |110| `minCheckoutItemsQuantity` | Minimum items required in checkout |111| `minSpent` | Minimum order amount (per channel) |112| `usageLimit` | Total number of times the voucher can be used |113| `applyOncePerCustomer` | Whether each customer can use it only once |114| `applyOncePerOrder` | Whether the discount applies to one item or all matching items |115| `onlyForStaff` | Restrict to staff-created orders |116| `startDate` | Activation date |117| `endDate` | Expiration date |118119### Key Voucher Mutations120121| Operation | Mutation |122|-----------|----------|123| Create voucher | `voucherCreate` |124| Update voucher | `voucherUpdate` |125| Delete voucher | `voucherDelete` |126| Add products | `voucherCataloguesAdd` |127| Remove products | `voucherCataloguesRemove` |128129## Manual Staff Discounts130131Staff users can apply manual discounts to orders:132133| Operation | Mutation | Scope |134|-----------|----------|-------|135| Add order discount | `orderDiscountAdd` | Entire order |136| Update order discount | `orderDiscountUpdate` | Modify existing discount |137| Delete order discount | `orderDiscountDelete` | Remove discount |138| Add line discount | `orderLineDiscountAdd` (draft orders) | Specific line item |139140> 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.141142## Gift Cards143144Gift cards function both as a product type and as a payment method:145146### Gift Card as Product147148| Aspect | Description |149|--------|-------------|150| Product type | Create a product type with `isDigital: true` for gift cards |151| Variants | Each variant represents a gift card denomination |152| Purchase | Customer buys a gift card like any other product |153| Activation | Gift card is automatically created and code sent to buyer |154155### Gift Card as Payment156157| Aspect | Description |158|--------|-------------|159| Application | Customer enters gift card code at checkout |160| Balance | Gift card has a remaining balance that decreases with each use |161| Partial use | Gift card can be used for partial payment; remainder stays as balance |162| Multiple cards | Multiple gift cards can be applied to one checkout |163164### Gift Card Mutations165166| Operation | Mutation | Notes |167|-----------|----------|-------|168| Create gift card | `giftCardCreate` | Staff-created gift card |169| Update gift card | `giftCardUpdate` | Modify balance, expiry |170| Deactivate | `giftCardDeactivate` | Disable without deleting |171| Activate | `giftCardActivate` | Re-enable a deactivated card |172| Resend code | `giftCardResend` | Resend gift card code via email |173| Bulk create | `giftCardBulkCreate` | Generate multiple cards at once |174| Add note | `giftCardAddNote` | Add staff note to gift card |175176## Discount Stacking Rules177178| Scenario | Behavior |179|----------|----------|180| Multiple catalog promotions | All matching promotions apply; discounts stack |181| Catalog promotion + voucher | Both apply; catalog discount reduces base price, voucher applies on top |182| Catalog promotion + order promotion | Both can apply; catalog reduces price, order promotion discounts checkout |183| Multiple vouchers | Only one voucher code per checkout |184| Voucher + manual discount | Voucher applies first; manual discount applies on remaining amount |185| Gift card + other discounts | Gift card applies after all other discounts as a payment method |186187## Best Practices188189- Use catalog promotions for sale prices visible on product pages; order promotions for cart-level discounts190- Use vouchers when a code-based redemption experience is required191- Set `startDate` and `endDate` on promotions to automate sale periods192- Use `usageLimit` and `applyOncePerCustomer` on vouchers to control distribution193- Test promotion stacking behavior in a staging environment before going live194- Use gift cards with expiration dates to manage liability195- Always specify channels on promotion rules to prevent unintended cross-channel discounts196197Fetch the Saleor promotions and voucher documentation for exact mutation inputs, predicate syntax, and discount stacking behavior before implementing.