> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete retail invoice

> Permanently delete a retail invoice and its associated data.

<Warning>
  This action is irreversible. The invoice record, its parsed details, and the source HTML file in S3 are all permanently deleted.
</Warning>

## Authentication

All requests to this endpoint must include a valid JWT in the `Authorization` header.

```
Authorization: Bearer <token>
```

## Path parameters

<ParamField path="invoice_id" type="string" required>
  The unique identifier of the retail invoice to delete.
</ParamField>

## What gets deleted

Deleting a retail invoice removes the following:

* The invoice record from the `RetailInvoices` DynamoDB table.
* The invoice's parsed detail record from the corresponding category detail table (e.g., `FoodDeliveryInvoices`, `ClothingInvoices`, `TechnologyInvoices`, `SubscriptionInvoices`, `GroceryInvoices`, `MiscUtilityInvoices`, `MiscInvoices`, `TravelInvoices`).
* The raw HTML invoice file from S3.

Ownership is validated before deletion — you can only delete invoices that belong to the authenticated user.

## Response

<ResponseField name="message" type="string">
  A human-readable confirmation message. Example: `"Invoice deleted successfully"`
</ResponseField>

<ResponseField name="code" type="number">
  HTTP status code. `200` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="deleted_invoice" type="object">
      Metadata of the deleted invoice.

      <Expandable title="properties" defaultOpen>
        <ResponseField name="invoice_id" type="string">
          The ID of the deleted invoice.
        </ResponseField>

        <ResponseField name="vendor_name" type="string">
          The name of the vendor associated with the invoice.
        </ResponseField>

        <ResponseField name="sub_type" type="string">
          The category of the retail invoice. One of: `food-delivery`, `clothing`, `technology`, `subscriptions`, `grocery`, `utility`, `miscellaneous`, `travel`.
        </ResponseField>

        <ResponseField name="invoice_date" type="string">
          The date of the invoice.
        </ResponseField>

        <ResponseField name="total_amount" type="number">
          The total amount of the invoice.
        </ResponseField>

        <ResponseField name="currency" type="string">
          The currency of the invoice amount. Defaults to `"SEK"` if not set.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Error code              | Description                                                                              |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `MISSING_FIELDS`        | The `invoice_id` path parameter is absent.                                               |
| `401`  | `INVALID_CREDENTIALS`   | The `Authorization` header is missing or the token is invalid.                           |
| `401`  | `TOKEN_EXPIRED`         | The JWT has expired.                                                                     |
| `404`  | `INVALID_REQUEST`       | No invoice found for the given `invoice_id`, or the invoice belongs to a different user. |
| `502`  | `DEPENDENCY_FAILURE`    | A downstream dependency (DynamoDB or S3) returned an error during deletion.              |
| `500`  | `INTERNAL_SERVER_ERROR` | An unexpected server-side error occurred.                                                |

Error responses follow this structure:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invoice not found or you don't have permission to delete it"
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.paypulse.io/v1/invoices/retail/inv_abc123 \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Invoice deleted successfully",
    "code": 200,
    "data": {
      "deleted_invoice": {
        "invoice_id": "inv_abc123",
        "vendor_name": "Domino's Pizza",
        "sub_type": "food-delivery",
        "invoice_date": "2025-03-10",
        "total_amount": 149,
        "currency": "SEK"
      }
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "INVALID_REQUEST",
      "message": "Invoice not found or you don't have permission to delete it"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": "DEPENDENCY_FAILURE",
      "message": "Error deleting invoice file from S3"
    }
  }
  ```
</ResponseExample>