Try-On

What you'll achieve

By the end of this guide the Try-On widget is live on your product pages. Shoppers upload a photo of their own space, and Epox shows your product placed in it.

You also set spending limits, choose which products show the widget, and learn how to check usage, turn it off, and fix it if it does not appear.

Try-On is for placing a product in a photo of a space. Don't use it to place products on a shopper's face or body.

Before you start

• A workspace with at least one product. The preview on the Try-On page needs one.
• Shopify or WooCommerce: your store connected to Epox. See Store connection.
• Try-on credits. Try-On spends from its own balance, separate from your regular generation credits. You can buy them in step 7.
• A custom or headless storefront: a developer for one server step.

1. Open the Try-On page

1. In the left sidebar, click Try-On.
2. On the left is the Storefront Try-On Widget card with your settings. On the right is a live preview of the widget.
3. Below them are the install card for your store, Shopper privacy, Try-on credits, and Try-On activity.

2. Preview the widget

1. Under Select product to preview, pick a product. The first product is chosen for you.
2. Under Theme, choose System, Light, or Dark. The preview updates right away.

The preview shows your saved settings. If you change a setting, click Save changes to see it.

3. Install the widget on your store

Use the path that matches your store. The card below the preview changes to match the store you connected.

Shopify

1. Find the Add the Try-On block card.
2. Click Preview in Theme Editor. Shopify opens your theme editor on a product page with the block ready to add.
3. If the button is missing, open your Shopify theme editor yourself and select a product page.
4. From the app blocks list, add the Epox Try-On block and place it where you want it, for example under the product gallery.
5. Click Save in Shopify.

Nothing to paste. Shopify connects the widget to your workspace for you.

The block only shows on products you enabled in step 5. If you update the app, run shopify app deploy so the theme block can read the product flag (see "How your store knows" in step 5).

WooCommerce

1. Find the Embed on your WordPress store card.
2. Paste the shortcode [epox_tryon] anywhere on a product page, such as the description, a text widget, or a page builder block.
3. Optional: add attributes. product_id shows the widget for a specific product, for example on a landing page. theme is system, light, or dark. ref_image pins one gallery photo instead of the main image.
4. Update the page in WordPress.

The Epox connector adds your widget key for you. Nothing to copy.

The shortcode only shows on products you enabled in step 5, and it needs connector version 1.2.0 or later. Update the Epox WooCommerce Connector plugin in WordPress if it is older.

Custom or headless storefront

Use this if your store is not connected to Epox, or you built your own storefront.

1. Open the Embed on your store card.
2. In Select product to preview, pick a product so its id is filled into the code.
3. Click Copy embed code and paste it into your product page. If you did not pick a product, replace YOUR_PRODUCT_ID.
4. Scroll to the Custom server integration card. Under Widget key, click the copy button and give the key to your developer.
5. Click Generate server key, then click the copy button next to it. The key is shown once. Store it on your server, never in your page code.
6. Ask your developer to build the same-origin endpoint named in data-permit-url. It sends the widget key and server key to Epox and returns the short-lived, one-time permit Epox gives back.

4. Set your spending limits

In the Storefront Try-On Widget card:

1. Per-shopper limit: the most try-ons one shopper can run in a session. Enter 1 to 50. Lower it to control spend.
2. Daily budget: the most try-ons your workspace is charged for in one day. Enter 1 to 100000. When it is reached, try-ons stop until the next day.
3. Click Save changes.

5. Choose what shoppers see and where

Wording

1. Prompt hint (optional): example text in the prompt box, such as next to the window, morning light.
2. Share message: the text sent when a shopper shares a result, up to 500 characters. Use {productName} and {link} to insert the product name and its link.

Choose which products show Try-On

New workspaces start with Choose products and nothing chosen, so Try-On is hidden everywhere until you pick products. Workspaces that were already using Try-On keep All products, with the exceptions they had set.

Where Try-On appears has two options:

• All products: Try-On shows on every product in your store, including products you never imported into Epox. Epox first asks you to confirm and tells you how many products your store has and roughly how long marking them takes (about 14 minutes for 35,000 products). Keep the page open until it finishes.
• Choose products: Try-On shows only on what you choose. Picking it turns Try-On off on every product, then back on for the products, collections, and tags you chose. No confirmation is needed.

Picking an option saves it right away. To choose products:

1. Under Where Try-On appears, select Choose products. The Products, Collections, and Tags lists open below it.
2. Open a list, search, and tick the ones you want. A match on any of them counts. Products search your whole store by name or SKU; a collection or tag covers every product in your store that has it, including products you never imported into Epox. A tag marked No product has this tag matches nothing.
3. Click Save changes.

The card lists what you chose, with how many store products each collection or tag matched. Remove a choice with the × on its chip, then save.

Its status line reads Updating your store… 12,500 of 35,000 products while Epox marks your products (keep the page open), then Published to your store with the number of products updated and when.

The first time you save, Epox marks every product you did not choose as off, so your store shows an explicit false instead of an empty field. Products you chose stay on.

How your store knows

After you save, Epox marks each product in your connected store so the storefront can skip the widget on products that are not enabled:

Things to know:

• It happens on its own. Epox updates the flags right after you save or pick an option, when you import products, and when a product changes in your store. Opening the page alone never updates them, and you never edit them by hand.
• Keep the Try-On page open until an update finishes. If your store asks Epox to slow down, Epox waits and continues; if it still cannot finish, click Continue on the message.
• On your live store, the widget shows only when the flag says Try-On is on. A product with no flag yet, or with false or no, shows nothing and makes no request.
• The flag is a shortcut, not the rule. Epox checks your settings again on every try-on, so a flag that is out of date can never let a shopper try an unenabled product.
• Your theme can read the flag too. In Shopify, use the metafield epox.tryon_enabled.
• A custom or headless storefront has no store product to mark. Epox keeps your choice and hides the product when the widget asks.

Shopper consent

1. Ask shoppers for consent is on by default. Shoppers tick a one-time checkbox before their first photo.
2. To turn it off, switch it off and click My storefront collects it. Do this only if your store already asks shoppers to agree before they upload a photo. Epox records the date. Click Keep it on to cancel.
3. Click Save changes.

A short privacy line under the upload button always shows.

Extra storefront domains

Epox detects your store's domains, including custom domains, on its own. Hover the info icon next to Extra storefront domains to see what is covered.

Only if you show the widget on another site, such as a headless storefront, type its domain (for example brand.com) and click Add. Click the X on a domain to remove it, then Save changes.

Privacy policy

1. In the Shopper privacy card, click Copy paragraph.
2. Paste it into your store's privacy policy and adjust the wording.

The paragraph says the shopper's uploaded photo is deleted after 7 days and the generated preview after 30 days.

6. Test it on your storefront

1. Open a product page on your live store in a private browser window.
2. Find the widget. Shoppers see See it in your space and an Upload a photo button. On a phone the button reads Choose from your library.
3. If consent is on, tick I agree my photo is processed to create this preview.
4. Upload a photo of a room, describe where the product goes, and click Generate.
5. Check the result. The shopper can adjust it, compare before and after, and share it.

A test try-on uses your try-on credits and counts toward your limits.

7. Keep credits topped up

The Try-on credits card shows your balance and roughly how many try-ons are left.

1. Choose Monthly or Annual if both are shown.
2. Pick a credit pack and buy it.

If the balance reaches zero, the widget hides itself on your storefront. Shoppers see nothing broken, and checkout is not affected. It comes back once you have credits.

Monitor usage

1. Scroll to Try-On activity for the last 30 days: Shoppers, Generated assets, Credits spent, Generations per shopper, and Most tried-on products.
2. Click See all analytics for more.
3. Pick a range: Last 7 days, Last 30 days, Last 90 days, or Last 12 months.
4. Open the Overview tab for products, or Shopper sessions to see each session.

Turn Try-On off

1. Remove the widget from your store: in Shopify, delete the Epox Try-On block in your theme editor and save. In WooCommerce, delete [epox_tryon]. On a custom site, delete the embed code.
2. To turn it off on only some products, select Choose products under Where Try-On appears, tick only the products you want, and click Save changes.
3. To stop spending without removing it, lower Daily budget and click Save changes.

Check your result

• The widget appears on a product page of your live store.
• A test try-on produces a result.
• Try-On activity shows the test under Shoppers and Credits spent.

If the widget does not show

On your live store the widget hides itself whenever it cannot load, so shoppers never see an error. Check these in order.

1. Credits: does Try-on credits show a balance above zero? An empty balance hides the widget.
2. Enabled products: look at Where Try-On appears. Under Choose products, is this product, one of its collections, or one of its tags chosen? Under All products, is it in an exception chip? Fix it and click Save changes. This is the most common reason a new workspace sees no widget.
3. Store flag: Epox updates the product flag right after you save, so give it a minute and reload the product page. On WooCommerce, check that the connector plugin is version 1.2.0 or later: an older one cannot receive the flag, so the widget stays hidden. On Shopify, run shopify app deploy if the block was installed before this feature.
4. Where the block is: in Shopify, the block must be on a product page template, not a general section. In WooCommerce, the shortcode must be on a product page.
5. Saved: did you save the theme in Shopify, or update the page in WordPress? Reload the product page.
6. Store connected: check your connection in Store connection.
7. Custom storefront: confirm your developer's permit endpoint answers on the same domain as the page and is not redirected to another domain.
8. Ask the widget why: in your Shopify theme editor, the block explains to you (and only you) why it cannot load. In any browser, open the developer console on the product page and look for a line starting with [Epox Try-On] widget hidden.

Next steps

• Connect your store
• Billing and usage