Saleor field notes
Fix Saleor checkout, channels, stock, orders, and fulfillment with a script
A working library of the problems that hit real Saleor stores, across checkout and stock reservation, channels and channel listings, warehouses and stock, orders and fulfillment, payments, and webhooks, and how to detect or repair each one with a small Python or Node.js script. 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.
Checkout & Stock Reservation
6 guidesPaid checkout never converts to an order
Browser closes after payment succeeds but before checkoutComplete runs, leaving a paid checkout orphaned. Script finds and completes them.
ReconcilerAbandoned checkout keeps stock reserved past TTL
CHECKOUT_TTL_BEFORE_RELEASING_FUNDS not enforced, leaving stale reservations. Script finds and releases expired checkout stock.
RepairConcurrent checkouts oversell the same stock
Simultaneous checkouts allocate more units than exist for a SKU. Script audits allocated versus on-hand stock per warehouse.
DiagnosticDuplicate stock checks still allow double selling
Repeated validation at checkout create and address update passes even at twice available stock. Script cross checks order line quantity against warehouse stock.
DiagnosticcheckoutCreate returns a stale existing checkout
New checkout requests reuse an old open checkout, carrying stale lines or vouchers. Script detects checkouts reused across sessions with mismatched metadata.
DiagnosticCheckout lines fail to add without a country or pickup
checkoutLinesAdd errors for anonymous carts lacking a shipping country when click and collect is off. Script reproduces via API to flag misconfigured channels.
DiagnosticShipping & Warehouses
4 guidesProduct unavailable from a warehouse zone channel mismatch
Warehouse not linked to the customer's shipping zone and channel combo makes an in-stock product unbuyable. Script cross checks warehouse zone channel links.
DiagnosticWarehouse cannot join a shipping zone without shared channel
Assigning a warehouse to a shipping zone silently fails when they share no channel. Script detects orphaned warehouse to zone links.
DiagnosticNo shipping methods available for a channel
Shipping method not listed for the checkout's channel yields an empty shipping list. Script finds channels with zero shipping method listings.
ReconcilerShipping methods do not refresh after address change
availableShippingMethods stays stale when the shipping address changes to a newly covered country. Script re-requests methods after address update to catch stale results.
ReconcilerStock & Inventory
4 guidesStock quantity reads zero despite items in warehouse
Stock.quantity shows zero while the warehouse actually holds units, a data consistency bug. Script diffs stock against allocations to detect drift.
ReconcilerBulk stock update leaves stale or partial rows
productVariantStocksUpdate fails to fully update stock across all warehouses. Script compares intended versus actual per warehouse stock after bulk updates.
ReconcilerStock update webhook not triggered on some mutations
PRODUCT_VARIANT_STOCK_UPDATED does not fire for certain stock changing mutations, desyncing external inventory. Script polls stock and diffs against webhook delivery logs.
ReconcilerUnpaid orders keep stock allocated indefinitely
Orders with canceled or missing payment never auto cancel, holding allocated stock forever. Script finds aged unpaid orders and deallocates or cancels them.
ReconcilerProducts, Variants & Channels
6 guidesVariant has no channel listing after creation
New or bulk created variants can end up with zero channel listings, making them unsellable though the product is published. Script finds variants with no channel listing.
ReconcilerProduct published but invisible from missing channel price
Variant published to a channel with no non-zero price stays invisible to storefronts. Script cross checks channel listing against variant price.
DiagnosticInvalid channel slug accepted without error
Passing a nonexistent channel slug to a query or mutation silently returns empty or wrong results instead of erroring. Script validates slugs against the channel list before use.
DiagnosticProduct without any variant crashes queries
Products created with zero variants cause crashes in storefront and checkout flows. Script scans products for missing default variants.
DiagnosticVariant pricing query returns null without channel argument
Pricing queries that omit the channel slug return null, which scripts can mistake for an unpriced variant. Script re-queries per channel before flagging unpriced variants.
DiagnosticVariant cost price miscalculates with multiple stock rows
costPrice computes incorrectly when a variant has more than one stock record and an empty cost. Script recomputes cost and flags inconsistent variants.
DiagnosticOrders & Fulfillment
9 guidesOrder stuck unfulfilled after payment succeeds
Order status never leaves UNFULFILLED even after a successful payment or fulfillment creation. Script queries paid orders with no fulfillment past a time threshold.
DiagnosticFulfillment fails when variant stock equals one
orderFulfill misreports available stock and blocks fulfillment when a variant has exactly one unit. Script re-verifies stock against requested fulfillment quantity.
DiagnosticDigital products not auto fulfilled despite setting enabled
automatic_fulfillment_digital_products is ignored for some orders, leaving digital only orders stuck unfulfilled. Script queries digital only orders still unfulfilled.
DiagnosticPartial fulfillment breaks on a zero quantity line
fulfillmentCreate errors when a multi line order intentionally leaves one line unfulfilled, blocking partial shipment. Script identifies orders stuck mid fulfillment.
DiagnosticEditing a confirmed order reverts it to draft status
Changing shipping address or lines on a placed order flips order status back to DRAFT, hiding it from normal queues. Script scans for draft orders that already have payments attached.
DiagnosticdraftOrderComplete drops the applied voucher
Converting a draft order with a voucher loses the discount on completion, understating the applied discount. Script compares draft versus completed order discount and totals.
DiagnosticDraft order taxes reset to zero on completion
Tax fields computed on the draft order get wiped once draftOrderComplete runs, leaving blank tax on the final order. Script compares pre and post completion tax fields.
DiagnosticManual order line discount deleted on recalculation
Manually applied line level discounts vanish after certain order update mutations trigger a recalculation. Script compares line discounts before and after updates.
DiagnosticCannot unfulfill or delete an order paid with a gift card
Orders partly paid with a gift card get stuck because unfulfill or delete mutations error out. Script detects gift card orders that fail lifecycle mutations.
DiagnosticPayments & Transactions
5 guidesCaptured amount doubles the order total
Two capture transactions each equal to the total get recorded, leaving totalCaptured at twice the order total. Script sums transaction events per order and flags totals exceeding the order total.
DiagnosticOrder can be charged more than its total
A bad payment or transaction amount lets captured plus authorized exceed the order total unchecked. Script flags any order where captured plus authorized exceeds total.
DiagnostictotalBalance drifts after refund or authorization adjustment
totalBalance is not recalculated correctly after authorization adjustment or refund success events. Script recomputes balance from transactions and flags mismatched orders.
DiagnosticNo available payment gateways despite plugin enabled
A payment plugin is enabled in the dashboard but checkout reports zero gateways for the channel. Script queries available payment gateways per channel to detect config gaps.
DiagnosticCharged amount stays stale after manual capture
totalCharged does not update after a manual capture unless a transaction event report or update call is made. Script reconciles gateway captures against Saleor transaction records.
ReconcilerVouchers & Gift Cards
5 guidesVoucher usage count double incremented on payment retries
Two stage payment flows call checkoutComplete twice, double incrementing voucher used count. Script recomputes real usage from orders and corrects the counter.
ReconcilerVoucher usable past its usage limit under concurrency
A race condition lets a single use voucher be redeemed by two simultaneous completing checkouts. Script counts actual redemptions against usage limit to find overages.
ReconcilerEntire order percentage voucher discount miscalculated
Percentage vouchers on the entire order compute a discount inconsistent with the stated percentage or base amount. Script recomputes expected discount and flags mismatched orders.
DiagnosticGift card balance update overwrites initial balance
Updating balanceAmount resets both current and initial balance even on an already used card. Script detects cards where current balance exceeds initial balance.
DiagnosticGift card balance not restored on order cancellation
Cancelling a paid order does not refund the gift card balance that was used. Script finds cancelled orders with gift card payments and restores the balance.
RepairWebhooks & Events
4 guidesWebhook deliveries stuck failed past retry limit
Async webhooks stop retrying after five exponential backoff attempts and sit as failed. Script queries event delivery status and retries stale failed ones.
RepairQueued events become permanently failed while app disabled
Disabling an app drops queued events as permanently failed instead of delivering them on reactivation. Script diffs expected versus delivered events after re-enabling an app.
ReconcilerWebhook payload fields diverge from documented schema
Delivered webhook payloads do not match the documented schema for that event type. Script diffs sample payloads against the expected schema to flag drift.
DiagnosticORDER_UPDATED webhook skipped on metadata change
Updating an order's metadata or private metadata does not trigger the ORDER_UPDATED async event. Script compares metadata update timestamps to webhook delivery logs.
DiagnosticTax, Pricing & Migration
5 guidesTax calculation off by rounding cents on totals
Flat rate tax calculation produces amounts off by cents from the expected rate, skewing order totals. Script recalculates expected tax and flags line or order mismatches.
DiagnosticOrder subtotal uses gross instead of net price
Order subtotal is computed from gross rather than net line prices when tax is included, producing an incorrect figure. Script recomputes subtotal from net prices and compares to the stored value.
DiagnosticDiscount rounding change breaks totals after upgrade
The 3.11 to 3.12 rounding mode change alters checkout and order totals for percentage vouchers post upgrade. Script recomputes discounted totals to find pre and post upgrade drift.
ReconcilerFailed concurrent index migration leaves invalid index
A failed CREATE INDEX CONCURRENTLY during a version upgrade leaves an invalid index in Postgres. Script queries pg_index for indisvalid false and rebuilds them.
DiagnosticBulk imported variants missing channel listings
Bulk variant or product creation can leave variants without required channel listing entries, making the imported catalog unsellable. Script diffs imported variant IDs against the channel listing table.
ReconcilerCustomers & Notifications
3 guidesOrder confirmation email sent before payment succeeds
Confirmation email fires on order creation ahead of payment success, misleading customers on unpaid orders. Script flags orders where the confirmation event predates the first charge success.
DiagnosticGuest checkout order not linked to matching customer account
Guest checkouts with an email matching a registered user do not attach the order to that user, undercounting customer orders. Script matches order email to user records and flags unlinked orders.
DiagnosticDuplicate address rows created instead of reusing saved address
Every order with shipping creates a new address row even when it matches a saved address, bloating the address book. Script finds and merges duplicate addresses per user.
ReconcilerFighting a Saleor bug right now?
If you have a problem in Saleor checkout, channel, stock, 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