# Building a Reliable Coffee Subscription Platform

## The Startup Context

A coffee subscription startup looks simple from the outside: customers choose a roast, set a delivery cadence, and wait for fresh beans. In practice, the product sits at the intersection of inventory forecasting, payment retries, fulfillment cutoffs, and customer preference changes. The core technical challenge is keeping those systems loosely coupled while still making each shipment feel personal and predictable.

## Subscription Scheduling

We model subscriptions as recurring plans, but we do not generate orders too far in advance. Instead, a daily scheduler finds subscriptions with an upcoming roast window, locks the record, and creates a shipment intent. This gives customers time to pause, change grind size, or swap origins without forcing support teams to cancel already-created orders.

```yaml
shipment_cutoff:
  timezone: America/New_York
  create_intents_days_before_roast: 3
  payment_retry_count: 4
  fulfillment_lock_hours_before_roast: 18
```

## Inventory and Roasting

Inventory is tracked at the green-coffee lot level and projected forward against active subscriptions, one-time orders, and expected spoilage. The roasting team needs a stable batch plan, so the application separates "reserved demand" from "locked fulfillment." That distinction lets the business forecast demand early while preserving operational flexibility until the roast schedule is finalized.

## Payments and Failure Handling

Payment collection runs before fulfillment locking, not after roasting. Failed charges move the shipment intent into a retry state and notify the customer with a self-service update link. If payment still fails before the cutoff, the system skips that shipment rather than creating manual exceptions that warehouse staff need to interpret.

## What We Learned

The most important engineering decision was treating coffee delivery as a workflow instead of a single order event. Subscriptions, payments, roasting, inventory, and fulfillment all change on different timelines. By making each transition explicit and observable, the startup can scale without losing the freshness and reliability customers expect from a local roaster.