Virtual Try-On API for Custom & Headless Stores
Manage try-on products, images, and usage from your own code with a REST API, then add live AR and AI photo try-on to product pages with a two-line embed. Built for WooCommerce, Magento, marketplaces, and custom platforms.
What is the TryOn Virtual API?
The TryOn Virtual API is a REST API for adding virtual try-on to stores that don’t run on Shopify. From your own backend you can create and update products, attach images by URL or upload, switch try-on on or off, and read your monthly usage against plan limits. Requests go to https://api.integration.tryonvirtual.com/v1 and authenticate with an API key created in the merchant panel. Each product reports a swap_ready flag and a tryon_status, so your code knows when to show the Try On button. You can keep your own IDs in external_id. Shoppers never touch the API: a button and a bootstrap script on the product page open the same production widget Shopify merchants use, with live AR for eyewear and watches and AI photo try-on for clothing, shoes, and jewelry. Full reference at docs.tryonvirtual.com.
Who the try-on API is for
Headless & custom storefronts: Your stack, your catalog
If your store runs on a custom backend or a headless frontend, the API keeps try-on products in sync with your catalog automatically instead of someone re-entering them in a dashboard.
Marketplaces & large catalogs: Sync thousands of SKUs by script
Create products in bulk from your own data, attach images by URL, and look them up by your own IDs. Try-on status and readiness come back on every product, so your code knows exactly when to show the button.
WooCommerce, Magento & others: Automate what the panel does by hand
Stores on WooCommerce or Magento can run entirely from the merchant panel and a script embed. The API is for teams that want new products to get try-on the moment they are published.
Agencies & integrators: Build try-on into client projects
Wire try-on into a client’s product pipeline once, with per-client API keys, and leave the storefront button to the embed. Usage can be checked from code to watch plan limits.
Endpoints and a first request
The API covers three resources: products, images, and usage. All paths are relative to https://api.integration.tryonvirtual.com/v1.
| Endpoint | What it does |
|---|---|
| GET /products | List products. Filter by category, tryon_status, or external_id; paginate up to 100 per page. |
| POST /products | Create a product with title, category, optional handle and external_id, and up to 10 image URLs. |
| GET /products/{id} | Product detail, including tryon_status, model_type, swap_ready, and images. |
| PATCH /products/{id} | Partial update. Set mode (realtime or swap) and switch try-on on or off. |
| DELETE /products/{id} | Delete a product with its images and 3D assets. |
| POST /products/{id}/images | Add an image by public URL or multipart upload (JPEG, PNG, WebP, GIF; 15 MB max). |
| DELETE /products/{id}/images/{image_id} | Remove an image. |
| GET /usage | This month’s try-on sessions, photo swaps, and product count against your plan limits. |
Create a product
curl -X POST https://api.integration.tryonvirtual.com/v1/products \
-H "Authorization: Bearer tryon_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Aviator Sunglasses",
"category": "eyewear",
"external_id": "SKU-1042",
"images": ["https://yourstore.com/images/aviator.jpg"]
}'Turn on try-on once swap_ready is true
curl -X PATCH https://api.integration.tryonvirtual.com/v1/products/PRODUCT_ID \
-H "Authorization: Bearer tryon_sk_your_key" \
-H "Content-Type: application/json" \
-d '{"mode": "swap", "tryon_enabled": true}'The create call returns the product with its TryOn id. Poll GET /products/{id} until swap_ready is true, which usually takes under a minute, then enable try-on. Step-by-step: API quickstart.
From API key to live try-on in four steps
Create an API key
In the merchant panel, go to Settings → API Keys. Admin users can create and revoke keys, with up to 10 active at a time.
Create products
POST a title, category, optional external_id, and up to 10 image URLs. Images are downloaded and processed for try-on.
Wait for ready, then enable
When swap_ready turns true (usually under a minute), PATCH the product with a mode and tryon_enabled: true.
Add the button
Drop the Try On button and bootstrap script on the product page. Render it only for products that are active and ready.
How the widget embed works alongside the API
The API manages your catalog. The embed is what shoppers see. On each product page, add a button with data-tryon-product-id and the bootstrap script. Clicking the button opens the try-on overlay, and you can also open it from your own code with window.openTryOn(). The shop_slug is in the panel under Settings → Shop, and the panel’s Install page generates the snippet pre-filled for you.
<button type="button" data-tryon-product-id="SKU-1042">Try On</button>
<script async
src="https://widget.tryonvirtual.com/api/v1/tryon/scripts/embed/bootstrap.js?shop_slug=YOUR_SHOP_SLUG&productId=SKU-1042">
</script>productId takes either the TryOn ID or your own external_id, so templates can use the SKU you already have. Only render the button when the product’s tryon_status is active and swap_ready is true. The bootstrap script is small, and the try-on engine loads only after a shopper clicks, so product pages stay fast. More in the storefront integration guide.
Two try-on modes, one API
Live AR with a 3D model (mode: realtime)
The product renders live on the shopper’s camera feed and follows their face or wrist. Used for eyewear and watches. Requires an active 3D asset on the product. Camera frames are processed in the browser and never leave the device.
- Eyewear: face tracking
- Watches: wrist tracking
- Earrings, necklaces, bracelets: in beta
AI photo try-on from product images (mode: swap)
The shopper uploads a photo and gets an image of themselves wearing the product in about 10–20 seconds. Works from ordinary product photos. Photos are processed by OpenAI or Google Gemini and deleted within 24 hours.
- Clothing, shoes, jewelry
- No 3D model needed
- Ready when swap_ready is true
Category pages: eyewear virtual try-on, watch virtual try-on, and AI photo swap.
Auth, limits, and errors
What to know before you write the integration.
Every request sends Authorization: Bearer tryon_sk_…. Keys belong to one shop and can only see that shop’s products; a product from another shop returns not_found. Revoke a key in the panel and it stops working immediately.
120 requests per minute per API key. Go over and you get a 429 with a Retry-After header, so a bulk import should back off and retry.
Every error uses the same envelope, {"error": {"code", "message"}}, with codes such as unauthorized, not_found, validation_error, rate_limited, unreachable_url, not_an_image, and too_large. Image URLs that fail on create are listed in images_failed without failing the whole request.
The API handles catalog data only: products, images, and usage. Shopper photos never pass through your API calls. Live AR stays on the shopper’s device, and photo try-on images are deleted within 24 hours.
Try-on API questions
Do I need the API to add virtual try-on to a custom site?
No. Any store can add products in the merchant panel and paste the embed — a button plus a bootstrap script — into its product template. The API is for automating the catalog side: creating products, attaching images, switching try-on on, and checking usage from your own code.
Is the API available for Shopify stores?
Shopify stores use the TryOn Virtual Shopify app instead, which syncs products from Shopify automatically. The public API is built for merchant-panel stores: WooCommerce, Magento, custom platforms, and other non-Shopify storefronts.
Which product categories does the API support?
The category field accepts eyewear, watch, shoes, jewelry, clothes, bag, and luggage. Eyewear and watches can use live AR (mode realtime) once a 3D asset is active; other categories typically use AI photo try-on (mode swap), which works from product images.
Can I use my own product IDs?
Yes. Set external_id when you create or update a product, filter with GET /products?external_id=…, and use it directly in the storefront button and script in place of our ID. REST paths still take the TryOn product ID.
Is there an AR try-on SDK?
The client side is the JavaScript embed: one script and a button that open the same production widget Shopify merchants use, with live AR and AI photo try-on. It runs in mobile and desktop browsers with no app download. You can also open it from your own code with window.openTryOn().
How much does the API cost?
There is no separate API fee on the pricing page. What counts toward your plan is try-on usage — sessions and 3D model generations — which GET /usage reports for the current month. The Starter plan is free with 25 sessions a month and 3 AI-built 3D models, and the Custom plan for non-Shopify retailers includes unlimited sessions.
Pricing is based on try-on usage
25 try-on sessions / month
3 free AI-built 3D models for AR try-on
150 try-on sessions / month
5 free AI-built 3D models for AR try-on
500 try-on sessions / month
10 free AI-built 3D models for AR try-on
5,000 try-on sessions / month
100 free AI-built 3D models for AR try-on
Unlimited try-on sessions
Unlimited AI-built 3D models for AR try-on
Merchant-panel stores pay by card in the panel. Retailers off Shopify that need unlimited sessions, smart mirrors, or a contract can choose Custom. See all plans and overage rates.
Ship try-on from your own stack
Create a free merchant-panel account, generate an API key, and make your first call in minutes.