Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: Insider One Catalog API
version: 1.0.0
description: 'Product catalog ingestion and update in flat and nested formats, plus locale configuration.
Derived by API Evangelist from Insider One''s own public Postman collection ("Insider One APIs", published at
https://developers.insiderone.com/). Paths, methods, headers, query parameters and request/response examples
are verbatim from that collection; nothing is invented. The 429 response is documented for all Insider One APIs
on https://academy.insiderone.com/docs/api-rate-limits-1 .'
contact:
name: Insider One Support
email: support@useinsider.com
url: https://academy.insiderone.com/docs/insider-one-apis-1
termsOfService: https://insiderone.com/terms-of-use/
externalDocs:
description: Insider One API reference
url: https://academy.insiderone.com/docs/api-reference-welcome
servers:
- url: https://catalog.api.useinsider.com
tags:
- name: Catalog APIs
paths:
/v2/ingest:
post:
operationId: addNewProductsInAFlatFormat
summary: Add New Products in a Flat Format
tags:
- Catalog APIs
description: "The Catalog API allows you to insert new products in a flat format into your product catalog.\
\ It creates new product records. If a product with the same item_id + locale already exists, it will be\
\ overwritten.\n\nEndpoint and Headers\nPOST https://catalog.api.useinsider.com/v2/ingest\n\nBody Parameters\n\
Default Product Attributes\nThe following product fields should be sent as parameters in the object, along\
\ with their field name and data type, as stated. If any required fields are not sent through the Catalog\
\ API, the product is not updated or inserted.\n\nField Name\nDescription\nData Type\nRequired\n\nitem_id\n\
Unique product identifier. Max 128 characters.\nString\nYes\n\nlocale\nISO locale code (e.g., en_US, pt_BR).\
\ Max 64 characters.\nString\nYes\n\nname\nProduct name. Max 512 characters.\nString\nYes\n\nurl\nProduct\
\ page URL. Must include protocol (e.g., https://). Max 512 characters.\nString\nYes\n\nimage_url\nProduct\
\ image URL. Must start with http://, https://, or //.\nString\nYes\n\nprice\nCurrent selling price per\
\ currency. e.g., {\"USD\": 100, \"BRL\": 500}.\nObject\nRequired for Stock & Revenue Feed Management Type\n\
\noriginal_price\nOriginal/list price per currency. Same structure as price.\nObject\nRequired for Stock\
\ & Revenue Feed Management Type\n\nomnibus_price\nOmnibus directive price per currency. Same structure\
\ as price.\nObject\nNo\n\nin_stock\n1 = in stock, 0 = out of stock.\nNumber\nRequired for Stock & Revenue\
\ and Availability Feed Management Types\n\nstock_count\nAvailable quantity. Must be >= 0.\nNumber\nNo\n\
\nitem_update_date\nLast update timestamp. Format: YYYY-MM-DD hh:mm:ss\nString\nRequired for Published Time\
\ Feed Management Type\n\nitem_start_date\nAvailability start date. Format: YYYY-MM-DD hh:mm:ss\nString\n\
Required for Start & End Time Feed Management Type\n\nitem_end_date\nAvailability end date. Format: YYYY-MM-DD\
\ hh:mm:ss\nString\nRequired for Start & End Time Feed Management Type\n\ndescription\nProduct description.\
\ Max 1024 characters.\nString\nNo\n\nbrand\nBrand name. Max 512 characters.\nString\nNo\n\nsku\nStock keeping\
\ unit. Max 512 characters.\nString\nNo\n\ncolor\nProduct color. Max 512 characters.\nString\nNo\n\nsize\n\
Product size. Max 512 characters.\nString\nNo\n\ngender\nGender classification. Max 512 characters.\nString\n\
No\n\ncategory\nCategory as an array\nString[]\nNo\n\ntags\nProduct tags\nString[]\nNo\n\ngroupcode\nProduct\
\ group identifier\nString\nNo\n\nvariants\nProduct variants. Max 512 characters per item.\nString[]\nNo\n\
\nrating\nProduct rating, 0–10\nNumber\nNo\n\nproduct_attributes\nCustom attributes defined in your account.\n\
Object {key:value}\nNo\n\nis_status_passive\n1 = passive/hidden in Smart Recommender and Eureka results,\
\ 0 = active.\nNumber\nNo\n\nCustom Product Attributes\nCustom Product Attributes allow you to define additional\
\ details specific to your business. These attributes enrich your catalog with data that supports your unique\
\ use cases, personalization logic, and recommendation filters.\n\nBefore sending Custom Product Attributes\
\ in your payload, you must define them in your account.\n\nIf a Default Product Attribute already exists\
\ for the information you want to include, use the default one instead of creating a custom one. This keeps\
\ your catalog structure consistent.\n\nCustom attributes are sent inside the product_attributes object:\n\
\n{\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"en_US\",\n \"name\"\
: \"Velocity Runner Pro - White\",\n \"product_attributes\": {\n \"material_type\": \"Leather\"\
,\n \"season\": \"Winter\",\n \"eco_friendly\": true,\n \"collection\": \"Winter Collection\
\ 2025\",\n \"delivery_type\": \"Express\"\n }\n\nFeed Management Types\nYour feed management\
\ type determines which pricing and stock attributes are required.\n\nStock and Revenue Based Feed Management\
\ Type\nThe Stock and Revenue Based Feed Management Type is the most common type. It requires pricing and\
\ stock information.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\" \\\n -H \"Content-Type:\
\ application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"X-REQUEST-TOKEN: your-api-token\"\
\ \\\n -d '[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"en_US\",\n\
\ \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n \
\ \"category\": [\"Shoes\", \"Running\", \"Velox\"],\n \"brand\": \"Velox\",\n \"price\":\
\ { \"USD\": 129.99 },\n \"original_price\": { \"USD\": 149.99 },\n \"in_stock\": 1\n }\n \
\ ]'\n\nAvailability Based Feed Management Type\nFor the Availability Based Feed Management Type, only the\
\ stock status is required. Pricing is optional.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\"\
\ \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"\
X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n\
\ \"locale\": \"en_US\",\n \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n \
\ \"in_stock\": 1\n }\n ]'\n\nPublished Time Based Feed Management Type\nThe Published Time Based\
\ Feed Management Type requires an update timestamp instead of pricing.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\"\
\ \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"\
X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n {\n \"item_id\": \"blog-top-running-shoes-2025\"\
,\n \"locale\": \"en_US\",\n \"name\": \"Top 10 Running Shoes for 2025\",\n \"url\": \"https://www.example-insiderone.com/blog/top-running-shoes-2025\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/blog/running-shoes-2025.jpg\",\n \
\ \"item_update_date\": \"2025-01-15 10:30:00\"\n }\n ]'\n\nStart & End Time Based Feed Management\
\ Type\nThe Start & End Time Based Feed Management Type requires date range attributes for time-bound content.\n\
\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\" \\\n -H \"Content-Type: application/json\"\
\ \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n\
\ {\n \"item_id\": \"promo-summer-clearance-2025\",\n \"locale\": \"en_US\",\n \"name\"\
: \"Summer Clearance Sale - Up to 50% Off\",\n \"url\": \"https://www.example-insiderone.com/campaigns/summer-clearance-2025\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/campaigns/summer-clearance.jpg\",\n\
\ \"item_start_date\": \"2025-06-01 00:00:00\",\n \"item_end_date\": \"2025-08-31 23:59:59\"\n\
\ }\n ]'\n\nProduct Availability by Feed Management Type\nA product is considered available based on\
\ criteria that vary by feed management type:\n\nFeed Type\nAvailability Condition\n\nStock & Revenue Based\n\
in_stock must be 1\n\nAvailability Based\nin_stock must be 1\n\nPublished Time Based\nitem_update_date must\
\ be within the last 2 days (default 2 days, adjustable in Smart Recommender campaigns)\n\nStart & End Time\
\ Based\nitem_end_date must not be in the past\n\nCurrencies\nPricing attributes accept an object mapping\
\ currency codes to amounts. You can include multiple currencies in a single record.\n\n{\n \"price\":\
\ {\n \"USD\": 129.99,\n \"EUR\": 119.99,\n \"GBP\": 104.99,\n \"BRL\": 899.90\n },\n \"original_price\"\
: {\n \"USD\": 149.99,\n \"EUR\": 139.99,\n \"GBP\": 119.99,\n \"BRL\": 999.90\n }\n}\n\nCategories\n\
The category attribute accepts an array of strings. How the array is interpreted depends on your account's\
\ category type, which is configured during onboarding. You must choose one of the two types:\n\nHierarchical\
\ Category Type\n\nUse this if your categories follow a parent-child structure, with subcategories nested\
\ under broader categories. Each element in the array represents a level in the hierarchy, ordered from\
\ broadest to most specific.\n\n{\n \"category\": [\"Clothing\", \"Men\", \"Shirts\", \"Casual Shirts\"\
]\n}\n\nThis creates the hierarchy: Clothing → Men → Shirts → Casual Shirts.\n\nThe order matters; the first\
\ element is the top-level category and each subsequent element is a child of the previous one.\n\nFlat\
\ Category Type\n\nUse this if your categories are independent and don't follow a parent-child hierarchy.\
\ Each element is a standalone category label at the same level.\n\n{\n \"category\": [\"Men's Shirts\"\
, \"Women's Dresses\", \"Kids' Shoes\"]\n}\n\nIn flat mode, all categories are treated equally; there is\
\ no implied nesting or ordering relationship between elements.\n\nLimits:\n\nCombined length of all category\
\ elements: max 1024 characters\n\nEach element: max 512 characters\n\nTags & Merchandising\nTags are used\
\ for product grouping and merchandising rules within the Insider One platform.\n\n{\n \"tags\": [\"new-arrival\"\
, \"bestseller\", \"summer-collection\", \"free-shipping\"]\n}\n\nYou can use tags to:\n\nCreate product\
\ segments for personalization\n\nTrigger merchandising rules\n\nFilter products in recommendation widgets\n\
\nDefine campaign audiences\n\nLimits:\n\nCombined length of all tags: max 4096 characters\n\nEach tag:\
\ max 512 characters\n\nGroup Code\nThe groupcode attribute links product variants together as a single\
\ product group. Products sharing the same groupcode are treated as variations of the same product (e.g.,\
\ different sizes or colors).\n\n[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"groupcode\"\
: \"velocity-runner-pro\",\n \"color\": \"White\",\n \"size\": \"10\"\n },\n {\n \"item_id\"\
: \"velocity-runner-pro-black\",\n \"groupcode\": \"velocity-runner-pro\",\n \"color\": \"Black\"\
,\n \"size\": \"10\"\n }\n]\n\nSample Request\nThe sample below displays a request to insert new products\
\ into the catalog using a flat format. Each product is a separate JSON object with all fields inline. Every\
\ locale/store combination is a separate object.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\"\
\ \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PARTNER-NAME: yourPartnerName\" \\\
\n -H \"X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n {\n \"item_id\": \"velocity-runner-pro-white\"\
,\n \"locale\": \"en_US\",\n \"name\": \"Velocity Runner Pro - White\",\n \"url\":\
\ \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\",\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\"\
,\n \"category\": [\"Shoes\", \"Running\", \"Velox\"],\n \"brand\": \"Velox\",\n \"\
color\": \"White\",\n \"groupcode\": \"velocity-runner-pro\",\n \"price\": { \"USD\": 129.99\
\ },\n \"original_price\": { \"USD\": 149.99 },\n \"in_stock\": 1,\n \"stock_count\"\
: 50\n },\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"\
en_US:newyork\",\n \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n\
\ \"category\": [\"Shoes\", \"Running\", \"Velox\"],\n \"brand\": \"Velox\",\n \"color\"\
: \"White\",\n \"groupcode\": \"velocity-runner-pro\",\n \"price\": { \"USD\": 119.99 },\n\
\ \"original_price\": { \"USD\": 149.99 },\n \"in_stock\": 1,\n \"stock_count\": 12\n\
\ },\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"en_US:losangeles\"\
,\n \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n\
\ \"category\": [\"Shoes\", \"Running\", \"Velox\"],\n \"brand\": \"Velox\",\n \"color\"\
: \"White\",\n \"groupcode\": \"velocity-runner-pro\",\n \"price\": { \"USD\": 129.99 },\n\
\ \"original_price\": { \"USD\": 149.99 },\n \"in_stock\": 0,\n \"stock_count\": 0\n\
\ },\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"pt_BR\"\
,\n \"name\": \"Velocity Runner Pro - Branco\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n\
\ \"category\": [\"Calçados\", \"Corrida\", \"Velox\"],\n \"brand\": \"Velox\",\n \"\
color\": \"White\",\n \"groupcode\": \"velocity-runner-pro\",\n \"price\": { \"BRL\": 899.90\
\ },\n \"original_price\": { \"BRL\": 999.90 },\n \"in_stock\": 1,\n \"stock_count\"\
: 30\n }\n ]'\n\nSample Response\nAll ingest endpoints return the same response structure:\n\
\n{\n \"success\": true,\n \"message\": {\n \"valid\": {\n \"count\": 95\n \
\ },\n \"invalid\": {\n \"count\": 5,\n \"details\": [\n {\n \"\
field\": \"original_price\",\n \"message\": \"Field is invalidated: 'original_price' is required\"\
,\n \"count\": 2,\n \"document_ids\": [\"item-1\", \"item-2\"]\n },\n {\n \
\ \"field\": \"url\",\n \"message\": \"Field is invalidated: 'url' must match pattern\",\n \
\ \"count\": 3,\n \"document_ids\": [\"item-3\", \"item-4\", \"item-5\"]\n }\n \
\ ]\n },\n \"warnings\": {\n \"count\": 1,\n \"details\": [\n {\n \
\ \"field\": \"image_url\",\n \"message\": \"Image URL could not be validated\",\n \"\
count\": 1,\n \"document_ids\": [\"item-6\"]\n }\n ]\n },\n \"invalidRatio\"\
: 0.05\n }\n }\n\nWarnings are informational and do not prevent records from being processed.\
\ \n\nLimitations\nFor all the limits applied, refer to Limitations."
security:
- PartnerName: []
- RequestToken: []
requestBody:
content:
application/json:
example:
- item_id: velocity-runner-pro-white
locale: en_US
name: Velocity Runner Pro - White
url: https://www.example-insiderone.com/shoes/velocity-runner-pro-white
image_url: https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg
category:
- Shoes
- Running
- Velox
brand: Velox
color: White
groupcode: velocity-runner-pro
price:
USD: 129.99
original_price:
USD: 149.99
in_stock: 1
stock_count: 50
- item_id: velocity-runner-pro-white
locale: en_US:newyork
name: Velocity Runner Pro - White
url: https://www.example-insiderone.com/shoes/velocity-runner-pro-white
image_url: https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg
category:
- Shoes
- Running
- Velox
brand: Velox
color: White
groupcode: velocity-runner-pro
price:
USD: 119.99
original_price:
USD: 149.99
in_stock: 1
stock_count: 12
- item_id: velocity-runner-pro-white
locale: en_US:losangeles
name: Velocity Runner Pro - White
url: https://www.example-insiderone.com/shoes/velocity-runner-pro-white
image_url: https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg
category:
- Shoes
- Running
- Velox
brand: Velox
color: White
groupcode: velocity-runner-pro
price:
USD: 129.99
original_price:
USD: 149.99
in_stock: 0
stock_count: 0
- item_id: velocity-runner-pro-white
locale: pt_BR
name: Velocity Runner Pro - Branco
url: https://www.example-insiderone.com/shoes/velocity-runner-pro-white
image_url: https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg
category:
- Calçados
- Corrida
- Velox
brand: Velox
color: White
groupcode: velocity-runner-pro
price:
BRL: 899.9
original_price:
BRL: 999.9
in_stock: 1
stock_count: 30
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/v2/ingest/nested:
post:
operationId: addNewProductsInANestedFormat
summary: Add New Products in a Nested Format
tags:
- Catalog APIs
description: "The Catalog API allows you to insert new items into your product catalog in a nested format.\
\ It creates new product records. If a product with the same item_id + locale already exists, it will be\
\ overwritten.\n\nEndpoint and Headers\nPOST https://catalog.api.useinsider.com/v2/ingest/nested\n\nBody\
\ Parameters\nDefault Product Attributes\nThe following product fields should be sent as parameters in the\
\ object, along with their field name and data type, as stated. If any required fields are not sent through\
\ the Catalog API, the product is not updated or inserted.\n\nField Name\nDescription\nData Type\nRequired\n\
\nitem_id\nUnique product identifier. Max 128 characters.\nString\nYes\n\nlocale\nISO locale code (e.g.,\
\ en_US, pt_BR). Max 64 characters.\nString\nYes\n\nname\nProduct name. Max 512 characters.\nString\nYes\n\
\nurl\nProduct page URL. Must include protocol (e.g., https://). Max 512 characters.\nString\nYes\n\nimage_url\n\
Product image URL. Must start with http://, https://, or //.\nString\nYes\n\nprice\nCurrent selling price\
\ per currency. e.g., {\"USD\": 100, \"BRL\": 500}.\nObject\nRequired for Stock & Revenue Feed Management\
\ Type\n\noriginal_price\nOriginal/list price per currency. Same structure as price.\nObject\nRequired for\
\ Stock & Revenue Feed Management Type\n\nomnibus_price\nOmnibus directive price per currency. Same structure\
\ as price.\nObject\nNo\n\nin_stock\n1 = in stock, 0 = out of stock.\nNumber\nRequired for Stock & Revenue\
\ and Availability Feed Management Types\n\nstock_count\nAvailable quantity. Must be >= 0.\nNumber\nNo\n\
\nitem_update_date\nLast update timestamp. Format: YYYY-MM-DD hh:mm:ss\nString\nRequired for Published Time\
\ Feed Management Type\n\nitem_start_date\nAvailability start date. Format: YYYY-MM-DD hh:mm:ss\nString\n\
Required for Start & End Time Feed Management Type\n\nitem_end_date\nAvailability end date. Format: YYYY-MM-DD\
\ hh:mm:ss\nString\nRequired for Start & End Time Feed Management Type\n\ndescription\nProduct description.\
\ Max 1024 characters.\nString\nNo\n\nbrand\nBrand name. Max 512 characters.\nString\nNo\n\nsku\nStock keeping\
\ unit. Max 512 characters.\nString\nNo\n\ncolor\nProduct color. Max 512 characters.\nString\nNo\n\nsize\n\
Product size. Max 512 characters.\nString\nNo\n\ngender\nGender classification. Max 512 characters.\nString\n\
No\n\ncategory\nCategory as an array\nString[]\nNo\n\ntags\nProduct tags\nString[]\nNo\n\ngroupcode\nProduct\
\ group identifier\nString\nNo\n\nvariants\nProduct variants. Max 512 characters per item.\nString[]\nNo\n\
\nrating\nProduct rating, 0–10\nNumber\nNo\n\nproduct_attributes\nCustom attributes defined in your account.\n\
Object {key:value}\nNo\n\nis_status_passive\n1 = passive/hidden in Smart Recommender and Eureka results,\
\ 0 = active.\nNumber\nNo\n\nCustom Product Attributes\nCustom Product Attributes allow you to define additional\
\ details specific to your business. These attributes enrich your catalog with data that supports your unique\
\ use cases, personalization logic, and recommendation filters.\n\nBefore sending Custom Product Attributes\
\ in your payload, you must define them in your account.\n\nIf a Default Product Attribute already exists\
\ for the information you want to include, use the default one instead of creating a custom one. This keeps\
\ your catalog structure consistent.\n\nCustom attributes are sent inside the product_attributes object:\n\
\n{\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"en_US\",\n \"name\"\
: \"Velocity Runner Pro - White\",\n \"product_attributes\": {\n \"material_type\": \"Leather\"\
,\n \"season\": \"Winter\",\n \"eco_friendly\": true,\n \"collection\": \"Winter Collection\
\ 2025\",\n \"delivery_type\": \"Express\"\n }\n\nFeed Management Types\nYour feed management\
\ type determines which pricing and stock attributes are required.\n\nStock and Revenue Based Feed Management\
\ Type\nThe Stock and Revenue Based Feed Management Type is the most common type. It requires pricing and\
\ stock information.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\" \\\n -H \"Content-Type:\
\ application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"X-REQUEST-TOKEN: your-api-token\"\
\ \\\n -d '[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"locale\": \"en_US\",\n\
\ \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n \
\ \"category\": [\"Shoes\", \"Running\", \"Velox\"],\n \"brand\": \"Velox\",\n \"price\":\
\ { \"USD\": 129.99 },\n \"original_price\": { \"USD\": 149.99 },\n \"in_stock\": 1\n }\n \
\ ]'\n\nAvailability Based Feed Management Type\nFor the Availability Based Feed Management Type, only the\
\ stock status is required. Pricing is optional.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\"\
\ \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"\
X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n\
\ \"locale\": \"en_US\",\n \"name\": \"Velocity Runner Pro - White\",\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n \
\ \"in_stock\": 1\n }\n ]'\n\nPublished Time Based Feed Management Type\nThe Published Time Based\
\ Feed Management Type requires an update timestamp instead of pricing.\n\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\"\
\ \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"\
X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n {\n \"item_id\": \"blog-top-running-shoes-2025\"\
,\n \"locale\": \"en_US\",\n \"name\": \"Top 10 Running Shoes for 2025\",\n \"url\": \"https://www.example-insiderone.com/blog/top-running-shoes-2025\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/blog/running-shoes-2025.jpg\",\n \
\ \"item_update_date\": \"2025-01-15 10:30:00\"\n }\n ]'\n\nStart & End Time Based Feed Management\
\ Type\nThe Start & End Time Based Feed Management Type requires date range attributes for time-bound content.\n\
\ncurl -X POST \"https://catalog.api.useinsider.com/v2/ingest\" \\\n -H \"Content-Type: application/json\"\
\ \\\n -H \"X-PARTNER-NAME: your-partner-name\" \\\n -H \"X-REQUEST-TOKEN: your-api-token\" \\\n -d '[\n\
\ {\n \"item_id\": \"promo-summer-clearance-2025\",\n \"locale\": \"en_US\",\n \"name\"\
: \"Summer Clearance Sale - Up to 50% Off\",\n \"url\": \"https://www.example-insiderone.com/campaigns/summer-clearance-2025\"\
,\n \"image_url\": \"https://cdn.example-insiderone.com/images/campaigns/summer-clearance.jpg\",\n\
\ \"item_start_date\": \"2025-06-01 00:00:00\",\n \"item_end_date\": \"2025-08-31 23:59:59\"\n\
\ }\n ]'\n\nProduct Availability by Feed Management Type\nA product is considered available based on\
\ criteria that vary by feed management type:\n\nFeed Type\nAvailability Condition\n\nStock & Revenue Based\n\
in_stock must be 1\n\nAvailability Based\nin_stock must be 1\n\nPublished Time Based\nitem_update_date must\
\ be within the last 2 days (default 2 days, adjustable in Smart Recommender campaigns)\n\nStart & End Time\
\ Based\nitem_end_date must not be in the past\n\nCurrencies\nPricing attributes accept an object mapping\
\ currency codes to amounts. You can include multiple currencies in a single record.\n\n{\n \"price\":\
\ {\n \"USD\": 129.99,\n \"EUR\": 119.99,\n \"GBP\": 104.99,\n \"BRL\": 899.90\n },\n \"original_price\"\
: {\n \"USD\": 149.99,\n \"EUR\": 139.99,\n \"GBP\": 119.99,\n \"BRL\": 999.90\n }\n}\n\nCategories\n\
The category attribute accepts an array of strings. How the array is interpreted depends on your account's\
\ category type, which is configured during onboarding. You must choose one of the two types:\n\nHierarchical\
\ Category Type\n\nUse this if your categories follow a parent-child structure, with subcategories nested\
\ under broader categories. Each element in the array represents a level in the hierarchy, ordered from\
\ broadest to most specific.\n\n{\n \"category\": [\"Clothing\", \"Men\", \"Shirts\", \"Casual Shirts\"\
]\n}\n\nThis creates the hierarchy: Clothing → Men → Shirts → Casual Shirts.\n\nThe order matters; the first\
\ element is the top-level category and each subsequent element is a child of the previous one.\n\nFlat\
\ Category Type\n\nUse this if your categories are independent and don't follow a parent-child hierarchy.\
\ Each element is a standalone category label at the same level.\n\n{\n \"category\": [\"Men's Shirts\"\
, \"Women's Dresses\", \"Kids' Shoes\"]\n}\n\nIn flat mode, all categories are treated equally; there is\
\ no implied nesting or ordering relationship between elements.\n\nLimits:\n\nCombined length of all category\
\ elements: max 1024 characters\n\nEach element: max 512 characters\n\nTags & Merchandising\nTags are used\
\ for product grouping and merchandising rules within the Insider One platform.\n\n{\n \"tags\": [\"new-arrival\"\
, \"bestseller\", \"summer-collection\", \"free-shipping\"]\n}\n\nYou can use tagsto:\n\nCreate product\
\ segments for personalization\n\nTrigger merchandising rules\n\nFilter products in recommendation widgets\n\
\nDefine campaign audiences\n\nLimits:\n\nCombined length of all tags: max 4096 characters\n\nEach tag:\
\ max 512 characters\n\nGroup Code\nThe groupcode attribute links product variants together as a single\
\ product group. Products sharing the same groupcode are treated as variations of the same product (e.g.,\
\ different sizes or colors).\n\n[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"groupcode\"\
: \"velocity-runner-pro\",\n \"color\": \"White\",\n \"size\": \"10\"\n },\n {\n \"item_id\"\
: \"velocity-runner-pro-black\",\n \"groupcode\": \"velocity-runner-pro\",\n \"color\": \"Black\"\
,\n \"size\": \"10\"\n }\n]\n\nSample Request\nThe sample below displays a request to insert new products\
\ using a nested format. Shared fields go in base, locale-specific fields go in locales, and store overrides\
\ go in stores.\n\nUse nested format when you have multiple locales or stores per product. Shared fields\
\ like url, image_url, and brand are defined once and inherited by all locales/stores, reducing payload\
\ size and repetition.\n\nThe following example is equivalent to the flat format: the same product, locales,\
\ and stores, but expressed as a single nested object instead of 4 separate records:\n\ncurl --request POST\
\ \"https://catalog.api.useinsider.com/v2/ingest/nested\" \\\n --header \"Content-Type: application/json\"\
\ \\\n --header \"X-PARTNER-NAME: yourPartnerName\" \\\n --header \"X-REQUEST-TOKEN: your-api-token\"\
\ \\\n --data '[\n {\n \"item_id\": \"velocity-runner-pro-white\",\n \"base\"\
: {\n \"url\": \"https://www.example-insiderone.com/shoes/velocity-runner-pro-white\",\n \"\
image_url\": \"https://cdn.example-insiderone.com/images/velocity-runner-pro-white.jpg\",\n \"brand\"\
: \"Velox\",\n \"groupcode\": \"velocity-runner-pro\",\n \"color\": \"White\"\n },\n\
\ \"locales\": {\n
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/insider/refs/heads/main/openapi/insider-catalog-openapi.yml