📦 WooCommerce integration

How to integrate the PrintWearAI configurator on a WordPress / WooCommerce store: theme snippet, automatic add-to-cart via wc-ajax, product sync and mapping.

How it works

1. embed.js injects the 3D configurator as an iframe on your product pages. On WooCommerce it auto-detects the current product: body.single-product, the input[name=product_id] / input[name=variation_id] field, the postid-N body class and the .sku element.
2. When the customer clicks add-to-cart inside the configurator, the widget emits an add_to_cart event to your page.
3. The built-in PwaiEmbed.handlers.woocommerce() handler posts the item to the WooCommerce cart via POST /?wc-ajax=add_to_cart.

Step 1 — Install the snippet in your theme

Add the snippet to your product template (child theme single-product.php, a hook in functions.php, or a "custom HTML" block/snippet plugin):

<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.woocommerce();   // automatic WooCommerce cart
  });
</script>

• data-key is your public embed key (fk_…), found in your workspace → Integration. It is required — the widget only reads data-key.
• Without a #pwai-configurator div, the widget inserts itself near your product form (.woocommerce-product-gallery, .product .summary, 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", data-no-consent="true".

Step 2 — Connect your store (product sync)

Tenant workspace → Integrations → WooCommerce → Connect:

• Shop URL — e.g. https://myshop.com
• Consumer key / Consumer secret — WooCommerce → Settings → Advanced → REST API → Add key, with Read permission. The connection is validated live against /wp-json/wc/v3/system_status before it is saved.
• Webhook secret (optional) — used to verify incoming WooCommerce webhooks (see below).

Then click Sync (runs automatically after connecting). PrintWearAI imports your published products from /wp-json/wc/v3/products — id, SKU, name, price, image and permalink — into your external products catalog.

Step 3 — Map WooCommerce products to 3D products

In Integrations → Product mapping, link each imported WooCommerce product to one of your 3D products. Linking stores external_product_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 WooCommerce product id, so the handler adds the correct product.

You can also set the external ids manually per product in Products → edit → External catalog link.

Automatic add-to-cart

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

1. Reads m.product.external_product_id. If it is missing it logs a warning and does nothing — the product must be mapped.
2. Sends POST /?wc-ajax=add_to_cart (with cookies, so the item lands in the visitor's session cart) with these form fields:

3. Redirects to /panier/ (disable with { redirect: false } — see pitfalls below if your cart lives at another URL).

WooCommerce core ignores extra POST fields by default. To persist the flare_* fields as cart/order item meta, add a small snippet in your (child) theme's functions.php:

add_filter('woocommerce_add_cart_item_data', function ($data) {
  foreach (['flare_config_id', 'flare_thumbnail', 'flare_sizes'] as $f) {
    if (!empty($_POST[$f])) $data[$f] = sanitize_text_field(wp_unslash($_POST[$f]));
  }
  return $data;
}, 10, 1);

add_action('woocommerce_checkout_create_order_line_item', function ($item, $key, $values) {
  foreach (['flare_config_id', 'flare_thumbnail', 'flare_sizes'] as $f) {
    if (!empty($values[$f])) $item->add_meta_data($f, $values[$f]);
  }
}, 10, 3);

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_product_id, m.customization.thumbnail …
});

Keep products in sync (WooCommerce → PrintWearAI webhook)

To update your imported catalog without manual re-syncs, create WooCommerce webhooks (WooCommerce → Settings → Advanced → Webhooks) for the topics product.created and product.updated, pointing to:

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

Use the same webhook secret as saved in Integrations: the X-WC-Webhook-Signature header is verified and 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.
• Redirected to /panier/ but my cart is at /cart/ — the built-in redirect targets /panier/. Call PwaiEmbed.handlers.woocommerce({ redirect: false }) and redirect yourself, or use PwaiEmbed.onAddToCart(fn).
• Console warning "product_id Woo manquant" — the 3D product has no external_product_id. Link it in Integrations → Product mapping, or set it manually in Products.
• Add-to-cart opens the PrintWearAI hosted cart instead of the Woo 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.woocommerce() (or PwaiEmbed.onAddToCart(fn)).
• Variable products — sync stores the parent product id only (no variation id). The handler posts product_id; if you need a specific variation, handle it yourself with PwaiEmbed.onAddToCart(fn).
• Sync fails with "WooCommerce HTTP 401" — wrong consumer key/secret, or the key lacks Read permission.
• Upgrade notice instead of the widget — the embedded widget requires a Pro plan or higher.

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