Widget API reference
Request configuration and products, create a session, submit a try-on, and retrieve its status.
Reviewed by Closku documentation team ·
Request context
Use https://closku.com as the API base from an authorized storefront origin. The public merchant ID is a UUID; find it in the installation script. JSON POST requests use Content-Type: application/json. The browser supplies its origin; do not put secret API keys in browser code. Origin validation is not secret authentication and sessions do not authenticate a shopper.
All operations can return 403:
origin_not_allowedwidget_inactiveconfig_not_foundconfig_fetch_failed
Check the origin and widget setup. Unexpected exceptions return 500 internal_error. Examples below use illustrative UUIDs and responses.
Configuration
GET /api/widget/config?merchantId=MERCHANT_UUID returns 200 with presentation and access configuration. The merchant UUID and an allowed origin are required.
GET /api/widget/config?merchantId=aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
200 OK
{"merchantId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","merchantName":"Example","trigger":"button","position":"bottom-right","label":"Virtual Try-On","theme":{"primaryColor":"#6366f1","accentColor":"#8b5cf6"},"isActive":true,"allowedOrigins":["https://shop.example.com"]}400 missing_merchant_id or invalid_id means correct the query. In addition to the shared 403 errors, 404 can return:
merchant_not_foundmerchant_inactivemerchant_fetch_failedwidget_inactive
Configuration validation runs before this lookup.
Products
GET /api/widget/products?merchantId=MERCHANT_UUID returns all active products for that merchant, without pagination. Product id and variant id are Closku UUIDs. sku, primaryImage, and variant color, size, sku, and imageUrl can be null. Variants are not filtered by activity.
GET /api/widget/products?merchantId=aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
200 OK
{"products":[{"id":"11111111-1111-4111-8111-111111111111","name":"Blue shirt","sku":"SHIRT-BLUE","primaryImage":"https://example.com/shirt.jpg","variants":[{"id":"22222222-2222-4222-8222-222222222222","color":"Blue","size":"M","sku":"SHIRT-BLUE-M","imageUrl":null}]}]}400 missing_merchant_id or invalid_id requires a corrected query. 500 products_fetch_failed means the catalog could not be loaded. See the shared 403 errors above.
Create a session
POST /api/widget/session requires merchantId; productId and variantId are optional UUIDs. The session currently defaults to one hour. A session is validated against the merchant and expiry on submission, but does not enforce a match with its initial product or variant.
POST /api/widget/session
Content-Type: application/json
{"merchantId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","productId":"11111111-1111-4111-8111-111111111111","variantId":"22222222-2222-4222-8222-222222222222"}
201 Created
{"sessionId":"33333333-3333-4333-8333-333333333333","expiresAt":"2026-11-09T12:00:00Z"}- 400
missing_merchant_idorinvalid_idrequires corrected input - 429
too_many_requestscalls for a pause - 500
session_create_failedrequires investigation
Shared 403 errors also apply.
Submit a try-on
POST /api/widget/try-on requires UUIDs merchantId and sessionId, and imageUrl containing a base64 data-image, not a remote URL. JPEG, PNG, and WebP photos are supported. The standard widget checks a 10 MiB client limit. productId and variantId are syntactically optional UUIDs, but a usable merchant-owned product and garment image are needed for a successful render. Custom flows may send a variant; the standard widget sends only the product.
POST /api/widget/try-on
Content-Type: application/json
{"merchantId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","sessionId":"33333333-3333-4333-8333-333333333333","productId":"11111111-1111-4111-8111-111111111111","imageUrl":"data:image/jpeg;base64,BASE64_PHOTO"}
202 Accepted
{"jobId":"44444444-4444-4444-8444-444444444444","status":"processing","estimatedTimeSeconds":15}Replace the photo placeholder with actual encoded bytes. A 202 can already report failed; it does not guarantee eventual success. The estimate is not a deadline.
- 400 returns
missing_session_id,missing_image_url,missing_merchant_id, orinvalid_id - 402 returns
merchant_not_entitled_for_try_onortry_on_limit_reached - 429 returns
too_many_requests - 503 returns
usage_check_unavailable
Shared 403 errors apply. Session failures such as session_lookup_failed, session_not_found, session_expired, and session_merchant_mismatch, as well as job_create_failed or job_update_failed, are currently returned as 500. A usage-check error does not prove no job exists.
Try-on status
GET /api/widget/try-on/JOB_UUID?merchantId=MERCHANT_UUID requires the job ID, matching merchant ID, and allowed origin, not a session credential. Status retrieval can advance or reconcile processing and persist a result.
GET /api/widget/try-on/44444444-4444-4444-8444-444444444444?merchantId=aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa
200 OK
{"jobId":"44444444-4444-4444-8444-444444444444","status":"completed","resultUrl":"https://example.com/temporary-result","error":null}States are pending, processing, completed, and failed; the last two are terminal. The returned result URL can expire. A failed job can expose an error such as missing_product or missing_garment_image. 400 can return missing_job_id, the literal merchantId is required, or invalid_id. 404 can return job_not_found or job_fetch_failed. Shared 403 and 500 errors apply.
There is no submission idempotency key or documented session-to-job lookup. Never automatically repeat an uncertain submission. Follow errors and retries.