Deleting Products from Marqo
This guide shows you how to delete product documents from your Marqo ecommerce search index. Learn how to remove specific products by ID or completely reset your index.
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)
Delete Documents by ID
Remove specific product documents by making a DELETE /documents/delete-batch
request with an array of document IDs.
["PROD-001", "PROD-002", "PROD-003"]
Single Product Deletion
Delete one product by providing a single ID in the array:
["PROD-001"]
Batch Product Deletion
Delete multiple products by providing multiple IDs:
["PROD-001", "PROD-002", "PROD-003", "VARIANT-004", "VARIANT-005"]
Single Product Deletion
Delete one specific product by providing its ID:
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["PROD-001"]'
Batch Product Deletion
Delete multiple products efficiently in a single request:
# Delete multiple products
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["PROD-001", "PROD-002", "PROD-003", "PROD-004"]'
# Delete product variants
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["VARIANT-001-RED", "VARIANT-001-BLUE", "VARIANT-001-GREEN"]'
Deletion Response
The response provides detailed information about the deletion operation:
{
"details": {
"deletedDocuments": 2,
"receivedDocumentIds": 2
},
"items": [
{"_id": "PROD-001", "result": "deleted", "status": 200},
{"_id": "PROD-002", "result": "deleted", "status": 200}
]
}
Response Fields
Field Name | Type | Description |
---|---|---|
details.deletedDocuments |
Integer | Number of documents successfully deleted |
details.receivedDocumentIds |
Integer | Number of document IDs received in the request |
items |
Array | Status of each individual document deletion |
items[].\_id |
String | The ID of the document |
items[].result |
String | Result of the deletion operation |
items[].status |
Integer | HTTP status code for this specific deletion |
Status Codes
Status Code | Description |
---|---|
200 |
Document successfully deleted |
404 |
Document with the specified ID was not found |
400 |
Bad request (invalid ID format) |
500 |
Internal error |
Reset Index (Delete All Products)
Use the reset endpoint to delete all products from your index at once. This is useful for complete catalog refreshes or testing.
⚠️ Warning: This operation is irreversible and will delete ALL documents in your index.
# Reset entire index
curl -X POST 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/reset' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json'
Common Deletion Scenarios
Product Discontinuation
Remove discontinued products from your catalog:
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["PROD-OLD-001", "PROD-OLD-002", "PROD-LEGACY-003"]'
Variant Management
Remove specific variants while keeping the parent product:
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["TSHIRT-001-XS", "TSHIRT-001-XXL"]'
Seasonal Cleanup
Remove seasonal products after the season ends:
curl -X DELETE 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/documents/delete-batch' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json' \
-d '["SWIMWEAR-001", "SANDALS-002", "SUNGLASSES-003"]'
Catalog Migration
Reset index before importing new catalog:
# Clear existing catalog
curl -X POST 'https://api.marqo.ai/api/v2/indexes/your-ecommerce-index/reset' \
-H "x-api-key: your_api_key_here" \
-H 'Content-type: application/json'
# Then add new catalog using the add documents endpoint
Best Practices
Deletion Safety
- Verify IDs - Ensure product IDs exist before attempting deletion
- Backup data - Keep backups before bulk deletions
- Test first - Test deletion operations on a staging index
- Batch wisely - Delete in reasonable batch sizes (50-100 IDs)
Error Handling
Check the response to monitor deletion results:
{
"details": {
"deletedDocuments": 3,
"receivedDocumentIds": 4
},
"items": [
{"_id": "PROD-001", "result": "deleted", "status": 200},
{"_id": "PROD-002", "result": "deleted", "status": 200},
{"_id": "PROD-003", "result": "deleted", "status": 200},
{"_id": "PROD-999", "result": "not found", "status": 404}
]
}
Monitor the details.deletedDocuments
vs details.receivedDocumentIds
and check individual item statuses for any failed deletions.
Reset Considerations
- Data Loss - Reset permanently deletes ALL data
- Confirmation - Implement confirmation prompts for reset operations
- Timing - Perform resets during low-traffic periods
- Re-indexing - Plan for re-adding products after reset
Always confirm reset operations before executing, as this operation cannot be undone.
Performance Tips
Batch Size Optimization
- Small batches - 50-100 IDs per request for optimal performance
- Parallel processing - Split large deletions across multiple requests
- Rate limiting - Avoid overwhelming the API with rapid requests
ID Management
- Valid formats - Ensure IDs match your indexing format
- Deduplication - Remove duplicate IDs before sending requests
- Validation - Verify IDs exist before deletion attempts