Skip to main content
This guide outlines the requirements and supported methods for integrating e-commerce platforms which host multiple merchants or storefronts into our catalog ingestion system.

​
Overview

To enable product discovery and shopping experiences across a large number of merchants hosted on your platform, we require two core data components and support multiple ingestion methods for flexibility and ease of integration.

​
Required Data Components

​
1. Merchant Product Feed (One per Merchant)

Each merchant must provide a product feed in Google Shopping CSV format. This file should include all relevant product attributes such as:
  • id - This should refer to the variantID on your platform
  • item_group_id - This should refer to the parentID on your platform - if this does not exist in the feed file, merchant’s products will be ingested as single-variant-products.
  • title
  • description
  • link
  • image_link
  • price
  • availability
  • brand
  • etc.
Note: Each merchant must have an individual feed file.

​
2. Merchant Onboarding Requirements

When a merchant is onboarded into the commerce AI system, we need some way to know that this merchant exists on your platform, how we should download their data, etc. We can receive this notification in a few ways, such as:

​
Option A. Merchant Manifest File (One per Platform)

This manifest should contain metadata for all participating merchants on your platform. The file must be structured as a CSV or JSON and include one row (or object) per merchant. Required Fields:
  • storeName (e.g., “Blueberry Boutique”)
  • storeUrl (e.g., “https://blueberry-boutique.com”)
  • currency (e.g., “USD”)
  • country (e.g., “US”)
  • favIcon (URL to the store’s favicon)
Recommended Additional Fields:
  • Supported shipping regions
  • Store category or vertical (e.g., apparel, electronics)
  • Internal merchant ID (if applicable)
Note:️ The manifest should be kept up-to-date with the latest list of opted-in merchants and their metadata.
B. Merchant sends us a webhook to onboard (one POST per merchant) The webhook should be a POST containing merchant information in a JWT encoded blob; content-type=plain/text. When decoded, the JWT should look like: 
{
  "storeName": "acme store",
  "storeUrl": "acmestore.com
  "currency": "USD",
  "country": "US",
  "favIcon": "favIcon.jpg",
  "platformMerchantId": "your-platforms-merchant-identifier",
  // Optional fields:
  "paypalId": "SAMPLEPYPLID5", # 13-character PayPal merchant id
  "shippingRegions": ["US","CA","MX"...],
  ...
  Any additional merchant-specific information you may deem relevant
}

​
2. Supported Feed Ingestion Methods

We support several ingestion methods for fetching the merchant feeds and manifest file. Choose the option that best fits your infrastructure:

​
Option 1: SFTP/FTP Server

  • Host the files on your SFTP/FTP server.
  • Provide us with access credentials and path details.
  • Files must be updated on a predictable schedule.

​
Option 2: Cloud Storage (Your Bucket)

  • Supported services: Google Cloud Storage (GCS) or Amazon S3.
  • Grant our service account read access to the specific bucket or path.
  • Ensure file names and structure remain consistent over time.

​
Option 3: Cloud Storage (Our GCS Bucket)

  • We provision a path within our GCS bucket for your platform.
  • You will be granted write access for your service account.
  • Upload merchant feeds and manifest files to this path.

​
Option 4: API access

  • You expose an API which can export a merchant’s catalog through a paginated endpoint
  • You can give our backend services access to this API, and describe the preferred workflow for authentication.
  • We will download each merchant’s catalog daily on a scheduled cadence.
  • Ensure that your systems will support this elevated rate of API requests without rate-limiting.

​
Option 5: Direct URL

  • Host feed files directly on a publicly accessible or whitelisted URL.
  • File URLs must follow a consistent naming scheme (e.g., https://merchantsite.com/product_feed.csv).
  • Ensure files are accessible via HTTPS.

​
Next Steps

  1. Choose and confirm the ingestion method you will use.
  2. Share access details (credentials, service account IDs, URLs, etc.) with our onboarding team.
  3. Provide a sample merchant feed file and manifest for validation.
  4. Coordinate a test ingestion run with our engineering team.
⌘I