API at a glance
Description: This API adds multiple products or content items to an existing catalog in Blueshift. You can add up to 100 items per API call.
Use this API only with API-created catalogs 📦This API adds catalog items only to catalogs created using the Create Catalog API.
Catalogs created using other import methods cannot be updated using this API. For all supported import methods, see Import catalog data.
Authentication & testing
Testing the API on this page
How to try it here
- Use your User API Key as the Username (leave Password blank).
- Select the appropriate API endpoint based on your Blueshift region.
- Enter the necessary parameters and click Try It to run the request.
Authentication using Base64 encoding
Note for developers
API requests require authentication using HTTP Basic Authentication with an API key.
The API key serves as the username, while the password field should be left empty.
The format to encode is: your_api_key: (note the trailing colon).
This string must be Base64-encoded and included in the request's Authorization header as follows:
Authorization: Basic encoded_valueYou can generate the encoded value using a trusted Base64 encoder.
Postman collection
Try it with Postman: Explore the API using Blueshift's Postman collection.
Things to know before you start
- Item limit: Maximum 100 items per API call.
- Catalog must exist: Use the Create Catalog API to create a new catalog first.
- Required fields:
image,product_id,title,web_link,availability, andcategory. - Price format: Numeric values without currency symbols (e.g.,
"999.99"not"$999.99"). - Location coordinates: Latitude: -90 to 90, Longitude: -180 to 180.
- Unique product IDs: Must be unique within and across catalogs.
- Use case: Bulk import product catalogs, update inventory, sync content feeds, add new items programmatically.
📖 Learn more
See the Catalogs overview user guide.
Finding the catalog UUID > >You can find the catalog UUID in the URL when viewing a catalog in the Blueshift app. For example, if you open a catalog in the Blueshift app, its URL looks like
https://app.getblueshift.com/dashboard#/app/catalogs/<CATALOG_UUID>/details.
Request parameters
Check out the request parameters
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
catalog_uuid | string | ✅ Yes | UUID of the catalog to add items to. |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
syncUpdateWithProductData | boolean | ❌ No | When true, returns product_id and uuid for each added item. When false or omitted, returns {"status": "ok"}. Default: false. |
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
catalog.products | array | ✅ Yes | Array of product/item objects. Maximum 100 items per request. |
Product object fields
| Parameter | Type | Required | Description |
|---|---|---|---|
product_id | string | ✅ Yes | Unique identifier (max 64 characters). Must match product IDs used in events. |
title | string | ✅ Yes | Title of the item (max 255 characters). |
image | string | ✅ Yes | URL of the item's image (max 500 characters). |
web_link | string | ✅ Yes | URL of the item on your website (max 500 characters). |
availability | string | ✅ Yes | Availability status (e.g., in_stock, out_of_stock). |
category | array | ✅ Yes | Category identifiers from root of taxonomy (e.g., ["Electronics", "Electronics > Laptops"]). |
brand | string | ❌ No | Brand name of the item. |
msrp | string | ❌ No | Maximum suggested retail price (numeric, e.g., "999.99"). |
price | string | ❌ No | Selling price (numeric, e.g., "899.99"). |
tags | array | ❌ No | Array of strings for grouping products (e.g., ["bestseller", "premium"]). |
parent_sku | string | ❌ No | SKU to tie all variants/child products together. |
latitude | string | ❌ No | Latitude of product location (-90 to 90). |
longitude | string | ❌ No | Longitude of product location (-180 to 180). |
Example requests & responses
Add items to catalog
{
"catalog": {
"products": [
{
"image": "https://example.com/images/product.jpg",
"product_id": "PROD123456",
"title": "Premium Laptop 15-inch",
"web_link": "https://example.com/products/laptop-001",
"availability": "in_stock",
"category": [
"Electronics",
"Electronics > Laptops"
],
"brand": "TechBrand",
"msrp": "999.99",
"price": "899.99",
"tags": [
"bestseller",
"premium"
],
"parent_sku": "SKU-PARENT-001",
"latitude": "40.7128",
"longitude": "-74.0060"
}
]
}
}{
"status": "ok"
}Add items with detailed response (syncUpdateWithProductData=true)
{
"catalog": {
"products": [
{
"image": "https://example.com/images/product.jpg",
"product_id": "PROD123456",
"title": "Premium Laptop 15-inch",
"web_link": "https://example.com/products/laptop-001",
"availability": "in_stock",
"category": [
"Electronics",
"Electronics > Laptops"
]
}
]
}
}{
"success": {
"products": [
{
"product_id": "PROD123456",
"uuid": "8da44313-e540-449d-9513-6eb36285bfe3"
}
]
},
"failure": []
}Payload Too Large - You can upload maximum 100 products in one API call.
Too Many Requests - Rate limit exceeded.
Internal Server Error - Please contact Blueshift support.
Bad Gateway - Service unavailable, please retry with exponential backoff.
Service Unavailable - Please retry with exponential backoff.
Gateway Timeout - Please retry with exponential backoff.