SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Pricing & Discounts

Versioned pricing rules, exact arithmetic, rule binding, stage evidence, agreed prices, tax extraction, and document rollup.

Overview

Signals prices rental lines through a versioned pipeline: rate resolution, rate-band tiers, quantity and duration, bundles, discounts, agreed prices, tax and the document rollup. Rental totals recalculate when lines, dates, discount groups, bundles, surcharges, or agreed prices change. The stage order, exact arithmetic, rule revisions, previews and accepted pricing manifests are described in Pricing engine internals.

Admin configuration lives under Admin → Money & Pricing (requires pricing management permissions).

Rate bands

Rate bands assign tiered pricing (e.g. retail vs trade) to catalogue items and rentals. Rate bands integrate with the rate engine so line calculations pick up the active band tier.

Configure bands at /admin/settings/pricing/rate-bands. See Rate Bands API.

Discount rules

Discount groups group related rules. Discount rules evaluate JSONB criteria via CriteriaMatcher and can auto-apply when a rental matches.

Discount rule changes are event-sourced on Verbs streams. Apply a discount group manually with POST /api/v1/rentals/{id}/apply_discount_group. In the UI, assignment flows through the account's discount group and auto-apply rules.

Rules use a strict versioned criteria schema. Unknown keys and malformed nested values are rejected instead of being ignored. When more than one discount applies, the highest percentage wins. The Maximum line discount percent setting caps group, automatic, extension-provided, and manual line discounts. An authorised agreed price is a separate commercial override and is not silently folded into that cap.

See Discount Groups API and Discount Rules API.

Surcharges

Surcharge groups bundle optional surcharges (delivery, weekend hire, etc.). Operators toggle groups on a rental; individual line surcharges can be overridden.

Each surcharge carries its own item tax code; surcharge line snapshots survive source deletion so historical invoices stay accurate.

Fixed surcharges are authored in one currency and apply per exact decimal quantity. A fixed surcharge in another currency is ineligible; Signals does not convert it. Zero or negative quantity produces no surcharge. Optional lines retain their line calculation but remain excluded from the rental headline, and structural/non-priceable lines are never surcharged.

Toggle a group: POST /api/v1/rentals/{id}/toggle_surcharge_group. Override a line surcharge: POST /api/v1/rentals/{id}/lines/{line}/override_surcharge.

See Surcharges API and Surcharge Groups API.

Volume and bundle pricing

Bundle rules implement quantity-break and bundle pricing — for example "hire 5+, get 10% off" or fixed bundle totals. Bundles run before line discounts and surcharges.

A bundle declares revenue-account or whole-document scope, sequential or exclusive-highest-saving stacking, a stable tie-break, and whether it may increase the price. Structured requirements use exact minimum and maximum quantities, required occurrences, optional constituents, and explicit excess-quantity participation. Fixed bundles are currency-bound and use deterministic largest-remainder allocation.

Configure at /admin/settings/pricing/bundle-rules.

Agreed price

Agreed price sets a manual headline total on a rental, bypassing calculated line totals. Two modes:

Mode Behaviour
Flat headline Sets a fixed rental total
Proportional Distributes the headline across lines proportionally

Agreed price is mutually exclusive with price lock — you cannot lock rates and override the total simultaneously. Use Recalculate to refresh lines from the pipeline, or Clear agreed price to remove the override.

API: POST /api/v1/rentals/{id}/agreed_price and DELETE /api/v1/rentals/{id}/agreed_price.

Accepted quotes, recalculation and rebase

An accepted quote version cannot be edited commercially in place. Create a new quote version, edit the draft, then accept it. Direct line, cost, deal, date, currency, tax, or rollup changes against accepted terms fail closed. Fulfilment changes that do not affect price continue normally. Accepted order amendments will use the explicit Rentals amendment command; until that command is available, direct commercial order edits are rejected.

Operation Permission Behaviour
Recalculate rentals.edit Restores the stored accepted projection. Reset switches are rejected.
Preview latest rentals.preview_pricing_terms Runs current definitions against in-memory clones and returns hashes and before/after changes without writes.
Rebase latest rentals.rebase_pricing_terms Publishes a reviewed manifest revision after version, preview, generation, reason, and idempotency checks.

The preview and rebase routes, manifest evidence and refusal codes are in Pricing engine internals → Accepted pricing manifests. Operator verification and repair commands are in Finance operations.

Checkout interaction

When a rental checks out to an invoice, the active pricing snapshot (lines, surcharges, agreed price, tax) is frozen onto the invoice. Post-checkout rental recalculation does not alter issued documents.

Using it in the app

Admin pricing configuration lives under Admin → Money & Pricing (admin sidebar group tax). Links require pricing.view; create, edit, and delete buttons require pricing.manage. Rate specifications sit in the same group but use rates.view.

Admin screen Route
Discount Groups /admin/settings/pricing/discount-groups
Discount group + rules form /admin/settings/pricing/discount-groups/create or …/{id}/edit
Rate Bands /admin/settings/pricing/rate-bands
Rate band + tiers form /admin/settings/pricing/rate-bands/create or …/{id}/edit
Bundle Rules /admin/settings/pricing/bundle-rules
Surcharge Groups /admin/settings/pricing/surcharge-groups
Surcharge group form /admin/settings/pricing/surcharge-groups/create or …/{id}/edit
Catalogue telemetry /admin/settings/pricing/telemetry (settings.manage)

There is no standalone Discount Rules index — rules are edited inline on each discount group form.

Catalogue telemetry

Catalogue telemetry (/admin/settings/pricing/telemetry, needs settings.manage) shows counts of catalogue and pricing runtime events in the current fifteen-minute window — held records, duplicate identities, publication failures, stale generations, registry collisions, manifest drift, dual-write failures, lock conflicts and slow calculations — each against its alert threshold. Observations are temporary and best effort: zero events do not certify catalogue health, and the page sends no notifications. If telemetry is unavailable, the page says so.

Discount groups and rules

The Discount Groups index lists name, description, and active status. Add Discount Group opens the create form.

On the discount group form, the Discount Rules section holds repeatable rule blocks. Each rule defines:

  • Discount %, quantity scope (per line / aggregate catalogue item / aggregate group), min/max quantity, sort order
  • Valid from / valid to (datetime)
  • Catalogue item groups, tags (comma-separated, all required), catalogue items, and transaction types (Rental, Sale, Service)

Empty criteria means the rule matches all catalogue-items. Rules use AND logic across criteria fields.

Rate bands and tiers

Rate Bands assign tiered multipliers. The form's Tier Multipliers section lists tier number, label, and multiplier (create defaults to one tier: "Day 1" at 1.0000).

Surcharge groups

Surcharge Groups index shows name, Default vs Optional badge, and status. The group form exposes:

  • Default group (auto-enabled on new rentals) checkbox
  • Repeatable Surcharges — name, percent value, fixed value (minor units), item tax code, and Default (applies when group is active)

Surcharge criteria fields (catalogue item groups, tags, valid dates, and so on) exist in the backend sync layer but are not rendered on the admin form.

Bundle rules

Bundle Rules configure fixed bundle price or percentage reduction modes with a required catalogue item set. Bundle Rules appear in the admin sidebar but not on the admin landing overview cards.

Account assignment

On the account create/edit form (Tax & Pricing section, companies and venues), assign:

Field Purpose
Rate Band Active price list for the account
Rate Band Tier Tier within that band
Discount Group Discount rule set to evaluate on their rentals

These feed the pricing pipeline when a rental is priced for that account.

Rental line-item editor

Pricing effects are visible on the rental Overview tab (/rentals/{id}), which embeds the line-item editor. Editing requires rentals.edit and an open rental; rentals.unlock_rates controls lock/unlock price.

Toolbar actions:

Control Behaviour
Recalculate Re-runs the pricing pipeline (resetPrices and resetDiscounts stay false in the UI)
Agreed price (currency icon) Opens modal — Flat headline override or Proportional line distribution; Clear / Set agreed price
Lock icon (footer/header) Opens confirm to lock or unlock rates (blocked while agreed price is active)

Line presentation:

  • Auto-applied discounts appear in the Disc % column
  • Manually overridden discounts show a Manual badge; row menu offers Reset to group discount
  • Charge breakdown popover (hover subtotal) shows rental charge and Surcharge amount
  • When agreed price is active, the footer shows the agreed total alongside the calculated subtotal
  • Each catalogue-backed line carries a rate picker and a read-only Rate breakdown popover — the per-line rate controls are documented in Rentals → Choosing a rate per line. Pinning a rate is part of editing the rental (rentals.edit) and needs pricing unlocked

Row edit modal exposes unit price override, discount %, dates, description, and substitute catalogue item.

Price lock: when locked, inline price/discount/qty edits and line removal are disabled; banner reads "Pricing is frozen — rates and tax are locked" unless a agreed price headline is shown instead.

Not in Web UI yet: toggling surcharge groups on a rental (toggle_surcharge_group exists on the API only). Applying a discount group manually is also API-only — assignment flows through the account's discount group and auto-apply rules.

Permissions summary

Permission UI effect
pricing.view Admin Pricing sidebar links
pricing.manage Create / edit / delete on pricing admin pages
rates.view Rate specifications admin link
rentals.edit Line-item toolbar and inline edits
rentals.unlock_rates Lock / Unlock price in Actions menu and editor