API Reference

Omnium Product API Guide

This guide provides a comprehensive overview of the Omnium Product API. It covers key operations such as managing product prices, handling languages, product search, and more, helping you effectively integrate and interact with the API.

Product Languages

In Omnium, product languages are configured through the Omnium configuration page. Each language version of a product is represented as a separate product using a language-based ID convention. For example:

• yellow_tennis_sock_no (Norwegian)
• yellow_tennis_sock_en (English)
• yellow_tennis_sock_se (Swedish)

Market Configuration

Markets are configured with a productContentLanguage, defining which language versions should be used. Language versions that share the same ProductId are grouped together in the UI. Inheritance can be configured so updates in one language automatically apply to others.

Product Category Model

The product category model is documented here.

Product Operations

Product Search

When retrieving products from Omnium, especially for e-commerce, consider the following:

• Leverage Search Parameters
  Use the various search parameters available with SearchProducts to tailor your queries effectively. This endpoint automatically gives you the "best" price for the product based on your search queries: It will filter prices on storeId, marketId, customerId, customerGroupId while also checking promotions filtering on active/inactive prices.
  Keep in mind that SearchProducts is not intended for deep pagination. If you are building an integration and need to fetch all products, you should use the scroll endpoints instead.

• Optimize Data Retrieval
  Use the includedFields and excludedFields parameters to retrieve only necessary data. For example:

  • Do you need to fetch all product categories or custom properties?
  • Could you exclude variants when searching for products on a product list page?

• Predefined Property Lists
  Utilize the PropertyListId search parameter to predefine which custom properties to return, set up directly in the Omnium UI.

• Ensure Accurate Pricing
  Use parameters like marketId, storeId, customerId, and language to get the correct price for returned products.

• Disable Unnecessary Features
  Disable facets unless required for your search. This reduces payload size and improves server and client-side performance.

• Single Product Retrieval
  Consider using SearchProducts instead of GET when fetching individual products, particularly if you don’t need all product properties. This will also ensure that you get the right price for the product based on your search parameters, such as marketId or customerId.

• High-Frequency Products
  For frequently loaded products, such as those visible on checkout or front pages, consider setting up caching with a short expiration time.

• Large scale queries
  For large-scale queries (20,000+ products), typically for most integrations, avoid using SearchProducts as this is not intended for deep pagination. Instead, use ScrollProducts for fetching all matching products.

Searching products

Search products using the SearchProducts endpoint:

SearchProducts documentation

{
  "take": 10,
  "page": 1,
  "searchText": "CamelBak"
}

A simple search object, with a free text search, fetching 10 first items.

Sort order

Products are not sorted by default. They are returned ordered by their document ID. To specify sort order, add sortOrder property to search request:

{
  "take": 10,
  "page": 1,
  "searchText": "CamelBak",
  "sortOrder": "CreatedDescending"
}

Sample query sorted by created date descending.

The following sort orders are available:

• CreatedAscending
• CreatedDescending
• BrandAscending
• BrandDescending
• AverageRatingAscending
• AverageRatingDescending
• ColorAscending
• ColorDescending
• NameAscending
• NameDescending
• SpecificationAscending
• SpecificationDescending
• SupplierNameAscending
• SupplierNameDescending
• SkuIdAscending
• SkuIdDescending
• CatalogAscending
• CatalogDescending
• PriceAscending
• PriceDescending
• InventoryAscending
• InventoryDescending
• IsInStockAscending
• IsInStockDescending
• CostPriceAscending
• CostPriceDescending
• ModifiedAscending
• ModifiedDescending
• LocationAscending
• LocationDescending
• PublishedAscending
• PublishedDescending
• SortIndexAscending
• SortIndexDescending
• PopularityDescending
• PopularityAscending
• DiscountPercentAscending
• DiscountPercentDescending
• ScoreDescending

Secondary and tertiary sort order

To add a secondary sort order, use the SortOrder2nd property in productSearchRequest. If it is used, the primary sort order (SortOrder) is required.

{
  "take": 10,
  "page": 1,
  "sortOrder": "DiscountPercentDescending",
  "sortOrder2nd": "InventoryDescending"
}

Sample query sorting by discount percent, and then by inventory.

To add a third sort order, use SortOrder3rd. If set, the primary (SortOrder) and secondary (SortOrder2nd) sort order are required.

Including and excluding fields

Excluding fields

There are two ways of excluding fields from product search:

1. Using boolean values to exclude large properties:

{
  "take": 10,
  "page": 1,
  "excludedFields": {
    "isVariantsExcluded": true,
    "isProductCategoriesExcluded": true,
    "isPropertiesExcluded": true,
    "isPricesExcluded": true,
    "isAssetsExcluded": true,
    "isInventoryExcluded": true
  }
}

2. Excluding fields from a list of field names:

{
  "take": 10,
  "page": 1,
  "excludedFields": {
    "specificFields": ["productCategories"]
  }
}

Sample query excluding categories from search result.

Include only selected fields

Exclude all fields except for ID. This would only be useful when used together with IncludedFields.

{
  "take": 10,
  "page": 1,
  "excludedFields": {
    "isEverythingExcluded": true
  },
  "includedFields": {
    "specificFields": [
      "color"
    ]
  }
}

Sample query getting only the color field from the product.

Sort index threshold

Sort index can be used for setting a threshold for returning products through search. Typically used for showing the most important products in content blocks or limiting the assortment in product lists in general.

{
  "take": 10,
  "page": 1,
  "sortOrder": "CreatedDescending",
  "sortIndexThreshold": 5
}

Sample query with sort index threshold 5.

Sort index value for a product is the sum of sortIndexBase and sortIndexBoost. The sortIndexBase is calculated by Omnium according to how many stores have the item in stock and how many stores have a price for that product.

In product settings, a boost value for promotion prices can be set by adding a value to omniumSortIndexProviderPromotionBoost. If a product has a price with a promotion, this value will be added to the sort index boost.

Assets

Media File Model

Details on the media file model can be found here.

Uploading Assets

Populate the Assets property with OmniumMediaFile objects to upload assets. External images from the ExternalUrl property will be uploaded to Omnium's CDN, replacing the Url property.

Force Upload

If ForceUpload is set to true:

• The ExternalUrl will be uploaded.
• The Url will be replaced with the new CDN URL.
• After replacement, ForceUpload is reset to false to avoid re-uploading.

Product Options

Product options refer to customizable elements, services, or additional features that can be added to a product. For instance, you can offer engraving on jewelry, allowing customers to choose their preferred text and style. Another example is offering waterproofing for clothing and footwear.

Setup

Here is an example of how you could set up product options:

1. Enable product options in the Omnium product settings.
2. Create a new product type named "ProductOption" in the product configuration.
3. Create a new product and set the type to "ProductOption". Give the product a name ("Engraving" or "Installation" are typical examples of product options). The product must be a SKU, so ensure "Is Sku" is activated and that the product has a SKU Id.
4. Edit a product of your choice (except for the newly created Product Option product) and go to the "Options" tab. The "Title" is an optional text that will be displayed when fetching product options from our API. The Type defines what kind of option this is. Since this is engraving, select "Field" as this should be a text input, and select the product from the product selector. Only use "dropdown" if you are going to have multiple values to choose from.

With this setup, you could use the GetProductOptions endpoint to simplify which product options are available for a product. This is mostly useful if you need to fetch all product option values and product data when you have multiple values.

GetProductOptions documentation

Product options can also be added to products when creating or updating products using standard product endpoints.

Add product option to cart

Use the AddProductOptionsItemToCart endpoint to add product options for a specific order line:

AddProductOptionsItemToCart documentation

Alternative way of handling product options

In order to add product options to a cart, you do not necessarily have to set up product options on products. The endpoint (AddProductOptionsItemToCart) accepts adding a product option to a cart using only a SKU (and, if necessary, a custom price).
If you have specific needs or use cases that do not fit with adding product options to products, you could, for instance, use related products to add possible options, and/or use custom properties for price.

 
{
  "cartId": "CART1234",
  "parentLineItemId": "53c7ba39-4b84-40ef-a14e-0fff3c660528",
  "productOptions": [
    {
      "skuId": "ENGRAVEMENT123",
      "price": 499
    }
  ]
}

Properties and Value Types

Drop-down

The drop-down value type allows you to configure a set of options that can be selected from a dropdown list in the UI.

These options are available when the property is edited, for example, through "Edit Product."

By default, only a single selection is allowed. If multiple selections are needed, enable the setting "Allow multiple selections." Additionally, you can enable "Allow custom dropdown values" to permit adding options that are not predefined.

List

The "List" value type allows multiple values to be added to the same key.

Default properties are not automatically saved or updated to the products. For example, in the "Edit Product" view, you may notice that these properties do not initially appear in the property list on the right. However, when the "Edit" modal is opened, default properties are added to the list, and the value types are updated according to the default properties in settings. These changes are not saved on the product until you click "Save."

Property Model

{
    "key": "Material",
    "value": "Carbon",
    "valueType": "DropDown",
    "keyGroup": ""
}

A property is a key-value pair with non-strongly typed properties.

• Key: The unique identifier.
• Value: The property value.
• ValueType: Defines the data type and determines the UI view & patch behavior for multiKey (multiselect dropdown/list) properties. Valid options include:
  • String, Boolean, DateTime, Date, Number, Textarea, Xhtml, Store, File, DropDown, List
• KeyGroup: Used to group properties in the UI.

Multi-select Drop-down & List Properties

A property can only consist of a single string value. To handle multi-select drop-down and list properties, multiple properties with the same key are stored.

DefaultProperty (from configurations)

In addition to the properties in the property model, default properties include:

{
    "valueOptions": [], // List of strings
    "isCustomValueOptionAllowed": true,
    "isMultiSelectEnabled": true,
    "readOnly": true
}

• ReadOnly: Makes the property read-only in the Omnium UI.
• ValueOptions, isCustomValueOptionAllowed, and isMultiSelectEnabled: Only applicable for properties with valueType = DropDown.
  • ValueOptions: Predefined options for the dropdown/multiselect.
  • isCustomValueOptionAllowed: Enables adding custom values.
  • isMultiSelectEnabled: Allows multiple selections if set to true.

Patch

The "Properties" patch operation is highly flexible and can be customized in several ways:

• Patch.Properties: Contains the properties to be updated.
• Patch.PropertiesRemovalConditions: Specifies conditions for removing existing properties before applying updates.
• Patch.KeepExistingCustomProperties: Controls whether new properties are added to existing ones or replace the entire list (default: true).
• Patch.DontOverwriteExistingPropertyValues: Prevents overwriting properties that already have values. Useful for list or multi-select properties.

PropertiesRemovalConditions

A list of OmniumPropertyItem that specifies conditions for removing existing properties. Maximum length: 250 items. Each condition contains multiple attributes, all of which must match an existing property for removal. For example:

{
    "keyGroup": "KeyGroupToRemove",
    "valueType": "List"
}

This removes properties only if both keyGroup == "KeyGroupToRemove" and valueType == "List". Conditions are evaluated using "OR" logic, so any matching condition triggers removal.

KeepExistingCustomProperties

Determines whether to keep or update existing custom properties.

• Set to false to update the entire properties list.
• Set to true to add new properties to the existing list. Default is true.

DontOverwriteExistingPropertyValues

Controls whether to overwrite existing property values.

• Set to true to skip updating properties that already have values.
• To add values to list/multi-select properties, set this option to true along with valueType: "List" or DropDown. Otherwise, the list property will be overwritten.

Product Alerts

Product Alerts Documentation

About Product Alerts

Product alerts in Omnium allow you to set up notifications to be sent to customers when a product is back in stock.
To enable the product alert feature, you need to configure the productAlertSettings in the product settings. The format of the settings is as follows:

"productAlertSettings": {
    "alertIsDeactivatedThreshold": 60,
    "isProductAlertEnabled": true
}

• 'alertIsDeactivatedThreshold': Specifies the threshold in days after which an alert will be deactivated. Once deactivated, customer contact information is removed from the alert object. (The object will be stored for reporting and statistics).
• 'isProductAlertEnabled': Determines whether the product alert feature is enabled (true) or disabled (false).

Important: Make sure to enable Product Alerts through settings before using.

Before an alert can be sent, you need to add a ProductAlertRequest. This request contains the following information:

{
  "id": "string (nullable: true)",
  "skuId": "string (required)",
  "email": "string (nullable: true)",
  "phone": "string (nullable: true)",
  "storeId": "string (nullable: true)"
}

• 'id' (optional): The unique identifier for the ProductAlert. If not set, it will be automatically assigned a GUID.
• 'skuId' (required): The SkuID of the product to set up an alert for.
• 'email' (optional): The email address to which the alert should be sent.
• 'phone' (optional): The phone number to which the alert should be sent.
• 'storeId' (optional): The StoreID of the specific store to monitor inventory for. If not set, the system will monitor all warehouses.

To view pending product alerts, you can select the 'Product alerts' option from the top right navigation menu in the products view.

Additionally, pending alerts will be visible in a separate tab within the product view.

Setting Up the Scheduled Task

To ensure that the notifications are sent out at the appropriate times, you need to add a scheduled task. The scheduled task should be configured using the following format:

{
  "schedule": "*/10 * * * *",
  "implementationType": "SendProductAlertsScheduledTask",
  "isDisabled": false
}

• schedule: Specifies the frequency at which the task should run, in cron format. In this example, the task runs every 10 minutes.
• implementationType: Indicates the type of task to be executed, which is "SendProductAlertsScheduledTask" in this case.
• isDisabled: Determines whether the task is currently enabled (false) or disabled (true).

Setting Up the Notification Template

To customize the content and timing of the notification sent to customers, you need to set up a notification template named "Product alert - in stock". It is recommended to configure the timing of the notification to allow a few minutes for the stock update to reflect on the online store, in case it is not updated immediately.