Overview

When you request ads, you can include the items that already appear on the page as context in the decision request. Inventory Item Filtering uses those contextual items to exclude matching items from the ad response.

There are two ways an item can be matched for filtering:

Item ID filtering: an ad item is filtered out when its item ID matches the item ID of a contextual item in the request.
Item group ID filtering: an ad item is filtered out when its item group ID matches the item group ID of a contextual item in the request. Item group ID filtering is available on the DecideAdProducts API only.

Contextual item limit

All decision APIs that support inventory items accept up to 500 contextual items per request. If a request exceeds 500 items, we recommend you to truncate the item list.

This limit reflects real usage, where some pages (such as a shopping cart) can include hundreds of contextual items.

Item group ID filtering

Item group ID filtering lets you exclude a whole group of related items (for example, variants of the same product) based on the item group ID rather than a single item ID.

Key points:

Item group ID filtering is supported on DecideAdProducts only.
The item group ID must be explicitly provided in the request for item group ID filtering to take effect.
Only the first 50 contextual values are used for item group ID filtering, to avoid excessive filtering.
Item group ID filtering only takes effect when inventory item filtering is enabled. Disabling item ID filtering automatically disables item group ID filtering. Item ID filtering can be enabled while item group ID filtering is disabled.

Behavior by ad type

The default behavior and configurability differ by ad type and decision API. The following table summarizes the behavior.

Ad type	Decision API	Contextual items field	Item ID filtering default	Item ID configurable	Item group ID filtering
Sponsored Products	DecideAdProducts	inventories.inventory_items	Enabled	Per platform or per inventory	Supported and configurable; first 50 values used; must be explicitly provided
Sponsored Products (legacy)	DecideAdItems	inventory.items	Enabled	Per platform or per inventory	Not supported
Sponsored Banner (legacy)	DecideAdCreative, DecideAdCreativesBulk	inventory.items, inventories.items	Enabled	Per platform or per inventory	Not supported
Sponsored Brands	DecideAdBrands	inventories.items	Disabled	Per inventory only	Not supported
Sponsored Display	DecideAdDisplay	inventories.items	Disabled	Per inventory only	Not supported
Reserved Display	-	-	Not applicable	-	Not supported

Reserved Display

Inventory Item Filtering is not applicable to Reserved Display, because contextual items cannot be provided in a Reserved Display request.

Configuration

Inventory Item Filtering can be configured at two levels:

Platform level: applies as the default across the platform (where supported by the ad type).
Inventory level: applies to a specific inventory and overrides the platform-level default (where supported by the ad type).

For Sponsored Brands and Sponsored Display, only inventory-level configuration applies.

To enable, disable, or change filtering behavior for your platform or a specific inventory, contact your Moloco representative.

Limitations and important notes

A maximum of 500 contextual items is accepted per request; exceeding this returns a 400 error.
Item group ID filtering is available on DecideAdProducts only.
For item group ID filtering, only the first 50 contextual values are used.
The item group ID must be explicitly provided for item group ID filtering to work.
Sponsored Brands and Sponsored Display support item ID filtering at the inventory level only, disabled by default, and do not support item group ID filtering.
Reserved Display does not support inventory item filtering.
Legacy APIs (DecideAdItems, DecideAdCreative, DecideAdCreativesBulk) support item ID filtering only, and no further enhancements are planned for legacy APIs.

FAQ

What does Inventory Item Filtering do?

It removes items from an ad response when those items are already present on the page and are passed as contextual items in the decision request. This prevents serving an ad for an item the shopper is already viewing or has in context.

Is this a new behavior?

No. The filtering behavior existed before but was implicit and undocumented. This page formalizes the behavior and adds official support for item group ID filtering. Existing customers should not see a change based on their historical usage.

How many contextual items can I send?

Up to 500 per request. Requests that exceed 500 items return a 400 error. We recommend you to truncate the item list if it exceeds 500 items.

When can I use item group ID filtering?

Item group ID filtering is available on the DecideAdProducts API only. You must provide the item group ID in the request (the item group ID will not be inferred from the item ID provided), and only the first 50 contextual values are used for filtering.

Why is inventory item filtering not applied for Sponsored Brands or Sponsored Display?

For these ad types, item ID filtering is disabled by default and can only be configured at the inventory level. Item group ID filtering is not supported for these ad types, because they are not item-centric ad types and related-item campaigns are typically preferred.

Does inventory item filtering apply to Reserved Display?

No. Contextual items cannot be provided in a Reserved Display request, so inventory item filtering does not apply.