This guide explains how to delete documents in custom data entities in Master Data v1 through the Master Data API v1 to reduce stored volume and billing. The flow uses Scroll documents to list document IDs and Delete document to remove each record.

To erase data for one specific customer for privacy reasons, follow Erasing customer data, which uses Search documents and Delete document. This guide does not replace that flow.

In Master Data v1, a data entity is the schema (table) that defines fields and storage rules. Each record stored in that entity is a document, identified by a unique ID. See Master Data for more on this model.

A common mistake when trying to reduce Master Data billing is clicking delete on the data entity in the Master Data v1 interface. That action removes the entity definition but does not delete the documents already stored, so Master Data consumption is not affected. For custom data entities, the monthly snapshot used for billing continues to count those records, and billed volume does not decrease.

If the data entity was already deleted from the Master Data v1 interface, the API can no longer search or scroll the documents stored under that acronym. Recreate the entity, publish it, and reindex it before you run the deletion flow below.

To recover access to a deleted entity:

1. Recreate the data entity in the Master Data v1 interface. See Data entity.
2. Publish the entity using the save action on the entity row, as described in Data entity.
3. Reindex the entity so the documents become searchable and scrollable through the API again. To reindex, follow the instructions in Filtering data on Master Data.
4. Run the scroll and delete flow to remove the records once reindexing completes.

Bulk deletion requires listing every document ID first. Use Scroll documents (GET /api/dataentities/{acronym}/scroll), the same endpoint used for large-scale data extraction. For query patterns and scroll limits, see Extracting data from Master Data with search and scroll and Querying documents in Master Data v1.

Send a GET request to the Scroll documents endpoint, replacing {acronym} with the data entity acronym. On the first request only, set _size (maximum 1000) to control how many documents are returned per page. Optionally set _fields=id to return only document IDs. You cannot change _size or filters on subsequent requests.

First request example:

From the response:

1. Collect the id value of each document.
2. Read the X-VTEX-MD-TOKEN response header from the first request.
3. Send another GET request with _token set to that header value while the response still contains documents. Repeat until the response returns an empty list. The token expires after 20 minutes of inactivity. For more details, see Scroll pagination.

Subsequent request example:

1. Send a DELETE request to Delete document (DELETE /api/dataentities/{acronym}/documents/{id}) for each document ID returned by the scroll requests.

Request example:

2. Repeat for every ID collected in the previous step. A successful deletion returns HTTP status 204 No Content.

Document deletion is irreversible. Before running this flow in production, confirm the entity acronym and test with a small set of records when possible.

After you delete documents through the API, they are no longer counted in stored volume.