# Archiving & cancelling documents

Business Central has no "revision" or "cancelled" state for an open document. It only has **Document Archive**, which snapshots a document into a versioned archive. This extension adds a cancel (soft delete) on top of the standard Archive and exposes both over the API. Every writable sales and purchase document exposes two bound actions built on it: `archive` (snapshot and keep the document open) and `cancel` (snapshot, then delete the document; a soft delete). Both are queryable through the archived-document feeds below.

## The `archive` action: snapshot a revision, keep editing

Invoke it on any open document with `POST /<entitySet>(<id>)/Microsoft.NAV.archive`. It freezes the current state as a new archive version and leaves the live document open, so calling it before each change gives you a revision history:

```
POST /salesQuotes(<id>)/Microsoft.NAV.archive
```

There is no separate "revision number". Business Central's standard archive `versionNo` *is* the revision number (1, 2, 3…), and it increments each time you archive the same document. This is the API twin of the **Archive Document** action on the Business Central document page.

## The `cancel` action: soft delete

Invoke it with `POST /<entitySet>(<id>)/Microsoft.NAV.cancel`. It archives the document the same way, then deletes the open document so it no longer appears in the writable endpoint. Use it instead of a hard `DELETE` when you want the record retained.

```
POST /salesOrders(<id>)/Microsoft.NAV.cancel
```

Cancelling releases the document's `integrationId`. Duplicate rejection ignores archived documents, so SmartConnect can correct a mistake by cancelling the document and sending it again under the same key. See [The Integration Id](https://eonesolutions.github.io/eone-bc-integration/integration-id.md).

Both actions announce themselves on the [Document events](https://eonesolutions.github.io/eone-bc-integration/core-documentEvents.md) feed: `archive` writes a `salesDocumentArchived` or `purchaseDocumentArchived` event, `cancel` a `...Cancelled` one that still carries the document's number and `integrationId`. A subscriber tells a cancel from a plain delete by the event's name, without cross-checking the archive.

```mermaid
flowchart TD
    A[Open document] -->|archive| B[Snapshot as the next version, document stays open]
    B --> A
    A -->|cancel| C[Snapshot, then delete the open document]
    C -->|delete checks pass| D[Soft deleted: integrationId released, cancelled in the archived feed]
    C -->|delete checks fail| E[One transaction, so the snapshot rolls back too]
    E --> A
```

## Where they are available

All open (unposted) sales and purchasing documents.

> **Caution:** `cancel` still runs Business Central's delete checks. A partially posted document (e.g. an order with a posted shipment not yet invoiced) cannot be deleted; the action returns that error and leaves the document open. Because the whole action is one transaction, the snapshot is rolled back too. Cancel is for documents that have not started posting.

## Enable it per document type: the UI actions follow

Archive and cancel are **off until an administrator turns them on**, per document type. The setting is the **Document Archive & Cancel** section of the **Document Processing** tab, on the **eOne Integration Setup** page. Tick a document type there to allow both the API actions *and* the matching UI actions for that type; untick it and both are unavailable.

This is not an API-only feature. When a document type is enabled, Business Central surfaces **Archive** and **Cancel** actions on that type's **standard card and list pages**, so a user can archive or soft-delete the same document by hand. The API actions and the on-page actions run the identical logic. Disabling a type hides those page actions again.

## Reading archived documents

Two read-only, document-type-agnostic feeds return only the documents archived through these two actions (not documents archived by other means):

- `archivedSalesDocumentsQuery`: archived sales documents across all types.
- `archivedPurchaseDocumentsQuery`: archived purchase documents across all types.

```
GET /archivedSalesDocumentsQuery?$filter=integrationId eq 'SHOPIFY-1001'
GET /archivedSalesDocumentsQuery?$filter=cancelled eq true
```

> **Note:** A document can be archived many times, so the feed can return several rows per document, one per `versionNo`. The highest version is the most recent snapshot.

## Related

- [Posted documents](https://eonesolutions.github.io/eone-bc-integration/posted-documents.md): the read-only feeds for documents that reached the ledger.
- [Sales Orders](https://eonesolutions.github.io/eone-bc-integration/core-salesOrders.md): where the `archive` and `cancel` actions are invoked.
- [Archive settings](https://eonesolutions.github.io/eone-bc-integration/core-documentArchiveSettings.md): the configuration that controls what Business Central retains.