Complete API reference for creating and managing Product Search promotions in Omnium OMS

Product Search Promotions - API Reference

Overview
API Endpoints
Data Models
Creating Promotions
Examples
Advanced Features
Best Practices

Overview

Product Search promotions allow you to create dynamic discounts based on flexible product search criteria. Unlike Category/Brand promotions that use predefined categories and brands, Product Search promotions use Omnium's powerful product search engine to define which products qualify for the discount.

Key Features

Dynamic product selection using advanced search criteria
Support for price-based filtering (e.g., "10% off all products between $50-$100")
Tag-based promotions (e.g., "20% off all products tagged 'Summer2025'")
Inventory-based promotions (e.g., "Discount on in-stock items only")
Date-based filtering (e.g., "Products published in the last 30 days")
Supplier-based promotions (e.g., "15% off all Nike supplier products")
Property-based filtering (e.g., "Discount on products with specific attributes")

Supported Discount Types

✅ Percentage-based discount (e.g., 20% off)
✅ Fixed amount discounts (e.g., $10 off)
✅ Multi-currency support

When to Use Product Search Promotions

Use Product Search Promotions when:

You need dynamic product selection based on multiple criteria
Products frequently change categories or attributes
You want to target products by price range, tags, or properties
You need promotions based on inventory status or publication dates
You want to create promotions for specific suppliers or assortments

Use Category/Brand Promotions when:

You have stable category structures
You only need simple category or brand filtering
Performance is critical (Category/Brand promotions are slightly faster)

API Endpoints

Base URL

/api/promotions

Create Promotion

POST /api/promotions
Content-Type: application/json

Request Body: OmniumPromotionRequest

Update Promotion (Patch)

PATCH /api/promotions
Content-Type: application/json

Request Body: OmniumPromotionPatch

Get Promotions

GET /api/promotions

Delete Promotion

DELETE /api/promotions/{id}

Data Models

OmniumPromotionRequest

The main request model for creating a Product Search promotion.

{
  "id": "string (Unique Id of the promotion, GUID will be generated if not provided)",
  "name": "Product Search Promo Q2",
  "title": "20% off selected items",
  "activeFrom": "2024-04-01T00:00:00Z",
  "activeTo": "2024-06-31T23:59:59Z",
  "markets": ["NOR", "SWE"],
  "stores": ["store1", "store2"],
  "filterOnWarehouseStores": false,
  "customerGroups": [],
  "priority": 0,
  "couponCode": "string (optional)",
  "additionalCoupons": [],
  "canBeCombinedWithOtherPromotions": false,
  "alwaysApply": false,
  "customerClubMembersOnly": false,
  "isBonusPointsReward": false,
  "orderTypes": ["online", "pos"],
  "tags": ["Summer2025"],
  "properties": [],
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 20.0,
      "usePercentage": true,
      "promotionAmounts": null
    },
    "productSearchRequest": {
      "tags": ["Summer2025"],
      "priceFrom": 50.0,
      "priceTo": 200.0,
      "isActive": true
    }
  }
}

OmniumPromotionTypeRequest

The promotion type configuration for Product Search promotions.

{
  "promotionType": 5,
  "reward": {
    "percentage": 20.0,
    "usePercentage": true,
    "promotionAmounts": null
  },
  "productSearchRequest": {
    "tags": ["Summer2025"],
    "isInStock": true,
    "marketId": "NOR"
  }
}

Properties

Property	Type	Required	Description
`promotionType`	int	Yes	Must be `5` for Product Search promotions
`reward`	OmniumPromotionReward	Yes	Discount configuration (percentage or fixed amount)
`productSearchRequest`	OmniumProductSearchRequest	Yes	Product search criteria defining which products qualify

OmniumPromotionReward

Defines the discount to be applied.

{
  "percentage": 20.0,
  "usePercentage": true,
  "promotionAmounts": null
}

For percentage-based discounts:

{
  "percentage": 25.0,
  "usePercentage": true
}

For fixed amount discounts:

{
  "usePercentage": false,
  "promotionAmounts": [
    {
      "amount": 10.00,
      "currency": "NOK",
      "marketId": "NOR"
    },
    {
      "amount": 10.00,
      "currency": "SEK",
      "marketId": "SWE"
    }
  ]
}

Properties

Property	Type	Required	Description
`percentage`	decimal	Conditional	Percentage discount (0-100). Required if `usePercentage = true`
`usePercentage`	bool	Yes	`true` for percentage discount, `false` for fixed amount
`promotionAmounts`	array	Conditional	Fixed amount discounts per currency/market. Required if `usePercentage = false`

OmniumProductSearchRequest

Defines the search criteria for qualifying products. This is a comprehensive model with many filtering options.

Common Search Properties

Property	Type	Description	Example
`marketId`	string	Filter by market	`"NOR"`
`storeId`	string	Filter by store	`"store1"`
`searchText`	string	Full-text search	`"summer dress"`
`productIds`	array	Specific product IDs	`["prod1", "prod2"]`
`productCategoryIds`	array	Category IDs	`["cat123"]`
`tags`	array	Product tags	`["Summer", "Sale"]`
`excludedTags`	array	Exclude products with these tags	`["Clearance"]`
`productType`	string	Product type filter	`"Clothing"`

Price Filtering

Property	Type	Description	Example
`priceFrom`	decimal	Minimum price	`50.00`
`priceTo`	decimal	Maximum price	`200.00`
`storeIdPriceFilter`	string	Store for price filtering	`"store1"`
`customerGroups`	array	Filter prices by customer group	`["VIP"]`

Stock and Status Filtering

Property	Type	Description	Example
`isInStock`	bool?	In stock filter	`true`
`inStockMarketIds`	array	Markets for stock check	`["NOR"]`
`inStockWarehouseIds`	array	Warehouses for stock check	`["warehouse1"]`
`isActive`	bool	Active products only	`true`
`isInactive`	bool	Inactive products only	`false`
`isOnSale`	bool?	Products on sale	`true`
`isPublished`	bool?	Published products	`true`

Product Type Filtering

Property	Type	Description	Example
`isSku`	bool?	SKU products (no variants)	`true`
`isBundle`	bool?	Bundle products	`true`
`isPackage`	bool?	Package products	`true`
`isMainProductVariant`	bool?	Main variants only	`true`

Date-Based Filtering

Property	Type	Description	Example
`modifiedFrom`	DateTime?	Products modified after date	`"2024-01-01T00:00:00Z"`
`modifiedTo`	DateTime?	Products modified before date	`"2024-12-31T23:59:59Z"`
`daysSincePublished`	int?	Days since publication	`30`
`startPublishFrom`	DateTime?	Publish start date from	`"2024-01-01T00:00:00Z"`
`startPublishTo`	DateTime?	Publish start date to	`"2024-12-31T23:59:59Z"`

Supplier and Assortment

Property	Type	Description	Example
`supplierIds`	array	Filter by supplier IDs	`["supplier1"]`
`supplierSkuIds`	array	Filter by supplier SKUs	`["sku123"]`
`assortmentCodeIds`	array	Filter by assortment codes	`["assort1"]`
`isAssortmentCodesRequired`	bool?	Require assortment codes	`true`

Property-Based Filtering

Property	Type	Description	Example
`property`	OmniumPropertyItem	Filter by property key/value	See below
`propertyListId`	string	Predefined property list	`"list1"`

Property Filtering Example:

{
  "property": {
    "key": "Color",
    "value": "Red"
  }
}

Advanced Options

Property	Type	Description	Example
`gtins`	array	Filter by GTIN/EAN	`["1234567890"]`
`externalIds`	array	Filter by external IDs	`["ext123"]`
`promotionIds`	array	Products with specific promotions	`["promo1"]`
`componentIds`	array	Products containing components	`["comp1"]`
`productParentIds`	array	Filter by parent product IDs	`["parent1"]`
`excludedProductIds`	array	Exclude specific products	`["prod1"]`

For complete details on all available search options, see the Product Search API documentation.

Creating Promotions

Basic Product Search Promotion (Tag-Based)

Scenario: "20% off all products tagged 'Summer2025'"

{
  "name": "Summer Sale 2025",
  "title": "20% Off Summer Collection!",
  "activeFrom": "2025-06-01T00:00:00Z",
  "activeTo": "2025-08-31T23:59:59Z",
  "markets": ["NOR", "SWE"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 20.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "tags": ["Summer2025"],
      "isActive": true
    }
  }
}

Price Range Promotion

Scenario: "10% off all products priced between $50 and $150"

{
  "name": "Mid-Range Discount",
  "title": "10% Off $50-$150 Items!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-12-31T23:59:59Z",
  "markets": ["US"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 10.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "priceFrom": 50.0,
      "priceTo": 150.0,
      "marketId": "US",
      "isActive": true
    }
  }
}

In-Stock Promotion

Scenario: "15% off all in-stock products from warehouse 'MAIN'"

{
  "name": "In-Stock Flash Sale",
  "title": "15% Off In-Stock Items!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-01-07T23:59:59Z",
  "markets": ["NOR"],
  "priority": 5,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 15.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "isInStock": true,
      "inStockWarehouseIds": ["MAIN"],
      "marketId": "NOR",
      "isActive": true
    }
  }
}

Fixed Amount Discount

Scenario: "50 NOK off products with tags 'NewArrival'"

{
  "name": "New Arrival Discount",
  "title": "50 NOK Off New Arrivals!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-02-28T23:59:59Z",
  "markets": ["NOR"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "usePercentage": false,
      "promotionAmounts": [
        {
          "amount": 50.00,
          "currency": "NOK",
          "marketId": "NOR"
        }
      ]
    },
    "productSearchRequest": {
      "tags": ["NewArrival"],
      "marketId": "NOR",
      "isActive": true
    }
  }
}

Examples

Example 1: Recently Published Products

Scenario: "25% off products published in the last 30 days"

{
  "name": "New Product Launch Promo",
  "title": "25% Off New Products!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-12-31T23:59:59Z",
  "markets": ["US", "UK"],
  "priority": 5,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 25.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "daysSincePublished": 30,
      "isActive": true
    }
  }
}

Example 2: Supplier-Specific Promotion

Scenario: "10% off all products from supplier 'Nike'"

{
  "name": "Nike Supplier Discount",
  "title": "10% Off Nike Products!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-03-31T23:59:59Z",
  "markets": ["US"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 10.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "supplierIds": ["nike"],
      "isActive": true
    }
  }
}

Example 3: Property-Based Promotion

Scenario: "20% off all products with property 'Color' = 'Red'"

{
  "name": "Red Items Sale",
  "title": "20% Off Red Items!",
  "activeFrom": "2025-02-01T00:00:00Z",
  "activeTo": "2025-02-14T23:59:59Z",
  "markets": ["NOR"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 20.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "property": {
        "key": "Color",
        "value": "Red"
      },
      "isActive": true
    }
  }
}

Example 4: Multi-Criteria Promotion

Scenario: "15% off in-stock products tagged 'Winter' priced between 100-500 NOK"

{
  "name": "Winter Clearance",
  "title": "15% Off Winter Collection!",
  "activeFrom": "2025-03-01T00:00:00Z",
  "activeTo": "2025-03-31T23:59:59Z",
  "markets": ["NOR"],
  "priority": 5,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 15.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "tags": ["Winter"],
      "priceFrom": 100.0,
      "priceTo": 500.0,
      "isInStock": true,
      "marketId": "NOR",
      "isActive": true
    }
  }
}

Example 5: Category-Based with Exclusions

Scenario: "30% off category 'Shoes' except products tagged 'Premium'"

{
  "name": "Shoes Sale - Standard Only",
  "title": "30% Off Shoes (Excludes Premium)!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-01-31T23:59:59Z",
  "markets": ["US"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 30.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "productCategoryIds": ["shoes"],
      "excludedTags": ["Premium"],
      "isActive": true
    }
  }
}

Example 6: Coupon Code Required

Scenario: "Use code SEARCH20 for 20% off tagged products"

{
  "name": "Coupon Code Search Promo",
  "title": "Use Code SEARCH20!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-12-31T23:59:59Z",
  "markets": ["US"],
  "couponCode": "SEARCH20",
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 20.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "tags": ["Eligible"],
      "isActive": true
    }
  }
}

Example 7: Multi-Currency Fixed Amount

Scenario: "$10 off in US, £8 off in UK for tagged products"

{
  "name": "Multi-Currency Tag Discount",
  "title": "Fixed Discount on Selected Items!",
  "activeFrom": "2025-01-01T00:00:00Z",
  "activeTo": "2025-12-31T23:59:59Z",
  "markets": ["US", "UK"],
  "priority": 10,
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "usePercentage": false,
      "promotionAmounts": [
        {
          "amount": 10.00,
          "currency": "USD",
          "marketId": "US"
        },
        {
          "amount": 8.00,
          "currency": "GBP",
          "marketId": "UK"
        }
      ]
    },
    "productSearchRequest": {
      "tags": ["International"],
      "isActive": true
    }
  }
}

Advanced Features

1. Complex Search Criteria Combinations

Product Search promotions support combining multiple search criteria for precise targeting:

{
  "productSearchRequest": {
    "tags": ["Summer", "Outdoor"],
    "priceFrom": 50.0,
    "priceTo": 300.0,
    "isInStock": true,
    "inStockMarketIds": ["NOR", "SWE"],
    "supplierIds": ["supplier1"],
    "isActive": true,
    "daysSincePublished": 90
  }
}

This example targets products that:

Have at least one of "Summer" OR "Outdoor" tags
Are priced between 50-300
Are in stock in Norway or Sweden
Are from a specific supplier
Are active
Were published in the last 90 days

2. Dynamic Product Selection

Unlike static Category/Brand promotions, Product Search promotions dynamically evaluate products at the time of cart calculation. This means:

Products added to categories after promotion creation automatically qualify
Products that no longer meet criteria are automatically excluded
Tag-based promotions automatically include/exclude products as tags change
Inventory-based promotions respect real-time stock levels

3. Performance Considerations

Product Search promotions execute a search query for each cart evaluation. For optimal performance:

Be as specific as possible with search criteria
Use indexed fields (productIds, categoryIds, tags) when possible
Avoid overly broad searches (e.g., no criteria at all)
Consider using Category/Brand promotions for simple scenarios
Test promotion performance in your test environment

4. Combining with Other Promotion Features

Product Search promotions support all standard promotion features:

Customer Group Restrictions:

{
  "customerGroups": [
    {
      "customerGroupId": "vip-members",
      "customerGroupName": "VIP Members"
    }
  ]
}

Store Restrictions:

{
  "stores": ["store1", "store2"],
  "filterOnWarehouseStores": true
}

Order Type Restrictions:

{
  "orderTypes": ["online", "pos"]
}

5. Promotion Combination Rules

Control stacking with other promotions:

{
  "canBeCombinedWithOtherPromotions": true,
  "alwaysApply": false
}

Property	Description
`canBeCombinedWithOtherPromotions`	Allow combination with other combinable promotions
`alwaysApply`	Apply even if other promotions have `canBeCombinedWithOtherPromotions = false`

6. Priority System

Promotions with lower priority numbers are evaluated first (0 = highest priority).

{
  "priority": 0  // Evaluated first
}

7. Translations

Provide localized titles and descriptions:

{
  "promotionTranslations": [
    {
      "marketId": "NOR",
      "title": "20% rabatt på sommerkollektion",
      "description": "Spar på alle sommerprodukter"
    },
    {
      "marketId": "US",
      "title": "20% Off Summer Collection",
      "description": "Save on all summer products"
    }
  ]
}

Best Practices

1. Be Specific with Search Criteria

Always include meaningful search criteria to avoid performance issues:

❌ Bad - Too broad:

{
  "productSearchRequest": {
    "isActive": true
  }
}

✅ Good - Specific:

{
  "productSearchRequest": {
    "tags": ["Summer2025"],
    "priceFrom": 50.0,
    "isActive": true
  }
}

2. Use Appropriate Filters

Choose the right filter type for your use case:

Tags: Best for flexible, changing product sets
Categories: Use when products naturally group by category
Price Range: Ideal for tiered pricing strategies
Supplier: Perfect for vendor-specific promotions
Properties: Use for attribute-based targeting
Date-based: Great for featuring new or seasonal products

3. Test Search Criteria First

Before creating a promotion, test your search criteria using the Product Search API:

POST /api/products/search

This helps you verify:

Number of products that will qualify
Performance of the search query
Correct interpretation of combined filters

4. Set Realistic Date Ranges

Always set activeTo dates to avoid promotions running indefinitely
For time-sensitive promotions (e.g., flash sales), set precise times
Use daysSincePublished for rolling "new product" promotions

5. Consider Performance

Use indexed fields (tags, categoryIds, productIds) for better performance
Avoid complex property queries on high-traffic promotions
Monitor promotion evaluation time in your logs
Consider caching strategies for frequently evaluated promotions

6. Use Descriptive Names

Internal names should clearly indicate the promotion mechanics:

✅ Good: "Search - Summer2025 - 20 percent - price range 50-200"
❌ Bad: "Promo456"

7. Document Complex Criteria

For promotions with multiple search criteria, document the logic:

{
  "name": "Winter Clearance - Complex",
  "description": "Targets in-stock winter products priced 100-500 NOK, excluding premium items, from main warehouse only",
  "promotionData": {
    "productSearchRequest": {
      "tags": ["Winter"],
      "excludedTags": ["Premium"],
      "priceFrom": 100.0,
      "priceTo": 500.0,
      "isInStock": true,
      "inStockWarehouseIds": ["MAIN"]
    }
  }
}

8. Monitor and Optimize

Track promotion performance using analytics
Monitor cart evaluation times
Review products qualifying over time
Adjust search criteria based on business results

9. Use Tags for Organization

Tag promotions for easier filtering and reporting:

{
  "tags": ["Summer2025", "Clearance", "AutoGenerated"]
}

10. Testing Checklist

Before activating Product Search promotions:

✅ Test product search criteria returns expected products
✅ Verify discount calculations are correct
✅ Test with various cart configurations
✅ Validate multi-currency scenarios (if applicable)
✅ Confirm performance is acceptable
✅ Test combination rules with other promotions
✅ Verify customer group restrictions (if used)
✅ Test coupon code functionality (if used)

Common Scenarios & Solutions

Scenario 1: "Discount New Products Only"

Create a rolling promotion for products published recently:

{
  "promotionData": {
    "promotionType": 5,
    "reward": {
      "percentage": 15.0,
      "usePercentage": true
    },
    "productSearchRequest": {
      "daysSincePublished": 14,
      "isActive": true
    }
  }
}

Scenario 2: "Clear Out Old Stock"

Target products that haven't been modified in 180 days:

{
  "productSearchRequest": {
    "modifiedTo": "2024-07-01T00:00:00Z",
    "isInStock": true,
    "isActive": true
  }
}

Scenario 3: "Premium Products Only"

Combine price and tag filters:

{
  "productSearchRequest": {
    "tags": ["Premium"],
    "priceFrom": 500.0,
    "isActive": true
  }
}

Scenario 4: "Specific Market Stock"

Discount only products in stock in a specific market:

{
  "productSearchRequest": {
    "isInStock": true,
    "inStockMarketIds": ["NOR"],
    "marketId": "NOR",
    "isActive": true
  }
}

Scenario 5: "Exclude Sale Items"

Target regular-priced items only:

{
  "productSearchRequest": {
    "isOnSale": false,
    "isActive": true
  }
}

Troubleshooting

Promotion Not Applying

Check:

✅ Is the promotion within its activeFrom and activeTo dates?
✅ Do products in the cart match the productSearchRequest criteria?
✅ Does the cart's market/store match the promotion's markets/stores?
✅ If using a coupon code, has it been applied to the cart?
✅ Are search criteria too restrictive?
✅ For customer group restrictions, does the customer belong to the required group?

No Products Qualifying

Check:

✅ Test the search criteria using the Product Search API
✅ Verify products exist that match ALL criteria
✅ Check if excludedTags or other exclusions are too broad
✅ Verify isActive, isInStock filters aren't excluding all products
✅ Confirm market/store filters align with available products

Discount Amount Incorrect

Check:

✅ For fixed amount discounts, verify promotionAmounts includes the correct currency
✅ For percentage discounts, verify usePercentage = true and percentage is set correctly
✅ Check if other promotions are being combined

Performance Issues

Check:

✅ Search criteria specificity - avoid overly broad searches
✅ Use indexed fields (tags, categoryIds) instead of complex property queries
✅ Consider splitting into multiple targeted promotions
✅ Review promotion evaluation logs for slow queries

API Response Models

Success Response (Create)

{
  "message": "Promotion 6b104835-c95c-4562-9b42-fba2e438eeec added, prices updated: 0",
  "statusCode": 200
}

Error Response

{
  "error": "Validation error message",
  "statusCode": 400
}

Additional Resources

Product Search API: Complete documentation
Promotion Types Overview: See PromotionType enum (0=Shipping, 1=CategoryOrBrand, 2=MultiBuy, 3=OrderAmount, 4=Kit, 5=ProductSearch)
Model Validation: All MaxLength attributes indicate array size limits
Date Formats: Use ISO 8601 format (e.g., 2025-01-01T00:00:00Z)

Support

For questions or issues:

Check this documentation
Review the troubleshooting section
Test search criteria using the Product Search API
Examine API error messages for validation details
Contact your Omnium support team

Document Version: 1.0 Last Updated: 2025 API Version: Compatible with Omnium OMS .NET 9.0+

Product Search Promotions - API Reference

On this page