Widget API reference

The production application origin is https://closku.com. Requests use JSON and the merchant's storefront origin. Read Widget origins and access before calling them.

The product list is read-only. Manage catalog records through merchant product tools and CSV import. No catalog-write, usage-history, or outbound-webhook configuration endpoint is exposed by this contract.

Use camelCase field names. productId must identify a Closku catalog product belonging to the merchant. The handler permits a missing product field, but the resulting job fails with missing_product; a useful request needs a mapped product.

{
  "merchantId": "MERCHANT_UUID",
  "sessionId": "SESSION_UUID",
  "productId": "CLOSKU_PRODUCT_UUID",
  "variantId": "CLOSKU_VARIANT_UUID",
  "imageUrl": "data:image/jpeg;base64,..."
}

imageUrl must be a base64 JPEG, PNG, or WebP data URL. HTTP(S) shopper-photo URLs are rejected. The standard widget accepts one photo up to 10 MB and reads the selected file into a data URL before submission. Use photos with permission.

sessionId must identify an existing session for the same merchant with a future expiresAt. The server validates it before creating the job. A missing, mismatched, or expired session currently returns HTTP 500 with session_not_found, session_merchant_mismatch, or session_expired; correct the session instead of replaying the same request.

The uploaded shopper photo is stored with a merchant/job path and passed to processing through a temporary signed URL. The garment image comes from the mapped catalog product: a requested variant image is preferred when available, otherwise an available product image is used. estimatedTimeSeconds is a hint, not a guaranteed deadline.

Keep the returned jobId and poll its status with the merchant ID. Jobs use pending, processing, completed, and failed. HTTP 202 can return a failed job when preparation fails; inspect status and then the status response's error.

{
  "jobId": "JOB_UUID",
  "status": "completed",
  "resultUrl": "https://YOUR_PROJECT.supabase.co/storage/v1/object/sign/widget-uploads/MERCHANT_UUID/JOB_UUID-result.jpg?token=SIGNED_TOKEN",
  "error": null
}

The result URL above is illustrative. Use the actual returned URL, whose accepted storage location is associated with the merchant and job. Status lookup requires the matching merchant ID as well as the job ID; a mismatched merchant lookup returns 404. Treat preview links as potentially time-limited, and do not construct a permanent public photo URL.

This job returns a visual preview URL. AI size recommendation is planned and is not currently available; this response is not a measurement or sizing API contract.

Errors return a JSON error field. Common responses include 400 for missing fields, 403 for a rejected origin or configuration, 402 for missing merchant entitlement, 404 for an unavailable configuration or status lookup, and 500 for internal failures. The widget routes do not implement Idempotency-Key; avoid automatically replaying a submission after an ambiguous timeout and poll the known job instead.