Catalog Ingestion via API

Your product catalog is the foundation of your Shoppable Ads integration. This section covers authentication, environment setup, and how to create and maintain products in Rokt Catalog via the API.

Planned successor feed intake

The Products and Variants endpoints on this page are the supported way to load and maintain your catalog today, and existing integrations keep working. Rokt is building a successor product-feed intake that accepts an industry-standard product feed, including files formatted to the Google product data specification, through a feed URL, SFTP, a CSV upload in the Rokt Catalog app, or a push API with credentials issued per feed source. When it is available this page will link to it and describe how to move. There is no switch-off date for the current endpoints.

Products

Creating a product via API

Add a product to your Rokt Catalog by sending a POST request to the Products endpoint. Each product represents a single item and may contain multiple variants (e.g. size, color). Product data includes titles, descriptions, images, variants, pricing, and inventory.

1. Create your products using the Product Create endpoint. Each product must include at least one variant with price, inventory_quantity, inventory_policy (continue or deny), and option1. Include a sku on every variant as well: the schema does not require it, but it is the identifier carried on order line items, so you need it to reconcile orders against your own system. You can also include images with a src URL and optional position.
2. Verify your products appear correctly in the Catalog tab of your Brand app.
3. When product-level details change (title, description, images, tags), update them using the Product Update endpoint.

Example

POST https://api.shopcanal.com/platform/products/

curl https://api.shopcanal.com/platform/products/ \
 --request POST \
 --header 'Content-Type: application/json' \
 --header 'x-canal-app-id: xxxx-xxxx-xxxx-xxxx' \
 --header 'x-canal-app-token: your_api_access_token' \
 --data '{
   "title": "Classic Running Shoe",
   "body_html": "<p>Lightweight everyday trainer.</p>",
   "vendor": "Your Brand Name",
   "product_type": "Apparel & Accessories > Shoes > Athletic Shoes",
   "status": "active",
   "image_src": "https://cdn.yourbrand.com/images/shoe-main.jpg",
   "images": [
     { "src": "https://cdn.yourbrand.com/images/shoe-side.jpg", "position": 1 }
   ],
   "variants": [
     {
       "sku": "SHOE-8-BLK",
       "price": "129.99",
       "inventory_quantity": 50,
       "inventory_policy": "deny",
       "option1": "8",
       "option2": "Black",
       "grams": 363
     }
   ]
 }'

備考

Sensitive categories: Certain product categories (e.g. alcohol, adult products, supplements) require explicit publisher approval before your ads can serve ads. Your Rokt account manager will advise if your catalog includes any such categories.

Updating a product via API

When product-level details change (title, description, images, tags), update them using the Product Update endpoint. These changes sync automatically to any connected Partners selling the product.

警告

The Product Update endpoint handles product-level fields only. To update variant-specific attributes like price, SKU, or inventory, use the Variant Update endpoint described in the Inventory Sync section below.

Inventory Sync

Inventory levels must be kept current to prevent overselling. Rokt mirrors your inventory_quantity values and stops serving a variant when its stock reaches zero and its inventory_policy is deny.

1. When a variant's price, compare_at_price, sku, or inventory_quantity changes in your system, push the update to Catalog using the Variant Update endpoint. Price and inventory changes sync automatically to Shoppable Ads.
2. To add a new variant to an existing product (e.g., a new size or color), use the Variant Create endpoint. The new variant syncs to Partners automatically.
3. While you can delete variants when no longer available using the Variant Delete endpoint, we instead recommend updating the Product Status or using the Pause Selling boolean on the Variant object.

Best practices:

• Push inventory updates as soon as possible after any stock change in your system
• Implement a full catalog reconciliation sync at least once every 24 hours
• For high-velocity products, consider real-time inventory updates from your OMS

Verifying your catalog

After adding products, confirm they were ingested correctly by logging in to the Rokt Catalog for Brands app at https://app.shopcanal.com/ and checking the Catalog tab under your Catalog for Brands account.