Delivery Module

Overview

The Delivery Module is an order fulfilment and delivery system for a business selling perishable hand-made products through an online store. It routes each order to the right fulfilment path. That means local courier, national shipping or in-store pickup. It manages daily production capacity, handles carrier labels and tracking, runs subscriptions and refunds and keeps customers informed by text and email. It serves operations staff who need to know exactly what to do with an order next. The business can't afford lost orders, duplicate shipping charges or double refunds.

Challenges

Order data lived in an external online store where orders could be deleted at any moment. That threatened the refund, shipping and fulfilment audit history the business needed to keep. Orders had to be routed correctly between a same-metro local courier and national carrier shipping based on postal code and shipping class. No reliable mechanism made that decision. The local fulfilment lifecycle regularly moved ahead of the store's own order status. A routine re-sync could overwrite a completed or in-transit order with stale data. Inbound updates re-triggered outbound pushes and created endless sync loops. The products are hand-made and perishable so each weekday could only absorb so many orders. Nothing capped production per day. Operator double-clicks risked minting duplicate carrier labels and double-charging shipping. Under concurrent load a cancellation could issue a refund twice or over-refund an order that already had a partial refund. Customer text messages had to respect opt-out law and prove delivery. There was no opt-out enforcement and no audit trail. Failed subscription renewals quietly lost recurring revenue. All of this still ran on a legacy application. It had to be ported onto a new multi-tenant platform without breaking the existing storefront.

Solution highlights

We built a bidirectional sync layer. It imports orders, products and subscriptions from the store and mirrors local status, production date, tracking and refunds back. An explicit field-ownership matrix governs it so neither side overwrites the other. Post-packaging fulfilment splits into three carrier-aware paths: local courier route stops, national carrier shipping and in-store pickup. The path comes from an operator-editable fulfilment method derived from postal-code delivery zones. Carrier integration was implemented end to end with token caching, label creation and voiding, address normalisation, daily pickup batching, tracking polling and a signature-verified tracking webhook. Label and invoice PDFs are stored permanently rather than relying on expiring hosted links. A production-capacity scheduler enforces a three-day lead time and per-weekday order caps with manual overflow overrides. Database row locks stop two concurrent assignments overbooking the same day. The subscription engine was ported in full including renewal cadence maths, pause and resume auditing, card recharges and a staged failed-payment reminder cadence before cancellation. Each concurrency and money-movement path was hardened with distributed locks, forward-only status guards, feedback-loop suppression and a two-phase cancel-and-refund flow with an idempotency backstop. All outbound side effects moved onto rate-limited retrying background tasks so staff actions return instantly.

Key Features

• Bidirectional store synchronisation with an explicit field-ownership matrix
• Three carrier-aware fulfilment paths: local courier, national shipping and in-store pickup
• Automatic routing by postal-code delivery zone with operator override
• End-to-end carrier integration with label creation, voiding, pickup batching and tracking webhooks
• Permanently stored label and invoice PDFs immune to expiring carrier links
• Production-capacity scheduler with lead time, per-weekday caps and manual overflow
• Packaging workflow resolving line items from templates or manual dimensions
• Full subscription engine with renewal cadence, pause/resume auditing and card recharges
• Staged failed-payment reminder cadence before subscription cancellation
• Customer SMS and email on status changes with opt-out enforcement and an append-only send log
• Concurrency safety through distributed locks, forward-only status guards and idempotent refunds
• Dry-run migration and reconciliation commands for backfilling legacy data

Our Role & Approach

Our role was to move a live revenue-critical operation onto a new platform without a single lost order or duplicate charge. Safety was the primary design constraint. We made each money-movement path fail closed rather than open. A refund that cannot be confirmed doesn't retry blindly. A cancel self-heals on retry. A label void is guarded so an already-shipped package is never voided. We used forward-only status guards and push suppression to fix the sync-loop and status-regression problems at the root instead of patching symptoms. All outbound calls to external services moved onto background tasks so staff never wait on a third party. And each migration command was written dry-run by default. Data could be validated before anything was written. Reconciliation reports proved the result.

Technology Stack

Backend: Django, Django REST Framework, Celery with rate-limited retrying tasks, Redis locks, multi-tenant architecture. Ecommerce: WooCommerce and WordPress integration with HMAC-verified webhooks. Shipping: FedEx API with OAuth token caching, ShipEngine address normalisation, tracking polling and webhooks. Payments: Stripe card recharges and refunds. Messaging: Twilio SMS and transactional email. Operations: dry-run migration and reconciliation management commands plus websocket staff alerts.

Outcomes

Each order now flows from intake through packaging to a final delivered or picked-up state across all three fulfilment paths. Local fulfilment state and the online store stay consistent without overwriting each other. Forward-only guards and push suppression prevent both status regressions and sync loops. Deleted store orders are preserved locally so refund, shipping and fulfilment audit history survives after the store removes them. Production days can no longer be overbooked. Capacity caps, lead time and weekday rules are enforced on both staff and customer reschedules. Carrier labels aren't double-charged or created against incomplete addresses. Order status advances automatically as tracking scans arrive. Subscriptions renew on schedule and recover revenue through a staged reminder cadence before cancellation. Customers get timely updates with opt-outs honoured and each message logged for compliance. Staff work from a fast orders board with status tabs, search, path filters and a computed next-step hint. Money moves stay safe under concurrency. The business runs entirely on the new platform with historical orders reconciled to their true status.