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, calculates delivery from the submitted address, and verifies the current product and wallet. The order, wallet entry, financial summary, and idempotency record are committed together.
Retry decision table
| Result | Action |
|---|---|
| Timeout / connection lost | Retry with the same idempotency key. |
IDEMPOTENCY_CONFLICT | Use a new key only for a genuinely different order. |
PRODUCT_CHANGED | Retry the same intended order with the same idempotency key. |
INSUFFICIENT_FUNDS | Top up the matching wallet, 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.