Rate specifications
Configure how catalogue items are priced over time using composable rate specifications, calculation strategies, and modifiers.
Overview
A rate specification describes how a charge is calculated over a rental window — it does not hold a price itself. Prices live on catalogue item prices, which attach a rate specification (and an amount) to a catalogue item. This separation lets one definition such as "Daily Rate" drive pricing for thousands of catalogue items, each at its own price.
Every rate specification is composed from three parts:
| Part | Description |
|---|---|
| Calculation strategy | How elapsed time becomes chargeable units — period-based, fixed, or hybrid |
| Base period | The granularity of a chargeable unit (half-hourly, hourly, daily, weekly, monthly) |
| Modifiers | Optional adjustments applied after the base charge — duration multipliers and quantity factors |
Signals ships 11 presets for common rate calculations. Presets are just pre-filled, fully-editable configurations — there is no special preset behaviour beyond a starting point.
Note
rate specifications are managed in the admin settings area, not the main catalogue. They are configuration intended for a small number of administrators, not a daily tool. Assigning rates to individual catalogue items happens on the catalogue item detail page.
Calculation Strategies
| Strategy | Behaviour | Base period |
|---|---|---|
| Period-based | Charges the unit price for each chargeable unit in the rental window | Required (any) |
| Fixed | A single flat charge regardless of duration | None |
| Hybrid | A fixed charge for an initial number of units, then a per-unit charge thereafter | Required (daily, weekly, monthly) |
Base Periods
A base period defines the length of one chargeable unit.
| Period | Unit length |
|---|---|
| Half-Hourly | 30 minutes |
| Hourly | 60 minutes |
| Daily | 1 day |
| Weekly | 7 days |
| Monthly | 30 days |
Note
Monthly is simplified to a fixed 30-day month in this version; calendar-month length is a planned refinement. Half-hourly and hourly periods are measured against the wall clock, while daily and longer periods are counted as whole calendar days.
Modifiers
Modifiers adjust the base charge after units are counted. They are applied in priority order: multipliers first, then factors.
| Modifier | Configuration | Effect |
|---|---|---|
| Multiplier | A tiers table of decimal multipliers, one row per period position |
Scales the unit price by tier as the rental lengthens. The last row inherits forward, so longer rentals keep the final tier's multiplier |
| Factor | A ranges table of {from, to, factor} rows |
Scales the per-unit subtotal based on the order quantity. An open-ended final range (to = null) covers everything above |
Multiplier tiers and factor ranges are stored as decimal strings to preserve precision; the engine performs all intermediate arithmetic losslessly and rounds only at final assembly.
Time Options
Period and hybrid strategies expose options that refine how elapsed time is counted:
| Option | Description |
|---|---|
| Day type | Count elapsed clock time, or only minutes within configured business hours |
| Business hours | Daily start/end times used when day type is Business Hours |
| Rental days per week | Treats a "week" as this many chargeable days (e.g. a 5-day working week) |
| Leeway minutes | Grace period before an extra unit is charged |
| First day cutoff | A pickup later than this time still bills the first day in full |
| Last day cutoff | A return prior than this time drops the final partial day |
Presets
| Preset | Strategy | Base period | Modifiers |
|---|---|---|---|
| Daily Rate | Period-based | Daily | — |
| Daily Multiplier and Factor | Period-based | Daily | Multiplier, Factor |
| Hourly Rate | Period-based | Hourly | — |
| Hourly Multiplier and Factor | Period-based | Hourly | Multiplier, Factor |
| Half Hourly Rate | Period-based | Half-Hourly | — |
| Weekly Rate | Period-based | Weekly | — |
| Monthly Rate | Period-based | Monthly | — |
| Monthly Multiplier and Factor | Period-based | Monthly | Multiplier, Factor |
| Fixed Rate | Fixed | — | — |
| Fixed Rate and Factor | Fixed | — | Factor |
| Fixed Rate and Subs Days | Hybrid | Daily | — |
Presets are seeded on install. They can also be re-seeded from Admin → Database Seeders.
Rate specifications Admin
Route: /admin/settings/rate-specifications
Browse all rate specifications in a table that distinguishes presets from custom definitions and shows how many catalogue item prices use each one.
- Presets are read-only starting points and cannot be deleted.
- Custom definitions can be edited and deleted (deletion is blocked while catalogue item prices still reference them).
Create / Edit
Route: /admin/settings/rate-specifications/create or /admin/settings/rate-specifications/{id}/edit
Creating a definition starts with a choice: pick a preset to pre-fill the form, or start From Scratch. The form is schema-driven — choosing a strategy constrains the available base periods, and enabling a modifier reveals its configuration table (tier or range rows you can add, remove, and reorder). Fields appear and hide based on other field values (for example, business-hours fields only show when day type is Business Hours).
Duplicate
Any definition — including a preset — can be duplicated to produce an editable custom copy named "{name} (Copy)".
Catalogue item prices
Route: /catalogue-items/{id}/prices
Each catalogue item has a Prices tab listing the price assignments for that catalogue item. A catalogue item price combines:
| Field | Description |
|---|---|
| rate specification | The calculation behaviour to apply |
| Transaction type | Rental, Sale, or Service |
| Unit price | The amount, in the price's currency |
| Currency | ISO 4217 currency code |
| Warehouse | Optional warehouse scope (blank = all warehouses) |
| Valid from / to | Optional date window the price applies within |
| Priority | Higher priority wins when multiple prices overlap |
| Default | Preferred generic fallback for this item and transaction type |
Prices are added and edited on a dedicated form page (/catalogue-items/{id}/prices/create); removal uses a confirmation modal. When a saved price overlaps another price of the same priority, type, and date window, a warning banner is shown and a publication reason acknowledging the shadowed prices is required before it can be saved. Overlapping prices are allowed and resolved by priority at calculation time.
Each item and transaction type has one explicit Default price, shown as a Default column on the item's Prices tab and set from the price form. The database enforces the rule: a partial unique index allows only one default per catalogue item and transaction type.
The first price for an item and type becomes the default automatically. Adding a higher-priority price without choosing a default promotes that price only when it has the same warehouse and price-band scope as the current default, and any demotion it performs stays inside that same scope — adding a warehouse-scoped price never flips the resolved price at another warehouse. Choosing Default explicitly demotes the preceding default.
Marking a price as the default does not make it win everywhere. The resolver first discards every candidate that is invalid for the line — wrong warehouse, wrong rate band, outside its date window, or in the wrong currency — and only then prefers the default among what remains. A customer's matching rate band price still takes precedence over a generic default; the default is used when no matching band-specific price applies, and normal priority resolution supplies the final fallback.
The is_default flag selects the default within its scope. Creating a price changes that selection only when explicitly requested; warehouse-scoped defaults do not change other scopes.
Permissions
rate specifications and catalogue item prices are governed by the rates.* permission group: rates.access, rates.view, rates.create, rates.edit, and rates.delete. The admin area additionally requires admin access. The corresponding API abilities are rates:read and rates:write.
Rate engine
The rate engine is the calculator behind catalogue pricing. A rate specification describes how a charge is counted (strategy, base period, modifiers). A catalogue item price attaches that specification and an amount to a catalogue item. This section documents the four read-only rate engine meta endpoints that expose the same strategy, modifier, preset, and config-schema catalogue the admin rate-specification form uses.
These endpoints do not repository prices and do not run a quote. For how definitions are edited in admin, see Rate specifications Admin. For discount groups, rate bands, surcharges, and bundle rules, see Pricing & Discounts (under Features → Finance); it is not duplicated here.
Token ability
Every meta route requires the rates:read token ability (rates.view on the session user).
Strategies
Route: GET /api/v1/rate_engine/strategies
Returns each registered calculation strategy: identifier, label, allowed base periods, and whether it supports multiplier / factor modifiers. Typical identifiers are period, fixed, and hybrid.
Modifiers
Route: GET /api/v1/rate_engine/modifiers
Returns registered rate modifiers in engine priority order (the same order used when a specification applies them). Each row is identifier, label, and priority.
Presets
Route: GET /api/v1/rate_engine/presets
Returns the framework-shipped rate-specification templates (slug, name, description, strategy, base period, enabled modifiers, and default configs). Presets are read-only starting points on this list; the specification you clone from a preset is a fully-editable configuration (see Presets). Cloning is a write on rate_specifications, not on this list.
Schema
Route: GET /api/v1/rate_engine/schema
Composes the config-form sections for one strategy and an optional set of modifier identifiers (strategy is required; modifiers[] is optional). Unknown strategy or modifier identifiers fail validation with 422. The response is form metadata only — it does not persist a specification.
Rate preview
POST /api/v1/catalogue_items/{catalogue_item}/calculate_rate uses resolver specification 1.0.0 for a warehouse, transaction type, rate band, currency, and start date, then runs the engine over the requested window. Selection is category-specific first, then an applicable explicit default, then a general rate. Inside the selected class it sorts by priority, warehouse specificity, newest published revision, and stable row ID. Invalid warehouse, date, category, and currency candidates do not win. When no rate is assigned the response is a zero-priced breakdown (meta.resolved is false). The preview does not persist a rate or a rental line. It requires rates:read or catalogue-items:read.
Every response includes the selected immutable rate revision ID and a compact rate_resolution summary. Set include_resolution_trace=true to request rejected-candidate evidence. Detailed traces require both the rates.view permission and rates:read token ability, are limited to 100 rows, and use trace_offset plus next_trace_offset for pagination. This prevents a catalogue-only reader from discovering negotiated pricing candidates.
The curated MCP tool calculate-rate wraps that same preview.
Price-book revisions
Rate specifications and catalogue item prices have stable logical UUIDs and immutable numbered revisions. A published revision records its schema version, content hash, effective interval, author, reason, publication time, and superseded revision. Create and update actions publish a matching revision in the same database transaction. Draft revisions never change the live columns and are not visible to runtime resolution.
Published rate revisions use effective-dated activation rows. Retiring a rate retires its activation; resolution then falls through to the next eligible candidate and does not require an explicit default. Existing rental lines repository the revision that actually supplied their price, plus a compact resolver summary, so replay does not silently move to current pricing. If an explicit pin is invalid, its pin remains visible for contract while the stored revision identifies the valid dynamic fallback that supplied the amount.
Rate specifications and catalogue item prices without revision records can be inspected or assigned revisions with:
php artisan signals:price-book:backfill-revisions --dry-run
php artisan signals:price-book:backfill-revisions --apply --reason="Capture price-book revisions."
The command preserves source identifiers and timestamps. It reports invalid definitions and does not silently repair or normalise them.