# Building a Reliable Farmers-Market Marketplace

A farmers-market marketplace looks simple: vendors list produce, customers place orders, and everyone meets at a pickup window. The complexity appears when inventory changes by the hour. A grower may arrive with 40 pints of strawberries, sell 12 at the physical stall, and receive several online orders before the stock count synchronizes. The platform therefore needs to treat availability as a real-time constraint rather than a static catalog field.

## Modeling Local Inventory

Each listing should represent a specific product, vendor, market date, and pickup location. Inventory reservations can expire after a short checkout window, returning unpurchased items to the available pool. To prevent overselling, the database should update stock atomically and reject an order when the requested quantity exceeds the remaining inventory. Optimistic locking works well when contention is modest; high-volume markets may benefit from serialized inventory updates or a dedicated reservation service.

## Designing the Order Flow

Orders should move through explicit states such as `pending`, `paid`, `ready`, `collected`, and `cancelled`. Payment confirmation must be handled through an idempotent webhook because providers can retry the same event multiple times. Vendor notifications should also be asynchronous: placing an order should not fail merely because an email or text-message service is temporarily unavailable. A queue allows those notifications to be retried independently.

```yaml
reservation:
  ttl_minutes: 10
  release_interval_seconds: 30
orders:
  pickup_grace_minutes: 20
  webhook_idempotency: true
```

## Handling Pickup and Substitutions

Pickup workflows must work on unreliable mobile connections. A lightweight vendor dashboard can cache the day’s order list and queue status changes until connectivity returns. Substitutions should require customer consent during checkout, with clear options such as “no substitutions” or “replace with a similar item up to the original price.” This avoids improvisation at the stall and gives payment logic a predictable ceiling.

## Operating the Marketplace

Useful operational metrics include reservation-expiration rate, payment failures, inventory conflicts, order preparation time, and uncollected orders. Structured logs should carry order, vendor, and market identifiers so support staff can trace an issue without exposing customer details. With atomic inventory updates, idempotent payments, and offline-tolerant pickup tools, the marketplace can preserve the informal character of a farmers market while providing the reliability customers expect from online commerce.