Adding Virtual Try-On to a Shopify Hydrogen Storefront

To add virtual try-on to a Shopify Hydrogen storefront, build a custom component and call the ZeDaq.ai REST API from a server route, because Hydrogen does not use your theme and so cannot load a theme app embed. The server route holds your x-api-key, and the component handles the photo and the result.

This is the developer path. If you run a normal Online Store theme, the Shopify app is faster, and our guide to the API for ecommerce developers explains when to choose the API instead.

Why can't you just install the app on Hydrogen?

The app's try-on button comes from a theme app embed, which needs a Shopify theme. A Hydrogen storefront is a separate React app that reads your store data through the Storefront API, so there is no theme to switch the embed on.

Shopify's own docs describe Hydrogen as a headless option that runs alongside frameworks such as React Router (Shopify Hydrogen docs). The REST API fits that model.

What do you need first?

• A ZeDaq.ai account and an API key from Dashboard → API keys, locked to your storefront domain.
• Your size charts in Dashboard → Size charts, if you also want size recommendations.
• Product image URLs from the Storefront API, such as the featured image.
• A server environment variable for the key, set through your hosting setup.

Never put the key into code that runs in the browser.

How do you call the API from a server route?

Hydrogen routes can export an action function that runs on the server when a form is submitted. The example below shows the shape; adapt how it reads the key to match your deployment.

// app/routes/api.tryon.tsx
export async function action({ request }: { request: Request }) {
  const apiKey = getZedaqKey(); // read from your server environment
  const form = await request.formData();
  const photo = form.get('photo') as File;
  const productImageUrl = String(form.get('productImageUrl'));
  const garmentType = String(form.get('garmentType') || 'upper_body');
  const toB64 = async (buf: ArrayBuffer) => btoa(String.fromCharCode(...new Uint8Array(buf)));
  const product = await (await fetch(productImageUrl)).arrayBuffer();
  const res = await fetch('https://www.zedaq.ai/api/v1/tryon', {
    method: 'POST',
    headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      person_image_base64: await toB64(await photo.arrayBuffer()),
      product_image_base64: await toB64(product),
      garment_type: garmentType,
    }),
  });
  return new Response(await res.text(), { status: res.status, headers: { 'Content-Type': 'application/json' } });
}

Resize photos in the browser before upload, because spreading a very large array into String.fromCharCode can fail. The API reference suggests a full-length photo around 800px wide.

How do you show the result in a component?

Post the form to your route with a fetcher, then show the image from the response. A 200 response holds image_base64 and mime_type. A 202 holds a job_id and poll_url, so poll through a second route about every 2 seconds, as the docs suggest.

The upload and display logic matches the one in our React storefront guide, since Hydrogen is React. Only the server route differs.

Where does the product image come from?

Query the product in your loader and pass its featured image URL to the component. Use a clear, front-facing product image from your catalog.

Map each product to a garment type with a metafield or a tag. Then pass upper_body, lower_body or dresses so the API treats the garment correctly.

How do you add size recommendations?

The REST API also has POST /api/v1/scan, which turns on-device pose data into measurements and a size from your own chart. The API reference describes a browser helper script, zedaq-scan.js, that produces the request body. The photo is not sent for sizing.

For the planning side, see what data you need before sizing.

What should you test before launch?

1. Test with a phone photo in good light.
2. Test a dress, a top and trousers.
3. Test the error path by using a wrong key on purpose.
4. Check the page on mobile data, where slow uploads show up.
5. Confirm the key is locked to your domain.

If your store is on Shopify Plus with a standard theme, the options differ. Read about adding try-on to a Shopify Plus store. Other custom front ends are covered in the Next.js headless guide.

FAQs

Can I use the Shopify app on a Hydrogen store?

The app works through a theme app embed, so it does not apply to a headless storefront. Use the REST API instead.

Does Hydrogen need a special server?

Your host determines where the action runs. The API call is a standard HTTPS request with a header, so it works wherever your route runs.

Is the key safe in an environment variable?

Yes, if the variable is only available to server code. Also lock the key to your domain in the dashboard.

Can I use the script-tag widget instead?

The widget is for WooCommerce, Wix, Squarespace, BigCommerce and custom sites. If you prefer it on a custom storefront, check the widget setup in the API docs first.