Promotions

This page provides an overview of Omnium’s promotion system and how it works. It covers the main concepts, API endpoints, automatic application logic, priority handling, combination rules, and store/market filtering. Promotions are usually managed through the Omnium UI, but can also be created and maintained via API when needed (for instance, for automation or integration purposes).

Overview

The promotion system in Omnium is a flexible, multi-layered discount engine that supports several types of discounts — including order-level, product-level, and shipping promotions. Promotions are automatically applied to carts and orders based on configured criteria.

Key Components

The Omnium promotion system consists of:

• Omnium UI – The primary interface for creating and managing promotions
• Promotion API – For advanced management, automation, or integrations
• Promotion Engine – Automatic application of discounts to orders and carts
• Promotion Types – Various discount models for different business scenarios

Promotion Types

The system supports several promotion service types:

Product-Level Promotions

• Category/Brand Promotions – Discounts on specific categories or brands
• Multi-Buy Promotions – Quantity-based promotions such as "Buy 2 get 1 free", "3 for 2", or tiered discounts when purchasing multiple items.
• Kit Promotions – Bundle product discounts

Order-Level Promotions

• Order Amount Promotions – Discounts based on order total and/or quantity (e.g. "$10 off orders over $100", "10% off when you buy 5+ items"). See Order Amount API Reference for detailed documentation including the new minimum quantity and condition operator features.

Shipping Promotions

• Shipping Promotions – Free or discounted shipping based on conditions

API Documentation

For detailed API documentation, including request/response schemas and examples:

• Promotions API Swagger Documentation - Interactive API explorer
• MultiBuy & Mix and Match API Reference - Comprehensive guide for MultiBuy promotions
• Order Amount API Reference - Complete guide including minimum quantity and AND/OR conditions
• Product Search API Reference - Documentation for product search promotions
• Tiered Pricing API Reference - Guide for quantity-based tiered pricing

Automatic Promotion Application

Promotions are automatically applied to carts and orders when they are processed by the Omnium system.

Automatic Promotion Application

Promotions are automatically applied to carts and orders when processed by Omnium.
The system evaluates all active promotions that match the current market, store, and order context, and applies the relevant discounts before recalculating totals.

Cart Promotion Control

Carts can be excluded from promotion evaluation by setting IgnorePromotions = true.

Promotion Priority System

Promotions use a two-level priority system:

1. Service Type Priority (Primary)

Promotions are processed in order by promotion service type:

1. Order line promotions (product-level discounts)
2. Shipping promotions
3. Order-level promotions

2. Promotion Priority (Secondary)

Within each service type, promotions are sorted by:

1. Priority value (ascending — lower numbers = higher priority)
2. Reward percentage (descending — higher discounts first)

Tip: Don’t use priorities like 1, 2, 3. Use 100, 200, 300. It makes it easier to insert new campaigns later without editing existing ones.

Promotion Combination Logic

Combination Rules

Promotions can be combined based on the CanBeCombinedWithOtherPromotions property:

• true – Can combine with other promotions
• false – Cannot combine (mutually exclusive)

Additional Combination Controls

• AlwaysApply – Forces promotion application regardless of combination rules
• DisallowCombinationWithCouponDiscounts – Prevents combination with coupon-based discounts
• CanNotBeCombinedWithTags – List of promotion tags that prevent combination

Combination Evaluation

The system evaluates combination rules during promotion processing, filtering out conflicting promotions before final application.

Market and Store Filtering

Market Filtering

Promotions must specify target markets in the markets property. They will only apply to orders from those markets.

Store Filtering

Store filtering has two modes, controlled by filterOnWarehouseStores:

Standard Store Filtering (filterOnWarehouseStores = false)

• Promotion applies if the order’s store ID is in the promotion’s stores list
• Used for store-specific promotions

Warehouse Store Filtering (filterOnWarehouseStores = true)

• Filters order lines by matching warehouse codes in shipments
• Used for promotions targeting specific fulfillment locations

Store Filtering Logic:

• If no stores are specified, the promotion applies to all stores
• If filterOnWarehouseStores is false, checks the order’s store ID against the promotion’s store list
• If filterOnWarehouseStores is true, filtering happens at shipment level

Order Type Filtering

Promotions can be restricted to specific order types using the orderTypes property.

Order Type Filtering:

• If no order types are specified, the promotion applies to all order types (the most common setup)
• If order types are specified, it only applies to matching orders

Important: Promotions with orderTypes specified do not generate product prices automatically, as they depend on order context. These prices won’t appear in PLPs or product pages but will be applied once items are added to the cart.

Price Generation

Automatic Price Generation

Some promotion types automatically generate product prices so they can be displayed in product list pages (PLP) or product detail pages (PDP).
These prices are stored on the products themselves, or in the separate price index if separate prices is enabled, allowing them to be fetched and displayed like regular prices.

Other promotion types, such as multi-buy or order-level promotions, are only evaluated when items are added to a cart. Their value depends on the full order context, for example, a "3 for 2" offer can’t produce a single discounted price until all three items are in the cart.

A promotion will generate product prices when:

1. The promotion type supports price generation
2. isBonusPointsReward is false
3. orderTypes is not set
4. No coupon code is required

Promotion Types and Price Generation

Coupon Management

Coupon Types

1. Primary Coupon – Single coupon code for the promotion
2. Additional Coupons – Multiple coupon codes for the same promotion
3. Personal Coupons – Customer-specific coupons assigned to individual customers

Coupon Usage Tracking

Coupon usage is tracked, and single-use coupons cannot be redeemed more than once. Attempts to reuse a redeemed coupon will result in an error.

External Coupon Providers

The system supports integration with external coupon validation systems for loyalty programs and third-party discount providers.

Best Practices

1. Promotion Design

• Use clear and consistent priority values
• Consider combination rules when creating campaigns
• Test with different order types if you use order-type restrictions
• Validate market and store targeting before deployment

2. Testing

• Test combinations well before major campaigns like Black Friday
• Verify market and store filtering with realistic order data
• Use realistic data volumes during testing
• Validate price generation for promotion types that support it