Skip to content
Copy site link for AI

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.

Both actions announce themselves on the Document events 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.

Where they are available

All open (unposted) sales and purchasing documents.

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
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.