Headless Shopify quickstart

Use the browser SDK when you want Antla’s try-on modal on your product page. It works as a custom HTML element and does not require the Shopify theme app embed.

1. Connect the store

Complete Headless SDK setup. Choose a product visible through the connected Storefront API, assigned to an Antla Funnel, with an available variant. If you are building a custom UI without the block, use Headless API instead.

2. Load the script once

Use the script URL from your Antla installation. This example uses the production CDN URL.

<script
  src="https://cdn.app-antla.com/antla-sdk/antla-sdk.js"
  defer
></script>

Load it once in your document or application shell, not every time a product component rerenders. The script registers antla-block; HTML elements already on the page upgrade when it loads.

3. Place the block on a product page

<antla-block
  sdk-key="YOUR_ANTLA_SDK_KEY"
  product-id="gid://shopify/Product/123"
  variant-id="gid://shopify/ProductVariant/456"
  cart-url="/cart"
></antla-block>

Replace both example IDs with real IDs from that merchant. The API requires a variant, but the block can choose one when variant-id is omitted.

If your storefront already owns a cart, pass its complete Storefront Cart ID at runtime:

const block = document.querySelector("antla-block");
block.setAttribute("cart-id", currentShopperCartId);

Do not hardcode a real shopper’s cart into shared HTML or a static build. Cart IDs include a secret key. Preserve the full ID in the current shopper’s session.

4. Synchronize product and variant changes

function updateTryOnContext(productId, variantId) {
  const block = document.querySelector("antla-block");
  block.setAttribute("variant-id", variantId);
  block.setAttribute("product-id", productId);
}

Changing product-id, sdk-key or language reinitializes the block. Changing variant-id updates its selection. Keep these attributes synchronized with the storefront’s active product, including after client-side navigation.

Set only IDs from the current product. Reinitialization cleans up in-flight browser work, but it does not cancel an already queued server job.

5. Connect cart state

The block adds a line using Shopify’s Storefront Cart API. It may create a cart if none is supplied. A cart created inside the block is not automatically written to Hydrogen’s server session or another framework’s cart provider.

Read Cart integration before launch. A working try-on followed by an empty /cart page usually means the block and storefront are using different cart identities.

What the SDK handles

• Loading the connected store’s public Storefront context.
• Product data, funnel resolution and Antla design settings.
• Image input and processing, storage upload and generation submission.
• Optional email collection and visitor state.
• Result polling and temporary-versus-permanent image handling.
• Shopify cart mutation and the configured cart/checkout/close action.

Your storefront owns script loading, placement, route state, cart synchronization and compatibility testing.

Confirm the result

Use a real available variant and an approved test photo. Check first load, variant switching, a second product after navigation, email-required behavior, a completed generation, add-to-cart and checkout.

The SDK renders through Shadow DOM. Theme selectors and theme event listeners are not an integration API for this block. Use the SDK reference for its actual attributes and limitations.