Orders

Each virtual try-on follows a defined lifecycle through the Closku platform. It begins in the Submitted state when the shopper initiates a try-on request with a photo and product selection. The system then moves to Processing as the AI rendering engine generates the preview. On success the state transitions to Completed and the rendered result is displayed in the widget. If an invalid image, unsupported product, or system error prevents completion, the state becomes Failed. If rendering exceeds the timeout limit, the state becomes Timed Out. Track these state transitions through webhook events or the API status endpoint: each transition is idempotent and safe to handle multiple times.

Model try-on orders as a sequence of explicit states rather than a single success event, with each transition having a clear meaning in your system. Keep downstream side effects tied to stable milestones like Completed or Failed, and make state transitions observable through webhooks. Design handlers to be idempotent since events may arrive more than once, and preserve enough context to inspect the full path when an order enters an unexpected state. Most operational exceptions come from misunderstood transitions, not broken transport, so interpret exceptions before automating around them.

Each try-on order counts against the merchant's monthly plan limit, with the usage counter incremented when a try-on enters the Submitted state. Note that failed try-ons still count against the limit, so validate inputs before submission to minimize waste. Check current usage via the API before accepting high-volume batches, and be aware that the API returns a 429 Too Many Requests status when the limit is reached.