IdealFactory Developer Docs

Quickstart — embed the Customiser

The whole integration is one snippet. No backend, no build step, no JavaScript objects to construct — an element with data attributes mounts the Customiser, and results come back as ordinary DOM events. Works anywhere you can add HTML.

Before you start

Integration is enabled per shop by IdealFactory. At onboarding you receive:

All three come from IdealFactory when your shop is connected — there is nothing to configure on your side beyond the snippet.

Testing tip: ask for a separate test connection (its own embed key and API token, with your staging domains registered on it). Everything it creates — designs, orders, print files — stays fully separate from your live shop's, so you can integrate and experiment without touching real production data, and swap to the live keys when you go live.

Step 1 — put the Customiser on a page

Designing is an immersive activity — give the Customiser the whole viewport. The pattern that works best is a dedicated design page (or a fullscreen overlay) your product page links to:

<!-- e.g. /design — a page that is just the Customiser -->
<div data-idealfactory-customiser
     data-embed-key="ek_your_key_here"
     data-sku="YOUR_PRODUCT_SKU"
     style="position: fixed; inset: 0;"></div>
<script src="https://api.idealfactory.com/embed/v1/customiser.js" defer></script>

data-sku is your product's SKU — nothing of ours has to live in your site. It resolves to our product through the mapping on your storefront page in the IdealFactory panel; if you sell under the supplier's SKUs there is nothing to map at all. If your storefront settings let customers choose the product inside the Customiser, leave data-sku out entirely and it opens on a product selection page instead.

Your storefront page also generates this snippet for you — pick which variant you want (by SKU, one specific product, or with selection), copy, paste.

Open the page: the Customiser should appear and be fully usable — your customers can already design and upload images at this point.

Prefer it inline on the product page? Any box works — the Customiser fills whatever element it's given — but stay generous (height: 700px is a comfortable minimum on desktop).

Step 2 — capture the design on finish

When the customer clicks finish, the element fires a bubbling customiser:design-ready event:

document.addEventListener('customiser:design-ready', function (e) {
  e.detail.design_version_id  // ← store this on your cart line
  e.detail.thumbnails           // raw base64 JPEGs of the approved views
});

Your one job: put design_version_id on the cart line, exactly like a size or colour option. It is the only thing that connects the customer's design to the order you'll place later.

To show a preview in the cart, prefix a thumbnail:

img.src = 'data:image/jpeg;base64,' + e.detail.thumbnails[0];

There's also customiser:back (the customer clicked the Customiser's exit control — close your overlay or navigate back) and customiser:error (see the JavaScript reference).

Step 3 — let customers edit a design in the cart

Mount from the stored id instead of a product — data-design-version replaces data-product:

<div data-idealfactory-customiser
     data-embed-key="ek_your_key_here"
     data-design-version="STORED_DESIGN_VERSION_ID"
     style="position: fixed; inset: 0;"></div>

Elements added dynamically (a modal you inject on "edit design") mount automatically — no re-initialisation call.

Every save returns a new id — replace the one on your cart line. Design ids are immutable: a re-edit never changes an existing design, so whatever id an order cites renders exactly as it was when saved.

Shopify recipe

A design page template (or section) with the snippet, the variant's own SKU as the product, design id onto the cart as a line item property:

<div data-idealfactory-customiser
     data-embed-key="ek_your_key_here"
     data-sku="{{ product.selected_or_first_available_variant.sku }}"
     style="position: fixed; inset: 0;"></div>
<script src="https://api.idealfactory.com/embed/v1/customiser.js" defer></script>
<script>
  document.addEventListener('customiser:design-ready', function (e) {
    fetch('/cart/add.js', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        id: {{ product.selected_or_first_available_variant.id }},
        quantity: 1,
        properties: { '_if_design': e.detail.design_version_id },
      }),
    }).then(function () { window.location.href = '/cart'; });
  });
</script>

The _if_design property survives into the Shopify order's line items — which is exactly what your production integration (or your team, manually) reads when creating the production order.

Where to go next