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 request with an ids array in the request body.

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

Request Body:

{
  "ids": ["43207430723", "43207430724", "43207430725"]
}

Single Product Deletion

Delete one product by providing a single ID in the ids array:

{
  "ids": ["43207430723"]
}

Batch Product Deletion

Delete multiple products by providing multiple IDs:

{
  "ids": ["43207430723", "43207430724", "43207430725", "43208765432"]
}

Single Product Deletion

Delete one specific product by providing its ID:

cURL
JavaScript

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43207430723"]}'

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

Batch Product Deletion

Delete multiple products efficiently in a single request:

cURL
JavaScript

# Delete multiple products
curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43207430723", "43207430724", "43207430725", "43208765432"]}'

# Delete product variants
curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43207430726", "43207430727", "43207430728"]}'

// Delete multiple products
fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ids: ["43207430723", "43207430724", "43207430725", "43208765432"],
    }),
  }
);

// Delete product variants
fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ids: ["43207430726", "43207430727", "43207430728"],
    }),
  }
);

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

Deletion Response

Deleting documents is asynchronous. A valid request returns 202 Accepted with the ID of the job that will remove the documents:

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

The documents remain searchable until the job completes. The response does not report per-document results; retrieve the job to confirm the outcome. 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.

IDs that are not in the index are silently ignored. They do not cause an error on the request or on the job, so deleting the same IDs twice is safe.

Errors

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

Status	When	`error`
`404`	The 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}"`
`422`	An ID is blank (empty or only whitespace)	A list with one validation issue whose `msg` is `"Value error, Document ID at index 0 must not be blank"` (the index points at the offending entry in `ids`)
`422`	`ids` is missing or empty, an ID is not a string, or the request body contains a key other than `ids`	A 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 blank ID:

{
  "error": [
    {
      "type": "value_error",
      "loc": ["body", "ids"],
      "msg": "Value error, Document ID at index 1 must not be blank",
      "input": ["sku-1", "  "],
      "ctx": { "error": {} }
    }
  ]
}

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.

Common Deletion Scenarios

Product Discontinuation

Remove discontinued products from your catalog:

cURL
JavaScript

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43209876543", "43209876544", "43209876545"]}'

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ids: ["43209876543", "43209876544", "43209876545"],
    }),
  }
);

Variant Management

Remove specific variants while keeping the parent product:

cURL
JavaScript

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43207654321", "43207654322"]}'

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ids: ["43207654321", "43207654322"],
    }),
  }
);

Seasonal Cleanup

Remove seasonal products after the season ends:

cURL
JavaScript

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json" \
	-d '{"ids": ["43208123456", "43208123457", "43208123458"]}'

fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ids: ["43208123456", "43208123457", "43208123458"],
    }),
  }
);

Resetting an index

You can reset your index with the reset endpoint. Resetting an index means deleting all documents from the index while keeping its configuration. Unlike the document endpoints above, a reset does not create a job: the response is returned once the reset request has been processed, and there is nothing to poll.

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

warning

This is a destructive action, intended for use as required during initial experimentation and integration. It cannot be undone.

Parameters

Parameter	Type	Default	Description
`quick`	boolean (query)	`false`	When `false`, the index is deleted and recreated. This takes several minutes and the index is briefly unavailable while it runs. When `true`, the documents are removed without recreating the index. This is faster, but it is not a full reset: the index may keep stale data and can behave inconsistently afterwards (for example, ranking the same documents differently), so prefer the default unless you are about to repopulate the index immediately.

Response

Status	Body	When
`204`	none	The full reset (default) was processed.
`200`	`null`	The quick reset (`quick=true`) was processed.
`404`	`{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}`	The index name is unknown, belongs to another account, or is not ready to serve requests yet.

cURL
JavaScript

# Clear existing catalog
curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reset \
	-H "Authorization: Bearer {api_key}" \
	-H "Content-Type: application/json"

# Then add new catalog using the add documents endpoint

// Clear existing catalog
fetch(
  "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/reset",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer {api_key}",
      "Content-Type": "application/json",
    },
  }
);

// Then add new catalog using the add documents endpoint

Best Practices

Deletion Safety

Confirm the job - Keep the jobId and check that the job reached COMPLETED before assuming the documents are gone
Unknown IDs are ignored - A deletion request never fails because an ID is missing from the index, so verify your ID list if a document you expected to disappear is still returned by search
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)

Prerequisites​

Delete Documents by ID​

Single Product Deletion​

Batch Product Deletion​

Single Product Deletion​

Batch Product Deletion​

Deletion Response​

Errors​

Common Deletion Scenarios​

Product Discontinuation​

Variant Management​

Seasonal Cleanup​

Resetting an index​

Parameters​

Response​

Best Practices​

Deletion Safety​

Prerequisites

Delete Documents by ID

Single Product Deletion

Batch Product Deletion

Single Product Deletion

Batch Product Deletion

Deletion Response

Errors

Common Deletion Scenarios

Product Discontinuation

Variant Management

Seasonal Cleanup

Resetting an index

Parameters

Response

Best Practices

Deletion Safety