A Stylux fulfillment bundle with more than one line generally consists of a base product and associated upsell products used to represent personalization pricing. Those related lines must have matching quantities.

This applies when the bundle is first added and after the customer changes the cart. If one line changes quantity or is removed, every line with the same bundle ID must be updated.

SDK Normalization

Enable normalization through the top level cart configuration, in the setup call after you load the SDK:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  cart: {
    adapter: cartAdapter,
    mutationPathFragments: ['/api/cart'],
    normalize: true,
  },
});

Normalization requires a cart adapter and bundle information recorded by SDK checkout. The SDK reads lines through getCart, then uses the adapter's silent write methods inside a CART_NORMALIZATION transaction when it needs to restore matching lines or quantities.

mutationPathFragments tells the SDK which storefront requests represent cart mutations. String entries match URL path fragments. Entries may also be path regular expressions, request functions, or { path, method, body } objects; every field in an object must match. After a matching request finishes, the SDK runs normalization. At least one effective matcher is required for normalization, including the initial pass during setup. Explicit matchers replace plugin defaults; an empty array disables normalization. See Cart Adapter for the matcher shapes.

Bundles with a single line do not need balancing and are skipped. UPSELL fulfillment offers also follow a different cart relationship and are not normalized as a base and upsell fulfillment bundle.

Legacy integrations that write cart lines from BUNDLE_CREATE do not populate SDK checkout storage. Do not enable SDK normalization for those manually written lines; migrate to a cart adapter so checkout and normalization share the required bundle information.

Shopify Defaults

The Shopify plugin provides a cart adapter, enables normalization by default, and registers these mutation path fragments when none are supplied:

• cart/change
• cart/update
• cart/add

You can explicitly override the default:

await Stylux.setup({
  apiKey: 'STLX_key-for-unsigned-requests',
  merchantId: 'merchant-id',
  cart: {
    normalize: false,
  },
  plugins: {
    shopify: true,
  },
});

The legacy Shopify normalizeCart option remains supported as a fallback, but cart.normalize is the preferred configuration.