Adding Products to Marqo

This guide shows you how to add product documents to your Marqo ecommerce search index. Learn about the core product data structure, different value types, and comprehensive examples for building a robust product catalog.

Prerequisites

A Marqo Cloud account (sign up here)
Your Marqo API key (find your API key guide)
An existing ecommerce index (create an index guide)

Add (or Replace) Documents

Documents (products) can be added or replaced by a POST /documents request to the following endpoint:

Endpoint: POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents

Request Body:

{
 "documents": [
     {
      "_id": "43207430723",
      "parentProductId": "43207430720",
      "productTitle": "Shirt",
      "variantTitle": "Shirt - Light Blue",
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/light-blue-tshirt.jpg?v=1754569578",
      "price": 100,
      "description": "Comfortable cotton shirt perfect for casual wear",
      "color": "Light Blue",
      "productCollections": ["shirts"]
     }
 ]
}

Add Documents Parameters

Add documents parameters	Value Type	Description
`documents`	Array of objects	An array of documents. Each document is represented as a JSON object.

Document Parameters

Each document has the following fields:

Parameter	Type	Required	Description
`_id`	string	Required	Must be the variant ID. A unique string identifying this specific product variant. This should be unique across all variants in your catalogue. It must also correspond to the document IDs captured by the Marqo pixel.
`productTitle`	string	Required	The main product's name e.g.: "Shirt", "Wireless Headphones"
`variantTitle`	string	Optional	The specific variant's name: e.g. "Shirt - Light Blue", "Wireless Headphones - Black"
`variantImageUrl`	url	Required	The image URL for this specific variant. Must be publicly accessible and represent the actual variant being indexed.
`price`	number	Required	The price of this specific variant.
`description`	string	Optional	A detailed description of the product. This text is used for search matching and can include features, materials, use cases, etc.
`productCollections`	array of strings	Optional	An array of collections that this product belongs to.
`parentProductId`	string	Optional	Enables variant grouping. If provided, variants with the same `parentProductId` will be grouped together in search results, showing only the top-scoring variant from each group. If omitted, all variants will be treated as separate products in search results.

Understanding Variant Grouping

The parentProductId field controls how product variants appear in search results:

With parentProductId: Only the highest-scoring variant from each parent group appears in search results
Without parentProductId: All variants are treated as individual products and can all appear in search results

Example: If you have 3 shirt variants (red, blue, light blue) with the same parentProductId, a search for "shirt" will return only the most relevant variant (e.g., the blue shirt), not all three variants.

Additional Custom Fields

You can add any other custom fields to your product documents beyond the core parameters listed above. Here are the accepted field types and their properties:

Field Type	Description
Strings	Text fields
Floats	Numeric fields that can be used to filter search results
Bools	Boolean fields that can be used to filter search results
Ints	Integer fields that can be used to filter search results
Array	Currently only arrays of strings are supported. Can be used for filtering and lexical search

Example with Custom Fields

{
  "_id": "43208765432",
  "parentProductId": "43208765430",
  "productTitle": "Premium Wireless Headphones",
  "variantTitle": "Premium Wireless Headphones - Black",
  "variantImageUrl": "https://cdn.example.com/headphones-black.jpg",
  "price": 199.99,
  "productCollections": ["electronics", "audio"],

  // Custom fields
  "brand": "AudioTech",                    // String
  "weight_grams": 250.5,                   // Float
  "is_wireless": true,                     // Bool
  "stock_quantity": 45,                    // Int
  "features": ["bluetooth", "noise-cancel"], // Array of strings
  "color": "Black",                        // String
  "description": "High-quality over-ear headphones with active noise cancellation"
}

Adding Products to Your Index

Single Product Example

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{
  "documents": [
    {
      "_id": "43208765432",
      "parentProductId": "43208765430",
      "productTitle": "Shirt",
      "variantTitle": "Shirt - Light Blue",
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/light-blue-tshirt.jpg?v=1754569578",
      "price": 199.99,
      "description": "Comfortable cotton shirt perfect for casual wear. Made from 100% organic cotton with a relaxed fit.",
      "productCollections": ["shirts", "sale", "casual"],
      "color": "Blue"
    }
  ]
}'

This will return the ID of the job.

Check for errors

Retrieve details for a specific job using its job ID:

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs/{job_id} \
-H "Authorization: Bearer {api_key}"

Multiple Variants Example

This example shows how to add multiple variants of the same product with proper variant grouping:

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{"documents": [
{
    "_id": "43207430723",
    "parentProductId": "43207430720",
    "productTitle": "Shirt",
    "variantTitle": "Shirt - Light Blue",
    "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/light-blue-tshirt.jpg?v=1754569578",
    "price": 100,
    "description": "Comfortable cotton shirt perfect for casual wear. Made from 100% organic cotton with a relaxed fit.",
    "color": "Light Blue",
    "productCollections": ["shirts"]
},
{ 
    "_id": "43207430724",
    "parentProductId": "43207430720",
    "productTitle": "Shirt",
    "variantTitle": "Shirt - Blue",
    "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/blue-tshirt.jpg?v=1754569578",
    "price": 200,
    "description": "Classic blue shirt with modern styling. Breathable fabric ideal for work or leisure.",
    "color": "Blue",
    "productCollections": ["shirts"]
},
{
    "_id": "43207430725",
    "parentProductId": "43207430720",
    "productTitle": "Shirt",
    "variantTitle": "Shirt - Red",
    "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/red-tshirt.jpg?v=1754569578",
    "price": 300,
    "description": "Bold red shirt that makes a statement. Premium quality cotton with excellent durability.",
    "color": "Red",
    "productCollections": ["shirts"]
}
]}'

Note: Replace {index_name} with your actual index name and {api_key} with your API key.

Response

The response of the add_documents endpoint operates on two levels. A status code of 200 indicates that the batch request has been successfully received and processed by Marqo. The response has the following fields:

Field Name	Type	Description
`errors`	Boolean	Indicates whether any errors occurred during the processing of the batch request.
`items`	Array	An array of objects, each representing the processing status of an individual document in the batch.
`processingTimeMs`	Integer	The time taken to process the batch request, in milliseconds.
`index_name`	String	The name of the index to which the documents were added.

Each item in the items array has the following fields:

Field Name	Type	Description
`_id`	String	The ID of the document that was processed.
`status`	Integer	The status code of the document processing.
`message`	String	A message that provides additional information about the processing status of the document. This field only exists when the status is not `200`.

Here is the HTTP status code of the individual document responses:

Status Code	Description
`200`	The document is successfully added to the index.
`400`	Bad request. Returned for invalid input (e.g., invalid field types). Inspect `message` for details.
`429`	Marqo vector store receives too many requests. Please try again later.
`500`	Internal error.

Best Practices

Data Quality

Consistent Variant IDs: Use meaningful, consistent variant IDs that clearly identify each product variant (e.g., shirt-red-medium, headphones-black-001)
Proper Variant Grouping: Use parentProductId consistently for variants of the same product to control search result display
High-Quality Images: Use clear, high-resolution images that accurately represent each specific variant
Accurate Pricing: Keep prices up-to-date and ensure each variant has the correct price
Descriptive Titles: Make variantTitle descriptive enough to distinguish between variants

Variant Management

With Grouping: Use parentProductId when you want only the most relevant variant to appear in search results
Without Grouping: Omit parentProductId when you want all variants to potentially appear as separate results
Consistent Grouping: If using parentProductId, ensure all variants of the same product use the same parent ID

Image Best Practices

Ensure variantImageUrl points to an image of the specific variant, not a generic product image
Use publicly accessible URLs that won't expire
Optimize images for fast loading while maintaining quality