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 eight promotion types:

Product-Level Promotions (Order Line)

• Category/Brand Promotions (promotionType: 1) – Discounts on specific categories or brands. Configure using categoryAndBrandFilter with the reward object.
• Multi-Buy Promotions (promotionType: 2) – Quantity-based promotions such as "Buy 2 get 1 free", "3 for 2", or tiered discounts when purchasing multiple items.
  • Conditional Pricing – Advanced MultiBuy feature that controls when promotional prices are displayed based on cart conditions
  • Tiered Pricing – Progressive pricing based on quantity thresholds
• Kit Promotions (promotionType: 4) – Bundle product discounts where customers must buy items from multiple component groups
• Product Search Promotions (promotionType: 5) – Dynamic discounts based on product search criteria (tags, price range, stock status, etc.)
• Price List Promotions (promotionType: 6) – Apply discounts from a predefined price list. Configure using priceListId. See Price List Promotions for detailed documentation.
• Cost Price Promotions (promotionType: "CostPricePromotion") – Dynamically calculate selling prices from product cost prices with a configurable markup percentage. Links to a price list containing cost prices and applies the formula: CostPrice x (1 + Markup%) x (1 + Tax%). See Cost Price API Reference for detailed documentation.

Order-Level Promotions

• Order Amount Promotions (promotionType: 3) – 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 minimum quantity and condition operator features.

Shipping Promotions

• Shipping Promotions (promotionType: 0) – Free or discounted shipping based on order amount conditions. Configure using shippingMethods and amountCondition.

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
• Kit Promotions API Reference - Complete guide for bundle/kit promotions
• Conditional Pricing API Reference - Control when promotional prices are displayed based on cart conditions
• Tiered Pricing API Reference - Guide for quantity-based tiered pricing
• Product Search API Reference - Documentation for product search promotions
• Order Amount API Reference - Complete guide including minimum quantity and AND/OR conditions
• Price List Promotions - How price list promotions combine price lists with promotion features
• Cost Price API Reference - Documentation for cost-plus pricing promotions
• Price Filters API Reference - Control which products are eligible based on their price type (discounted, member prices)

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

Price Filters

Price filters allow you to control which products are eligible for a promotion based on their price type. This is useful when you want to prevent promotions from stacking on top of already-discounted or member-specific prices, or conversely, when you want a promotion to apply only to products that are already on sale or have member pricing.

How It Works

Price filtering is controlled by three properties on the promotion:

Price Filter Mode

• None (default) — No filtering. All products are eligible regardless of their price type.
• Exclude — Products matching the selected price types are removed from the promotion.
• Include — Only products matching the selected price types are eligible for the promotion.

Price Types

The priceTypeFilter property uses a flags-based system:

• Discounted — Regular sale/discounted prices where the product has a discount amount and is not a customer club specific price.
• MemberPrice — Customer club specific prices (member prices).
• Discounted, MemberPrice — Both types (combined).

Classification priority: Member prices always take priority. A price marked as a customer club specific price is always classified as MemberPrice, regardless of whether it also has a discount amount.

Use Discounted Price as Base

When useDiscountedPriceAsBase is set to true, the promotion calculates its discount from the already-discounted price instead of the original price. This is only relevant when the promotion allows discounted products (i.e., when discounted prices are not excluded).

Example: A product has an original price of $100 and a sale price of $80. With a 10% promotion:

• useDiscountedPriceAsBase: false (default) — 10% off $100 = $10 discount
• useDiscountedPriceAsBase: true — 10% off $80 = $8 discount

Where Price Filters Apply

Price filters apply in two contexts:

1. Price generation — When the promotion generates product prices for display in product listings and detail pages, the filter determines which existing prices are eligible for promotional pricing.
2. Cart/order evaluation — When the promotion is evaluated at checkout, the filter determines which order lines are eligible for the discount based on the product's prices.

Common Use Cases

For full API documentation including request/response examples, see the Price Filters API Reference.

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