Skip to content

realtimeLookupSubstore

When realtime lookup is enabled for your tenant, the SDK calls /api/realtime-lookup for settings and debounced POST lookups while the customer configures product options. Responses can mutate catalog data for selected SKUs (today: dynamic price on product options) before constraints and BOM run.

You normally do not call lookup yourself — the substore subscribes to the active config’s values and quantities, plans SKU context, merges mutations into form evaluation, and triggers formSubstore.runConstraints when new data arrives.

Table of contents

Properties

Per-config state (RealtimeLookupStoreItem)

Hooks

Properties

settings

settings: ApiResource<{ enabled: boolean }>

Whether realtime lookup is turned on for this session. When enabled is false, lookup configs are cleared and no POST requests are sent.

Fetched automatically on store init via the realtimeLookupSettings query.

lookupConfigs

lookupConfigs: Record<number, RealtimeLookupStoreItem>

Per-configuration lookup state. Entries are created when configsSubstore.addConfig runs (and copied/removed with config copy/remove). Cleared on full reset, pre-config with reset: true, and when restoring drafts or request copies.

Use useRealtimeLookupByConfigId or useRealtimeLookupByCurrentConfigId to read one config’s item — the raw map is mainly for debugging.

Per-config state (RealtimeLookupStoreItem)

mutationsBySku

mutationsBySku: Record<string, RealtimeLookupMutationFields>

Latest merged field overrides keyed by product SKU. Known fields:

FieldTypeEffect
pricenumber (optional)Overrides the option’s sales price during constraint evaluation and pricing

Mutations are applied together with formSubstore dynamic prices when building constraint input.

loadingSkus

loadingSkus: Set<string>

SKUs currently waiting on a debounced lookup response (~300 ms debounce). Use this to show per-option loading indicators in custom UIs.

committed

committed: LookupCommitted | null

Internal snapshot of the last successfully committed lookup request for this config. Not required for typical integrations.

React / Vue selectors

The SDK exposes:

HookScope
useRealtimeLookupEntire substore (e.g. settings)
useRealtimeLookupByCurrentConfigIdActive config’s RealtimeLookupStoreItem
useRealtimeLookupByConfigId(id, selector)A specific config

Example — show a spinner while any selected product SKU is loading:

const loadingSkus = sdk.useRealtimeLookupByCurrentConfigId(
  (item) => item?.loadingSkus,
);
const isLoading = loadingSkus && loadingSkus.size > 0;

Related