@genlook/storefront SDK instead: it is the same channel with upload, polling, quota, and errors already handled. Come here when you are not on JavaScript, or when you would rather not take a dependency. Everything the SDK does is built on these endpoints, and nothing is reserved.
Why not go through the storefront
The storefront path leans on things a browser on your shop’s domain gets for free: cookies, a familiar user agent, and a session your platform already trusts. Code running anywhere else carries none of that, so it tends to be treated as a scraper. Mobile apps hit this hardest:- Bot protection challenges requests that arrive without browser fingerprints, whether it comes from your platform’s edge or a firewall you configured yourself.
- Redirects between your
myshopify.comdomain and your primary domain drop request bodies in several common HTTP clients. - Shared mobile IPs are the norm. Carriers put thousands of subscribers behind a single address, so any protection that counts per IP will eventually block real customers.
Choosing your path
Call Genlook directly
Shopify and SHOPLINE. Your code calls Genlook directly with a publishable key. Nothing sits in between.
Through your site
WooCommerce and PrestaShop. Your code calls the Genlook proxy that the plugin already runs on your site.
Get your publishable key
In your Shopify admin, open the Genlook Try-On app, go to Settings, and press Create key in the Publishable key section. The key stays on that screen, so you can come back and copy it whenever you need it. On SHOPLINE, email support@genlook.app and we will issue the key for your store. It is safe to embed in your code: it can only do what a shopper on your storefront could already do. It cannot read your catalog, reach the merchant dashboard, or touch any admin data. Two more things the merchant can do from that screen:- Replace the key if it leaked. The new key works immediately and the old one stops, so anything still shipping the old key breaks until you update it.
- Turn off the key, which closes this channel right away. The website widget is unaffected either way.
Base URL and authentication
Identifying the shopper
The anonymous id is what ties a shopper to their try-on history and their quota, so generate it once and persist it: device storage in an app, a first-party cookie or local storage in a browser. A new id on every session means the shopper loses their history and gets a fresh quota, which is not the experience you want.
Customer identity is optional, and worth sending when you have it: it links try-ons to the shopper across their devices and feeds the merchant’s analytics.
The flow
Things worth knowing
Photo requirements. Photos can be JPEG, PNG, WebP, HEIC, or HEIF, up to 20 MB, and at least 500 × 625 px. Validate on your side before uploading for the best experience. You send a product id, nothing more. The server reads the title and images from your platform. Product details sent by the caller are ignored. Handled errors arrive as a 200. A try-on that cannot start returns a 200 with acode in the body, so branch on the payload rather than the status. Authentication problems use real status codes: 401 for an unknown or replaced key, 403 for a blocked request.
Several limits can refuse a try-on. The store’s plan, the per-shopper quota, and the ceilings the merchant sets on the key itself (a weekly total and a weekly per-IP allowance) all surface as QUOTA_EXCEEDED or FITTING_ROOM_WEEKLY_LIMIT_EXCEEDED on the try-on call. GET /availability reflects the store’s plan, so check it before showing your button, but treat a refusal on the try-on itself as a state your UI handles too. One note for server-side integrations: all your requests come from one address, so ask the merchant to raise or clear the per-IP ceiling in their key settings.
Try-ons count against the merchant’s plan. Same allowance as the storefront widget, not a separate subscription; a shopper’s quota is shared between your app and the website.
“Logged-in customers only” is not available on this channel. If the merchant has that setting on, try-ons return 403 LOGIN_REQUIRED even when you send a customer id. Ask them to turn it off and rely on your own sign-in instead.
The store’s settings are readable. GET /settings returns the merchant’s per-shopper quota and related widget settings, so your client can match the widget’s behavior. The SDK does this for you.
Report funnel events if you can. POST /events feeds the merchant’s analytics with the same funnel the widget reports; see the Events endpoint.
Shoppers can erase their data. DELETE /shopper removes the calling shopper’s photos, try-on images, and identity. On this channel it is scoped to the calling device, never another shopper’s data.
Through your site
WooCommerce and PrestaShop stores already run a Genlook proxy as part of the plugin. Your app or server can call it exactly as your storefront does, and it will attach your product details and credentials on the server side. This path avoids the problems described at the top of this page, because the infrastructure in the request path is yours. Any bot protection in front of it is protection you control and can allowlist. On WordPress, the plugin serves this same API under:Authorization header (the proxy attaches your site’s credentials server-side), and on the try-on call the proxy resolves the product’s title and images from your catalog, so you still send only a product id. On JavaScript, the SDK targets this proxy with one option.
On PrestaShop, the module’s proxy is protected by a storefront session token, so it is callable from pages your shop serves, using the proxy URL the widget on the page already uses.
Endpoint reference
Every endpoint from the widget API is available on this channel, with the base URL and authentication header described above.Upload Image
The 3-step signed-URL flow for shopper photos.
Create Try-On
Start a try-on job.
Try-On Status
Poll a try-on until it completes.
Availability
Verify the store can run try-ons before starting.
Share Try-On
Create public share links for results.
Collect Email
Record the shopper’s email for the merchant’s email collection step.
Delete My Data
Erase the shopper’s photos, try-ons, and identity on request.
Events
Report funnel events that power the merchant’s analytics.
Error codes
A failedtry-ons call returns a message and a code:
The
message is for your logs, not your UI; it is not localized and can change. Authentication problems are different: an unknown or replaced key returns a 401 before any of this, and a store that requires shopper login returns a 403 with LOGIN_REQUIRED (see the notes above).
