--- updatedAt: 2025-08-21T23:48:28.000Z agentTools: projectIndex: https://mcm-docs.moloco.com/v1.1/llms.txt --- # DecideAdItems Request product ads by auction. Please consider using DecideAdProducts instead, which supports multi-inventory. Server host may vary by platform. Moloco's staff will provide accurate host information. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Decision API", "description": "MOLOCO Cloud RMP Decision API provides the product recommendation service.", "version": "1.0", "contact": { "name": "Moloco Inc.", "url": "https://www.molocoads.com" } }, "paths": { "/rmp/decision/v1/platforms/{platform_id}/auction": { "post": { "summary": "DecideAdItems", "description": "Request product ads by auction. Please consider using DecideAdProducts instead, which supports multi-inventory. Server host may vary by platform. Moloco's staff will provide accurate host information.", "operationId": "RmpDecisionApi_DecideAdItems", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/publicDecisionResponse" } } } }, "400": { "description": "Bad request. Detailed cause can be found in the response message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } }, "401": { "description": "Unauthorized. The request does not have valid authentication credentials for the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } }, "403": { "description": "Permission denied. The caller does not have permission to execute the specified operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } }, "404": { "description": "Not found. One or more resources required to perform the request does not exist. Detailed cause can be found in the response message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } }, "429": { "description": "Too many requests either by platform or by user. Detailed cause can be found in the response message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } }, "500": { "description": "Internal server error. Detailed cause can be found in the response message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } } }, "parameters": [ { "name": "platform_id", "description": "Identifier of the platform who requests sponsored product decision. It is passed as a path parameter.", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/publicDecisionInput" } } }, "required": true }, "tags": [ "Decision" ] } } }, "security": [ { "ApiKeyAuth": [] } ], "x-readme": { "explorer-enabled": true }, "servers": [ { "url": "https://sandbox-dcsn.mcm-api.moloco.com" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "x-api-key", "in": "header" } }, "schemas": { "CustomItemContext": { "type": "object", "properties": { "shipping_charge": { "$ref": "#/components/schemas/commonMoneyMicro" }, "distance": { "type": "number", "format": "float", "description": "Distance to the user from where this specific item is located. There is no requirement on the unit of distance as long as the implied unit is consistently used when communicating with Moloco." }, "discount": { "$ref": "#/components/schemas/commonDiscount" } } }, "CustomItemPoolCustomItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Required. ID of the item." }, "context": { "$ref": "#/components/schemas/CustomItemContext" }, "score": { "$ref": "#/components/schemas/CustomItemScore" } }, "description": "Information of the item from the pool.", "required": [ "id" ] }, "CustomItemScore": { "type": "object", "properties": { "quality_score": { "type": "number", "format": "float", "description": "Platform-defined quality score for items in the pool, based on its relevance to the request. To use this feature, each item in the custom item pool requires this score, between 0 and 1, which helps determine the adRank." } } }, "DecidedItemAuctionResult": { "type": "object", "properties": { "ad_account_id": { "type": "string", "description": "The ID of the owning ad account. The relationship among platform, ad account, and campaign is explained on https://mcm-docs.moloco.com/docs/2-solution-components. In short, a platform has many sellers, and each seller corresponds to an ad account. One ad account can own many ad campaigns." }, "campaign_id": { "type": "string", "description": "The ID of the owning ad campaign. Refer to ad_account_id for relationship among platforms, ad accounts, and campaigns." }, "win_price": { "$ref": "#/components/schemas/commonMoneyMicro" } }, "description": "AuctionResult contains auction specific information of the item such as ad_account_id and campaign_id.", "required": [ "ad_account_id", "campaign_id" ] }, "FilteringAgeGroup": { "type": "object", "properties": { "age_groups": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given age groups will be served." } }, "description": "This field is used to filter ads based on age groups.", "required": [ "age_groups" ] }, "FilteringBrand": { "type": "object", "properties": { "brand_id": { "type": "string", "description": "Deprecated. Only ads matching the brand id will be served. Please provide only one of brand_id or brand_ids." }, "brand_ids": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given brand ids will be served. Please provide only one of brand_id or brand_ids." } }, "description": "This field is used to filter ads based on brand." }, "FilteringCategory": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/FilteringOperator" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching the given category filtering option will be served." } }, "description": "This field is used to filter ads based on categories.", "required": [ "categories" ] }, "FilteringColor": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given the colors will be served." } }, "description": "This field is used to filter ads based on colors.", "required": [ "colors" ] }, "FilteringCondition": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given conditions will be served." } }, "description": "This field is used to filter ads based on conditions.", "required": [ "conditions" ] }, "FilteringDelivery": { "type": "object", "properties": { "delivery_option": { "type": "string", "description": "Deprecated. Only ads matching the delivery option will be served." }, "delivery_options": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given delivery options will be served. Please provide only one of delivery_option or delivery_options." } }, "description": "This field is used to filter ads based on delivery." }, "FilteringGender": { "type": "object", "properties": { "genders": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given genders will be served." } }, "description": "This field is used to filter ads based on genders.", "required": [ "genders" ] }, "FilteringMaterial": { "type": "object", "properties": { "materials": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given materials will be served." } }, "description": "This field is used to filter ads based on materials.", "required": [ "materials" ] }, "FilteringOperator": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR" }, "FilteringPattern": { "type": "object", "properties": { "patterns": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given patterns will be served." } }, "description": "This field is used to filter ads based on patterns.", "required": [ "patterns" ] }, "FilteringPrice": { "type": "object", "properties": { "min_price": { "type": "number", "format": "double", "description": "Required. Only ads with price greater than or equal to min_price will be served. Prices are in platform's default currency." }, "max_price": { "type": "number", "format": "double", "description": "Required. Only ads with price less than or equal to max_price will be served. Prices are in platform's default currency." } }, "description": "This field is used to filter ads based on price.", "required": [ "min_price", "max_price" ] }, "FilteringRating": { "type": "object", "properties": { "min": { "type": "number", "format": "double", "description": "Required. Only ads with rating greater than or equal to min rating will be served." }, "max": { "type": "number", "format": "double", "description": "Required. Only ads with rating less than or equal to max rating will be served." } }, "description": "This field is used to filter ads based on rating.", "required": [ "min", "max" ] }, "FilteringReviewCount": { "type": "object", "properties": { "min": { "type": "number", "format": "double", "description": "Required. Only ads with review count greater than or equal to min review_count will be served." }, "max": { "type": "number", "format": "double", "description": "Required. Only ads with review count less than or equal to max review_count will be served." } }, "description": "This field is used to filter ads based on review count.", "required": [ "min", "max" ] }, "FilteringSalePrice": { "type": "object", "properties": { "min_sale_price": { "type": "number", "format": "double", "description": "Required. Only ads with sale price greater than or equal to min_sale_price will be served. Prices are in platform's default currency." }, "max_sale_price": { "type": "number", "format": "double", "description": "Required. Only ads with sale price less than or equal to max_sale_price will be served. Prices are in platform's default currency." } }, "description": "This field is used to filter ads based on sale price.", "required": [ "min_sale_price", "max_sale_price" ] }, "FilteringSize": { "type": "object", "properties": { "sizes": { "type": "array", "items": { "type": "string" }, "description": "Required. Only ads matching any of the given sizes will be served." } }, "description": "This field is used to filter ads based on sizes.", "required": [ "sizes" ] }, "commonChannelType": { "type": "string", "enum": [ "UNKNOWN_CHANNEL_TYPE", "APP", "SITE", "DESKTOP_SITE", "MOBILE_SITE" ], "default": "UNKNOWN_CHANNEL_TYPE", "description": "ChannelType enumerates available channel types. Simply using APP and SITE is fine, but you can also further distinguish DESKTOP_SITE and MOBILE_SITE for web users.\n\n - APP: Mobile App (iOS or Android)\n - SITE: Site (e.g. Website)\n - DESKTOP_SITE: Desktop Site (e.g. Desktop Website)\n - MOBILE_SITE: Mobile Site (e.g. Mobile Website)" }, "commonCurrency": { "type": "string", "enum": [ "UNKNOWN_CURRENCY", "USD", "KRW", "JPY", "EUR", "GBP", "SEK", "INR", "THB", "IDR", "CNY", "CAD", "RUB", "BRL", "SGD", "HKD", "AUD", "PLN", "DKK", "VND", "MYR", "PHP", "TRY", "VEF", "AED" ], "default": "UNKNOWN_CURRENCY", "description": "Currency enumerates available currencies.\n\n - UNKNOWN_CURRENCY: Unknown currency.\n - USD: US Dollar.\n - KRW: Korean Won.\n - JPY: Japanese Yen.\n - EUR: EU Euro.\n - GBP: British Pound.\n - SEK: Swedish Krona.\n - INR: India Rupee.\n - THB: Thailand Baht.\n - IDR: Indonesia Rupiah.\n - CNY: China Yuan.\n - CAD: Canada Dollar.\n - RUB: Russia Ruble.\n - BRL: Brazil Real.\n - SGD: Singapore Dollar.\n - HKD: Hong Kong Dollar.\n - AUD: Autrailia Dollar.\n - PLN: Poland Zloty.\n - DKK: Denmark Krone.\n - VND: Viet Nam Dong.\n - MYR: Malaysia Ringgit.\n - PHP: Philippines Peso.\n - TRY: Turkey Lira.\n - VEF: Venezuela Bolívar.\n - AED: United Arab Emirates Dirham." }, "commonDiscount": { "type": "object", "properties": { "rate": { "type": "number", "format": "float", "description": "Discount rate for the item (e.g., 0.15 for 15% discount). Applied before price_amount if both are non-zero." }, "price_amount": { "$ref": "#/components/schemas/commonMoneyMicro" } }, "description": "Discount from the original price defined either using rate or a price amount, or both." }, "commonMoneyMicro": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/commonCurrency" }, "amount_micro": { "type": "string", "format": "int64", "description": "Amount in micro unit. (e.g., 1234 means 0.001234)" } }, "description": "A monetary amount in a specific currency; the unit is micro at fixed point value for accurate accumulation operation.\nFor example, `{\"currency\": \"USD\", \"amount_micro\": \"1234\"}` means $0.001234.", "required": [ "currency", "amount_micro" ] }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "publicDecisionInput": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique identifier of the request. The client is responsible to create this value.", "maxLength": 128 }, "channel_type": { "$ref": "#/components/schemas/commonChannelType" }, "domain": { "type": "string", "description": "Set domain to a value that can identify the domain portion of your website's URL. We recommend you keep the same value across your website and application if they share your backend." }, "session_id": { "type": "string", "description": "Deprecated. Unique identifier for tracking users regardless of sign-in status.", "maxLength": 128 }, "custom_id": { "type": "string", "description": "Alternative ID to track users regardless of sign-in status or device. This ID should be provided as a third option following the user.user_id and device.persistent_id, and is highly recommended to be hashed prior to being sent to Moloco. This ID must be provided if both the user.user_id and device.persistent_id fields are left empty. Please do not fill in a default value, and instead randomize it if you must, but we recommend you send some ID that can be used to track users even if for a short time span. Please reach out to Moloco if you have further questions about this ID.", "maxLength": 128 }, "user": { "$ref": "#/components/schemas/v1User" }, "device": { "$ref": "#/components/schemas/v1Device" }, "inventory": { "$ref": "#/components/schemas/v1Inventory" }, "page_id": { "type": "string", "description": "ID of the page where the ads will be displayed. It is a mandatory field if the Ad Placement (Inventory) is configured to use the PAGE_VIEW event type. \nIf the ad placement is configured to use this Event type, please ensure that the 'page_id' value is consistent with the value you’re passing via the User Event API. If the ad placement is not configured to use the PAGE_VIEW event type, it is not required to have a value for the 'page_id' parameter." }, "custom_item_pool": { "$ref": "#/components/schemas/v1CustomItemPool" }, "filtering": { "$ref": "#/components/schemas/v1Filtering" } }, "description": "Request body for product decision.", "required": [ "request_id", "inventory" ] }, "publicDecisionResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Identical with `request_id` of the corresponding `DecisionRequest`." }, "decided_items": { "type": "array", "items": { "$ref": "#/components/schemas/v1DecidedItem" }, "description": "Items recommended by the recommendation or winning the auction." } }, "required": [ "request_id", "decided_items" ] }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/protobufAny" } } } }, "v1CustomItemPool": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomItemPoolCustomItem" }, "description": "Items in the pool." } }, "description": "Using this field requires internal setup for the inventory so please contact your representative before using this.\nIf specified, Decision API picks the most relevant items from the item pool. So the response.decided_items will be a subset of the given items.", "required": [ "items" ] }, "v1DecidedItem": { "type": "object", "properties": { "item_id": { "type": "string", "description": "The item id specified in the client's catalog." }, "auction_result": { "$ref": "#/components/schemas/DecidedItemAuctionResult" }, "imp_trackers": { "type": "array", "items": { "type": "string" }, "description": "Impression tracker is a URL attached for each returned item. Whenever the ad is displayed on a webpage or app, the URL records an \"impression\" by sending a signal back to Moloco's tracking system. This helps advertisers track how many times their ads are seen, even if users don't click on them." }, "click_trackers": { "type": "array", "items": { "type": "string" }, "description": "Click tracker is a URL attached for each returned item. When a user clicks on the ad, the URL registers the click and sends data back to the Moloco's tracking system. This data helps advertisers understand how many users are clicking on their ads and where the clicks are coming from." }, "track_id": { "type": "string", "description": "Identifier to track the decided item." } }, "description": "DecidedItem represents either a recommended item for recommendation request or a winning item for auction request.", "required": [ "item_id", "imp_trackers", "click_trackers" ] }, "v1Device": { "type": "object", "properties": { "os": { "type": "string", "description": "OS of the device. For app traffic, \"ios\", \"android\" should be provided. When `advertising_id` is provided, this field also should be specified." }, "os_version": { "type": "string", "description": "OS version which is taken from the device without manipulation or normalization. (e.g., \"14.4.1\")" }, "advertising_id": { "type": "string", "description": "Deprecated. For app traffic, IDFA of iOS or ADID of android should be filled in this field. (e.g., \"7acefbed-d1f6-4e4e-aa26-74e93dd017e4\")" }, "unique_device_id": { "type": "string", "description": "Deprecated. Please use persistent_id as alternative. For app traffic, a unique identifier for a device should be filled in this filed. A client is able to issue an identifier for a user device, or use IDFV value for iOS app.", "maxLength": 128 }, "model": { "type": "string", "description": "Device model, which is taken from the device without manipulation or normalization. (e.g., \"iPhone 11 Pro\")" }, "persistent_id": { "type": "string", "description": "Alternative ID to track users regardless of sign-in status. This can typically be an ID associated with the device that the user is on, and is highly recommended to be hashed prior to being sent to Moloco. Please provide this value in addition to the user.user_id whenever available to achieve optimal performance. If the value is unknown for any reason, please leave empty and do not fill in a default or random value. For further information, please refer to this guide: https://mcm-docs.moloco.com/docs/generating-persistent-identifiers", "maxLength": 128 } } }, "v1Filtering": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/FilteringCategory" }, "location": { "$ref": "#/components/schemas/v1FilteringLocation" }, "brand": { "$ref": "#/components/schemas/FilteringBrand" }, "delivery": { "$ref": "#/components/schemas/FilteringDelivery" }, "price": { "$ref": "#/components/schemas/FilteringPrice" }, "sale_price": { "$ref": "#/components/schemas/FilteringSalePrice" }, "rating": { "$ref": "#/components/schemas/FilteringRating" }, "review_count": { "$ref": "#/components/schemas/FilteringReviewCount" }, "color": { "$ref": "#/components/schemas/FilteringColor" }, "gender": { "$ref": "#/components/schemas/FilteringGender" }, "size": { "$ref": "#/components/schemas/FilteringSize" }, "material": { "$ref": "#/components/schemas/FilteringMaterial" }, "pattern": { "$ref": "#/components/schemas/FilteringPattern" }, "condition": { "$ref": "#/components/schemas/FilteringCondition" }, "age_group": { "$ref": "#/components/schemas/FilteringAgeGroup" } }, "description": "This field is used to filter ads based on a variety of criteria. Multiple filtering criteria are considered in an AND relationship. This means that an ad must meet all of the filtering criteria in order to be displayed.\nWe support up to 5 simultaneous filtering criteria." }, "v1FilteringLocation": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "string" }, "description": "Each location is defined using a multi-level hierarchy, such as US>CA>Redwood. The list of locations provided is combined using OR logic to form a union, which is then used for location-based filtering. For example, if an ad is configured to show only to users in US > CA, and the incoming location values are {\"US>CA\", \"US>WA\"}, the ad will match. However, if the values are {\"US>NY\", \"US>WA\"}, the ad will not match because neither of them meets the filter condition.\nWhen an ad request includes a location filter, it will match not only that location but also all of its sub-locations. For example, if the request specifies \"US>WA\", it will match items in \"US>WA>Seattle”\" or \"US>WA>Bellevue\". This is because broader locations automatically include everything nested underneath them." } }, "description": "This field is used to filter ads based on locations.", "required": [ "locations" ] }, "v1Inventory": { "type": "object", "properties": { "inventory_id": { "type": "string", "description": "A unique identifier for the inventory that the platform manages. This will be used to calculate metrics per inventory." }, "num_items": { "type": "integer", "format": "int32", "description": "Number of items requested for the inventory. It's highly recommended not to set this greater than 50." }, "items": { "type": "array", "items": { "type": "string" }, "description": "The main item ids of the page. For example, homepage inventories don't have any main items, and product-detail-page inventories have one main item." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categories of the page: This contextual data is used for ML training and not for other purposes such as filtering. Each category string has a hierarchy separated by '>'. For example, \"Sports & Fitness > Athletic Clothing > Shoes\" represents a category with three different levels of hierarchy." }, "search_query": { "type": "string", "description": "Search query string. It should be provided if the page of serving inventory is a search result page." }, "search_metadata": { "$ref": "#/components/schemas/v1SearchMetadata" } }, "description": "Inventory where decided items will be displayed.", "required": [ "inventory_id", "num_items" ] }, "v1SearchMetadata": { "type": "object", "properties": { "synonyms": { "type": "array", "items": { "type": "string" }, "description": "Synonyms of the search query. For the search query \"car\" as an example, a client can put the synonyms in this field like `\"synonyms\": [\"vehicle\", \"automobile\"]`." } }, "description": "Metadata of the search query. This field can be used to provide additional information about the search query which may improve the response quality of the search inventories." }, "v1User": { "type": "object", "properties": { "user_id": { "type": "string", "description": "User identifier used by the platform. This should typically be the sign-in ID used within the platform, and is highly recommended to be hashed prior to being sent to Moloco. Please provide this value whenever available to achieve optimal performance. If the value is unknown for any reason, please leave empty and do not fill in a default or random value.", "maxLength": 128 }, "interests": { "type": "array", "items": { "type": "string" }, "description": "Interests of the user. e.g. [\"sports\", \"outdoor\"]" } }, "description": "User who gets items decided by auction." } } } } ```