Skip to content

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

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

Next Steps