Skip to main content

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​

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​

Updating documents is asynchronous, exactly like adding them. A valid request returns 202 Accepted with the ID of the job that will apply the updates:

{
  "jobId": "4eb23b8c-8d50-4a39-9bb1-490d8e6df521"
}

The response does not report per-document results. Retrieve the job to find out which updates were applied; the polling flow and the meaning of each jobStatus are described under Add Products: Response, and every job field is listed on the Monitor Jobs page.

Updates to an _id that does not exist in the index are not rejected when the request is made. They fail while the job runs, so the job finishes with jobStatus ERROR and lists the missing IDs under errorItemsDetails with the reason document_missing.

Errors​

Requests that fail validation are rejected immediately and no job is created. Error responses have the shape {"error": ...}.

StatusWhenerror
400documents is an empty array"No documents to update"
404The index name is unknown, belongs to another account, or is not ready to serve requests yet"Marqo settings not found for shop {system_account_id}-{index_name}"
422A document has no _id, an _id is an empty string, or the request body contains a key other than documentsA list of validation issues. Each issue has a loc path to the offending value and a msg such as "Field required".

Example of a 422 for a document without an _id:

{
  "error": [
    {
      "type": "missing",
      "loc": ["body", "documents", 0, "_id"],
      "msg": "Field required",
      "input": { "price": 89.99 }
    }
  ]
}

Each issue always carries type, loc and msg. Other keys may be present: input holds the value that was rejected, and ctx appears on issues that have extra context such as an allowed value list.

An update is skipped when a newer version of the document has already been indexed, which is reported as the CONFLICT job status. Send the x-marqo-bypass-conflict: true header to force the write through. See bypassing the version conflict check.

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​

Keep the jobId from each response and check the job once it finishes. A jobStatus of ERROR or FAILED means some updates were not applied; the affected IDs are grouped by reason under errorItemsDetails and failedItemsDetails. Fix the documents and resend only those.

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
}