Updating Products in Marqo

This guide shows you how to update existing product documents in your Marqo ecommerce search index using partial updates. Learn how to efficiently modify specific fields without needing to resend the entire product document.

Prerequisites

• A Marqo Cloud account (sign up here)
• Your Marqo API key (find your API key guide)
• An existing ecommerce index with products (add products guide)

Partial Update Documents

Update existing product documents by making a PATCH /documents request. This endpoint allows you to modify specific fields without affecting other product data.

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

Request Body:

{
 "documents": [
     {
      "_id": "43207430723",
      "price": 150
     }
 ]
}

Key Differences from Add Products

• Method: PATCH instead of POST
• Required Fields: Only _id is required - all other fields are optional
• Behavior: Updates only the fields you specify, leaving other fields unchanged
• Body Structure: Identical to Add Products but with optional fields

For complete field documentation, see the Add Products guide.

Update Examples

Price Update

Update just the price of a product:

{
  "_id": "43207430723",
  "price": 149.99
}

Description and Collections Update

Update product description and add it to new collections:

{
  "_id": "43207430724", 
  "description": "Enhanced cotton blend with improved comfort and durability",
  "productCollections": ["shirts", "premium", "bestsellers"]
}

Stock and Custom Fields Update

Update custom fields like stock quantity and availability:

{
  "_id": "43207430725",
  "stock_quantity": 25,
  "is_available": true,
  "last_updated": "2024-01-15T10:30:00Z"
}

Variant Information Update

Update variant-specific information:

{
  "_id": "43208765432",
  "variantTitle": "Premium Wireless Headphones - Matte Black - Limited Edition",
  "price": 229.99,
  "productCollections": ["electronics", "audio", "limited-edition"]
}

Updating Products in Your Index

cURL

# Single product update
curl -X PATCH 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",
      "price": 150
    }
  ]
}'

# Bulk update example
curl -X PATCH 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", 
      "price": 120
    },
    {
      "_id": "43207430724",
      "price": 130
    },
    {
      "_id": "43207430725",
      "price": 160
    }
  ]
}'

JavaScript

// Single product update
fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      documents: [
        {
          _id: "43207430723",
          price: 150,
        },
      ],
    }),
  }
);

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

Response

The response structure is identical to the Add Products endpoint. A status code of 200 indicates successful processing.

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 update.
processingTimeMs	Integer	The time taken to process the batch request, in milliseconds.
index_name	String	The name of the index where documents were updated.

Response Status Codes

Status Code	Description
200	The document was successfully updated.
400	Bad request. Invalid input or document ID not found.
404	Document with the specified _id does not exist.
429	Too many requests. Please try again later.
500	Internal error.

Best Practices

Efficient Updates

• Update only changed fields - Don't include fields that haven't changed
• Batch updates - Group multiple updates into single requests for better performance
• Use specific IDs - Ensure _id values match existing documents exactly

Common Update Patterns

• Price updates - For sales, promotions, or inventory changes
• Stock management - Update availability and quantity fields
• Content improvements - Enhance descriptions and add new collections
• Seasonal changes - Update collections for holidays or seasons

Error Handling

Check the response status and handle errors appropriately:

# Example error response handling
{
  "errors": true,
  "items": [
    {"_id": "43207430723", "status": 200, "message": "Document updated successfully"},
    {"_id": "nonexistent-product", "status": 404, "message": "Document not found"}
  ]
}

Monitor the errors field and individual item statuses to identify any failed updates.

Performance Tips

• Batch size - Update 25-75 products per request for optimal performance
• Frequency - Avoid updating the same products too frequently
• Field types - Remember that only certain field types can be vectorized (see Add Products guide)

Common Update Scenarios

Inventory Management

Update stock levels and availability:

{
  "_id": "43207430723",
  "stock_quantity": 15,
  "is_available": true,
  "last_restocked": "2024-01-15"
}

Pricing Changes

Update prices for sales or promotions:

{
  "_id": "43207430724", 
  "price": 99.99,
  "sale_price": 79.99,
  "on_sale": true
}