Headless product configurator and API guide
A headless product configurator separates product truth from presentation. Websites, ecommerce storefronts, dealer portals, mobile apps and kiosks can create different experiences while one API-led engine controls valid choices, dimensions, pricing context, saved state and downstream identity.
Six architecture layers
Assign product, channel and workflow ownership
Ten API capabilities
Cover configuration from context to release
Twenty buyer questions
Evaluate API-first claims with evidence
Eighteen detailed FAQs
Answer technical and commercial intent
Clear definition
A headless configurator exposes product configuration capabilities independently of one fixed user interface. The service receives product, market, language, account and channel context; creates or loads a configuration; evaluates intended changes; and returns authoritative state, allowed choices, derived values, validation and revision identity. The channel decides how to present that result.
This differs from a product API that merely lists attributes. Configurable products contain dependencies, exclusions, dimensional boundaries, calculated values and sometimes review conditions. If each frontend reconstructs those relationships, the architecture is headless in appearance but fragmented in behavior. A buyer can then create a product in one channel that another channel, price engine or factory rejects.
Headless is valuable when several experiences need the same product engine or when a company needs complete frontend control. It also creates responsibility: channel teams own accessibility, content, SEO, performance and interaction quality; platform teams own contracts, versions, authorization, limits and observability; product owners still own the meaning of a valid and sellable product.
Interactive architecture planner
Select the channel model, source of product and commercial truth, and final business outcome. The planner returns the minimum architecture concerns to turn into specific contracts and acceptance tests.
Channel model
Authority model
Final outcome
Suggested pattern
Put a storefront orchestration layer between public clients, configuration services and private commerce operations.
Market, currency, customer, inventory and cart context
Configured-line identity, reopen behavior and checkout handoff
Price-token validity and recovery from changed product state
Explicit boundary between valid product state and contextual commerce price
Reconciliation when configuration, promotion, tax or checkout context changes
One final transaction price authority
Configured cart line, checkout and order identity with safe retry
Expired state, repricing and customer-confirmation policy
Order acknowledgement and duplicate reconciliation
Channel
Ecommerce
Authority
Split with commerce
Outcome
Cart + order
Reference architecture
The layers can be separate services or responsibilities inside a smaller system. What matters is that ownership and contracts are explicit, while every downstream action keeps the same configuration identity.
Owns
Layout, interaction, accessibility, content, localization, account entry points and channel-specific calls to action.
Contract
Consumes permitted options, validation, visual state, price status and save or transact actions.
Avoid: Reimplementing dependency rules in every frontend because the API returns only raw option lists.
Owns
Session state, defaults, dependencies, exclusions, dimensions, derived values, validity and canonical configuration identity.
Contract
Accepts context plus intended changes; returns authoritative state, allowed next choices, messages and revision.
Avoid: Letting the client declare a configuration valid instead of validating every relevant mutation server-side.
Owns
Price source, currency, market, customer group, quantity, discounts, tax responsibility, validity and approval status.
Contract
Calculates from configuration revision plus commercial context and returns explainable lines or a price token.
Avoid: Copying formulas into a frontend, configurator and commerce platform with no named authority or reconciliation.
Owns
Runtime assets, scene bindings, materials, camera states, optional AR assets, thumbnails and configured snapshots.
Contract
Maps stable product IDs and configuration state to versioned visual assets and deterministic scene instructions.
Avoid: Returning an image without enough structured state to reproduce, price or continue the configured product.
Owns
Lead, quote, cart, order, approval, project, document and optional production transition responsibilities.
Contract
Consumes an accepted configuration revision exactly once and returns durable destination identity and status.
Avoid: Treating a timed-out request as failed, retrying blindly and creating duplicate leads, quotes or orders.
Owns
API versions, schemas, credentials, rate limits, observability, audit, catalogue release, migration, deprecation and recovery.
Contract
Publishes supported behavior and makes every request traceable across service and destination boundaries.
Avoid: Shipping an undocumented private API whose behavior changes whenever the original frontend changes.
Configuration API contract
These are logical responsibilities, not mandatory endpoint names. A contract can combine or separate them, but consumers should know what they send, what authority responds and which guarantee survives retries, releases and downstream handoffs.
Request
Market, language, channel, account or role and effective time
Response
Product families, availability, entry points, labels, assets and catalogue revision
Guarantee
Only published and permitted products are exposed for the supplied context
Request
Product ID, channel context and optional known template or saved revision
Response
Configuration ID, defaults, current state, allowed actions, messages and version set
Guarantee
The returned state is valid or explicitly marked incomplete with resolvable requirements
Request
Configuration revision plus user intent such as option, dimension or quantity change
Response
Accepted canonical state, consequences, allowed values, validation and new revision
Guarantee
Clients cannot bypass dependencies, exclusions or dimensional constraints
Request
Configuration revision and authoritative commercial context
Response
Status, currency, lines, total, provenance, validity and approval requirements
Guarantee
The result identifies its configuration and calculation source revisions
Request
Configuration revision, target device or visual mode and requested viewpoint
Response
Asset manifests, node or material bindings, transforms, camera and snapshot capability
Guarantee
The visible scene maps to the same structured selection used by price and output
Request
Configuration revision, permitted identity, label and optional customer context
Response
Durable project reference, share policy, expiry and continuation URL or token
Guarantee
Reloading identifies whether the saved revision is current, historical or needs migration
Request
Accepted configuration, price result or token, customer and channel action context
Response
Quote, cart or review reference plus status and destination link
Guarantee
Retries do not create unintended duplicates and the destination retains configuration identity
Request
Approved configuration and named release status
Response
Order structure, BOM class, files, documents, destination acknowledgement or review hold
Guarantee
Output is revisioned, attributable and cannot silently change after release
Request
Meaningful completed action with event, object and tenant identity
Response
Acknowledgement, delivery status or subscriber processing result
Guarantee
Events are authenticated, deduplicated, replayable by policy and observable
Request
Authorized draft change, validation action, publication or rollback
Response
Draft and published revisions, affected objects, checks and release status
Guarantee
Customer APIs cannot perform privileged catalogue or price administration
Canonical response
A useful response connects identity, context, accepted selections, derived values, validity, allowed next changes, commercial status and versions. The example is a design pattern to adapt—not a promise of one fixed Configurix payload.
{
"configurationId": "cfg_01J8P4A2",
"revision": 14,
"status": "valid",
"context": {
"product": "pergola_bioclimatic_04",
"market": "NL",
"language": "nl-NL",
"channel": "dealer-web",
"account": "dealer_havenform"
},
"selection": {
"widthMm": 4200,
"projectionMm": 3500,
"roof": "louvered",
"finish": "anthracite",
"sideScreen": true,
"ledLighting": true
},
"derived": {
"postCount": 4,
"roofBays": 2,
"areaM2": 14.7
},
"allowed": {
"projectionMm": { "min": 2500, "max": 5000, "step": 100 },
"finish": ["anthracite", "black", "white", "bronze"]
},
"messages": [],
"commercial": {
"status": "priced",
"priceResultId": "price_7K2",
"currency": "EUR",
"total": "10440.00",
"validUntil": "2026-08-26T23:59:59Z"
},
"versions": {
"api": "2026-08",
"catalogue": "PERG-EU-12.4",
"rules": "rules_perg_8.2",
"price": "DEALER-NL-8",
"visual": "scene_pergola_04@3.2.0"
},
"links": {
"self": "/configurations/cfg_01J8P4A2/revisions/14",
"continue": "/projects/cfg_01J8P4A2",
"snapshot": "/configurations/cfg_01J8P4A2/revisions/14/snapshot"
}
}Transport and delivery patterns
REST, GraphQL, webhooks and embedded bridges solve different communication problems. A mature architecture can use more than one while preserving the same canonical product and transaction identity.
Good fit
Clear resources and commands such as configurations, evaluations, prices, quotes and orders.
Strength
Familiar HTTP semantics, cacheable reads, explicit operation contracts and broad tooling.
Watch: Avoid turning every option change into an unrelated resource mutation with no canonical state response.
Good fit
Channel teams need typed access to related catalogue, configuration and presentation data with different field needs.
Strength
Strong schema, introspection and client-selected response shape can support varied frontends.
Watch: Query flexibility does not replace configuration commands, authorization, cost limits, revisioning or business-flow protection.
Good fit
Lead, quote, order, catalogue or status transitions that other systems can process asynchronously.
Strength
Decouples the interactive response from slower destinations and supports multiple subscribers.
Watch: Sign payloads; define ordering, retry, deduplication, replay, dead-letter and reconciliation behavior.
Good fit
A faster branded launch where the configurator owns its interaction but the parent site supplies context and receives events.
Strength
Less frontend reconstruction while still connecting identity, analytics, resize, save and transaction actions.
Watch: This is not fully headless. Define parent-child origin, message schema, navigation, consent and failure behavior.
State and revision design
A client submits the intended change. The configuration service applies rules and returns the accepted state plus consequences. The frontend does not become an alternative rule engine.
Mutations reference the state revision they were based on. If another actor or process changed the project, the API rejects or reconciles deliberately instead of overwriting silently.
Products, options, components, assets, price sources, configurations and outputs use durable identifiers. Labels, ordering and translations can change without breaking saved projects.
A result may depend on application, catalogue, rules, price, asset, document and integration contracts. Capture the relevant set so the state can be explained later.
The contract distinguishes valid, incomplete, invalid, review-required, unpriced and unavailable states. A missing price must never become zero and a warning must not become an approval.
Saved configurations declare whether they reopen exactly, migrate to a new catalogue, remain view-only or require review. The policy is a product decision, not an accidental API side effect.
API security model
Headless expands the number of consumers and exposed operations. Authorization must follow tenant, object, property and action boundaries while resource and sensitive workflow controls protect more than credentials alone.
Check tenant, account, project and configuration access on every object request—not only at login.
Return only fields permitted for the role; dealer margin, internal cost and production notes must not leak through broad schemas.
Separate public configuration from price administration, catalogue publication, exports and privileged workflow actions.
Bound payload, dimensions, query cost, rendering work, file size, request rate, session count and expensive business operations.
Protect quote creation, checkout, invitation, account-price lookup and large export flows from scripted abuse.
Keep private service tokens server-side, scope permissions, rotate secrets and distinguish browser, workforce and service identities.
Validate requests and upstream responses against explicit contracts; never trust integrated APIs merely because they are internal.
Maintain an endpoint and event inventory with owners, versions, exposure, data classes, consumers and deprecation dates.
Implementation sequence
Start with business authority and one real vertical slice. A long endpoint inventory built before the canonical product and outcome are clear usually creates more integration work, not a reusable platform.
Name the customer journeys, identities, markets and final business outputs. Headless is an architecture choice, not a requirement by itself.
For catalogue, rules, state, price, assets, customer, cart, order and production, name the system that owns the accepted value.
Define stable IDs and revisions before endpoint shapes. Include configuration state, context, provenance and historical behavior.
Describe the calls required to start, change, validate, price, save, reopen and transact for each channel and failure condition.
Use machine-readable API and payload schemas, examples, error models, permissions, limits and lifecycle policy.
Connect one real product from channel UI through rules, price, saved state and one destination. Do not prove architecture with mock data alone.
Define timeouts, retries, idempotency, concurrency, partial failure, event replay and reconciliation before load or outage testing.
Test object, property and function authorization plus payload limits, query cost, latency and dependency failure.
Make provider and consumer checks part of releases; test historical configurations and destination acknowledgements.
Monitor service objectives, traces, errors, event lag, schema use and deprecations. Publish migration paths before removing behavior.
Architecture failure patterns
The failure is rarely the protocol itself. It is missing authority, weak identity, duplicated rules, unsafe retry or a contract that describes syntax but not business meaning.
The API exposes products and options but not allowed transitions, derived values or authoritative validation.
Control: Return canonical evaluated state and consequences for every configuration mutation.
Website, dealer portal and mobile app each hide or disable options differently, creating channel-specific truth.
Control: Keep validation authoritative in the service and return presentation-ready permission and message data.
Every request transfers the complete catalogue, all assets, private commercial fields and unrelated state.
Control: Design bounded resources, field permissions, pagination or query limits and staged asset loading.
A client sends selected labels and expects a total without configuration revision, account context or source identity.
Control: Calculate from canonical IDs, exact state revision and explicit commercial context.
A network timeout causes the client to resubmit and creates multiple leads, quotes, cart lines or orders.
Control: Define idempotent business commands, durable action identity and destination reconciliation.
The browser reports an error but no team can follow the request across configuration, pricing and destination services.
Control: Propagate correlation identity, structured events, service timing and actionable failure codes.
A response field or behavior changes in place and silently breaks one of several independent channel teams.
Control: Publish compatibility rules, consumer usage, deprecation notice, migration examples and removal gates.
Documentation omits tenant rules, rate limits, lifecycle, authorization or historical state because the first consumer shared tribal knowledge.
Control: Treat each contract as an independent product with owners, examples, limits and acceptance evidence.
API-first vendor evaluation
Ask each provider against one real product, channel and outcome. Require schemas, examples, limits, failure demonstrations and versioned evidence instead of accepting “API available” as a complete answer.
Which services are genuinely API-first, and which capabilities require the vendor's own frontend?
Can the API return allowed next choices, rule consequences and validation—not only product attributes?
What is the canonical configuration object, and which revisions identify it completely?
How are incomplete, invalid, review-required, unavailable and unpriced states represented?
Can website, dealer, mobile and showroom channels share saved projects without sharing unauthorized fields?
Which system owns list, account, market, discount, tax and final transaction pricing?
How are concurrent changes to one saved configuration detected and resolved?
Can historical configurations reopen after catalogue, rule, price or asset changes?
What REST, GraphQL, webhook, SDK or embedded-bridge contracts are available and documented?
Are OpenAPI, GraphQL schema, JSON Schema, examples and error models available for automated checks?
How are contracts versioned, deprecated, measured for use and eventually removed?
What latency, availability, payload and rate limits apply to each interactive call?
What happens in the channel when configuration, pricing, asset or destination services are unavailable?
How are create operations protected from duplicates after client retries or destination timeouts?
How are webhook signatures, ordering, retries, replay and dead-letter cases handled?
How are tenant, object, property and function permissions enforced and tested?
Which tokens may exist in a browser, and which credentials must remain in a server-side layer?
Can traces connect a customer action to configuration, price, quote, cart, order and destination records?
What consumer contract, load, security and end-to-end tests are included in release evidence?
Who owns frontend accessibility, SEO, analytics, upgrades and support when the experience is custom-built?
Primary architecture references
These sources define widely used API descriptions, payload validation, query schemas, API security, headless commerce and composable principles. They do not define your product rules or ownership; those remain business-specific requirements.
The language-agnostic standard for describing HTTP API capabilities so people and software can understand a service without reading its source code.
The current published JSON Schema specification for describing and validating JSON instance structure and constraints.
The official GraphQL resource explains its strongly typed schema, predictable responses, introspection and query model.
The OWASP API Security Project covers object and property authorization, resource consumption, sensitive flows, inventory and unsafe API consumption.
Shopify's official headless documentation shows how commerce capabilities can serve web, app and other custom storefront experiences through an API.
The MACH Alliance describes open, composable and connected architecture through transparent APIs, headless capabilities and independently evolvable components.
Headless product configurator FAQ
Continue the architecture
Define the API boundary between governed configuration state, accepted product definitions, digital-thread events and synchronized operational twins.
Open guideSeparate human federation, service identities, tenant membership, roles and object authorization across headless channels.
Open guideMap CRM, ERP, ecommerce, PIM, pricing, quote, BOM and analytics ownership across the complete workflow.
Open guideDefine stable product, option, component, configuration and revision identity before publishing contracts.
Open guideModel dependencies, dimensions, derived values, validation messages and authoritative state transitions.
Open guideApply identity, tenant boundaries, authorization, file controls, retention, audit and incident readiness.
Open guideVerify contracts, journeys, roles, failure recovery and cross-domain outputs with versioned evidence.
Open guideConnect configuration identity, pricing, cart, checkout, saved projects and B2B or B2C commerce.
Open guideBring one real channel and product