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

​
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

# 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
    }
  ]
}'
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 NameTypeDescription
errorsBooleanIndicates whether any errors occurred during the processing of the batch request.
itemsArrayAn array of objects, each representing the processing status of an individual document update.
processingTimeMsIntegerThe time taken to process the batch request, in milliseconds.
index_nameStringThe name of the index where documents were updated.

​
Response Status Codes

Status CodeDescription
200The document was successfully updated.
400Bad request. Invalid input or document ID not found.
404Document with the specified _id does not exist.
429Too many requests. Please try again later.
500Internal 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
}