Add items to a catalog

API at a glance

Description: This API allows you to add multiple products or content items to an existing catalog in Blueshift. You can add up to 100 items per API call. Catalogs organize items such as products, movies, courses, and other content that users interact with, enabling personalized recommendations and content delivery.

Authorization: Basic encoded_value

Things to know before you start

• You can add up to 100 items per API call.
• The catalog must already exist in Blueshift. Use the Create Catalog API to create a new catalog.
• Required fields for each item: image, product_id, title, web_link, availability, and category.
• Price fields (msrp and price) must contain numeric values without currency symbols (e.g., "999.99" not "$999.99").
• Latitude must be between -90 and 90; longitude must be between -180 and 180.
• Product IDs must be unique within and across catalogs.
• Use case: Bulk import product catalogs, update inventory, sync content feeds, or add new items to existing catalogs programmatically.
• Catalog UUID: You can find the catalog UUID in the URL when viewing a catalog in the Blueshift app. For example, https://app.getblueshift.com/dashboard#/app/catalogs/<CATALOG_UUID>/details.

📖 Catalogs – user guide
To learn more about catalogs and how they work in Blueshift, see the Catalogs overview.

Request parameters

Check out the request parameters

Path parameters

Parameter	Type	Required	Description
catalog_uuid	string	✅ Yes	UUID of the catalog to which you want to add items. You can get the catalog's UUID from its URL. For example, if you open a catalog on the Blueshift app, its URL looks like https://app.getblueshift.com/dashboard#/app/catalogs/89ee8378-a887-474b-8afe-e2369cc9297c/details, where the UUID is 89ee8378-a887-474b-8afe-e2369cc9297c.

You can find the catalog UUID in the URL when viewing a catalog in the Blueshift app.

Query parameters

Parameter	Type	Required	Description
syncUpdateWithProductData	boolean	❌ No	When set to true, the API returns the product_id and uuid for each successfully added item. When set to false or not provided, returns a simple {"status": "ok"} response. Default: false.

Body parameters

Parameter	Type	Required	Description
catalog.products	array	✅ Yes	Array of product/item objects to add to the catalog. Maximum 100 items per request.
product_id	string	✅ Yes	Unique identifier for the item (max 64 characters). Must match the product IDs used in your 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 of the item (e.g., in_stock, out_of_stock).
category	array	✅ Yes	Category identifiers starting from the root of the taxonomy (e.g., ["Electronics", "Electronics > Laptops"]).
brand	string	❌ No	Brand name of the item.
msrp	string	❌ No	Maximum suggested retail price (numeric value without currency symbol, e.g., "999.99").
price	string	❌ No	Selling price (numeric value without currency symbol, e.g., "899.99").
tags	array	❌ No	Array of strings for grouping similar products (e.g., ["bestseller", "premium"]).
parent_sku	string	❌ No	SKU to tie all variants or child products together.
latitude	string	❌ No	Latitude of the product location (must be between -90 and 90).
longitude	string	❌ No	Longitude of the product location (must be between -180 and 180).

Example requests & responses

curl --request PUT \
     --url https://api.getblueshift.com/api/v1/catalogs/89ee8378-a887-474b-8afe-e2369cc9297c.json \
     --header 'accept: application/json' \
     --header 'authorization: Basic YWNlZDZlNGYxMWExYWVhOTZmNTJkNDg4M2ZmMjI4Mjg6' \
     --header 'content-type: application/json' \
     --data '
{
  "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"
}

{
  "success": {
    "products": [
      {
        "product_id": "PROD123456",
        "uuid": "8da44313-e540-449d-9513-6eb36285bfe3"
      }
    ]
  },
  "failure": []
}