Product definition reference

Every field of a product definition, every check it must pass, how a request runs through it, and the API that authors, executes, explains and replays products. The guide builds one end to end.

Identity and versions

A definition is a PRODUCT_DEFINITION setting identified by organisation, optional binder, and product code, with the key definition. Versions, effective dates, two-person approval and audit are the settings machinery’s; a binder’s definition overrides the organisation’s for that binder. It is published dated: a future start leaves today’s version live until then.

The document

{
  "schemaVersion": 1,
  "name": "Outbound Travel Insurance",
  "currency": "USD",
  "records":   [ { "name": "Traveller", "fields": [ ... ] } ],
  "inputs":    [ ... ],
  "coverages": [ ... ],
  "stages":    { "validation": {...}, "eligibility": {...}, "underwriting": {...},
                 "pricing": {...}, "quote": {...} },
  "rules":     [ ... ],
  "options":   { "pricingOnDecline": false },
  "carrier":   { "name": "Insurer X Ltd", "reference": "IX-TRAVEL-2026" },
  "source":    { "name": "Broker Y Ltd", "reference": null },
  "quoteClass": { ... }
}

The document is read strictly: an unknown property is a DEFINITION_UNPARSEABLE finding, never dropped. carrier is required on a broker’s or agency’s product and refused on an insurer’s; source only comes with a carrier.

inputs

• dateRange bounds are today (the request’s date), an ISO date, or another DATE input’s name; an absent referenced input sets no bound.
• ageRange is whole years on the request’s date, for a date of birth; one after the date is out of range.
• requiredWhenCoverage makes an input required when a named cover is on.
• Record fields are checked the same way, recursively, with paths like inputs.travellers[1].dateOfBirth.

coverages

Resolution is deterministic: mandatory, default and requested items are on; a child of an item that is off is off; a child explicitly requested under a parent that isn’t chosen is a COVERAGE_CONFLICT, never silently dropped. Stages receive the covers that are on as coverages, a list of records with code, type, parent, limitAmount, deductibleAmount, deductiblePercent, excessAmount, excessPercent and waitingDays (absent amounts 0, no parent "").

stages

"pricing": { "workflow": "motor-rating",
  "inputMapping":  { "sumInsured": "vehicleValue",
                     "ratingDate": "context.asOfDate",
                     "currency": "context.currency",
                     "loadingPercent": "underwriting.loadingPercent" },
  "outputMapping": { "pricing.netPremium": "premium",
                     "pricing.taxTotal": "levies",
                     "pricing.total": "total" } }

A stage takes only what it declares. A workflow record may ask for a subset of a product record’s fields; a field the workflow wants that the product lacks is a stage failure, never a default. A product DATE fills a DATE or STRING; an ENUM fills an ENUM or STRING. Stages run in the order validation, eligibility, underwriting, pricing; any may be absent.

The pricing contract

The quote rounds these to two places, half to even. It doesn’t check that lines add up to the total, so round before combining in the workflow when they must.

rules

{code, stage, effect (ERROR | DECLINE | REFER), message, firedBy, coverage?}. firedBy names a BOOLEAN output of that stage’s workflow, after its outputMapping; a missing or non-BOOLEAN flag is a stage failure, never “not fired”. Pricing-stage rules are assessed after pricing and can move an ACCEPT to REFER or DECLINE; whether pricing runs is decided by the earlier stages.

quoteClass

Checks

A finding is {rule, path, message, tier}. STRUCTURAL findings refuse the draft. REFERENCE findings are reported by validate and block publish, since a workflow may be written after the definition.

How a request runs

A stage that can’t do its job (its workflow not in effect, an input it can’t be given, a value of the wrong type) fails closed with its stage and workflow named. An eligibility check that couldn’t run must never read as “eligible”.

Executing: API version 2

Send the header API-Version: 2 with every product call. A version the API doesn’t serve is 400 API_VERSION_UNSUPPORTED. Within a version, changes are only additive: a field may be added, never renamed or removed; a breaking change is a new version served beside it.

curl -s -X POST https://<your-address>/api/products/travel-outbound/execute \
  -H "Authorization: Bearer $TOKEN" -H "API-Version: 2" -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<insurer>",
    "binderCode": null,
    "asOfDate": "2026-10-09",
    "inputs": { "destinationZone": "WORLDWIDE_PLUS", "tripDays": 10,
                "travellerAges": [10, 70] },
    "coverages": [ { "code": "BAGGAGE", "selected": true } ],
    "options": { "includeTrace": false }
  }'

{ "requestId": "019a…", "contractVersion": "2",
  "product": { "code": "travel-outbound", "name": "Outbound Travel Insurance",
               "versionId": "018f…", "versionNumber": 3, "effectiveFrom": "2026-10-01" },
  "asOfDate": "2026-10-09", "currency": "USD",
  "outcome": "ACCEPT", "reasons": [],
  "coverages": [ { "code": "BAGGAGE", "enabled": true, "limitAmount": 1500, … } ],
  "premium": { "netAmount": null, "taxAmount": null, "feeAmount": null,
               "totalAmount": 69.86, "lines": [] },
  "rateVersionsUsed": [
    { "kind": "PRODUCT_DEFINITION", "key": "travel-outbound", "version": 3, … },
    { "kind": "RATE_TABLE", "key": "travel-outbound-base-premium", "version": 2, … } ],
  "trace": null }

• Numbers are exact decimals as sent; nothing is coerced, so "10" for a NUMBER is INPUT_TYPE_INVALID.
• Every field is always present, null when it doesn’t apply; premium is null for a DECLINE.
• rateVersionsUsed lists everything versioned the quote read: the definition, each stage workflow, every table, setting, formula and block link.
• Errors are RFC 7807 problems with a stable code, the requestId, and for a bad request errors[] of {code, fieldPath, message}. A rejected request isn’t recorded.

Recorded and replayable

Every execute and explain writes one insert-only row: the request, the quote and the definition version. Its id is the requestId. Replay runs the request again at its own date against the same definition version, and says what moved:

{ "identical": false,
  "differences": [ "premium",
    "rateVersionsUsed: RATE_TABLE/travel-outbound-base-premium@v1 is no longer used",
    "rateVersionsUsed: RATE_TABLE/travel-outbound-base-premium@v2 is now used" ] }

The usual cause is a table or workflow republished with a start date on or before the quote’s date. A record also says who sold the product and on what basis: their own, a distribution agreement, through a broker, on a storefront or as platform content, and who carries the risk.

Authoring API