Browser API

The hosted loader exposes a command API through window.virtualfit. Define the queue before loading the script so early commands replay in order.

window.virtualfit = window.virtualfit || function () {
  (window.virtualfit.q = window.virtualfit.q || []).push(arguments);
};

`init`

Initialize one storefront configuration.

virtualfit('init', {
  siteKey: 'site_pub_your_key',
  mount: '.product-media'
});

siteKey is required. Calling init starts product matching and keeps it current as the page URL changes. See Loader configuration for all fields.

`setContext`

Patch multiple parts of the active configuration.

virtualfit('setContext', {
  product: {
    id: 'sku-10042',
    handle: 'linen-midi-dress'
  },
  customer: {
    id: 'customer-8421'
  }
});

Use setContext when a single application state update changes both product and customer context.

`setProduct`

Set or replace the current product and optional exact variant context.

Product
Exact variant

virtualfit('setProduct', {
  id: 'dress-10042',
  handle: 'linen-midi-dress',
  title: 'Linen Midi Dress',
  imageUrl: 'https://cdn.example.com/linen-midi-dress.jpg'
});

virtualfit('setProduct', {
  id: 'dress-10042',
  handle: 'linen-midi-dress',
  title: 'Linen Midi Dress',
  imageUrl: 'https://cdn.example.com/linen-midi-dress.jpg',
  variantId: 'linen-black-petite-2',
  variantImageUrl: 'https://cdn.example.com/linen-black.jpg'
});

Provide id or handle. The value must resolve to a synced, enabled product with usable garment images.

string

Stable product ID used during catalog sync.

string

Synced product handle. Provide id or handle; providing both is recommended.

string

Current shopper-facing product title.

string

Display fallback for the current product. It does not override prepared catalog media.

string

Exact source_variant_id synced under this product. Use it when the shopper has selected a specific variant.

string

Optional display hint for the selected variant. virtual.fit verifies the variant against the synced product and uses canonical prepared variant media for try-on.

Call setProduct after an SPA commits a product route when URL detection cannot identify the product. Call it again when the product or selected variant changes. Keep id stable across all variants of one product. Use variantId for the exact color, style, fit, and size combination. A size-only variant can reuse the product’s shared prepared media. A color or pattern variant uses its own prepared media when you synced it.

A variant ID must belong to the supplied product and must be available when availability is known. An unknown, mismatched, or unavailable variant fails with an actionable error instead of silently using the wrong garment.

`setCustomer`

Update shopper identity after login, logout, or account switching.

virtualfit('setCustomer', {
  id: 'customer-8421',
  email: '[email protected]'
});

Clear identity on logout:

virtualfit('setCustomer', {
  id: '',
  email: ''
});

Set customer context as early as possible so try-on and commerce events join to the same shopper journey.

`setConsentMode`

Choose whether analytics may include shopper identity.

virtualfit('setConsentMode', 'cookieless');

Supported values:

Value	Behavior
`consented`	Analytics may include the resolved shopper identity.
`cookieless`	Analytics omits shopper identity and uses cookieless measurement.

Call this when your consent manager initializes and whenever the shopper changes analytics consent.

consentManager.onChange(({ analyticsAllowed }) => {
  virtualfit(
    'setConsentMode',
    analyticsAllowed ? 'consented' : 'cookieless'
  );
});

See Privacy and consent. Request hydrated products for a storefront placement:

const result = await virtualfit('recommend', {
  intent: 'likely_purchases',
  excludeProductIds: ['sold-out-belt'],
  limit: 8
});

renderRecommendations(result.items);

Use similar for same-category alternatives, complete_the_look for the next category in an outfit, and likely_purchases for general “You may also like” or cart recommendations. If intent is omitted, the browser API defaults to likely_purchases. The hosted browser API supplies shopper identity automatically and keeps the existing merchant order if a recommendation request is rate-limited. See the Recommendations API rate limits for backend integrations. virtual.fit automatically uses the active product and products selected in the fitting room. likely_purchases can return products from categories already represented in the context. Pass the latest cart contents as cartProductIds. This augments the automatically resolved current product and fitting-room selection:

const result = await virtualfit('recommend', {
  intent: 'likely_purchases',
  cartProductIds: ['linen-shirt', 'tailored-trousers'],
  excludeProductIds: ['sold-out-belt']
});

Send the complete current cart, including an empty array after the shopper removes its last item. An explicit cartProductIds value is authoritative for that call. On a single-page storefront, you may call recommend immediately after setProduct or a product-bearing setContext call. The loader waits for the newest product resolution, so the request cannot fall back to the previously mounted product. To replace all automatically resolved context instead, pass productIds:

const result = await virtualfit('recommend', {
  intent: 'complete_the_look',
  productIds: ['linen-shirt', 'tailored-trousers'],
  excludeProductIds: ['sold-out-belt', 'hidden-accessory']
});

productIds must contain one to five outfit IDs for complete_the_look and exactly one ID for similar. For likely_purchases, it may contain zero to five IDs: productIds: [] deliberately suppresses automatic page and fitting-room context so a supplied cartProductIds array can be the entire request context. A non-array value is rejected. selectedProductIds, cartProductIds, and excludeProductIds must also be arrays when supplied. excludeProductIds is a hard per-request override and accepts up to 500 IDs. Context products are always excluded automatically.

Copy-paste recommendation placements

Call recommend after the hosted loader is ready. Giving the loader script an ID makes that easy on a server-rendered storefront:

<script
  id="virtual-fit-loader"
  async
  src="https://virtual.fit/vfr/v1/vfr.js"
></script>
<script>
  function whenVirtualFitReady(callback) {
    if (window.VirtualFit?.recommend) {
      callback();
      return;
    }

    document
      .getElementById('virtual-fit-loader')
      .addEventListener('load', callback, { once: true });
  }
</script>

Keep the queued virtualfit('init', ...) block before the loader, as shown in the Custom JavaScript quickstart.

Product page: similar products

The current synced product is supplied automatically. This example renders a basic accessible row and leaves the placement hidden if recommendations are unavailable:

<section id="similar-products" hidden>
  <h2>You may also like</h2>
  <div data-recommendation-items></div>
</section>

<script>
  function productURL(product) {
    // Adapt this to your storefront's product routing.
    return '/products/' + encodeURIComponent(product.handle);
  }

  function renderProductCards(section, products) {
    const list = section.querySelector('[data-recommendation-items]');
    const fragment = document.createDocumentFragment();

    for (const product of products) {
      const link = document.createElement('a');
      link.href = productURL(product);

      const image = document.createElement('img');
      image.src = product.preview_image_url;
      image.alt = product.title;
      image.loading = 'lazy';

      const title = document.createElement('span');
      title.textContent = product.title;

      link.append(image, title);
      fragment.append(link);
    }

    list.replaceChildren(fragment);
    section.hidden = products.length === 0;
  }

  async function loadSimilarProducts() {
    const section = document.getElementById('similar-products');
    section.setAttribute('aria-busy', 'true');

    try {
      const result = await window.VirtualFit.recommend({
        intent: 'similar',
        limit: 6
      });
      renderProductCards(section, result.items);
    } catch (error) {
      section.hidden = true; // Keep your existing merchandising row visible.
    } finally {
      section.removeAttribute('aria-busy');
    }
  }

  whenVirtualFitReady(loadSimilarProducts);
</script>

Cart drawer: likely purchases

Always read the full live cart after an add, removal, quantity change, or checkout. productIds: [] makes this a cart-only request instead of also using the product page behind the drawer:

let cartRecommendationRequest = 0;

async function refreshCartRecommendations(cart) {
  const request = ++cartRecommendationRequest;
  const cartProductIds = cart.items.map((item) => String(item.productId));

  if (cartProductIds.length === 0) {
    renderCartRecommendations([]);
    return;
  }

  try {
    const result = await window.VirtualFit.recommend({
      intent: 'likely_purchases',
      productIds: [],
      cartProductIds,
      excludeProductIds: unavailableProductIds,
      limit: 8
    });
    if (request !== cartRecommendationRequest) return;
    renderCartRecommendations(
      result.fallbackUsed ? existingMerchandisingFallback : result.items
    );
  } catch (error) {
    if (request !== cartRecommendationRequest) return;
    renderCartRecommendations(existingMerchandisingFallback);
  }
}

whenVirtualFitReady(() => {
  cartStore.subscribe((cart) => {
    refreshCartRecommendations(cart);
  });
});

Omit productIds: [] when you want the current product or fitting-room selection to augment the cart instead. The request counter prevents a slower response for an older cart from replacing recommendations for the latest cart.

Custom outfit builder: complete the look

Send the complete current outfit whenever a shopper adds or removes an item. The first product is treated as the primary outfit item and all supplied products are excluded from results automatically:

let outfitRecommendationRequest = 0;

async function refreshOutfitRecommendations(selectedProducts) {
  const request = ++outfitRecommendationRequest;
  const productIds = selectedProducts
    .map((product) => String(product.id))
    .slice(0, 5);

  if (productIds.length === 0) {
    renderOutfitRecommendations([]);
    return;
  }

  try {
    const result = await window.VirtualFit.recommend({
      intent: 'complete_the_look',
      productIds,
      excludeProductIds: hiddenOrUnavailableProductIds,
      limit: 8
    });

    if (request !== outfitRecommendationRequest) return;
    renderOutfitRecommendations(result.items);
  } catch (error) {
    if (request !== outfitRecommendationRequest) return;
    renderOutfitRecommendations([]);
  }
}

An empty items array is a valid result when there is no compatible open outfit category. Hide the row instead of replacing it with unrelated products.

Load another page

Pass the returned cursor with the same context and intent:

const firstPage = await window.VirtualFit.recommend({
  intent: 'likely_purchases',
  cartProductIds: currentCartProductIds,
  limit: 8
});

if (firstPage.nextCursor) {
  const nextPage = await window.VirtualFit.recommend({
    intent: 'likely_purchases',
    cartProductIds: currentCartProductIds,
    cursor: firstPage.nextCursor,
    limit: 8
  });

  appendRecommendationCards(nextPage.items);
}

The promise resolves to:

{
  items: [
    {
      product_id: 'leather-loafer',
      target_type: 'variant',
      variant_id: 'leather-loafer-black-38',
      rank: 1,
      score: 1.274,
      title: 'Leather Loafer',
      preview_image_url: 'https://cdn.example.com/loafer.jpg'
    }
  ],
  nextCursor: null,
  fallbackUsed: false
}

Items are in display order, and rank is authoritative. score is optional and meaningful only within that response. Do not re-sort items by score or compare scores across requests. A recommendation may target the whole product, a visual choice, or one exact variant. Render one card per product. When variant_id is present, use it to preselect the recommended variant or pass it as variantId after navigation. virtual.fit does not return several cards for different variants of the same product. Keep your existing merchandising order as the placement fallback when a request fails. An empty successful complete_the_look response is valid when the outfit has no compatible open slot or no eligible product is available for that slot. Hide the empty row instead of filling it with unrelated products.

`track`

Send a commerce event.

virtualfit('track', 'product_added_to_cart', {
  cartId: 'cart-123',
  quantity: 1,
  totalAmount: 79,
  currency: 'USD',
  productId: 'sku-10042',
  productHandle: 'linen-midi-dress',
  productTitle: 'Linen Midi Dress'
});

virtual.fit adds the current product context when it is available. Explicit payload fields take precedence. Only call track after storefront analytics has initialized. Events sent before analytics is ready are not queued and may be dropped with a console warning. See the commerce event reference →

Object-style alias

The loader also exposes window.VirtualFit:

window.VirtualFit.setProduct({
  id: 'sku-10042',
  handle: 'linen-midi-dress'
});

Available methods are init, setContext, setProduct, setCustomer, setConsentMode, recommend, and track. Prefer the queued virtualfit(...) form for commands that do not return a value. Call recommend after the hosted loader has initialized because it returns a promise with the ranked products.

SPA integration pattern

router.afterEach((route) => {
  if (route.type !== 'product') return;

  virtualfit('setProduct', {
    id: route.product.id,
    handle: route.product.handle,
    title: route.product.title,
    imageUrl: route.product.featuredImage,
    variantId: route.selectedVariant?.id || '',
    variantImageUrl: route.selectedVariant?.featuredImage || ''
  });
});

Keep one loader and one initialization per page. Update context instead of injecting another script after each route or variant change.

Get started

Shopify

Custom JavaScript

Recommendations

Operate

API reference

`init`

`setContext`

`setProduct`

`setCustomer`

`setConsentMode`

Copy-paste recommendation placements

Product page: similar products

Cart drawer: likely purchases

Custom outfit builder: complete the look

Load another page

`track`

Object-style alias

SPA integration pattern

​init

​setContext

​setProduct

​setCustomer

​setConsentMode

​recommend

​Copy-paste recommendation placements

​Product page: similar products

​Cart drawer: likely purchases

​Custom outfit builder: complete the look

​Load another page

​track

​Object-style alias

​SPA integration pattern

`init`

`setContext`

`setProduct`

`setCustomer`

`setConsentMode`

`recommend`

Copy-paste recommendation placements

Product page: similar products

Cart drawer: likely purchases

Custom outfit builder: complete the look

Load another page

`track`

Object-style alias

SPA integration pattern