Payday Shopify App

Order Lifecycle Correctness as an Architecture

• Dedicated webhook handlers cover orders, cancellations, direct cancellations, exchanges, refunds, asynchronous refunds and returns — each one able to create or amend a financial document.
• Behind them sits a decision layer that refuses to act until the state is genuinely unambiguous: original-invoice readiness checks, refund-coverage analysis, and an explicit invoice-matching policy.
• Work that can't be resolved on the webhook is handed to cron schedulers with explicit queue gates, so a return that depends on a not-yet-created invoice waits rather than guessing.
• A wrong invoice isn't a cosmetic bug — it's an accounting error in a real business's books, and that constraint shapes every branch in the codebase.

Untangling Shopify Exchanges — the hardest thing in the project

• Shopify emits no single "exchange" event. An exchange arrives as an interleaved tangle of return, refund and transaction webhooks that individually look like ordinary returns and refunds.
• A dedicated exchange-batching layer correlates those events and labels each part correctly, so the return webhooks don't trigger a return, the refund webhooks don't trigger a refund, and the added and removed items all land on one invoice with the right calculations.
• Shipped soon after Shopify first allowed exchanges in their admin, which meant building against a brand-new, sparsely documented event shape — and it's covered by its own targeted test suite.

Unambiguous Order Identity Across Reconnects

• Merchants reconnect, reinstall and change credentials, which historically allowed one Payday client identifier to be associated with more than one Shopify shop — meaning "did we already invoice this order?" could return another shop's row.
• The fix routes every lookup through a single resolver that resolves against the querying shop's own recorded identifier history and returns a classification (exact match, ambiguous match, recovered-history match, no match) rather than a boolean.
• Callers then interpret that classification for their own direction: duplicate prevention treats an ambiguous hit as a reason to stop, while the cancellation credit gate refuses to act on one. Same resolver, opposite polarity — the kind of distinction that only becomes obvious after a near-miss.
• Delivered as staged workstreams with an atomic, DB-backed claim to prevent races, and grandfathering so existing merchants keep working.

Tests Pointed at the Dangerous Parts

• Rather than chase coverage numbers, the suite concentrates on where an error becomes a wrong invoice: cancellation decisions, exchange batching, refund coverage, original-invoice matching, webhook snapshots and resource-ID parsing.
• Runs on Node's built-in test runner via tsx with no heavyweight framework, split into focused npm scripts (order-race fixes, refund/cancellation, branch matrices) so a risky change can be verified in seconds.

Living With Sustained Shopify API Churn

• Shopify's API and feature set move constantly, so keeping current is structural work, not occasional maintenance: versioned GraphQL fragments, a schema-validation script that checks queries against a pinned Admin schema dump, and centralised transformers between Shopify shapes and Payday's invoice model.
• dependency-cruiser enforces architectural boundaries (with a separate "critical" ruleset), and generated project-reference maps of exports, dependencies and structure keep a 52k-line codebase navigable for a single maintainer.
• Design decisions and deferred work are captured as dated design docs and an engineering backlog with explicit exit criteria and abort gates.

Public App Store Compliance

• Full mandatory GDPR webhook coverage — customer data requests, customer redaction and shop redaction — plus app install/uninstall handling, as required of a public Shopify app.
• Billing runs through Shopify's subscription APIs with plan checks and trial handling, alongside merchant-facing onboarding, settings, order and product surfaces (including bulk sync with confirmation steps and inventory options).