Guide · Orders API

How checkout works

What happens between a customer pressing Pay and the receipt landing in their inbox — one POST /v2/orders, eight steps.

Checkout flow: web shop, API gateway, auth service, orders service, orders database, payment provider, event bus and email worker — Figure 1 — The checkout flow. Match each numbered step below to the boxes above.

1The request

The web shop creates an order by calling POST /v2/orders with the cart and the customer's access token. Send an Idempotency-Key so a retried request can never create a second order.

POST /v2/orders HTTP/1.1
Authorization: Bearer eyJhbGciOi…
Idempotency-Key: 7f3c1a90-…
Content-Type: application/json

{ "items": [{ "sku": "MUG-01", "qty": 2 }], "currency": "CAD" }

2API gateway

Every call enters through the gateway. It enforces a limit of 100 requests per minute per API key and routes /v2/orders to the orders service. Over the limit, it answers 429 Too Many Requests with a Retry-After header.

3Authentication

Before forwarding, the gateway asks the auth service to verify the token — signature, expiry and the orders:write scope. A missing or invalid token stops the request here.

HTTP/1.1 401 Unauthorized
{ "error": "invalid_token", "message": "The access token has expired." }

4Orders service

The orders service checks every SKU and quantity against the catalogue, prices the cart and creates the order with status pending. An invalid cart is rejected with 422 and a list of problems.

5Orders database

The order is written to PostgreSQL in a single transaction, together with the idempotency key. If the same key arrives again, the service returns the original order instead of creating a new one.

Idempotency keys are kept for 24 hours.

6Payment

The orders service charges the card through the payment provider. On success the order becomes paid. A decline marks it failed and the API returns 402 Payment Required with the provider's reason.

HTTP/1.1 201 Created
{ "id": "ord_9Qx2", "status": "paid", "total": { "amount": 3200, "currency": "CAD" } }

7Event bus

Once paid, the service publishes an order.created event. Anything that reacts to new orders — fulfilment, analytics, the receipt — subscribes to this event instead of being called directly.

8Receipt email

The email worker consumes order.created and sends the receipt. It runs after the API has already answered, so the customer never waits for email — and a slow mail provider can't fail a checkout.