Headless Integration Walkthrough

How much code this actually takes

The integration is one loop. Everything past it is styling — the same work you would do for any other component on your site.

Before you start

You need two values, both from your project’s Share tab: the project ID (also in the editor URL) and the share token. Turn sharing on first. Both are public by design — they already appear in every share link you have sent. See Building a Custom UI for why an API token must never be used here instead.

You also need a static file server. That is the whole toolchain.

Step 1 — Get the viewer bundle

There are two builds, and picking the wrong one is a silent failure rather than an error:

Step 2 — Render the product

Note there is no API URL to configure: the production endpoint is compiled into the package. Pass apiUrl only if you are pointing at a staging or self-hosted deployment, and sharePassword only if the share link is password-protected.

Step 3 — Build your controls

Read the project’s own option blocks and turn them into whatever markup you like. This is the entire integration — the three lines that matter are marked.

Re-read getState() inside applied rather than tracking selections yourself. When a rule reveals a block, its default option is applied automatically — with no click and no user action — so any state you kept in parallel drifts.

Step 4 — Serve it over HTTP

Step 5 — Check the payload if something looks wrong

The endpoint behind all of this needs no credential, so you can call it directly and see exactly what the viewer sees:

A wrong token is 403, not 404 — that distinction saves a lot of time. 404 means the project is not shared at all.

The API you will actually use

Reading the project

blocks, pricingBlocks, formFields and project are live references, not copies — mutating them mutates the viewer. Only visibility and getState() hand you a copy.

Driving it

Selection shapes

A number-input is a map, not a number: one block can expose several numeric parameters, and a conditional rule targets one of them specifically. Set it through setState — select() cannot express a map.

Events

Handling failure properly

isUnavailable is true only for the 402 case. Treat it as a neutral, permanent-for-now state: no retry loop, and no billing detail on the page — that is the merchant’s private business state, not the shopper’s.

Traps that fail silently

Each of these produces no error. The page simply looks wrong — or looks right and is wrong.

1. Never feed the payload’s renderQuality into quality

quality defaults to 'high'. Leave it there. The payload’s renderQuality is the editor viewport’s setting, and both the Share view and the Preview modal ignore it in favour of high. Passing it through switches off filmic tone mapping and disables shadows entirely, changing the whole look of the product relative to what was approved in the dashboard.

2. setState replaces, it does not merge

It clears the map first, so setState({ blockA: 'x' }) drops every other block’s selection. To change one block, spread the current state in: setState({ ...viewer.getState(), blockA: 'x' }). Do still use it — and not a loop of select() calls — when restoring a saved configuration: each select re-applies materials, and where two blocks target the same mesh the last one applied wins, so a loop is order-dependent.

3. A hidden block can still paint

A fixed-material block marked not visible gates the UI, not the material — it is a normal way to paint a fixed part of the product, such as metal legs or hardware. Skip hidden blocks when drawing controls; never skip them when reasoning about what is being rendered.

4. Load-time events fire before you can subscribe

progress, model-load errors, the first applied and ready all fire before the promise resolves, so viewer.on() can never observe them — there is no viewer to subscribe to yet. A loading bar wired to viewer.on('progress') never moves. Pass the onProgress, onReady, onApplied and onError options instead.

5. Variant values are only unique inside their block

Two blocks routinely both use material-1, option-1 or on/off, because values are minted per block. Key your own UI state by block id. Keying by variant value alone cross-wires two controls that look unrelated.

6. A colour alone is not a usable swatch

Texture-driven materials carry a neutral base colour, so a colour-chip UI renders several indistinguishable squares. Use the platform’s own fallback chain, in order: variant.thumbnailUrl (the merchant’s uploaded thumbnail — do not skip this rung) → variant.materialData.textureMap → a flat colour → variant.materialData.thumbnail → a neutral placeholder. Cache broken URLs so a dead link falls through to the next rung.

7. Call dispose, or the page eventually stops rendering

Browsers allow only a limited number of live WebGL contexts (commonly around sixteen, and it varies). Call viewer.dispose() when your component unmounts — releasing the renderer alone is not enough to free the GPU context. Skip it and repeated mount/unmount cycles exhaust the pool, after which a canvas on the page goes blank with no error.

8. Select Material blocks in “From Category” mode ship no variants

A Select Material block authored in From Category mode stores an empty variant list — the hosted viewer fetches the category’s materials separately at runtime. The package does not make that request, so such a block yields no buttons and paints nothing. Use Manual mode for a headless build, or fetch /share/:projectId/:token/category-materials yourself and build those controls by hand.

Going further

Showing a price

There is no anonymous pricing endpoint: the calculate route requires a credential that must never reach a browser, and browsers cannot send it anyway. Your options are to evaluate viewer.pricingBlocks and viewer.pricingFormula in the browser (both ship in the payload — this is what the hosted share view does), or to proxy the calculation through your own backend. Either way, treat a displayed price as an estimate: the server recomputes the total at checkout and that figure is the authoritative one. See API → Pricing & CPQ.

Capturing a lead

Post to /share/:projectId/:token/submit — anonymous, returns a requestId, and triggers the owner’s email, PDF and webhooks. Attach viewer.snapshot() as the screenshot. Submissions arrive in Requests.

Saved and shareable configurations

On Enterprise, the save-config and saved-configuration endpoints are anonymous too, so a shopper can email themselves a permalink. Restore it with viewer.setState(). Note the permalink the server generates is derived from the calling page’s own origin, so on a headless site you will usually want to build the link yourself from the returned id.

Checkout

Anonymous routes exist for Shopify cart permalinks, SKU-matched multi-line carts and WooCommerce checkout URLs, so a custom UI can hand off to a real basket. See Shopify and WooCommerce.

What the package deliberately does not do

It appends a canvas and nothing else. There is no UI and no viewport chrome — no floating tools, watermark, brand logo, custom loading animation or dimension overlay. It reads about sixteen of the project’s ~168 settings (lighting, exposure, camera, background, auto-rotate, shadows, zoom and pan limits), and a newly added platform setting does not reach it automatically. There is no pricing, no forms, no AR, and no modular drag-and-drop placement — modular projects render their base scene only. Selecting on a text-input, file-upload, design-canvas, pattern-designer or hotspot block stores the state and emits an event but paints nothing.

If you want the merchant’s complete experience instead, with every setting and the localised floating tools, the ?ui=viewer embed is the better trade — see Building a Custom UI.

Next steps

Every option, method and signature is in SDK → Headless Renderer. If you are considering writing your own renderer instead, API → 3D Viewer lists the rendering rules the payload does not describe — the reason this package exists. For a native app, see Mobile & Native Apps.