The Shopify plugin is the cart integration for a standard Online Store theme. It keeps personalized lines balanced, updates the offer when the selected variant changes, and opens Stylux from the theme's add to cart button.

On the personalization product page, the theme add to cart control is hidden when that page has a single add to cart form. In the cart, links to the personalization product cannot be opened.

Use this plugin for Online Store themes. Headless storefronts should still install the Stylux Shopify application, then provide a cart adapter instead of this plugin.

Load the SDK and enable the plugin with plugins.shopify set to true, or pass an object to change the defaults below. shopify: true turns on cart normalization. Place the offer with the button offer block, or render it yourself.

Configuration

Name	Type	Description
`detectVariantChanges`	`boolean`	Detects product variant changes; defaults to `true`
`overrideAddToCart`	`boolean`	Opens Stylux from the theme add to cart button. Defaults to `true`. Offers that require personalization still open Stylux when this is `false`.
`addToCartSelector`	`string`	Add to cart control selector; defaults to `[name="add"], [name="add"] *`
`activeVariantIdSelector`	`string`	Active variant input selector; defaults to `input[name="id"], select[name="id"]`
`normalizeCart`	`boolean`	Legacy fallback for `cart.normalize`; defaults to `true` when the plugin is enabled
`sectionsForCartRequests`	`string \| string[]`	Shopify sections included in AJAX cart requests
`getQuantity`	`() => number`	Optional. Returns the active PDP quantity for offer flows that do not specify one. Defaults to `input[name="quantity"]`, or `1` if that input is missing. If the PDP has a quantity selector, this should return the currently selected quantity.
`getLineItemProperties`	`(config) => properties \| Promise<properties>`	Adds or changes line item properties for checkout adds
`getActiveSellingPlanId`	`(config) => id \| null \| Promise<id \| null>`	Returns the selling plan for a product
`beforeUpdateCart`	`(config) => void \| Promise<unknown>`	Adds extra lines before an `ADD_TO_CART` write
`afterUpdateCart`	`(payload) => void \| Promise<unknown>`	Runs after a completed cart transaction. V1 receives the Shopify cart; V2 receives `{ action, cart }`
`afterUpdateCartVersion`	`'V1' \| 'V2'`	Chooses the `afterUpdateCart` payload; defaults to `V1`
`nestedCartLines`	`boolean`	Uses Shopify nested cart line relationships; defaults to `false`

Prefer cart.normalize over plugins.shopify.normalizeCart:

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

Cart Transaction Hooks

beforeUpdateCart runs before checkout adds and can append Shopify line items:

beforeUpdateCart({ action, addLineItems }) {
  if (action === 'ADD_TO_CART') {
    addLineItems({
      items: {
        id: 'variant-id',
        quantity: 1,
      },
    });
  }
}

afterUpdateCart runs from the Shopify adapter's transaction completion behavior. The default V1 callback receives the Shopify cart. V2 receives the cart and the action that caused the transaction:

plugins: {
  shopify: {
    afterUpdateCartVersion: 'V2',
    afterUpdateCart({ action, cart }) {
      // refresh storefront cart UI for this action
    },
  },
}

Actions are ADD_TO_CART, CART_NORMALIZATION, UPDATE_CART, CLEAR_CART, and UPDATE_ATTRIBUTES. Check action and run the side effects that action needs. See Cart Adapter.

If no afterUpdateCart hook is set, ADD_TO_CART redirects to /cart. CART_NORMALIZATION, UPDATE_CART, and CLEAR_CART reload when the customer is already on a cart URL. UPDATE_ATTRIBUTES does not reload the cart.

Using a Custom Adapter

If cart.adapter is provided, the plugin does not replace it. Shopify cart behavior such as beforeUpdateCart, extra line item properties, selling plans, the default redirect, and afterUpdateCart belongs to the built-in Shopify adapter and will not run automatically.

Variant detection and add to cart override still work. Implement the cart behavior you need in your custom adapter's transact method.