Design Case Studies · Lesson 21

Design: E-commerce Saga Checkout API

In a microservice-based e-commerce platform, checking out requires updating multiple independent services (order, payment, inventory). Because these services run on separate databases, we cannot use a single SQL database transaction. Two-Phase Commit (2PC) blocks resources and fails to scale. We must design a distributed transaction workflow using the Saga Pattern, compensating transactions, and the Transactional Outbox pattern.

Requirements

Designing a checkout flow across microservices requires strict reliability and consistency guarantees:

• Atomicity. Either the order is placed, payment captured, and inventory deducted, OR everything is rolled back to a clean state. Partial states (payment captured but no order created) are unacceptable.
• Availability. The payment gateway or inventory database might be down. The API must handle partial failures gracefully, queueing retries or executing rollbacks.
• Idempotency. Network failures will cause clients to retry checkout requests. The API must ensure duplicate checkout requests never result in multiple charges or double-deducted inventory.

Design decisions

Saga Orchestration vs. Choreography

A Saga is a sequence of local transactions. Each transaction updates data within a single service and publishes a message to trigger the next step. If a step fails, the Saga runs compensating transactions to undo the changes.

We choose **Saga Orchestration** for checkout. It keeps the core business logic (order of operations, rollback rules) visible in a single state machine rather than distributed across multiple event consumer handlers.

Transactional Outbox Pattern

When a service completes a transaction (e.g., creating an order), it must publish an event to the orchestrator. If the database write succeeds but the server crashes before sending the event, the system drifts. If it sends the event first but the DB write fails, it is even worse. We solve this with the **Transactional Outbox Pattern**: the application writes both the business record (the order) and an outbox record (the event message) to the same database using a local database transaction. A separate publisher process reads the outbox table and pushes the messages to the broker, guaranteeing **at-least-once** delivery.

The API model

Checkout API (Orchestrator Entry)

The client submits the checkout request. The request payload contains an idempotency_key to prevent double charges.

# Client initiates checkout
POST /v1/checkout HTTP/1.1
Host: checkout-orchestrator.example.com
Content-Type: application/json
Idempotency-Key: idemp_chk_99210aa

{
  "user_id": "usr_alice",
  "cart_id": "cart_772",
  "payment_method_id": "pm_card_visa_882"
}

# Orchestrator creates saga session and returns immediately
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "saga_id": "saga_chk_abc123",
  "status": "processing"
}

Inventory Service: Hold and Release (Compensating API)

Sagas require all non-read steps to be **reversible**. The inventory service must expose a reserve (hold) endpoint and a compensating release endpoint.

# 1. Hold inventory items (Normal Step)
POST /v1/inventory/hold HTTP/1.1
Idempotency-Key: idemp_saga_abc123_inv

{
  "saga_id": "saga_chk_abc123",
  "items": [
    { "item_id": "item_book_1", "qty": 1 }
  ]
}

# 2. Release inventory items (Compensating Step, run if payment fails)
POST /v1/inventory/release HTTP/1.1
Idempotency-Key: idemp_saga_abc123_release

{
  "saga_id": "saga_chk_abc123"
}

Under the hood: Orchestrated checkout flow

The checkout orchestrator drives the state machine, communicating with services sequentially and rolling back on failure.

CREATE TABLE saga_executions (
    saga_id VARCHAR(64) PRIMARY KEY,
    status VARCHAR(20) NOT NULL,          -- 'STARTED', 'COMPENSATING', 'FAILED', 'SUCCESS'
    current_step VARCHAR(50) NOT NULL,
    payload JSONB NOT NULL,               -- Holds checkout parameters
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

CREATE TABLE saga_compensating_tasks (
    task_id VARCHAR(64) PRIMARY KEY,
    saga_id VARCHAR(64) REFERENCES saga_executions(saga_id),
    target_service VARCHAR(50) NOT NULL,  -- 'INVENTORY_SERVICE', 'PAYMENT_SERVICE'
    payload JSONB NOT NULL,               -- Parameters for compensating API
    status VARCHAR(20) NOT NULL,          -- 'PENDING', 'SENT', 'COMPLETED'
    retry_count INT DEFAULT 0,
    next_retry_at TIMESTAMP NOT NULL
);