Create orders safely
A checkout is safe when network retries cannot create a duplicate order or duplicate wallet charge.
The safe checkout
Idempotency
Generate a unique reference between 8 and 200 characters for each intended checkout. Store it before calling Shioja. If the request times out, retry with the same key. Never generate a new key merely because the response was lost.
Transaction behavior
Shioja checks the idempotency record first. It then validates quote ownership, mode, expiry, consumption, current product stock, and wallet balance. Order, wallet entry, financial summary, quote consumption, and idempotency record are committed together.
Retry decision table
| Result | Action |
|---|---|
| Timeout / connection lost | Retry with the same idempotency key. |
QUOTE_EXPIRED | Create a new quote; keep the checkout reference only if your own workflow treats it as the same attempt. |
QUOTE_ALREADY_USED | Look up the stored order result; do not create another charge blindly. |
INSUFFICIENT_FUNDS | Top up the matching wallet, create a fresh quote if needed, then retry deliberately. |
PRODUCT_UNAVAILABLE | Stop checkout and ask the customer to choose another product. |
Order status
New orders begin at PROCESSING. Use the order identifier returned as data.orderNo as your canonical Shioja reference. Existing v1 order-read endpoints remain available with a secret key while v2 order reads are introduced separately.
Customer experience
Disable duplicate submit actions, show a durable “processing” state during uncertain network outcomes, and reconcile by idempotency key or stored order number before telling a customer to try again.