Blue Dragonfly Sales Holds

Sales Holds product page

Blue Dragonfly Sales Holds is a Microsoft Dynamics 365 Business Central extension that automatically places sales documents on hold when a customer exceeds their credit limit or has past due invoices, and releases them through Business Central’s standard approval process.

A document on hold receives one of two hold types:

• Credit Limit Hold, when the customer’s total exposure exceeds their credit limit
• Past Due Hold, when the customer has open invoices past their due date

While a document is on hold, it cannot be released, posted, shipped, or printed until an authorized approver reviews and approves it.

This guide covers three roles: sales and order entry users who work with held documents, approvers who review the requests, and administrators who configure the extension.

Prerequisites

Before using Sales Holds, ensure the following are in place:

#	Requirement	Who is responsible
1	Sales Holds extension installed from AppSource	System administrator
2	Permission sets assigned to users (see Permission Sets)	System administrator
3	Sales Holds Setup configured with hold rules enabled	Administrator
4	The approval workflow created with Create Default Workflow on the setup page and enabled on the Workflows page (see Approval Workflows)	Administrator
5	Approvers added to the workflow user group	Administrator

Until requirements 3 to 5 are complete, hold evaluation will run but users will not be able to send approval requests.

For sales and order entry users

What you will see on sales documents

When you open a Sales Quote, Sales Order, Sales Invoice, or Sales Credit Memo, these fields appear on the General FastTab of the document header:

Field	What it tells you
Hold Status	Whether the document is on hold and why
Approval Status	Whether an approval has been requested and its current state
Released Clean At	When the document was released while the customer was within all limits
Released Clean By	Who released it at that time

All four fields are read-only. Hold Status and Approval Status appear only when your administrator has enabled holds for that document type. If you do not see them on a Sales Quote, for example, quotes are not being evaluated in your company.

Released Clean At and Released Clean By are blank unless clean release tracking is in use. See Clean Release Tracking.

Hold Status values

Value	Meaning	Actions blocked?
No Hold	The customer is within all limits, no action needed	No
Credit Limit Hold	The customer’s total exposure exceeds their credit limit	Yes, release, post, warehouse, and print are blocked
Past Due Hold	The customer has overdue open invoices beyond the tolerance	Yes, release, post, warehouse, and print are blocked
Approved	The hold was reviewed and approved, the document can proceed	No
Bypass Credit Limit	The customer is flagged to bypass credit limit checks (informational)	No
Bypass Past Due	The customer is flagged to bypass past due checks (informational)	No

Approval Status values

Value	Meaning
Not Requested	No approval has been requested for this document
Pending Approval	An approval request has been sent and is waiting for a decision
Approved	The document has been approved and can be processed

When a document is on hold

If Hold Status shows Credit Limit Hold or Past Due Hold, the document is blocked. You will not be able to:

• Release the document. You will see: “This document cannot be released because it is on Sales Hold (Credit Limit Hold). Request approval and complete the approval process first.”
• Post the document, including Ship, Invoice, Post, and Post and Send. You will see: “This document cannot be posted because it is on Sales Hold (Credit Limit Hold). Request approval and complete the approval process first.”
• Create a Warehouse Shipment, Inventory Pick, or Inventory Put-away
• Print the document

The hold type in parentheses reflects the hold on your document, so a past due hold shows “Past Due Hold” in the same message.

A hold can also be applied at the moment you try to post. Sales Holds evaluates the document again immediately before posting, so a document that showed No Hold earlier in the day can be held if the customer’s balance has changed since.

Requesting approval

1. Open the sales document that is on hold.
2. In the action bar, choose Request Approval, then Send Approval Request.
3. A confirmation message appears.
4. The Approval Status field changes to Pending Approval.
5. Wait for the approver to review the request.

Tip

Check the status of your request in the Approval Status field, or search for Approval Entries and filter to your document.

After approval

Once the approver approves your request:

• Hold Status changes to Approved
• Approval Status changes to Approved
• All blocked actions become available, so you can release, post, ship, and print

What happens if you then edit the document depends on how your administrator configured Allow Changes to Approved Documents in Sales Holds Setup:

• On: you can add lines, change quantities, and change dates freely. No new hold is applied and no second approval is needed.
• Off: the document is evaluated again after your change. If the customer still exceeds a limit, a new hold is applied and you must request approval again.

If you are unsure which applies in your company, ask your administrator, or make a change and check the Hold Status field.

If your request is rejected

• Hold Status stays as it was, so the document is still on hold
• Approval Status returns to Not Requested
• The document remains blocked

Discuss the rejection with the approver, make adjustments if needed, and send a new approval request.

On the Sales Holds list page, the Workflow Status column shows Rejected for the document even though Approval Status reads Not Requested. The two columns come from different sources: Workflow Status reports the last approval decision, and Approval Status reports whether an approval is currently in effect.

Canceling an approval request

If you sent a request by mistake, or need to make changes before the approver acts:

1. Open the sales document.
2. Choose Request Approval, then Cancel Approval Request.
3. Approval Status returns to Not Requested.
4. The document remains on hold. Send a new request when you are ready.

Finding all held documents

To see every sales document currently on hold:

1. Search for Sales Holds using Tell Me.
2. The Sales Holds list page opens, showing all documents with a Credit Limit Hold or Past Due Hold.

The list shows these columns:

Column	Contents
Customer No.	The bill-to customer on the document
Document Type	Quote, Order, Invoice, or Credit Memo
Document No.	The document number
Document Date	The date of the document
Amount	The total amount including VAT
Sales Hold Type	Credit Limit Hold or Past Due Hold
Approval Status	Not Requested, Pending Approval, or Approved
Days On Hold	How long the document has been held
Workflow Status	The last approval decision: Pending Approval, Approved, or Rejected
Pending Approval By	The approver responsible for the document

From the list you can also choose View Customer to open the customer card, or View Document to open the held document itself.

Note

If your Role Center includes the Sales Holds cue, the Documents On Hold tile shows the current count. Choose the tile to open the Sales Holds list.

For approvers

Receiving approval requests

When a user sends an approval request for a held document, you receive a notification according to your notification settings. You can also find pending requests by searching for Requests to Approve and filtering to the entries assigned to you.

Reviewing a request

From the approval request you can:

• Open the document to review its details
• Check Hold Status to see whether it is a Credit Limit Hold or a Past Due Hold
• Open the Customer Card to review the credit limit, exposure, and past due invoices

Taking action

Action	What it does
Approve	Clears the hold, sets the document to Approved, and unblocks all processing actions
Reject	Keeps the document on hold. The requestor is notified and can resubmit
Delegate	Forwards the request to the next approver in the workflow user group

Approving several documents at once

If you have many held documents to clear:

1. Search for Sales Holds using Tell Me.
2. Select the documents you want to approve.
3. Choose Approve Selected.

To approve a single document from the list, select it and choose Approve.

After you approve

• The user can immediately release, post, ship, or print the document
• Your decision is recorded in the Approval Entries for audit purposes
• Whether later edits require a second approval depends on the Allow Changes to Approved Documents setting. See After Approval

For administrators

Environment requirements and installation

System requirements

Requirement	Details
Business Central version	Microsoft Dynamics 365 Business Central 2025 Release Wave 2 (version 27.0) or later
Deployment type	Cloud (SaaS) only. On-premises and private cloud deployments are not supported
Supported countries and regions	United States only
Required dependency	The Blue Dragonfly Registration app, installed automatically with Sales Holds

Installing the extension

Sales Holds is installed directly from Microsoft AppSource. End-customer administrators install and manage the app.

1. Go to Microsoft AppSource and search for Sales Holds.
2. Choose Get it now on the Blue Dragonfly Sales Holds listing.
3. Sign in with your Microsoft 365 administrator account when prompted.
4. Select the Business Central environment where you want to install the app.
5. Accept the permissions and confirm the installation.
6. Business Central notifies you when the installation is complete.

Note

Sales Holds requires the Blue Dragonfly Registration app. It is a Microsoft Marketplace library app and is installed automatically along with Sales Holds, so there is nothing separate for you to install.

Registering the extension

The registration wizard starts automatically the next time a Role Center opens after installation. When registration succeeds, the Sales Holds Setup page opens so you can begin configuring the extension.

If registration does not complete, you see a message asking you to contact support@bluedragonflyllc.com.

To re-synchronize your license later, open Sales Holds Setup and choose Sync License.

Post-installation checklist

#	Step	Where
1	Configure hold types and tolerances	Tell Me: Sales Holds Setup
2	Create the approval workflow	Sales Holds Setup, Create Default Workflow
3	Enable the workflow	Tell Me: Workflows, then enable BD-SHSALESHOLDS
4	Add approvers to the workflow user group	Tell Me: Workflow User Groups, then SALESHOLDAPPR
5	Assign permission sets to users	Tell Me: Users
6	If using customer-level mode, enable the hold toggles on each Customer Card	Customer Card, Sales Hold Options
7	Review orders that were released before installation	Sales Holds Setup, Previously Released Orders
8	Create a test Sales Order for a customer over their credit limit and confirm a hold is applied	Sales Order page

Important

Step 7 is easy to overlook. Sales orders that were released before Sales Holds was installed are not automatically exempt. They are evaluated and held like any other order the next time they change. See Previously Released Orders.

Uninstalling

To uninstall Sales Holds, open Extension Management, locate Blue Dragonfly - Sales Holds, and choose Uninstall.

Sales Holds Setup

Search for Sales Holds Setup using Tell Me. The setup record is created automatically the first time you open the page.

Sales Documents

Choose which document types Sales Holds evaluates.

Setting	Description
Sales Quote	Evaluate holds on Sales Quotes
Sales Order	Evaluate holds on Sales Orders
Sales Invoice	Evaluate holds on Sales Invoices
Sales Credit Memo	Evaluate holds on Sales Credit Memos

Turning a document type off also hides the Hold Status and Approval Status fields on that document’s page.

Customer Sales Holds Configuration

Setting	Description
Enable Customer Sales Holds Configuration	On selects customer-level mode, where each customer has individual hold settings and tolerances. Off selects company-level mode, where one set of tolerances applies to everyone and individual customers can be flagged to bypass holds

Choose customer-level mode when your credit terms vary by customer and you want tolerances set per account. Choose company-level mode when one policy applies across the business and you only need exceptions for a few customers.

Tolerance

These fields appear only in company-level mode, when Enable Customer Sales Holds Configuration is off.

Setting	Description
Credit Limit Tolerance %	The percentage above the credit limit allowed before a hold is applied. For example, 5% on a $10,000 limit allows up to $10,500
Past Due Days Tolerance	The number of days past due allowed before a hold is applied. For example, 7 means invoices up to 7 days overdue do not trigger a hold
Past Due Amount Tolerance	The total past due amount (LCY) allowed before a hold is applied

Sales Hold Configuration

Setting	Description
Enforce Credit Limit Sales Hold	When On, documents are placed on hold when customers exceed their credit limit
Enforce Past Due Sales Hold	When On, documents are placed on hold when customers have past due invoices

These are the master switches. In customer-level mode, a hold type must be enabled here and on the customer before it applies to that customer’s documents.

Allow Changes to Approved Documents

Setting	Description
Allow Changes to Approved Documents	When On, an approved document can be edited without being evaluated again, so no new hold is applied and no second approval is needed. When Off, the document is evaluated again after each change, and a new hold and approval are required if the customer still exceeds a limit

Turn this on when approval represents a business decision about the order as a whole, and users routinely adjust documents afterward. Turn it off when the approval should apply only to the document as it stood when it was approved.

Clean Release Tracking

Setting	Description
Enable Clean Release Tracking	When On, a document released while the customer is within all limits is marked, and it is not evaluated for holds again

See Clean Release Tracking for the full description.

Diagnostic Logging

Setting	Description
Enable Diagnostic Logging	When On, Sales Holds records detailed event data for troubleshooting. Off by default
Diagnostic Log Retention Days	How many days entries are kept. Set to 0 to disable automatic cleanup. The default is 30. This field appears only when logging is on

See Diagnostic Logging.

Customer-level configuration

When Enable Customer Sales Holds Configuration is on, a Sales Hold Options group appears on each Customer Card:

Field	Description
Credit Limit Hold	Evaluate credit limit holds for this customer
Credit Limit Tolerance %	This customer’s credit limit tolerance
Past Due Hold	Evaluate past due holds for this customer
Past Due Days Tolerance	This customer’s past due days tolerance
Past Due Amount Tolerance	This customer’s past due amount tolerance (LCY)

The two toggles are independent. Turning on Credit Limit Hold alone gives that customer credit limit holds but not past due holds.

Important

New customers have both toggles off by default. In customer-level mode, a customer with both toggles off is never held, no matter what the company-level settings say. An administrator must enable them on each Customer Card.

Note

Business Central has its own credit limit warning that may appear when you create a sales document. That warning is separate from Sales Holds. It does not block the document and does not mean a hold was applied. If you see the Business Central warning but Hold Status shows No Hold, check that the customer’s Credit Limit Hold toggle is on.

Company-level bypass flags

When Enable Customer Sales Holds Configuration is off, a Bypass Sales Hold Options group appears on each Customer Card:

Field	Description
Bypass Credit Limit Hold	When On, this customer is exempt from credit limit holds. Their documents show Bypass Credit Limit instead of being blocked
Bypass Past Due Hold	When On, this customer is exempt from past due holds. Their documents show Bypass Past Due instead of being blocked

Bypass statuses are informational. They never block processing.

Credit limit field security

The Credit Limit (LCY) field on the Customer Card is read-only unless the user is assigned the Sales Holds Credit Limit permission set (SHL HOLDCREDIT BLD). This prevents a user from clearing a hold by raising the customer’s credit limit.

Permission sets

Permission set	Who needs it	What it grants
Sales Holds Setup (SHL HOLDSETUP BLD)	Administrators	Full access to Sales Holds Setup, Previously Released Orders, and the Sales Holds Diagnostic Log
Sales Holds Manage (SHL HOLDMANAGE BLD)	Sales managers, credit staff	The Sales Holds list page, the Role Center cue, and the diagnostic log, plus the ability to edit customer hold fields
Sales Holds Credit Limit (SHL HOLDCREDIT BLD)	Credit managers	The ability to edit Credit Limit (LCY) on the Customer Card

Approval workflows

Sales Holds uses one approval workflow for both hold types. The extension creates it for you.

1. Open Sales Holds Setup.
2. Choose Create Default Workflow.
3. A message confirms that the workflow was created and lists the next steps.

The action creates:

• Workflow BD-SHSALESHOLDS, described as “BD Sales Hold - Approval”, in the workflow category BD Sales Holds
• Workflow user group SALESHOLDAPPR, described as “Sales Holds Approvers”

Important

The workflow is created disabled, and it has no approvers. Complete both of these before going live:

1. Search for Workflows, locate BD-SHSALESHOLDS, and select Enabled.
2. Search for Workflow User Groups, open SALESHOLDAPPR, and add the users authorized to approve Sales Hold requests.

Note

If you choose Create Default Workflow again after the workflow exists, you see “The Sales Holds workflow (BD-SHSALESHOLDS) already exists. No changes were made.” Your existing workflow is left untouched.

Clean release tracking

Clean release tracking prevents a document that was released legitimately from being pulled back into a hold later because the customer’s position deteriorated afterward.

When Enable Clean Release Tracking is on and a user releases a document while no hold is active, Sales Holds records Released Clean At and Released Clean By on that document. From then on, the document is not evaluated for holds again.

Details worth knowing before you turn it on:

• The mark is written once and never overwritten, so releasing a document a second time does not change who or when.
• Documents released through the approval workflow are not marked. They carry Hold Status = Approved instead.
• Documents released while a bypass status is in effect are not marked. This keeps the customer’s bypass toggle as the control for those orders, so clearing the toggle brings them back under evaluation.
• Turning the setting off makes Sales Holds ignore existing marks and resume normal evaluation. The recorded values are kept, so turning it back on restores the exemption for previously marked documents.

Use this when your users release orders as part of a normal daily process and you do not want a later balance change to block a shipment that was already approved to go out.

Previously released orders

Sales orders released before Sales Holds was installed have no hold history. They are not treated as exempt: the next time such an order changes or is posted, it is evaluated and can be held like any other order.

This is deliberate. If released orders were exempt automatically, a user could disable Sales Holds, release a batch of orders, and re-enable it to avoid the credit controls.

To clear these orders:

1. Open Sales Holds Setup and choose Previously Released Orders. The page lists released sales orders that have no hold status and no approval status.
2. Review the orders. Use Open Order to inspect one in detail.
3. Select the orders you want to clear.
4. Choose Admin Approve. A message confirms how many orders were approved.

Approved orders receive Hold Status = Approved and Approval Status = Approved, and they proceed without going through the approval workflow.

Important

Do this during implementation, before users begin working with existing orders. Otherwise the first change to an old order can block a shipment unexpectedly.

Hold priority rule

When a customer triggers both a Credit Limit Hold and a Past Due Hold at the same time, only the Credit Limit Hold is applied. Credit limit has priority, and evaluation stops as soon as that hold is set.

Once the Credit Limit Hold is approved and Allow Changes to Approved Documents is off, past due is evaluated on the next document change, and a Past Due Hold can then be applied.

How hold evaluation works

Sales Holds evaluates a document automatically when it changes. Evaluation runs when:

• The Sell-to Customer No. or Bill-to Customer No. changes
• A sales line is added, modified, or deleted
• The Posting Date changes
• A user posts the document, immediately before posting begins

Evaluation does not run during release, or while a posting is already in progress.

Credit limit evaluation

Total exposure is the sum of:

Balance (LCY)
+ Outstanding Orders (LCY)
+ Shipped Not Invoiced (LCY)
+ Outstanding Invoices (LCY)
+ Open service orders and service invoices

For a Sales Quote, the quote’s own amount is added to that total, because quotes are not included in the standard Business Central exposure figures.

The allowed limit is the customer’s Credit Limit (LCY) increased by the tolerance percentage, rounded up to the cent. A Credit Limit Hold is applied when total exposure is greater than the allowed limit.

Note

If a customer’s Credit Limit (LCY) is zero, the tolerance percentage has no effect, and any exposure above zero results in a hold while Enforce Credit Limit Sales Hold is on. Set a credit limit for every customer you intend to trade with.

Past due evaluation

Sales Holds looks at open posted sales invoices in the customer ledger with a due date on or before the day before the work date. It totals the remaining amounts and measures days past due from the oldest of those invoices.

A hold is not applied when:

• There is no past due amount
• A Past Due Days Tolerance is set and the oldest invoice is within it
• A Past Due Amount Tolerance is set and the total is within it

Diagnostic logging

Sales Holds can record detailed information about every hold decision to the Sales Holds Diagnostic Log. Logging is off by default and is intended for troubleshooting.

To use it, turn on Enable Diagnostic Logging in Sales Holds Setup, set Diagnostic Log Retention Days, reproduce the problem, then choose View Diagnostic Log to review the entries or provide them to support. Clear Diagnostic Log removes all entries.

Turn logging off again once troubleshooting is complete.

Troubleshooting

Holds are not being applied

Documents open normally for customers who are over their credit limit or have past due invoices, but Hold Status shows No Hold.

Check	What to do
Hold evaluation is enabled	In Sales Holds Setup, confirm Enforce Credit Limit Sales Hold or Enforce Past Due Sales Hold is on
The document type is enabled	In Sales Holds Setup, confirm the relevant document type is enabled under Sales Documents. If the Hold Status field is missing from the page entirely, that document type is off
Customer-level toggles	In customer-level mode, open the Customer Card and confirm the relevant toggle is on under Sales Hold Options
Bypass flags	In company-level mode, open the Customer Card and confirm neither flag is on under Bypass Sales Hold Options
The customer has a credit limit	A customer with no Credit Limit (LCY) and exposure of zero is never over the limit
Evaluation has not run yet	Evaluation runs when the document changes. Edit a sales line and check the field again
The document was released clean	If Released Clean At has a value, the document is exempt from re-evaluation. See Clean Release Tracking
The document is approved	An approved document is not re-evaluated while Allow Changes to Approved Documents is on

The Request Approval action is missing or unavailable

Check	What to do
The workflow was never created	In Sales Holds Setup, choose Create Default Workflow
The workflow is disabled	Search for Workflows, locate BD-SHSALESHOLDS, and select Enabled. The workflow is created disabled
No approvers assigned	Search for Workflow User Groups and add at least one user to SALESHOLDAPPR
A request is already pending	If Approval Status shows Pending Approval, wait for a decision or cancel the existing request
User permissions	Confirm the user has a role that allows sending approval requests

A user cannot open Sales Holds Setup

Assign the Sales Holds Setup (SHL HOLDSETUP BLD) permission set.

A user cannot edit customer hold fields or bypass flags

Assign the Sales Holds Manage (SHL HOLDMANAGE BLD) permission set.

A user cannot edit the Credit Limit field

This is by design. Assign the Sales Holds Credit Limit (SHL HOLDCREDIT BLD) permission set to the users who should be able to change credit limits.

A document is still blocked after approval

Check	What to do
Hold Status and Approval Status	Both should show Approved. If Hold Status still shows a hold type, the workflow did not complete
Approval entry state	Search for Approval Entries, filter to the document, and check the Status column. An Open entry means the approval chain is not finished
Multiple approvers	The workflow user group may require more than one approver. All must approve before the hold clears

An old order was held unexpectedly

The order was released before Sales Holds was installed and was evaluated the first time it changed. Open Sales Holds Setup, choose Previously Released Orders, and use Admin Approve on the affected orders. See Previously Released Orders.

A new document for the same customer is held again

Each sales document is evaluated on its own. Approving one document does not change the customer’s credit or past due position, so the next document is evaluated fresh. Resolve the underlying cause with your credit team, by raising the credit limit or applying a payment.

Quick reference

For sales users

Situation	What to do
Document shows Credit Limit Hold or Past Due Hold	Choose Request Approval, then Send Approval Request
Waiting for approval	Check Approval Status for Pending Approval
Document approved	Proceed normally: release, post, ship, print
Approval rejected	Contact the approver, adjust the document, resubmit
Need to cancel a pending request	Choose Request Approval, then Cancel Approval Request
Want to see all held documents	Search for Sales Holds

For approvers

Situation	What to do
Received an approval request	Open Requests to Approve and review the document
Ready to approve	Choose Approve. The document is unblocked immediately
Need to decline	Choose Reject. The requestor is notified
Want to forward to someone else	Choose Delegate
Several documents to clear at once	Open Sales Holds, select them, and choose Approve Selected

For administrators

Task	Where to go
Enable or disable hold types	Sales Holds Setup, Sales Hold Configuration
Choose which document types are evaluated	Sales Holds Setup, Sales Documents
Set company-wide tolerances	Sales Holds Setup, Tolerance
Set customer-specific tolerances	Customer Card, Sales Hold Options
Flag a customer to bypass holds	Customer Card, Bypass Sales Hold Options
Control who can edit credit limits	Assign the Sales Holds Credit Limit permission set
Create the approval workflow	Sales Holds Setup, Create Default Workflow
Enable the workflow	Tell Me: Workflows, then BD-SHSALESHOLDS
Assign workflow approvers	Tell Me: Workflow User Groups, then SALESHOLDAPPR
Clear orders released before installation	Sales Holds Setup, Previously Released Orders
Troubleshoot a hold decision	Sales Holds Setup, Enable Diagnostic Logging, then View Diagnostic Log