Overview
We partnered to rebuild a flower and gift company's order-fulfillment engine as a multi-tenant Django plugin that sits behind a WooCommerce storefront. We built bidirectional store sync, carrier-aware routing across local courier, FedEx, and in-store pickup, a production-capacity scheduler, packaging, subscription renewals, and customer notifications, porting the entire operation off a legacy Flask-and-SQLite routing app without changing the WooCommerce storefront. The result is a single fulfillment backbone that moves every order from checkout to delivery with concurrency-safe carrier, refund, and tracking handling.
Challenges
- Order fulfillment data lived in an external WooCommerce store where orders could be trashed or deleted at any time, threatening to wipe out the refund, FedEx, and fulfillment audit history the business needed to keep.
- Orders had to be routed correctly between a same-metro local courier (Chicagoland) and national FedEx shipping based on the customer's ZIP code and WooCommerce shipping class, with no reliable mechanism to make that decision.
- The local fulfillment lifecycle regularly advanced past the WooCommerce order status, so a routine re-sync from the store could clobber a completed, cancelled, or in-transit order with stale data.
- Inbound webhook writes re-triggered outbound mirror pushes, creating infinite WooCommerce-to-database-to-WooCommerce sync loops.
- Producing hand-made, perishable flower arrangements meant each weekday could only absorb so many orders, yet there was no way to cap production per day while still allowing manual overflow when the shop chose to accept more.
- Operator double-clicks and repeated batch-ship actions risked minting duplicate FedEx labels and double-charging the business for shipping.
- Under concurrent workers, cancelling and refunding an order risked issuing a WooCommerce refund twice or over-refunding orders that already carried a partial refund.
- Customer SMS had to respect TCPA opt-out law and prove delivery, yet there was no opt-out enforcement or audit trail for notifications.
- Failed subscription renewal payments quietly lost recurring revenue, with no structured way to remind customers before giving up on a subscription.
- The entire operation was still running on a legacy Flask routing app backed by SQLite alongside a WordPress/WooCommerce storefront, and had to be ported onto a new multi-tenant Django platform without breaking the storefront's existing custom endpoints.
- FedEx labels were being generated against blank or unverified shipping addresses, producing failed and returned shipments.
- Hosted FedEx label URLs expire, so a label or invoice PDF fetched once could later become unretrievable when staff needed to reprint it.
Solution highlights
- We built a bidirectional WooCommerce sync layer that imports orders, products, and subscriptions and mirrors local status, scheduled production date, tracking, and refunds back to the store, governed by an explicit field-ownership matrix so neither side clobbers the other.
- We split post-packaging fulfillment into three carrier-aware paths — Chicagoland local courier route stops, FedEx national shipping, and in-store pickup — keyed off an operator-editable fulfillment method derived from ZIP-code delivery zones.
- We implemented FedEx end to end with OAuth token caching, label creation and voiding, ShipEngine address normalization, daily pickup batching, tracking polling, and a signature-verified tracking webhook, persisting label and invoice PDFs in the database.
- We built a production-capacity scheduler that enforces a three-day lead time and per-weekday order caps with manual overflow overrides, using row locks to prevent two concurrent assignments from overbooking the same day.
- We delivered a packaging workflow that resolves each line item automatically from product package templates or accepts manual dimensions, gating orders into the shippable state FedEx label creation requires.
- We ported the legacy subscription engine end to end: renewal-cadence math, pause and resume auditing, renewal orders that recharge the customer's saved Stripe card through the storefront, and a 3/6/9-day failed-payment reminder cadence that cancels a persistently failing subscription after twelve days.
- We added customer SMS and transactional email on order-status transitions with per-order TCPA opt-out, an append-only send log, and staff websocket alerts when a new WooCommerce order arrives.
- We hardened every concurrency and money-movement path with Redis single-flight locks, forward-only status guards, feedback-loop suppression, and a two-phase cancel-and-refund flow with an idempotency backstop.
- We moved all outbound side effects onto rate-limited, retrying Celery tasks fanned out per tenant, so staff status changes and reschedules return immediately instead of blocking on WooCommerce, FedEx, or Twilio calls.
- We wrote a suite of dry-run-by-default migration and reconciliation commands that backfill production dates, FedEx shipment history, and fulfillment methods from legacy exports and repair the data artifacts the migration introduced.
Outcomes
- Every order now flows from WooCommerce intake through packaging to a terminal delivered or picked-up state across local courier, FedEx, and pickup paths.
- Local fulfillment state and WooCommerce stay consistent without overwriting each other, because forward-only guards and push suppression prevent both status regressions and sync loops.
- Trashed or deleted WooCommerce orders are soft-preserved locally, so refund, FedEx, and fulfillment audit history survives even after the store removes them.
- Production days can no longer be overbooked; capacity caps, lead time, and per-method weekday rules are enforced on both staff and customer self-reschedules.
- FedEx labels are no longer double-charged or minted against incomplete addresses, and order status advances automatically as tracking scans arrive by polling and webhook.
- Subscriptions renew on schedule and recover revenue through a staged reminder cadence before a persistently failing payment is cancelled.
- Customers receive timely SMS and email updates on order-status changes, with SMS branded to the business, opt-outs honored, and every SMS send logged for compliance.
- Staff work from a fast Orders board with status tabs, indexed search, fulfillment-path filters, and a computed next-step hint that tells them what to do next.
- Money moves stay safe under concurrency: refunds fail closed rather than double-charging, cancels self-heal on retry, and FedEx label voids are guarded so an already-shipped package is never voided.
- The business runs entirely on the new multi-tenant platform with the legacy WordPress plugin repointed unchanged, and historical orders reconciled to their true fulfillment status.