Sales rules
PaidPredicate 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, 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.
Sales rules run when Carbon 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), ornone(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'stransaction.quantity. - Operator:
eq,neq,in,notIn,isSet,isNotSet,gt,lt.
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.
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 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".
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 Inventory page.
Unlike storage rules, sales rules always target items — there is no work-center target.
Rule fields
error (block) or warn (acknowledge and continue).{token} interpolation.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 Inventory page.
Sales rules are an Enterprise capability, gated to the Business plan. On other plans the screen shows an upgrade prompt and no rules are evaluated.
Related
The sibling rule family: the same condition builder, applied to inventory transactions instead of sales documents.
The first surface: rules run as quote lines are written and again at finalize and convert.
Rules gate order confirmation and the shipment that fulfills it.
The last checkpoint: an invoice raised with no upstream order is still checked at post.