Try-on jobs and status

A try-on job generates a clothing preview; it is separate from a purchase order. It begins as pending, moves to processing when inference is submitted, and ends as completed or failed. Preparation failures can produce a failed job immediately.

Inference cancellations and provider timeouts map to failed. The storefront waiting timeout is a client behavior, not an additional server state or a guaranteed server deadline.

Keep jobId from POST /api/widget/try-on and call GET /api/widget/try-on/JOB_UUID?merchantId=MERCHANT_UUID. The response includes status, resultUrl, and error. The standard widget polls at two-second intervals until a terminal result or its client waiting limit.

Job lookup is scoped to the merchant, so keep the original merchant ID with the job ID. Use the returned preview URL; its storage location must belong to the merchant/job, and a link can be time-limited.

Polling can advance stored state by checking the inference provider. Avoid unlimited polling, overlapping status loops, or automatic re-submission after a timeout. A repeated POST can create another job because the widget routes do not implement idempotency keys.

The dashboard reports monthly try-on activity. A new try-on records a creation event before rendering completes; a failed render is not the same as no recorded activity. Compare submitted, completed, and failed outcomes separately.

The submission route checks subscription entitlement. A rejected entitlement returns HTTP 402 with merchant_not_entitled_for_try_on. It is not a 429 usage-limit response. Review the subscription and usage dashboard and contact support when access or recorded usage is unclear.

The service also checks that the shopper session exists, belongs to the merchant, and is unexpired before creating the job or recording its creation event. A session rejection has no returned job ID; create or use the correct unexpired session before submitting again.

A completed job returns a generated image; it does not guarantee physical clothing fit. AI size recommendation is planned and is not currently available. Keep garment information and the size chart available to shoppers. The widget job fields here do not document a measurement or sizing API.