orcaqubits/saleor-promotions

Saleor Promotions and Discounts

Before writing code

Fetch live docs:

1. Web-search site:docs.saleor.io promotions catalog order rules for promotion types and rule configuration
2. Web-search site:docs.saleor.io vouchers voucher codes for voucher creation and usage patterns
3. Web-search site:docs.saleor.io gift cards for gift card creation, activation, and redemption
4. Fetch https://docs.saleor.io/docs/developer/discounts and review the promotion model, rules, and conditions
5. Web-search site:docs.saleor.io manual discount order staff for staff-applied manual discounts
6. 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 discounts

Fetch the Saleor promotions and voucher documentation for exact mutation inputs, predicate syntax, and discount stacking behavior before implementing.