Skip to content

Order Cancellation

Worked example of what design-service produces. implement-service reads this file and refuses to start unless status is approved.

Design: Level 1 — Context

Problem. A customer can cancel an order until it has been dispatched. Today they contact support, who cancel manually in the admin tool — around 400 tickets a week, and a median of six hours before the warehouse is told, by which time roughly a fifth have already shipped.

Actors. The customer (via the storefront); support (via the admin tool, same API); the warehouse system (consumes the outcome); finance (needs the refund initiated).

Bounded context. Order Management. Cancellation is part of an order's lifecycle and uses the same ubiquitous language, so it belongs in the existing orders-service. It is not a new service: no independent release cadence, no divergent scaling, one owning team (service-boundaries checklist item 9 — no force applies).

In scope. Customer-initiated and support-initiated cancellation; releasing the inventory reservation; initiating the refund; notifying the warehouse.

Out of scope. Partial cancellation of individual lines (a separate capability, deliberately deferred); post-dispatch returns (a different process owned by the Returns context); the refund itself — payments-service owns that, and we only initiate it.

Constraints. Cancellation must not be possible once dispatch has begun; that check is authoritative in warehouse-service, not here. Refunds must be traceable end to end for audit. Storefront p99 latency budget for this operation: 800 ms.

Success measure. 90% of eligible cancellations self-served within six months; cancelled orders that ship anyway drop below 0.5%.

Assumptions (stated, not confirmed): current cancellation volume is estimated from support ticket tags rather than measured; peak is assumed to follow the existing checkout profile.

Design: Level 2 — Components

Component Responsibility Layer Owns New/Existing
Order (aggregate) The cancellation invariant and the state transition Domain orders, order_lines Existing — extended
CancellationPolicy Whether this order, in this state, may be cancelled Domain — New
CancelOrder (use case) Load, transition, persist, record the outbox event Application — New
OrderRepository Load and store the aggregate Application (port) — Existing
DispatchStatusPort Ask the warehouse whether dispatch has begun Application (port) — New
CancellationController POST /v1/orders/{id}/cancellation Adapter — New
WarehouseDispatchClient HTTP implementation of DispatchStatusPort Adapter — New
OutboxRepository Append events in the business transaction Adapter outbox Existing

Invariant (data-and-cqrs): an order may move to CANCELLED only from PLACED or CONFIRMED, and only when the warehouse has not begun dispatch. The Order aggregate owns the state transition; the dispatch fact comes from outside and is passed in as a parameter, so the aggregate stays free of I/O.

Data ownership. orders-service owns order state. Inventory reservation is owned by inventory-service and released by it in reaction to our event — we do not write to it. The refund is owned by payments-service.

Design: Level 3 — Interactions

Customer ──POST /v1/orders/{id}/cancellation──▶ orders-service
                                                    │
                        1. authorise: caller owns this order
                        2. load the aggregate
                        3. ── GET dispatch status ──▶ warehouse-service   [sync]
                        4. Order.cancel(dispatchStatus)
                        5. ┌ persist order (CANCELLED) ┐  one transaction
                           └ append OrderCancelled ────┘
                                                    │
                        6. Debezium ──▶ Kafka: orders.order.cancelled     [async]
                                          │
              ┌───────────────────────────┼──────────────────────────┐
              ▼                           ▼                          ▼
      inventory-service           payments-service           notification-service
      releases reservation        initiates refund           emails the customer

Hop 3 — dispatch status (synchronous). The caller needs the answer to decide, so this is a call, not an event.

Property Value
Timeout 300 ms (within the 800 ms budget, leaving room for the transaction)
Retry 1 retry, exponential backoff with full jitter, only on timeout or 5xx
Circuit breaker 50% failure rate over the last 20 calls; open 30 s; 3 half-open probes
Fallback Fail closed — return 503 and do not cancel
Idempotent Yes, it is a read

Decision — fail closed rather than degrade. Cancelling an order that has already shipped costs a physical return and a support ticket; refusing a cancellation costs the customer a retry. Recorded below.

Hops 6 — downstream reactions (asynchronous). None of them is required for the cancellation to be valid, so all three are event-driven. Published through the transactional outbox; no dual write. Consumers are idempotent on the event id and tolerate redelivery and reordering.

Consistency boundary. The order's state is strongly consistent at step 5. Inventory release, refund initiation, and notification are eventually consistent, budgeted at under 30 seconds and alerted at 2 minutes.

Idempotency. POST carries an Idempotency-Key. A replay within 24 hours returns the original response. Cancelling an already-cancelled order returns 200 with the existing state, not a 409 — the caller's intent is satisfied.

Trust boundary (secure-service). The caller's JWT is verified in this service. The order is loaded scoped to the authenticated customer, so an order belonging to someone else returns 404, not 403 — no existence disclosure. Support callers are authorised by a distinct orders:cancel:any scope, and every such cancellation is audit-logged with the acting user.

No compensation required. The order transition is the only local write; everything downstream reacts to a fact that has already happened. There is no saga here — a good outcome, and the reason the boundary was drawn this way.

Design: Level 4 — Contracts

POST /v1/orders/{orderId}/cancellation

Headers: Authorization: Bearer <jwt> (required), Idempotency-Key: <uuid> (required).

// request
{ "reason": "CUSTOMER_CHANGED_MIND" }   // enum, required; consumers must tolerate new values

// 200 OK
{
  "orderId": "01J8ZQ...",
  "status": "CANCELLED",
  "cancelledAt": "2026-09-05T11:04:00Z",
  "refundInitiated": true
}
Status Code Meaning Retry?
400 INVALID_REASON Reason not in the enum No
401 — Token missing or invalid No
404 ORDER_NOT_FOUND No such order for this caller No
409 ORDER_ALREADY_DISPATCHED Dispatch has begun No
422 IDEMPOTENCY_KEY_REUSED Same key, different body No
503 DISPATCH_STATUS_UNAVAILABLE Warehouse unreachable; breaker open Yes, with backoff

All errors use application/problem+json and carry traceId.

Event orders.order.cancelled (Avro, registry compatibility FULL)

{
  "id": "01J8ZR...",                       // for consumer-side deduplication
  "type": "orders.order.cancelled",
  "schemaVersion": 1,
  "occurredAt": "2026-09-05T11:04:00Z",
  "correlationId": "...",
  "producer": "orders-service",
  "data": {
    "orderId": "01J8ZQ...",
    "customerId": "cus_...",
    "reason": "CUSTOMER_CHANGED_MIND",
    "lines": [ { "sku": "SKU-1234", "quantity": 2 } ],   // inventory needs these
    "refundAmount": { "minorUnits": 4599, "currency": "GBP" }
  }
}

Lines and refund amount are included deliberately so consumers need no callback. Partition key is orderId, giving per-order ordering, which is all any consumer requires.

Test obligations

Behaviour Level
The cancellation invariant, including every state transition Unit (Order, CancellationPolicy)
409 when dispatched; 404 for another customer's order; audit log on support cancellation Component
Idempotency-Key replay returns the original response Component
Warehouse timeout → 503, breaker opens after the threshold Component, with a WireMock delay
Order row and outbox row committed atomically Component, Testcontainers PostgreSQL
Storefront's expectations of the endpoint Contract (Pact, consumer: storefront-bff)
inventory-service can consume orders.order.cancelled Contract (message pact)
Customer cancels an order end to end One end-to-end journey, and no more

Decisions Log

2026-09-05 — Cancellation lives in orders-service, not a new service

Options: a new cancellation-service; a capability inside orders-service. Decision: inside orders-service. Because: cancellation is a transition of the order aggregate and shares its invariant and language. None of the four forces for a separate service applies. A separate service would have needed a distributed transaction over the order's own state. Reversibility: reversible — extraction later would follow the strangler-fig sequence.

2026-09-05 — Fail closed when the warehouse is unreachable

Options: degrade (cancel optimistically, reconcile later); fail closed (503). Decision: fail closed. Because: the cost of cancelling an order that has already shipped is a physical return and a support ticket; the cost of a refused cancellation is a retry. Correctness outranks availability here — a product decision, confirmed with the ops lead. Reversibility: costly — customers would come to rely on optimistic cancellation. Consequences: cancellation availability is now the product of this service's and the warehouse's. Alert on the breaker opening.

2026-09-05 — Downstream effects are events, not synchronous calls

Options: call inventory, payments and notification in sequence; publish one event. Decision: publish orders.order.cancelled through the transactional outbox. Because: none of the three is required for the cancellation to be valid, and coupling to three services would make cancellation the least available operation in the system. Reversibility: costly — three consumers will bind to the schema. Consequences: refund and inventory release are eventually consistent; the response reports refundInitiated: true meaning requested, not settled. The event is a published contract governed by api-contracts.

Open Questions

  • Cancellation window after dispatch begins but before hand-off to the carrier — the warehouse team believes there is a short reversible period. Needs their input; does not block v1, which treats any dispatch as final.
  • Partial cancellation — explicitly deferred. Would change the aggregate's invariant, so it warrants its own design pass rather than an extension of this one.