SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Catalogue item API and pricing reference

Catalogue item identity and SKU rules, lifecycle tombstones and version conflicts, composition revisions, rate pins and pricing order, and supplier cost monetary units.

Loose-stock asset balances, catalogue fleet figures and utilisation summaries retain quantities with up to two decimal places, such as 1.25; a serialised asset continues to represent one unit.

Overview

This page is the integration reference for catalogue items. For the catalogue list, detail page, form and merge, see Catalogue items.

Generic MCP execute-endpoint refuses destructive catalogue operations, including deletion and merge, with mcp_confirmation_required. Use a dedicated confirmation-aware tool when available or the authenticated API.

Identity, lifecycle and pricing decisions

The permanent identity is the item ID. Names are editable display labels; the edit form keeps them unique, but the API does not enforce this, so do not rely on a name as an identifier. An optional SKU is an operator-facing identity: blank becomes null, while nonblank values compare after Unicode whitespace normalization, NFC normalization and full case folding. Display spelling is retained. Archived items, merged sources and aliases still reserve their SKU; a similar name does not authorize combining items or reusing an identifier. Use Duplicate suggestions on the item to review likely duplicates.

Only active items are eligible for new commercial selection. inactive items remain editable and their historical references remain readable. Archive and delete both retain the item and its history; restore requires capability/dependency checks. retired and merged are permanent tombstones, with reserved identifiers. Ordinary edits and lifecycle controls use the item's captured lock_version; a stale supplied version refuses with version_conflict and requires a reload. An omitted version remains a contract path, not a concurrency guarantee.

The related item Included and Included free combinations are tabulated in Catalogue items → Identity and lifecycle.

Composition links have stable identities and immutable revisions. Existing lines retain their selected revision after quantities, ordering or definitions change. A merge preview covers supported catalogue dependencies, composition, prices, aliases and historical-reference dispositions; it must refuse unsupported/ambiguous edges. It is not a promise that every historical foreign key moves, or that a merge can be undone with restore.

Published rate presets are immutable. Duplicate a preset to create a custom specification rather than editing the preset in place. A valid line rate pin wins before dynamic resolution; stored-amount snapshots can retain a valid superseded pin as provenance without adopting its newer price. Invalid unlocked pins can use ordinary fallback, while locked pricing refuses an invalid pin. Accepted terms read their captured manifest and never fall forward to current prices. Surcharge pinned/follow binding is a separate rule decision described in Pricing. An intentional zero and an unresolved rate are different states.

Pricing runs strategy and modifiers, then tier, exact quantity, bundles, line discount, proportional deal discount, inclusive-tax extraction, additive surcharges, flat headline and grouped tax/rollup. Duration is already part of the strategy result and must not be multiplied twice. See Pricing for exact rounding and binding rules.

For POST /api/v1/catalogue_items/{catalogue_item}/calculate_rate, supply quantity as plain decimal digits with up to six decimal places, such as "1.250000". The whole part must be 0 or start with a nonzero digit. Surrounding whitespace, line breaks and exponent notation are rejected through both REST and MCP.

An inactive rate band is a separate policy from an inactive catalogue item. The rate resolver excludes inactive rate bands: a rate scoped to an inactive category does not match new resolution.

See Pricing for recovery and integration details.

Catalogue prices

Manage an item's prices through /api/v1/catalogue_items/{catalogue_item}/prices and /prices/{price}. Each price combines a rate specification, warehouse, transaction type, currency, validity window and priority. Responses identify records as catalogue_item_price:{id}; the prices include returns those records on a catalogue item. Rental pricing references use catalogue_item_price_id and catalogue_item_price_revision_id.

Use /prices/overlap_preview, /prices/{price}/publication_preview and /prices/{price}/publish to review and publish changes. Overlap previews accept price_id for an existing assignment and return overlapping_price_ids. The rate engine, rate specifications and rate bands retain their own names and the shared rates:read/rates:write abilities.

Asset adjustments

Use POST /api/v1/assets/{asset}/adjustments for manual movements of type purchased, found, written_off, sold or built. The quantity must be positive, with at most eight whole digits and two decimal places, up to 99999999.99; barcoded assets require exactly 1. Supply the quantity as decimal digits with an optional decimal point; surrounding whitespace, line breaks and exponent notation are rejected. For example, {"transaction_type":"purchased","quantity":"1.25"} adds 1.25 units. Responses return quantities and signed movements as exact two-decimal strings. Movements that would leave a negative balance or exceed the quantity precision are refused.

The server assigns the boolean manual flag, source references and quantity balances. Requests must omit manual, source_type, source_id, quantity_on_hand and quantity_allocated; responses include manual as a boolean. Read movement history at GET /api/v1/assets/{asset}/ledger.

Catalogue item supplier monetary units

Catalogue item supplier create/update commands and the Suppliers editor use the supplier's currency_code, not the company base currency. Integer inputs mean minor units; decimal strings/numbers mean major units. New costs retain a versioned original currency/precision record. An amount-only edit uses that stored precision even if currency settings later change. Changing the currency requires an explicit replacement amount. Inputs that would lose a fraction of a minor unit or exceed integer storage bounds are refused; the editor does not silently round them.

Supplier REST responses include cost_decimal_places and cost_precision_status. A captured cost has a decimal cost at its original scale. A row without proven original precision has null cost/cost_decimal_places and missing_source_precision status; its raw amount is not reinterpreted from current settings. The editor labels this gap and starts with an empty replacement amount. A non-money edit does not manufacture original precision; an explicit replacement admits a new amount and unit.

Invoice cost estimates capture the supplier's original precision and convert into the invoice's named unit. Different precisions for the same currency require explicit unit rescaling at half-up rounding, not an FX quote or a nominal minor-unit subtraction. Missing source precision leaves the cost estimate incomplete; it does not prevent a legally valid invoice solely because estimated margin is unavailable. Frozen issue estimates remain distinct from live forecasts.

Original-precision capture currently applies to supplier costs and invoice cost estimates; rental and project cost units, sub-hire and purchasing do not use it yet. Costs without captured precision show missing_source_precision until a replacement amount is entered.

Catalogue field groups

Requests, responses, filters, sorts and webhook resource objects use offered_for (rental, sale, both) and tracking (bulk, serialised). availability contains buffer_before_minutes, turnaround_minutes and reserve_percent. Commercial settings are grouped under commercial.rental, commercial.sale, commercial.sub_hire and commercial.purchase. Cost inputs are non-negative integer minor currency units; response costs are decimal strings. Expanded references live beside their identifiers within each group. See API field groups for the complete fields and include paths.

standalone_allowed defaults to true; set it to false when an item requires a related item relationship. replacement_value records the replacement amount. Commercial cost references use cost_category_id and expanded cost_category values. Catalogue prices use rate_band_id and rate_band_name; rate bands are managed through /api/v1/rate_bands. Related item requests use included_free to include a related item without a charge.

External references

Catalogue items and assets support external_ref and PUT /api/v1/catalogue_items/by-external-ref/{ref} or PUT /api/v1/assets/by-external-ref/{ref}. Read without writing using filter[external_ref][eq]. Asset updates cannot change their catalogue item or warehouse through this upsert. See Integration identities for uniqueness, permissions and create/update responses.

Bulk availability

POST /api/v1/availability/bulk is a read-only operation costing 20 units per call. It requires availability.view, the availability:read token ability and access to every requested warehouse. Choose either catalogue_item_ids (1–500 distinct IDs) or catalogue_item_group_id, and supply warehouse_ids (1–10 distinct IDs). A group with more than 500 items is refused; split it into explicit item batches. Unknown items return 422; inaccessible warehouses return 404.

POST /api/v1/availability/bulk
Content-Type: application/json

{"catalogue_item_ids":[18],"warehouse_ids":[2],"from":"2026-11-04","to":"2026-11-05"}

The range must end on or after its start and fit availability.api_max_range_days (366 days by default). A response excerpt with one slot:

{
  "data": {
    "from":"2026-11-04T00:00:00+00:00",
    "to":"2026-11-05T00:00:00+00:00",
    "catalogue_items":[{
      "catalogue_item_id":18,"warehouse_id":2,
      "min_available":3,"max_available":3,"calculated_at":"2026-11-03T23:55:00+00:00",
      "slots":[{
        "slot_start":"2026-11-04T00:00:00+00:00","date":"2026-11-04",
        "total_stock":10,"available":3,"booked":5,"held":2
      }]
    }]
  }
}

Each item/warehouse pair has range minima/maxima and slots at the installation's configured resolution. booked is active demand excluding holds; held is held-phase demand, and both reduce availability. Composed items use the kit calculator and report all demand as booked with held: 0. Availability agrees with the per-item endpoint. This computed grid has no cursor or incremental-sync timestamp feed.