Overview
ZenHQ's client operated multiple grocery delivery stores on Shopify but needed capabilities far beyond what Shopify offers natively — custom checkout with specific payment gateways, complex delivery scheduling with capacity management, batch pricing operations, employee shift tracking, and real-time delivery GPS tracking.
We built three interconnected applications: a multi-tenant operations dashboard (Rails), a standalone checkout REST API (Rails), and a white-label checkout frontend (React). The system handles the full lifecycle from product browsing on Shopify to payment processing through Paysafe 3D Secure to delivery tracking via Tookan — all multi-tenant with per-store configuration for payment gateways, delivery zones, pricing rules, and branding.
💡
The Challenge
The project pushed us across every layer of the stack with several unique technical challenges:
Custom Checkout on Top of Shopify
Shopify's native checkout doesn't support complex delivery scheduling, multiple payment gateways per store, or capacity-managed time windows. We needed to build a complete checkout experience that replaces Shopify's checkout while still creating orders in Shopify after payment — maintaining catalog and inventory sync bidirectionally.
Multi-Gateway Payment Processing
Each store could use different payment providers — one store on Paysafe, another on Payfirma, a third accepting PayPal. The checkout API needed to route payments to the correct gateway based on the store's configuration, handle 3D Secure v2 authentication flows, and manage card tokenization for returning customers — all while maintaining PCI compliance.
Delivery Zone Detection & Capacity Management
Delivery zones are irregular geographic polygons, not simple radius circles. We needed point-in-polygon detection from GPS coordinates, with fallback to zip code prefix matching. Each delivery time window has limited capacity — when slots fill up, they must close in real-time to prevent overselling. Same-day delivery requires surcharge calculation with configurable cutoff times.
Multi-Tenant Data Isolation
Three separate applications sharing tenant context. Every API call, webhook, background job, and database query must be scoped to the correct tenant. A payment processed for Store A must never touch Store B's Paysafe account. Batch pricing for one tenant must never affect another's products.
Real-Time Fulfillment Operations
The operations dashboard handles live grocery fulfillment — shoppers picking items in stores with real-time tracking of found, missing, substituted, and damaged items at the line-item level. Delivery drivers tracked via GPS with ETA, signature capture, and customer ratings. Employee shifts with wage calculation and receipt management.
Bilingual Support
The platform serves Canadian grocery stores requiring full English and French support across the checkout interface — every label, error message, email, and delivery option must work in both languages.
⚡
Our Solution
We architected ZenHQ as three purpose-built applications, each optimized for its role, connected through REST APIs and shared tenant configuration.
Operations Dashboard (ZenManage)
A Rails application with 100+ database tables managing the full post-order workflow:
- Shopify webhook receivers for real-time order, product, customer, and inventory sync
- Order assignment system — assign groups of orders to shoppers by delivery date with department and vendor filtering
- Line-item tracking with granular quantity states: found, missing, substituted, error, damaged, not delivered
- Batch pricing engine — schedule future price and inventory changes, auto-applied and reversed by daily Sidekiq cron jobs
- Shift management with start/end times, pause tracking, wage calculation, gas costs, and per-shift receipt logging
- Delivery tracking integration with Tookan and CIGO — GPS locations, driver assignment, ETA, signature, and ratings
- B2B company management — auto-extract company from order notes, track spending analytics, order frequency, and customer hierarchy
- Xero accounting integration — auto-post orders, payments, refunds, and adjustments with configurable GL account mapping
- Role-based access control: admin, shopper, account manager, superadmin
Checkout REST API
A dedicated Rails API handling the cart-to-order pipeline with token-based cart state management:
- Cart lifecycle: dehydrated → hydrated → closed, with automatic price recalculation from Shopify on every load
- Multi-step validation: customer info, shipping address geocoding, delivery slot availability, billing address, payment readiness
- Payment gateway abstraction via ActiveMerchant — Paysafe (with 3DS and card vault), PayPal Express, Payfirma — routed per store
- Delivery fee rule engine — dynamic pricing based on customer email, company, products in cart, delivery option, and time window
- Discount code system — percentage, fixed amount, and free shipping codes with minimum purchase thresholds and one-time redemption tracking
- Tax calculation with configurable rates per tenant, applied to taxable items and delivery fees
- Order creation pipeline: record payment → create Shopify order via API → reserve delivery slot → redeem discount codes → close cart
- Geolocation-based zone detection using Geokit point-in-polygon with zip code prefix fallback
Checkout Frontend (ZenPay)
A React SPA providing the customer-facing checkout experience:
- 4-step checkout wizard with Material-UI components and responsive mobile layout
- Google Places address autocomplete with automatic delivery zone detection
- Calendar-based delivery date picker with time window selection and capacity indicators
- Store pickup mode with Google Maps showing store locations with marker clustering
- Paysafe hosted fields for PCI-compliant card capture with 3D Secure v2 challenge flow
- Saved credit card management — select, use, or remove stored payment methods
- Real-time cart editing with quantity adjustment and line item removal
- Promo code validation and application with instant price recalculation
- Full EN/FR internationalization via i18next with language toggle
- White-label theming — colors, logo, and branding pulled dynamically from backend configuration
- Dual-mode operation: standalone ZENPAY checkout or embedded SCHEDULER within Shopify stores
Multi-Tenancy (Apartment Gem)
Database-level tenant isolation across all three applications:
- Subdomain-based tenant routing — each store gets its own subdomain
- Per-tenant database schema with complete data isolation
- TenantConfig key-value store with 100+ configurable parameters per tenant
- Tenant-scoped Sidekiq jobs — batch pricing, order sync, and reporting all isolated per store
- Per-tenant payment gateway credentials, Shopify API keys, delivery zones, and branding
📈
Results & Impact
ZenHQ launched as a fully operational multi-tenant e-commerce platform serving grocery delivery businesses across Canada.
Platform Scale
- 100+ database tables across the operations dashboard covering orders, products, customers, assignments, shifts, deliveries, batches, and accounting
- Three interconnected applications — operations dashboard, checkout API, and React frontend — working as a unified ecosystem
- Multi-tenant architecture supporting multiple Shopify stores with complete data isolation
- Full REST API powering the checkout frontend and mobile integrations
Checkout & Payments
- Custom 4-step checkout replacing Shopify's native checkout with delivery scheduling, multiple payment gateways, and bilingual support
- Paysafe 3D Secure v2 integration for PCI-compliant card processing with card vault for returning customers
- Multi-gateway routing — Paysafe, PayPal Express, Payfirma, and on-delivery payment — configurable per store
- Automated order creation in Shopify after successful payment with full line item, address, and discount mapping
Delivery & Logistics
- GPS-based delivery zone detection with polygon mapping and zip code fallback
- Capacity-managed delivery time windows with automatic slot closing to prevent overselling
- Real-time driver tracking via Tookan and CIGO integration with ETA, signature, and rating capture
- Dynamic delivery fee calculation based on customer type, products, zone, and time window
Operations Efficiency
- Batch pricing engine — schedule future price changes across hundreds of products, auto-applied and reversed by daily background jobs
- Order-to-shopper assignment system with department filtering and delivery date grouping
- Line-item-level fulfillment tracking: found, missing, substituted, damaged — providing granular accuracy metrics per shopper
- Employee shift management with automated wage calculation, gas expense tracking, and receipt logging
- Automated Xero accounting integration — orders, payments, and refunds auto-posted to general ledger
Business Impact
The platform handles the complete grocery delivery lifecycle that would normally require separate tools for e-commerce, checkout, payments, delivery scheduling, fulfillment tracking, employee management, and accounting — unified into one multi-tenant system. Each new store onboards with its own Shopify connection, payment gateway, delivery zones, and branding without any code changes.
Technical Deep-Dive
Cart Calculation Pipeline
The checkout API recalculates the cart on every request to ensure pricing accuracy:
- Fetch current product prices from Shopify API (prevents stale pricing)
- Calculate subtotal from line items with weight-based pricing support
- Apply automatic discounts from Shopify product tags (tag-based percentage rules)
- Apply manual discount codes (percentage, fixed amount, or free shipping)
- Calculate delivery fee via rule engine (customer, company, product, time window rules)
- Calculate taxes on taxable items and delivery fees
- Apply bottle deposit surcharges (per-item environmental fees)
- Compute final total with all adjustments
Payment Transaction Flow
- Cart readiness validation — customer, address, delivery slot, billing address all required
- Credit card verification via Paysafe — AVS (address verification) and CVV checks
- Card tokenization — temporal tokens from frontend converted to vault tokens for repeat customers
- Authorization vs. Purchase routing — first-time customers get authorization only, repeat customers get direct purchase
- 3D Secure v2 challenge flow — handled by Paysafe hosted checkout with callback to frontend
- Post-payment pipeline: record transaction → create Shopify order → reserve delivery slot → redeem discounts → close cart
- Void handling — if order creation fails after authorization, the payment is automatically voided
Delivery Zone Engine
- Zones defined as GPS coordinate polygons stored in the database
- Point-in-polygon detection using Geokit when customer enters address
- Fallback to zip code prefix matching for areas without polygon coverage
- Each zone has its own delivery options, time windows, fees, and capacity limits
- Time window capacity tracking — reserved slots increment on order, decrement on cancellation
- Blackout date management for holidays with bulk date range closing
Batch Pricing System
- Create batches with start and end dates covering multiple products
- Each batch product stores original price and batch price with status tracking
- Daily Sidekiq cron job (JobUpdateWorker) checks dates and auto-applies or reverses batch pricing
- Manual force-apply and reverse operations for immediate changes
- Updates pushed to Shopify via variant API to keep storefront pricing in sync
- Status lifecycle: pending → active → done, with error tracking for failed Shopify updates
Fulfillment Tracking
- Orders assigned to shoppers by delivery date with bulk assignment support
- Shoppers report per-item quantities: found, missing, substituted, error, damaged, not delivered
- Report submission auto-updates order and line item statuses in the system
- Delivery tasks created in Tookan/CIGO with webhook callbacks for status updates
- GPS location tracking — driver coordinates stored with timestamps for route visualization
- Post-delivery: signature capture, customer rating, and driver feedback
Frontend Architecture
- React 16 with Redux state management — cart, navigation, customer, payment, and shipping state
- Material-UI component library with dynamic theme color injection from backend configuration
- Google Maps integration for store location picker with Supercluster marker clustering
- Google Places API for address autocomplete with automatic lat/lng extraction
- Paysafe hosted fields loaded via external script for PCI-compliant card capture
- i18next for full EN/FR internationalization with language toggle
- Dual deployment: standalone checkout (S3 hosting) and embedded Shopify mode (iframe integration)
- Responsive design — two-column desktop (form + summary) collapses to single-column mobile
External Integrations
- Shopify REST API — products, customers, orders, inventory, fulfillment, webhooks
- Paysafe/Netbanx — card payments, vault tokenization, 3D Secure v2, AVS/CVV verification
- PayPal Express Checkout — alternative payment method with CAD currency
- Payfirma — secondary card gateway for multi-merchant support
- Xero — automated accounting integration with configurable GL account mapping
- Tookan — delivery tracking, driver assignment, task management, GPS webhooks
- CIGO — alternative delivery tracking platform
- Google Maps & Places — delivery zone visualization, address autocomplete, store locations
- SendGrid — transactional emails (password reset, order confirmation, reports)
- AWS S3 — file uploads (product images, shift receipts)
Technology Stack
Ruby on Rails
React 16
Redux
Material-UI
MySQL
PostgreSQL
Redis
Sidekiq
Shopify API
Paysafe API
PayPal API
Payfirma
Xero API
Google Maps API
Tookan API
CIGO API
AWS S3
Docker
AWS Elastic Beanstalk
ActiveMerchant
Apartment (Multi-Tenancy)
i18next
