# Inventory Batch Delete

The Inventory Batch Delete API enables external integrations to programmatically delete inventory data from Claret. This API complements the [Inventory Import](https://docs.claret.app/apis/public-apis/inventory/import) API to support complete inventory refresh workflows.

The API supports two deletion modes:

* **Row-based deletion** - Delete specific inventory rows by unique identifiers (recommended for UI-driven deletions)
* **Filter-based deletion** - Delete by broad criteria (items, locations, bins, etc.)

As with all Claret API endpoints, the Inventory Batch Delete API requires token authentication. For instructions on how to retrieve and pass through the authentication token, please refer to the [Authentication](https://docs.claret.app/apis/authentication) documentation.

{% hint style="info" %}
All API documentation herein contains a `{tenant}` section of the URL path. These should always be replaced with the name of the actual tenant making the API call (i.e., `demo`, `yourcompany`, etc.)
{% endhint %}

### POST Inventory Batch Delete

<mark style="color:green;">`POST`</mark> `https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete`

Delete inventory records matching the specified criteria.

#### Headers

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer {token}`   |

***

## Deletion Modes

The API accepts one of two deletion modes. If both are provided, row-based deletion takes precedence.

### Mode 1: Row-Based Deletion

Use this mode to delete specific inventory rows by providing an array of row objects. Each row uniquely identifies allocation(s) using any combination of fields.

#### Request Body (Row-Based)

| Name                                          | Type   | Description                         |
| --------------------------------------------- | ------ | ----------------------------------- |
| rows<mark style="color:red;">\*</mark>        | array  | Array of row objects to delete      |
| (rows) item<mark style="color:red;">\*</mark> | string | Item name (required for each row)   |
| (rows) location                               | string | Location name                       |
| (rows) location\_area                         | string | Location area name                  |
| (rows) bin                                    | string | Bin name                            |
| (rows) lot                                    | string | Lot name                            |
| (rows) date\_filled                           | string | Date filled. **Format: YYYY-MM-DD** |

{% hint style="info" %}
**Row Logic:** All provided fields within a row use **AND** logic - the allocation must match ALL specified fields. Multiple rows use **OR** logic.
{% endhint %}

#### Example: Row-Based Request

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "item": "122-18",
        "location": "ZAM-WHS",
        "location_area": "Storage",
        "bin": "FG-GEN-BIN",
        "lot": "FG-GEN-LOT",
        "date_filled": "2023-01-01"
      },
      {
        "item": "ZAMNVCAS19",
        "location": "ZAM-WINERY"
      }
    ]
  }'
```

***

### Mode 2: Filter-Based Deletion

Use this mode for bulk deletions matching broad criteria.

#### Request Body (Filter-Based)

| Name               | Type   | Description                                    |
| ------------------ | ------ | ---------------------------------------------- |
| items              | array  | Array of item names                            |
| locations          | array  | Array of location names                        |
| location\_areas    | array  | Array of location area names                   |
| bins               | array  | Array of bin names                             |
| lots               | array  | Array of lot names                             |
| date\_filled\_from | string | Start date (inclusive). **Format: YYYY-MM-DD** |
| date\_filled\_to   | string | End date (inclusive). **Format: YYYY-MM-DD**   |

{% hint style="info" %}
**Filter Logic:**

* **Within a filter (OR):** `items: ["A", "B"]` matches records for item A **OR** item B
* **Across filters (AND):** `items: ["A"], locations: ["X"]` matches records for item A **AND** location X
  {% endhint %}

{% hint style="warning" %}
At least one filter must be provided. If all provided filters are empty arrays, a 422 validation error is returned.
{% endhint %}

#### Example: Filter-Based Request

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["WIP-2024-CHARD", "WIP-2024-PINOT"],
    "locations": ["Warehouse A"]
  }'
```

***

## Response

{% tabs %}
{% tab title="200: OK Deletion Successful" %}

```json
{
  "message": "Inventory deleted successfully",
  "content": {
    "records_deleted": 1500
  }
}
```

{% endtab %}

{% tab title="200: OK No Matches Found" %}

```json
{
  "message": "No matching inventory records found",
  "content": {
    "records_deleted": 0
  }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity No Filters" %}

```json
{
  "message": "Validation failed",
  "errors": {
    "filters": ["You must provide at least one filter (rows, items, locations, bins, lots, or dates)."]
  }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Invalid Date" %}

```json
{
  "message": "Validation failed",
  "errors": {
    "date_filled_from": ["The date_filled_from is not a valid date."]
  }
}
```

{% endtab %}

{% tab title="401: Unauthorized" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}
{% endtabs %}

***

## Examples

### Delete by Item Only

Delete all allocations for specific items:

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["WIP-2024-CHARD", "WIP-2024-PINOT"]
  }'
```

### Delete by Location

Delete all inventory at a specific location:

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["Warehouse A"]
  }'
```

### Delete by Date Range

Delete inventory within a date range:

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "date_filled_from": "2024-01-01",
    "date_filled_to": "2024-06-30"
  }'
```

### Delete with Combined Filters (AND Logic)

Delete inventory matching multiple criteria:

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["116"],
    "locations": ["ZAM-WHS"],
    "location_areas": ["Storage"],
    "bins": ["FG-GEN-BIN"]
  }'
```

### Row-Based: Delete Specific Rows

Delete exact rows (e.g., user-selected rows from UI):

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "item": "122-18",
        "location": "ZAM-WHS",
        "bin": "FG-GEN-BIN",
        "lot": "FG-GEN-LOT",
        "date_filled": "2023-01-01"
      }
    ]
  }'
```

### Row-Based: Delete by Item Name Only

Delete all allocations for specific items using row mode:

```bash
curl -X POST "https://plan.claret.app/{tenant}/api/v1/inventory/batch-delete" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"item": "122-18"},
      {"item": "ZAMNVCAS19"}
    ]
  }'
```

***

## Behavior Notes

### Idempotency

The delete operation is idempotent. Re-running the same request returns success with `records_deleted: 0` if the records were already deleted.

### Data Integrity

* Only transactional inventory data is deleted (allocations and empty containers)
* Master data (Items, Locations, Bins, Lots) is **not** deleted
* All operations are scoped to the authenticated tenant only

### Performance

* Large deletions are processed in chunks of 1000 records
* The operation is synchronous and returns when complete

### Name Matching

All filters match by the **name field** of each entity, not by ID or description. Matching is case-sensitive.

***

## Related Documentation

* [Inventory Import](https://docs.claret.app/apis/public-apis/inventory/import) - Import inventory records
* [Job Status](https://docs.claret.app/apis/public-apis/job-status) - Monitor import job progress
* [Authentication](https://docs.claret.app/apis/authentication) - API authentication guide