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

# Sales rules

> Predicate guards on sales documents: block a restricted item with an error, or warn and let the user acknowledge and continue.

A **sales rule** validates an item on a sales document. If its condition fails, the rule either **blocks** the write or **warns** and allows the user to acknowledge the warning. Rules apply to **quote lines**, **sales order lines**, and **sales invoice lines**.

For example, to restrict an export-controlled part, scope the rule to its item group, enable all three document types, and require `customer.location.countryCode` `notIn` the restricted-country list. Set severity to **error** and the message to `` `{item.id}` cannot ship to this destination``. A matching line is then rejected with that message.

NOTE

Sales rules run when Alforse finalizes a quote, converts it to an order, confirms an order, posts a shipment, or posts an invoice. This catches lines created through conversions, imports, and the API. A blocked document writes nothing.

## What a rule checks

Each rule holds a small **condition tree**, a match kind over one or more field/operator/value rows:

* **Match kind**: `all` (every condition must hold), `any` (at least one), or `none` (none may hold).
* **Field**: chosen from a fixed registry: item facts (`item.type`, `item.replenishmentSystem`,
  `item.itemTrackingType`, item custom fields), customer facts (`customer.customerTypeId`,
  `customer.customerStatusId`, customer custom fields), the document's ship-to country
  (`customer.location.countryCode`), and the line's `transaction.quantity`.
* **Operator**: such as `eq`, `neq`, `in`, `notIn`, `isSet`, `isNotSet`, `gt` and `lt`; the builder offers the operators each field allows.

The **message** shown on a violation supports tokens like `` `{item.id}` `` and
`` `{customer.location.countryCode}` ``, so the text can name the offending line. The rule "passes" when its
conditions hold; a violation fires when they don't.

NOTE

Aside from the `isSet` / `isNotSet` checks, a condition pointing at a field that has **no value** fails as a
*"…is required"* violation. A country rule on an order with no ship-to location fails closed as *"Customer
location is required"* rather than waving the line through. The same applies to a standalone invoice line
(no source order) on an invoice with no **"Ship To"**: the bill-to address is never substituted for it.

## Where rules fire

A rule lists the **surfaces** (sales-document line types) it applies to: `quoteLine`, `salesOrderLine`, and
`salesInvoiceLine`. Two kinds of checkpoint run them:

* **Line checks** as a line is created or edited on a quote, sales order, or sales invoice.
* **Document gates** at each commitment point: finalizing a quote, converting a quote to an order (or an RFQ to a quote),
  confirming a sales order, posting its shipment, and posting a sales invoice. The gate re-reads **every**
  line on the document, so it also catches staleness — a rule authored after the line was written, or a
  ship-to that changed.

The ship-to that country rules evaluate is where the goods actually go: a drop shipment
overrides the order header's address, an invoice line converted from a sales order resolves its
destination through that order, and a standalone invoice line uses the invoice's own **"Ship To"**.

NOTE

On the customer-facing digital quote page, `error` violations refuse acceptance with a neutral message and
your internal rule text never reaches the customer. `warn` violations are logged for the seller and the
acceptance proceeds — there is no employee present to acknowledge them.

## Block or warn

| Severity | Behavior |
| - | - |
| `error` | Blocks the line or document until the condition is satisfied. Cannot be acknowledged past. |
| `warn` | Surfaces the message but lets the user **acknowledge and continue**. |

Both outcomes leave a trail: a blocked write and an acknowledged warning are each recorded as evidence
(rule, document, line, item, who, when), and the people in the **sales rule notification group**
(Settings → Sales) are notified by email.

## Scope and assignment

A rule reaches the lines it applies to in one of two ways:

* **By filter**: scope to **item types** and/or **item groups**, combined with OR or AND. An empty filter
  matches **every** item.
* **By assignment**: pin a rule to a specific item from the **Sales rules** card on that item's Sales
  tab.

Unlike [storage rules](/docs/reference/storage-rules.md), sales rules always target items — there is no
work-center target.

## Rule fields

FieldType

<details>
  <summary>**Name**</summary>

  A unique name for the rule.
</details>

<details>
  <summary>**Severity**</summary>

  `error` (block) or `warn` (acknowledge and continue).
</details>

<details>
  <summary>**Conditions**</summary>

  The match kind plus the field / operator / value rows.
</details>

<details>
  <summary>**Message**</summary>

  Shown on a violation; supports `{token}` interpolation.
</details>

<details>
  <summary>**Surfaces**</summary>

  Which sales-document lines the rule fires on.
</details>

<details>
  <summary>**Item filters**</summary>

  Item types and/or groups to scope a rule (empty = all items).
</details>

<details>
  <summary>**Active**</summary>

  Whether the rule is currently evaluated.
</details>

## Where to manage them

Sales rules live in the **Sales** area, under **Sales Rules**. Create, edit, and toggle them there. To attach
an existing rule to a single item, use the **Sales rules** card on the item's Sales tab.

HEADS UP

Sales rules are gated to the **Business** plan. On other plans the screen shows
an upgrade prompt and no rules are evaluated.

## Related

**Storage rules**

The sibling rule family: the same condition builder, applied to inventory transactions instead of sales
documents.

[Open](/docs/reference/storage-rules.md)

**Quotes**

The first surface: rules run as quote lines are written and again at finalize and convert.

[Open](/docs/reference/quotes.md)

**Sales orders**

Rules gate order confirmation and the shipment that fulfills it.

[Open](/docs/reference/sales-orders.md)

**Invoices**

The last checkpoint: an invoice raised with no upstream order is still checked at post.

[Open](/docs/reference/invoices.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.