Skip to content

Published option-price catalogs

Published option-price catalogs provide immediate, authoritative prices for product choices without evaluating the configurator for every selection. They are intended for FORGE's internal configurator and STORE storefronts.

Runtime model

For a published catalog, the displayed configured price is:

base price
+ each selected option adjustment
+ each matching conditional adjustment

The browser performs only this arithmetic. It does not derive a selling price from BOM items, router tasks, costs, markup, or Price Components.

The configurator still evaluates product validity, dependencies, BOM, routing, documents, scheduling, and fulfillment output. When a configuration is added to a quote or order, FORGE verifies the published catalog revision and total before persisting it.

The normal salesperson UI should not show BOM or router detail. Show the base price, signed option adjustments, and running total. If authorized users need an explanation, expose material, process, rule, and mapping provenance through an on-demand price-details or audit panel after configuration.

Products without an applicable published catalog continue using legacy configurator pricing.

Authorization

Catalog administration endpoints require a platform ROOT user or tenant administrator. The published-catalog bootstrap endpoint requires an authenticated request context.

Calculate a product catalog

Compile a product from its canonical/default configuration:

POST /v1/products/{productID}/option-price-catalogs/compile
Content-Type: application/json
{
  "canonicalConfiguration": {
    "productID": "PRODUCT-ID",
    "currencyID": "USD",
    "attributes": {
      "Memory": { "name": "Memory", "value": "8 GB" }
    }
  },
  "currencyID": "USD",
  "priceListID": "",
  "minQuantity": 1,
  "maxQuantity": null,
  "effectiveFromUTC": "2026-11-14T00:00:00Z"
}

Compilation evaluates the canonical configuration and every publishable valid value outside the interactive pricing path. It records material cost, process cost, proposed and approved price, margin, attribution evidence, validation findings, and a deterministic checksum.

After the first calculation, recalculate from the stored canonical snapshot without resending it:

POST /v1/products/{productID}/option-price-catalogs/recompile

Recalculation creates a new revision. It never changes an already published amount or historical quote/order line.

Monitor product calculation status

ROOT users can open ADMIN > Option Price Catalogs to see every configurable product's catalog status. The page shows the latest revision, currency, calculation/publication times, and blocking-finding count.

Use Calculate for a product with no catalog and Recalculate for an existing catalog. Calculation can take time because it evaluates all publishable choices; the action disables itself while the request is running. Select View to inspect the resulting option prices.

The catalog detail view separates material cost, process cost, proposed price, published price, and margin. Use the per-choice details control only when rule/item/task provenance is needed. Those engineering details are intentionally collapsed by default and are not part of the salesperson or storefront presentation.

The initial ROOT administration view can use:

GET /v1/option-price-catalogs/product-statuses

Each active product reports its latest catalog, revision, status, currency, calculation and publication timestamps, and blocking-finding count. NeverCalculated means no compilation exists. Stale means the current released product-design version differs from the version used for the latest catalog.

Use the compile or recompile endpoint as the per-product Calculate action.

Review, validate, compare, and override

Inspect a revision:

GET /v1/products/{productID}/option-price-catalogs/{catalogID}

Re-evaluate its stored findings and lifecycle status:

POST /v1/products/{productID}/option-price-catalogs/{catalogID}/validate

Compare draft price, cost, and margin with the applicable published revision:

GET /v1/products/{productID}/option-price-catalogs/{catalogID}/compare

Approve an explicit option-price override:

PATCH /v1/products/{productID}/option-price-catalogs/{catalogID}/options/{optionPriceID}
Content-Type: application/json
{
  "publishedPrice": 125.00,
  "displayMode": "Adjustment",
  "reason": "Approved market price for the November release"
}

The reason is required. Calculated evidence remains intact, and applicable price findings are resolved with the approval reason.

Display modes are:

  • Included: show no additional charge.
  • Adjustment: show the signed amount, such as +$125.00 or -$10.00.
  • CallForPrice: do not permit configuration finish until an approved amount exists.

Publish and retire

Publish a validated revision:

POST /v1/products/{productID}/option-price-catalogs/{catalogID}/publish

Blocking findings prevent publication. Publication supersedes the prior published catalog in the same product, currency, price-list, and quantity scope. Published rows are immutable.

Retire the current revision:

POST /v1/products/{productID}/option-price-catalogs/{catalogID}/retire

Load prices in a configurator or storefront

At product bootstrap, fetch the one applicable published catalog:

GET /v1/products/{productID}/commercial-catalog?currencyID=USD&priceListID=&quantity=1

The response contains:

  • catalog ID, revision, design-version ID, and calculation checksum;
  • currency, price-list, quantity, and effective-date scope;
  • base price;
  • option adjustments and display modes;
  • conditional adjustments.

Index options by durable attributeID and valueID when possible. Names and displayed values are explanatory snapshots and compatibility keys.

When a selection changes, sum the base, selected option adjustments, and conditions whose complete condition set matches. No API call or configurator execution is required to update the displayed price.

A stale product-design catalog returns 409 STALE_PRODUCT_DESIGN; the UI must disable finishing and offer recalculation rather than falling back to a misleading displayed price.

Finish-time verification

Send these fields on ConfigurationModel when adding the configuration to a quote or order:

{
  "priceListID": "",
  "publishedCatalogID": "CATALOG-ID",
  "publishedCatalogChecksum": "SHA-256-CHECKSUM",
  "presentedCatalogPrice": 1425.00
}

FORGE resolves the current catalog again and rejects stale IDs/checksums, CallForPrice, manipulated presented totals, and a configured line total that differs by more than one cent. A 409 response includes a stable code such as STALE_CATALOG, STALE_PRODUCT_DESIGN, PRESENTED_PRICE_MISMATCH, or CONFIGURED_PRICE_MISMATCH.

On success, every persisted configured line snapshots the catalog ID, revision, checksum, verified unit price, and published contributions. Later recalculation cannot rewrite that commercial history.

Attribution DSL

Rule-created output can identify its commercial owner without breaking existing rules:

config.AddTask("STAT02")
    .ForOption(memory)
    .Detail("Install memory")
    .Time(1m);

config.AddItem("MEM-32GB", 1m)
    .ForOption(memory)
    .Markup(1.40m);

config.AddTask("STAT05")
    .ForBaseProduct()
    .Detail("System test")
    .Time(30m);

Existing rules without attribution remain valid and default to base-product ownership. Single-condition item mappings are automatically attributed to that choice. Compound mappings require an explicit commercial owner or produce a publication finding.

Price Components are optional classification metadata. They are retained when present but are not required for calculation, attribution, validation, or publication.