Keep variants in sync and carry the design to checkout

This guide explains how Composerie keeps your Shopify variant selection correct when it shows its own variant controls, and how the customer’s design travels with the order all the way to your print provider. It is for merchants who want to understand what happens behind the scenes at the product page and checkout, especially when a variant goes out of stock. You do not need to configure anything here. This is reference material so you know the order is charging the right variant and carrying the right design.

A quick note on terms. Composerie offers different storefront modes, and they behave differently here. On-page mode shows the customizer right on your normal product page. Full-page mode opens a dedicated personalization page on your own domain. Linked mode connects a Shopify product to a Composerie design without showing a customizer on the page.

How variant selection stays correct

In On-page mode, Composerie replaces your theme’s variant picker with its own controls. It can show those controls as a dropdown, swatches, radio buttons, a segmented bar, or visual cards. Your theme’s native variant controls are hidden, but they are not removed. Composerie keeps Shopify’s hidden variant field in sync underneath the surface.

Here is what happens when a shopper picks a variant. Composerie writes the chosen variant back into the hidden Shopify select[name=id] field and fires a change event, so the native cart form will submit the correct variant. It also updates the ?variant= value in the page URL (the pattern Dawn and similar themes use) and dispatches a variant:change event so other scripts on the page stay in step. The result is that the price, the stock status, and the add-to-cart button all match the variant the shopper sees selected.

Out-of-stock values are handled too. Composerie detects which option values are unavailable and shows them disabled in its own variant UI, with an “Out of Stock” label. A shopper cannot select a disabled value, so they cannot add an unavailable variant to the cart.

Screenshot to capture On-page customizer showing Composerie variant swatches above the personalization fields

Linked and Full-page modes do not replace your variant UI, so there is nothing to sync in those modes.

• In Linked mode, the page shows your normal Shopify variant picker. Shopify handles the selection on its own.
• In Full-page mode, the personalization happens on a dedicated page on your own domain, so the standard theme behavior applies there.

How the design reaches checkout

Once a shopper has personalized a product, the design needs to travel with the item through checkout and into the order. How that happens depends on the storefront mode.

For On-page and Full-page modes, the chosen variant and a reference to the design both ride along on the cart line. Checkout then charges the correct variant, and the order carries the design reference. When the order webhook arrives, Composerie reads the _composerie_design_id property on each line to find the design for that personalized item.

Full-page mode runs on your own store’s origin. That means add-to-cart uses the same-origin Shopify AJAX cart at /cart/add.js, and the shopper is returned to your theme’s normal cart and checkout. There is no iframe and no cross-origin hop.

Linked products work differently. A Linked product ships no line properties, so there is no design reference on the cart line. Instead, Composerie resolves the design on the server when the order comes in. It matches the order’s variant to its design through the variant mapping you set up in the dashboard.

Either way, the outcome is the same. The order in Shopify ends up connected to the correct design, so fulfillment can produce the right print file for that item.

Next

To understand exactly how the cart line is built and what data Composerie attaches at add-to-cart, read how the cart interceptor works.