> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deleting packages

> How to delete packages one at a time or in bulk, and how deleting differs from revoking.

NSEV never deletes packages on its own. Once a package reaches a final state it is stored
indefinitely until you remove it explicitly. This page covers how to delete a single package, how
to delete many at once, and how deleting differs from revoking a package.

## Prerequisites

* A valid access token or Basic Auth credentials - see [Platform Access](/docs/nsev/getting-started/basic-setup)
* Your tenant's base URL set as `BASE_URL`
* The `Id` of each package you want to delete

All examples use `Bearer` authentication. Replace the token and variable values with your own.

***

## When a package can be deleted

A package can only be deleted when its status is `draft` or one of the final states `finished`,
`archived`, `rejected`, or `revoked`. Deleting a package in any other state - for example a
`pending` package that is still out for signature - returns `409 Conflict` with the error code
`Package.InvalidStatus`.

If you need to remove a package that is still `pending`, revoke it first (see
[Deleting versus revoking](#deleting-versus-revoking) below), then delete the revoked package.

***

## Delete a single package

Send a `DELETE` to `/packages/{packageId}`. On success the call returns `204 No Content`.

```bash theme={null}
curl -X DELETE "$BASE_URL/packages/$PACKAGE_ID" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0"
```

| Status           | Meaning                                                                 |
| ---------------- | ----------------------------------------------------------------------- |
| `204 No Content` | The package was deleted.                                                |
| `404 Not Found`  | No package with that `Id` exists (`Package.NotFound`).                  |
| `409 Conflict`   | The package's status does not allow deletion (`Package.InvalidStatus`). |

## Delete packages in bulk

To remove many packages at once, `POST` their IDs to `/packages/delete/bulk`. The same status rule
applies to every package in the list - only `draft`, `finished`, `archived`, `rejected`, or
`revoked` packages can be deleted.

```bash theme={null}
curl -X POST "$BASE_URL/packages/delete/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "PackageIds": [
      "b459d74c-1f90-4d63-9f4a-6de9cead8c5e",
      "1fdbad81-75e5-4cc8-b113-39255fa119d7"
    ]
  }'
```

Bulk actions are processed asynchronously, so the call does not report per-package success
immediately. Instead it returns a **bulk action session identifier** - a GUID - that you use to
follow progress.

```json theme={null}
"b459d74c-1f90-4d63-9f4a-6de9cead8c5e"
```

### Polling the bulk action session

Pass the returned identifier to `GET /packages/bulkactionsession/{bulkActionSessionId}` to check
whether processing has finished and how many packages succeeded or failed. Add
`?includeDetails=true` to get a per-package breakdown.

```bash theme={null}
curl "$BASE_URL/packages/bulkactionsession/$SESSION_ID?includeDetails=true" \
  -H "Authorization: Bearer {access_token}" \
  -H "User-Agent: MyApp/1.0"
```

```json theme={null}
{
  "SessionId": "b459d74c-1f90-4d63-9f4a-6de9cead8c5e",
  "Action": "DeletePackage",
  "Status": "Finished",
  "Total": 2,
  "Succeeded": 1,
  "Failed": 1,
  "FinishedTime": "2025-02-27T09:09:46Z",
  "Details": {
    "Succeeded": [
      { "PackageId": "1fdbad81-75e5-4cc8-b113-39255fa119d7", "ExecutedTime": "2025-02-27T09:09:40Z" }
    ],
    "Failed": [
      {
        "PackageId": "9b2e6f3a-1c44-4e2b-8a77-2d6f0a1b3c4d",
        "ExecutedTime": "2025-02-27T09:09:42Z",
        "ErrorCode": "Package.InvalidStatus",
        "ErrorMessage": "The package is not in a final state."
      }
    ]
  }
}
```

`Status` moves from `Pending` through `Finishing` to `Finished`; `FinishedTime` is only populated
once the session reaches `Finished`. Poll until then. The `Action` field identifies the kind of
bulk action the session ran - for a bulk delete it is `DeletePackage`.

<Note>
  Because each package in a bulk delete is processed independently, a session can finish with a mix
  of successes and failures - for example when some packages are in a deletable state and others are
  not. Always check `Failed` and the per-package `Details` rather than assuming the whole batch
  succeeded.
</Note>

***

## Audit trails

The audit trail - the human-readable and machine-readable record of a package's events - is
retrieved while the package still exists, through `GET /packages/{packageId}/audittrail`. Once a
package is deleted it can still be fetched but will not contain stakeholders information, so if
you need a full copy of the audit trail for your records, retrieve it **before** deleting the package.
For a final package you can also request the audit-trail PDFs of many packages at once with
`POST /packages/audittrails/download/bulk`, which returns a bulk action session you poll and
then download as a `.zip`.

***

## Deleting versus revoking

Deleting and revoking are different operations with different effects:

* **Revoking** changes a package's *status* to `revoked`. The package still exists; it has simply
  been withdrawn so stakeholders can no longer act on it. Revoking is a `pending` → `revoked`
  status transition, done with `PUT /packages/{packageId}/status` (or, for many packages,
  `POST /packages/status/bulk`).
* **Deleting** removes the package *record* from the database entirely. It is only allowed once the
  package is in `draft` or a final state - including `revoked`.

So to get rid of a package that is still out for signature, you revoke it first and then delete it.
Revoking is the way to stop an in-flight package; deleting is the way to remove a finished or
withdrawn one.

<Tip>
  When revoking in bulk you can set `SuppressNotifications` to `true` so stakeholders are not emailed
  about the revocation. See [Callbacks and redirects](/docs/nsev/build/guides/callbacks)
  for how NSEV's notifications work.
</Tip>

***

## Next steps

* Create and activate packages in [Send a document for signing](/docs/nsev/build/tutorials/send-for-signing)
* Understand package statuses and the object model in [The package model](/docs/nsev/build/concepts/package-model)
* Review [Best Practices](/docs/nsev/build/guides/good-practices) for error handling, pagination, and security