# Brewing a Reliable Coffee Subscription Platform

BeanRoute started with a simple promise: deliver freshly roasted coffee on each customer’s preferred schedule. Behind that promise is a subscription system that must coordinate recurring payments, inventory, roast dates, and shipping without sending duplicate bags or charging customers after they pause.

## Designing Around Subscription Events

Our platform uses an event-driven architecture built around subscription changes. When a customer starts, skips, pauses, or updates a plan, the API records the change in PostgreSQL and publishes an event to a queue. Separate workers handle billing, fulfillment, notifications, and analytics, allowing each workflow to retry independently when an external service is unavailable.

## Making Fulfillment Idempotent

Payment providers and message queues can deliver the same event more than once, so every fulfillment job includes a unique cycle identifier. Before creating a shipment, the worker checks whether that cycle already has a fulfillment record. A database uniqueness constraint provides the final safeguard against duplicate orders during concurrent retries.

```yaml
subscription_cycle:
  retry_limit: 5
  idempotency_key: "{subscription_id}:{billing_date}"
  shipment_cutoff_hours: 48
```

## Matching Demand to Fresh Roasts

Coffee inventory behaves differently from ordinary retail stock because freshness matters as much as quantity. Each night, a forecasting job aggregates upcoming subscription cycles by roast profile, grind size, and bag weight. Roasters receive a production plan for the next seven days, while a small safety margin covers failed payments that are later recovered and last-minute customer changes.

## Observability in Production

We monitor the customer journey rather than only server health. Key metrics include successful renewals, duplicate-event suppression, time from payment to fulfillment, and shipments created after their cutoff. Distributed traces connect webhook ingestion to billing and warehouse jobs, making it possible to diagnose whether a delayed order originated in our application or an external provider.

## What We Learned

The hardest part of a coffee subscription business is not scheduling recurring charges; it is maintaining a consistent state across systems with different failure modes. Durable events, idempotent workers, explicit cutoff rules, and operational metrics gave BeanRoute enough resilience to scale while keeping the experience simple for customers—and the coffee fresh.