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.