The Catalog API enables you to send your product catalog data to the Insider One platform. You can ingest new products, update existing ones, and manage locale configurations through a set of REST endpoints.
Product data powers Insider One's personalization, recommendation, and merchandising features. Keeping your catalog up to date ensures accurate product information across all Insider One powered experiences on your website, app, and messaging channels.
The Catalog API has five different endpoints with different functions:
POST /v2/ingest to add new products in a flat format
POST /v2/ingest/nested to add new products in a nested format
POST /v2/update to update existing products in a flat format
POST /v2/update/nested to update existing products (nested format)
POST /v2/locales/batch to create locale configurations
Ingest vs Update:
Ingest creates new product records. If a product with the same item_id + locale already exists, it will be overwritten.
Update modifies existing products. You can send only the fields you want to change (partial update).
The key concepts while using the Catalog API are:
Locale
A locale identifies the market context for your product data. It combines a language/country code with an optional store identifier, enabling you to serve localized content and region-specific pricing to different markets.
Products can exist in multiple locales simultaneously. Each locale maintains its own product name, description, pricing, categories, and stock data, allowing you to manage a global catalog from a single integration.
The locale value in your API payload must exactly match a locale defined in your account. Payloads with undefined locales will not be ingested.
Language and Country Code
The base locale follows the ISO standard format {language}_{COUNTRY} (e.g., en_US, pt_BR, de_DE). It determines the language of your product names/descriptions and the country context of your catalog.
When using stores, the locale value is extended with a store suffix: {locale}:{store} (e.g., en_US:newyork).
Store
A store sits under a locale and represents a specific warehouse, retail branch, delivery hub, or virtual storefront within that locale. Stores enable inventory segmentation; prices, availability, and stock can differ by store.
Store-level data is limited to pricing and stock fields only (price, original_price, omnibus_price, in_stock, stock_count). All other product attributes (name, category, image, etc.) are defined at the locale level and shared across stores.
Example | Locale | Stores | Purpose |
|---|---|---|---|
Grocery chain (US) | en_US | en_US:east_coast, en_US:west_coast | Separate warehouses, price zones |
Fashion retailer (EMEA) | en_GB, fr_FR, de_DE | No stores | Language-only personalization |
Electronics store (Brazil) | pt_BR | pt_BR:saopaulo, pt_BR:riodejaneiro | Regional stock and pricing |
Managing Locales
You can create and manage locales through the Insider One’s InOne panel.
Alternatively, you can create locales in bulk via the Catalog API using the Create Locale API.
For stores with a small number of locales, creating locales through the InOne panel is quick and straightforward.
For larger or more complex setups, the Create Locale API enables faster and more scalable locale management.
Feed Management Type
Your account is configured with a Feed Management Type that determines which pricing/stock fields are required in your product payloads.
Every Ingest request requires core product fields (item_id, locale, name, url, image_url). Based on your Feed Management Type, some fields are added as required fields on top of these:
Type | Additional Required Fields | Use Case |
|---|---|---|
Stock & Revenue Based | price, original_price, in_stock | Standard ecommerce catalogs with pricing and inventory |
Availability Based | in_stock | Catalogs where pricing is not tracked |
Published Time Based | item_update_date | Content feeds ordered by publication date |
Start & End Time Based | item_start_date, item_end_date | Time-bound promotions or campaigns |
Your feed management type is selected during the onboarding process. If you are unsure which type applies to your integration, check your Catalog Settings or contact the Insider One team.
Limitations
The Catalog API enforces limits on request size, field lengths, and field values to ensure data quality and system stability. Records that exceed these limits will be rejected or reported as invalid in the response.
Request & Rate Limits
Limit | Value | Details |
|---|---|---|
Maximum records per request | 10,000 | Exceeding returns 400 |
Maximum request body size | 5 MB | Exceeding returns 400 |
Maximum single record size | 512 KB | Oversized record is marked invalid; other records are not affected. |
Rate limit (per account) | 60 requests/minute | Rolling window. Exceeding returns 429 |
Each Catalog API call counts as one request regardless of how many records it contains. To maximize throughput, batch as many records as possible per request (up to 10,000) rather than sending many small requests.
Example: If you send 60 requests within a 1-minute window, subsequent requests will be rejected with 429 Too Many Requests until the oldest requests fall outside the window.
Field Length Limits
Fields that exceed the maximum length will cause the individual record to be marked as invalid. Other records in the same request are not affected.
Field | Max Lenght |
|---|---|
item_id | 128 characters |
name | 512 characters |
url | 512 characters |
description | 1024 characters |
brand, sku, color, size, gender | 512 characters each |
locale | 64 characters |
category (combined) | 1024 characters |
tags (combined) | 4096 characters |
variants (each) | 512 characters |
product_attributes values | 512 characters per value |
product_attributes arrays | 1024 characters combined |
Value Constraints
The following constraints are enforced during validation. Records that violate these rules will be marked as invalid in the response with a corresponding error detail.
Field | Constraint |
|---|---|
item_id, locale | Cannot be undefined, unknown, null, or empty |
in_stock | Must be 0 or 1 |
stock_count | Must be >= 0 |
rating | Must be 0–10 |
price, original_price amounts | Must be >= 0 |
url | Must include protocol (https://...) |
image_url | Must start with http://, https://, or // |
Usage Notes
When updating products, price and original_price must be sent together if either is included.
For updates with present=true, products not found in the catalog will be reported as errors.
Locale Limits
Maximum 1000 locales can be created.
Maximum 64 characters for locale + store key combined
The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team — we can adjust it to fit your needs.
Error Handling
The Catalog API distinguishes between request-level and record-level errors:
Request-level errors (4xx) mean the entire request was rejected; no records were processed. These occur for authentication failures, malformed JSON, or exceeding request size/count limits.
Record-level errors are returned inside a 200 response. Even if every record in your payload is invalid, the API still returns 200. You must always check the response body to determine how many records were accepted and how many failed.
HTTP Status Codes
Code | Meaning |
|---|---|
200 | Request processed. Check response body for individual record results. |
400 | Invalid request (malformed JSON, limit exceeded, invalid fields). |
401 | Authentication failed. Invalid token or partner name. |
403 | Forbidden. API integration not active or IP not allowed. |
429 | Rate limit exceeded. |
500 | Internal server error. |
Common Error Messages
Error | Status | Cause |
|---|---|---|
Maximum allowed record count is exceeded. | 400 | More than 10,000 records in request |
Maximum allowed request size is exceeded. | 400 | Request body larger than 5 MB |
Request data is not in valid JSON format. | 400 | Malformed JSON body |
Unknown field in nested payload: "<field_name>" | 400 | Field not recognized in nested payload structure |
Partner does not have necessary integration settings for Catalog API. | 403 | API integration not enabled for your account |
Partner token authentication is unsuccessful. | 401 | Invalid token |
IP is not allowed. | 403 | Request from unauthorized IP address |
No locales sent in payload | 400 | Empty locales array in /v2/locales |
Record size limit is exceeded. | 200 | Single record exceeds 512 KB. The request succeeds but the oversized record is reported as invalid in the response body. Other records are not affected. |