🛍️ Shopify integration

How to integrate the PrintWearAI configurator on your Shopify store: theme snippet, automatic add-to-cart via /cart/add.js, product sync and variant mapping.

How it works

embed.js injects the 3D configurator as an iframe on your product pages. On Shopify it auto-detects the current product from ShopifyAnalytics.meta.product (product id, first variant id, SKU) and resolves it to your linked 3D model.
When the customer clicks add-to-cart inside the configurator, the widget emits an add_to_cart event to your page.
The built-in PwaiEmbed.handlers.shopify() handler turns that event into a real Shopify cart line via POST /cart/add.js, with the customization attached as line item properties.

Step 1 — Install the snippet in your theme

Shopify admin → Online Store → Themes → Edit code. In your product template (e.g. sections/main-product.liquid, or theme.liquid for all pages), add:

<div id="pwai-configurator"></div>

<script src="https://printwearai.com/embed.js"
        data-key="fk_YOUR_KEY"
        defer></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    PwaiEmbed.handlers.shopify();   // automatic Shopify cart
  });
</script>

data-key is your public embed key (fk_…), found in your workspace → Integration. It is required — the widget only reads data-key.
If the #pwai-configurator div is missing, the widget inserts itself before your product form (.product-form, [data-product-form], form[action*="cart"]…). Add the div explicitly to control placement.
Useful optional attributes: data-height (default 700), data-locale (fr/en/es/de/it), data-product (force a catalog slug), data-autodetect="false" (disable auto-detection), data-no-consent="true" if you already handle cookie consent.

The embedded widget requires a Pro plan or higher. On Free/Essentiel plans the widget shows an upgrade notice and your customers use your hosted configurator page instead.

Step 2 — Connect your store (product sync)

Tenant workspace → Integrations → Shopify → Connect:

Shop URL — e.g. https://my-shop.myshopify.com
Admin API access token — create a custom app in Shopify (Settings → Apps and sales channels → Develop apps) with at least the read_products scope. The connection is validated live against the Shopify Admin API before it is saved.
Webhook secret (optional) — used to verify incoming Shopify webhooks (see below).

Then click Sync (runs automatically after connecting). PrintWearAI imports your published products — id, first variant id, variant SKU, title, price, image and handle — into your external products catalog.

Step 3 — Map Shopify products to 3D products

In Integrations → Product mapping, link each imported Shopify product to one of your 3D products. Linking stores external_product_id / external_variant_id / external_sku on the 3D product, which enables:

Auto-detection — /api/resolve matches the SKU or product id found on the page and opens the right 3D model.
Cart payloads — the add_to_cart event carries the Shopify variant id, so the handler can add the correct variant.

You can also set the external ids manually per product in Products → edit → External catalog link (external platform, product id, variant id, SKU).

Automatic add-to-cart

PwaiEmbed.handlers.shopify(options) registers a handler that, for each add_to_cart event:

Picks the variant: m.product.external_variant_id, falling back to m.product.external_product_id. If neither is set it logs a warning and does nothing — the product must be mapped.
Calls POST /cart/add.js with { id: variantId, quantity: m.quantity, properties: … }.
Redirects to /cart (disable with { redirect: false }).

Line item properties attached to the cart line:

Property	Content
`_pwai_config_id`	Saved configuration id — the link to production on the PrintWearAI side
`_pwai_product`	Product name
`_pwai_thumbnail`	Preview image URL of the finished design
`_pwai_patron_url`	`options.patronEndpoint + config_id` (empty prefix if not set)
`_pwai_sizes`	JSON size breakdown, e.g. `{"M":3,"L":2}`

Options:

Option	Default	Role
`redirect`	`true`	`false` to stay on the page after adding to cart
`patronEndpoint`	`''`	URL prefix for the `_pwai_patron_url` property

Prefer full control? Register your own callback instead of the built-in handler:

PwaiEmbed.onAddToCart(function (m) {
  // m.config_id, m.quantity, m.sizes,
  // m.product.external_variant_id, m.customization.thumbnail …
});

Keep products in sync (Shopify → PrintWearAI webhook)

To update your imported catalog without manual re-syncs, create Shopify webhooks for products/create and products/update pointing to:

POST https://printwearai.com/api/webhooks/shopify/fk_YOUR_KEY

If you saved a webhook secret in Integrations, the X-Shopify-Hmac-Sha256 signature is verified and unsigned or invalid deliveries are rejected (401).

FAQ & common pitfalls

Nothing shows, console says data-key missing — you wrote data-embed-key; the widget only reads data-key.
Console warning "variant Shopify manquant" — the 3D product has no external_variant_id / external_product_id. Link it in Integrations → Product mapping, or set the ids manually in Products.
Add-to-cart opens the PrintWearAI hosted cart instead of the Shopify cart — the event is only sent to your page when the 3D product carries an external_product_id. Map the product.
Add-to-cart does nothing and logs "add_to_cart sans handler" — you forgot to call PwaiEmbed.handlers.shopify() (or PwaiEmbed.onAddToCart(fn)).
Wrong variant added — sync stores the first variant id of each product. For a specific variant, set external_variant_id manually on the 3D product.
Widget opens the wrong product — auto-detection found another SKU on the page. Force it with data-product="your-slug" or disable with data-autodetect="false".
Upgrade notice instead of the widget — the embedded widget requires a Pro plan or higher.

See also: Embed widget · Webhooks · Custom site (API)