Multi-Inventory Decision Requests and Deduplication

A single decision request can ask for ads for more than one inventory at once. This is called a multi-inventory request. Multi-inventory requests let you fill several placements on a page with one call, and let Moloco deduplicate ads across those placements so the same item, campaign, line item, or advertiser does not appear more than once, depending on ad type.

Overview

When a page has multiple ad placements, you can either send one decision request per placement or send a single multi-inventory request that covers several placements together. Multi-inventory requests are supported across all four official decision APIs - Sponsored Products, Sponsored Brands, Sponsored Display, and Reserved Display.

A multi-inventory request has two advantages:

• Fewer calls. You fill multiple placements with one request.
• Cross-inventory deduplication. Moloco can ensure the same item, campaign, line item, or advertiser (depending on ad type) is not returned twice across the placements in the request.

Support for multi-inventory requests, multiple ads per inventory, and deduplication criteria differs by ad type, as summarized below.

Support by decision API

Limits

The following limits apply to decision requests. Values shown are defaults; Moloco can configure higher limits for your platform, subject to the combined-limit formulas below each table.

Combined-limit formulas (the total across all inventories in one request cannot exceed these products):

• Sponsored Products: inventories per request × ads per inventory ≤ 2,000
• Sponsored Brands: inventories per request × ads per inventory × items per request ≤ 5,000
• Sponsored Display: inventories per request × ads per inventory ≤ 50
• Reserved Display: inventories per request × ads per inventory ≤ 50

Requests that exceed a limit are rejected. If you expect to exceed these limits, contact your Moloco representative.

Deduplication

Deduplication prevents the same ad from appearing more than once in a response. It can happen at two levels: within a single inventory, and across the inventories in a multi-inventory request.

Per-inventory deduplication

Per-inventory deduplication applies within a single inventory. Multiple ads may be considered for that inventory, but duplicates are filtered out based on defined criteria. A basic level of per-inventory deduplication always applies and cannot be disabled:

• Sponsored Products deduplicates by item ID.
• Sponsored Brands and Sponsored Display deduplicate by campaign ID.
• Reserved Display deduplicates by line item ID.

Sponsored Brands, Sponsored Display, and Reserved Display can optionally be configured to deduplicate by ad account ID instead. Sponsored Products supports only item ID, which matches its always-on default, so no additional configuration is needed or possible for Sponsored Products.

When duplicate candidates are found within an inventory, the higher-priority candidate is kept - the winning bid for auction-based ad types, or the higher-priority line item for Reserved Display - and ties are broken at random.

Per-request (cross-inventory) deduplication

Per-request deduplication applies across the inventories in the same multi-inventory request, and is available for all four decision APIs. After each inventory is decisioned, Moloco removes ads that would be duplicated across inventories so the same item, campaign, line item, or advertiser does not appear in more than one placement in the response.

Deduplication criteria by ad type:

• Sponsored Products: item ID
• Sponsored Brands / Sponsored Display: campaign ID or ad account ID
• Reserved Display: line item ID or ad account ID

Two methods control how a cross-inventory duplicate is resolved:

• Waterfall (default). The inventory that appears earlier (lower index) in the request is prioritized; the duplicate is removed from later inventories. Use this when earlier inventory positions are more likely to be seen and should receive the best available ad responses.
• Interleaved. The higher-ranked ad wins, regardless of which inventory it came from - where rank means how early the ad appears within its own inventory's response. If ranks tie, the earlier inventory in the request wins. Use this when inventory positions are similarly prominent, or when you're requesting more ads than needed per inventory to support client-side filtering.

You configure both per-inventory and cross-inventory deduplication using the deduplication_setting object, available in DecideAdProducts, DecideAdBrands, DecideAdDisplay, and DecideAdReservedDisplay.

Notes

• Multi-inventory requests and cross-inventory deduplication are supported across all four decision APIs: DecideAdProducts, DecideAdBrands, DecideAdDisplay, and DecideAdReservedDisplay.
• A basic level of per-inventory deduplication always applies and cannot be disabled; cross-inventory deduplication, criteria, and method are configurable via deduplication_setting.
• Reserved Display can return more than one ad per inventory: at most one CPT line item at rank 1, with remaining ranks filled by CPM line items by priority.