---
title: "Destroy invoice"
description: "Deletes an invoice permanently so its number can be used again. For an invoice created by mistake (an order opened by accident) that was never emailed. When the invoice holds the latest sequential number, rewind_counter:"
url: https://docs.invoicefalcon.com/v3-reference/documents/destroy-invoice/
api: "API v3 reference"
method: DELETE
path: "/documents/invoices/{id}/permanent"
---

# Destroy invoice

`DELETE https://app.invoicefalcon.com/api/v3/external/documents/invoices/{id}/permanent`

Deletes an invoice permanently so its number can be used again. For an invoice created by mistake (an order opened by accident) that was never emailed. When the invoice holds the latest sequential number, `rewind_counter: true` also sets the template's next invoice number back to it. Refused for an invoice that was emailed, has a credit note or has an e-invoice: raise a credit note for those instead. Paid plans only.

**Note:** Permanent: the document, its PDF and its history are removed. Cannot be undone. Opening the order again creates a new invoice. Send it first without `confirm`: nothing changes and the 409 `confirmation_required` says what would, including whether the counter can be rewound. Tell the merchant, ask, and resend with `confirm: true` (`?confirm=true` on a DELETE) only after they agree. To hide an invoice without freeing its number, trash it instead ([`DELETE /documents/invoices/:id`](https://docs.invoicefalcon.com/v3-reference/documents/delete-invoice/)).

## Path parameters

- `id` (string, required)

## Query parameters

- `confirm` (boolean): Send true only after the merchant agreed. Without it nothing is deleted and the 409 says what would be.
- `rewind_counter` (string): true also sets the numbering template's next invoice number back to this invoice's number. Only honoured when the invoice holds the latest number; otherwise rewinding would hand that number out twice.

## Returns

- `id` (integer): e.g. `980191001`
- `number` (string): e.g. `A26-1`
- `deleted` (boolean): e.g. `true`
- `next_invoice_number` (string): e.g. `1`

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Example request

```sh
curl -X DELETE "https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/permanent" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

The updated resource.

```json
{
  "id": 980191001,
  "number": "A26-1",
  "deleted": true,
  "next_invoice_number": "1"
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 404

The resource does not exist for this shop, or no action is registered at this path.

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

