How Shioja works

Shioja separates the customer experience you own from catalogue, pricing, delivery, wallet, and fulfilment infrastructure it operates.

System boundary

Your application controls presentation, customer sessions, cart behavior, and when checkout begins. Shioja returns product and delivery data, validates checkout inputs, deducts the merchant wallet, and creates fulfilment records.

Catalogue path

1. Listings

   v2 list and batch reads come from a versioned compressed product catalogue cached by the API.

2. Search

   Typesense finds product IDs only. Results are hydrated from the same cached catalogue before they are returned.

3. Details

   Long product detail reads the canonical longProducts record so checkout uses current stock and product data.

4. Analytics

   BigQuery receives product analytics asynchronously. It is not in the customer request path.

Checkout path

1. Validate location

   The v2 address is matched against the versioned delivery catalogue.

2. Create quote

   Shioja snapshots product price, delivery fee, address, catalogue version, and pricing version for 15 minutes.

3. Create order

   An idempotent transaction verifies ownership, expiry, stock, and wallet funds before charging once.

4. Fulfil

   The order begins in PROCESSING. Status updates can be read by API and delivered to the configured merchant webhook.

Data boundaries

Failure model

Read requests may be retried normally. Quote creation can be repeated if it fails. Order creation must always use an idempotency key: retry the same intended checkout with the same key, and use a new key only for a genuinely new order.