Shopify field notes
Fix Shopify orders, payments, subscriptions, and inventory with a script
A working library of the problems that hit real Shopify stores, across orders and payments, refunds and payouts, subscriptions, inventory, and fulfillment, and how to detect or repair each one with a small Python or Node.js script on the Admin GraphQL API. Every guide has a diagram of the problem, a diagram of the fix, full code in both languages, tests, and links to the source reports.
Orders, payments, and webhooks
8 guidesOrders stuck Unpaid after an outside payment
Bank transfer or cash on delivery came in but the order still says Pending. Mark the eligible ones paid, safely.
RepairWebhook subscription auto-deleted
Too many failed deliveries and Shopify removed your webhook. Detect the gap and recreate the subscription.
RepairWebhook HMAC check keeps failing
The raw body got parsed before you verified it, so every event is rejected. Verify against the raw bytes.
DiagnosticDuplicate webhook deliveries run twice
The same event arrives more than once and doubles your work. Dedupe on the webhook id.
ReconcilerMissed webhooks with no backfill
Your app was down past the retry window. Poll updated orders and apply what you missed.
ReconcilerAuthorized payment expires uncaptured
The seven day hold runs out before you capture. Sweep authorized orders and capture the valid ones.
ReconcilerDouble charge from duplicate transactions
Two SALE transactions landed on one order. Find the duplicates and refund the extra.
RepairHigh-risk orders left unactioned
Fraud-flagged orders sit and ship anyway. Read the risk assessment and hold or cancel them.
DiagnosticRefunds, payouts, and reconciliation
7 guidesTransactions total does not match the order
The sum of captures and refunds drifts from the order total. Report the ones that do not tie out.
DiagnosticReconcile orders against payouts
A bank deposit never equals the order totals. Tie each payout to its balance transactions to the cent.
ReconcilerProcessing fee not recorded on the order
Reports show gross, not what you kept. Pull the fee from the balance transaction onto the order.
ReconcilerPartial refund leaves the tax untouched
A refund gave back the item but not its tax. Recompute the tax portion on partial refunds.
RepairRefund exists but the money never moved
The refund shows on the order while the gateway transaction failed. Catch the stuck ones.
ReconcilerChargeback pulled funds, order still Paid
A dispute took the money but the order looks fine. Write the dispute state onto the order.
ReconcilerPresentment vs settlement currency
The buyer paid one currency and you settled another. Make the exchange explicit in the report.
ReconcilerSubscriptions and billing
7 guidesRenewal fails on an expired card
The saved card expired and the renewal stalls. Find the contracts and send an update-card email.
ReconcilerContract has no valid payment method
The method was revoked or never set. Detect the contracts that cannot bill and prompt the buyer.
DiagnosticDunning never retries a failed charge
A billing attempt failed and nothing tried again. Schedule retries with a safe backoff.
RepairDuplicate renewal charges
A retry with no idempotency key billed twice. Use a deterministic key per contract and cycle.
ReconcilerNext billing date drifts
The stored date and the real cycle disagree. Compare them and realign the schedule.
ReconcilerBilling runs on a cancelled contract
A scheduled attempt still made an order after cancel. Guard attempts on the contract status.
ReconcilerSelling plan deleted after app uninstall
Removing the app dropped the plan and broke the product. Recreate the group and re-point it.
RepairInventory
6 guidesAvailable drifted from real on-hand
The number on the store no longer matches the shelf. True it up with a compare-and-set write.
ReconcilerOverselling from concurrent writes
Two updates raced and the count went wrong. Use compare quantity so a stale write is rejected.
ReconcilerOn-hand vs available vs committed
Raw stock got treated as sellable. Read the real quantity names and report the difference.
DiagnosticNegative or phantom inventory
The oversell policy let the count fall below zero. Find the items and set the right policy.
RepairUntracked items sell without limit
Tracking was off so the item never runs out. Detect them and turn tracking on.
DiagnosticBulk stock true-up after a bad import
An import left the counts wrong across the catalog. Re-set them in safe batches.
ReconcilerFulfillment
4 guidesOrders stuck Unfulfilled
The fulfillment was never created so the order never ships. Find the open ones and fulfill them.
DiagnosticFulfillment stuck On hold
A hold was placed and never released. Release the specific holds and let the order move.
Repair3PL fulfillment out of sync
The warehouse shipped but Shopify still shows in progress. Close or move the fulfillment order.
ReconcilerRouted to an out-of-stock location
The order went to a location with no stock. Move the fulfillment order to one that can ship.
RepairCustomers and data
4 guidesDuplicate customers for one email
The same shopper has several records. Merge them so history and credit stay in one place.
ReconcilerPaid checkouts stranded as abandoned
A checkout paid but no order exists. Find the stranded ones and reconcile them.
ReconcilerTest and Bogus Gateway orders in live data
Test orders slipped into your real reports. Flag and separate them from live sales.
ReconcilerExternal id metafield dropped on create
Your linking key vanished on order create. Audit and set the metafield back.
RepairFighting a Shopify bug right now?
If you have a problem in Shopify orders, payments, subscriptions, inventory, or fulfillment that you would rather hand off, this is the kind of work I do. Message me and we can work through it together.
Found this useful?
These guides are free and always will be. If one saved you a support ticket or a refund, you can throw a coffee my way. It keeps the notes coming.
Buy me a coffee on Ko-fi