Item Kill Switch

The "Item Kill Switch" feature is designed to immediately stop specific items from being advertised. This is particularly useful when items are out of stock or need to be hidden due to fraudulent product reports and other urgent reasons.

Item Kill Switch updates the status of items in real time through the UpdateItemStatusBulk API, which is part of the Management API suite of tools. When an item is removed using UpdateItemStatusBulk, it is immediately pulled from ad serving, ensuring the Decision API does not return these items for any decision quest. For more information on Management API usage please see: API and SSO Credential Management

Prerequisites

  1. To use UpdateItemStatusBulk, the catalog field labeled updated_time must be populated and contain the most current timestamp when the catalog and incremental feed files are sent to Moloco.
  2. Contact your Moloco representative to enable the Item Kill Switch feature once you have verified your catalog feed(s) meets the requirement above.

✏️

For more information on catalog fields, please review the Catalog Feed specifications page.

API Behavior

  • The item is blocked for 12 hours beginning at the timestamp provided in the UpdateItemStatusBulk request, labeled updated_time. After the updated_time period, the item’s availability will follow your catalog feed update schedule.

🚧

If you wish to continue blocking an item, we recommend updating your catalog to include the blocked field. This field is used to block an item from decision requests. You may remove the block at any time by deleting the data in the blocked field. Once removed, the item will be available for decision requests after the next catalog feed update is sent to Moloco.

  • The UpdateItemStatusBulk API does not affect a user's ability to search for a specific item on your e-commerce site. UpdateItemStatusBulk only removes the ability for an item to be advertised; it does not remove the item from the catalog feed or the site.
  • If the item_id passed to the UpdateItemStatusBulk API is not present in the catalog feed, an error will be returned.

Catalog Behavior

SSPI (Single Seller Per Item): When using the SSPI catalog specification, if an item is removed, no decision response will return it.

MSPI (Multiple Sellers Per Item) When using the MSPI catalog specification, providing the seller_id removes the item from the specified seller, while leaving the seller_id empty removes the item from all decision requests.

API Usage

Example Request Body

{
  "items": [
    {
      "item_id": "12345",
      "blocked": "blocked_reason",
      "updated_time": "2024-10-15T12:00:00Z"
    },
    {
      "item_id": "67890",
      "blocked": "blocked_reason",
      "updated_time": "2024-10-15T12:00:00Z"
    }
  ]
}

Example Response Body

{
  "success_items": [
    {
      "item_id": "12345",
      "seller_id": "",
      "region": ""
    },
    {
      "item_id": "67890",
      "seller_id": "",
      "region": ""
    },
  ],
  "failure_items": []
}

FAQ

Q. What happens if the Catalog Feed file contains outdated (updated_time) timestamps?

  • The item remains blocked for 12 hours from the timestamp passed in the updated_time field. After that time has passed, the item's availability follows the catalog feed file update schedule.
    • Example: If the catalog feed refreshes every 24 hours, the blocked status will only change once the updated_time has passed or Moloco ingests the next catalog feed. In this case, the item may remain blocked for more than 12 hours.