> ## Content Index > Fetch the complete content index at: https://blog.tsd.digital/llms.txt > Use this file to discover other available public pages before exploring further. # Umbraco Commerce payment retries: the hidden order number trap - URL: https://blog.tsd.digital/umbraco-commerce-payment-retries-the-hidden-order-number-trap/ - Published: 2026-09-29T16:20:41.000Z - Updated: 2026-09-29T16:20:41.000Z - Description: Cancel a payment, come back and pay, and Umbraco Commerce may issue a new order number and overwrite the first attempt. Here's what that means for payment history, customer service and logging, and how to plan for it. - Author: Tim Gaunt - Tags: Umbraco, Customer Experience, Ucommerce, Advice If you're building on Umbraco Commerce, or deciding between it and Ucommerce, this one's worth five minutes. It's a small difference in how the two platforms handle payments. It caught us out recently, and the knock-on effects reach further than you might expect. We build on both Umbraco Commerce and Ucommerce, and we'd recommend either if the project suits it. Even so, the more time we spend in each codebase, the more obvious the differences become. ## What happened A customer on one of our Umbraco Commerce sites got as far as the Stripe payment page and cancelled. People do this all the time. The doorbell goes, or the card's in another room. By then Umbraco Commerce had already generated an order number and handed it to Stripe. So far, so normal - Ucommerce does the same. Later on, the customer came back and paid. The order went through and nothing looked out of place. We'd have been none the wiser if the customer hadn't contacted the retailer to say they'd struggled to pay. We opened the audit trail hoping the logs would explain what went wrong, and found some of the information we expected was missing from the order. Tracing it further, the order number had changed between the first attempt and the second. ## Why it matters more than it first appears A new order number is harmless enough on its own. What bothered us was the payment that came before it. **The earlier attempt leaves no trace.** Umbraco Commerce stores payment details as properties on the order itself, so there's only ever one set per order. When the customer tries again, the `TransactionId` and the Stripe properties (`paymentIntentId`, `stripeChargeId`, `stripeCustomerId` and `stripePaymentIntentId`) are all overwritten, along with the order number. Once our customer had paid, nothing in the database showed the first attempt had ever happened. The attempts do still exist in Stripe. That's little comfort to a customer service team who rarely have access to it, and the order itself can't tell you its own history. Ucommerce stores each payment attempt as its own record against the order, with its own identifier and status. A declined card or a switch to PayPal stays on the order for anyone to see. Umbraco Commerce has no equivalent table - payment data lives in the order properties - so keeping a history would mean changing the data model. We wouldn't expect a quick fix. Customer service feels this most. Picture a customer ringing up to say they tried to pay twice and it wouldn't go through. Whoever answers probably can't log into Stripe. On Ucommerce, the failed attempts are there on the order. On a default Umbraco Commerce build there's nothing to look at and nothing to support what the customer is telling you. And it isn't rare. Around 19% of orders on one of our Ucommerce sites have more than one payment attempt against them, mostly declined cards (insufficient funds comes up a lot) or people changing payment method halfway through. **Don't use the order number as your log correlation ID.** Anyone who's run a busy store will know this one, but it's easy to miss. Filter on the order number and you'll only see the latest attempt, with everything before the reset filed under a number the order no longer carries. ## Is this documented? Sort of. It's intended behaviour, but you have to go looking. The order number customisation guide mentions it under "Important considerations": > In Umbraco Commerce, order numbers are generated before redirecting to the payment gateway. If a customer cancels or modifies their order after an order number has been assigned, a new number is generated for the subsequent attempt, leading to gaps in the sequence. The custom checkout tutorial adds that once `BeginPaymentFormAsync` has assigned the order number, "no modifications must be made to the order after this point as it may result in the order number getting reset and the payment failing." Both statements are accurate, yet neither mentions payment history or what customer service will be left looking at. We only worked it out by reading the source. Debugging didn't help either. The reset happens inside the payment gateway's webhook call, which is a separate request from the one you're stepping through, so the data changes under your feet while the debugger shows nothing. ## Planning for it on Umbraco Commerce You can work around all of this, and it's far cheaper to do at the start of a build than after the first complaint. In rough order of importance: - **Record payment attempts yourself.** Hook into Umbraco Commerce's notification events and log each attempt, with the gateway's own reference, somewhere you control. Show it in the back office so customer service doesn't need a developer to find out what happened. - **Correlate logs on the order ID.** It's a GUID and it stays put when the order number changes. Keep the order number as a secondary property. - **Leave the order alone once `BeginPaymentFormAsync` has run.** A late shipping update, or a basket change in another tab, can trigger a reset. Get the order final before the customer goes to pay. - **Don't lose sleep over the gaps.** The docs warn that gaps in the order number sequence can cause problems for VAT receipts. We think that's overcautious. Gaps are standard on most e-commerce platforms, and invoice numbers should come from your accounting system or ERP anyway. Apart from the odd customer who likes a tidy sequence, nobody notices. ## Where this leaves the two platforms It comes down to design intent. Umbraco Commerce keeps its order model lean and sits natively in the Umbraco back office, so it's quicker to get a store live and easier for editors to pick up. For a smaller store or a retailer taking its first steps into e-commerce, that's a reasonable trade. Ucommerce starts from the assumption that payments fail, get retried and get split across methods, and models them accordingly. Once you've a customer service team fielding calls and a finance team reconciling against the gateway, we'd pick Ucommerce. If you're starting out on Umbraco Commerce, our starter kit, [Igloo Commerce](https://marketplace.umbraco.com/package/iglootheme.commerce?ref=blog.tsd.digital), gets a store up and running quickly with the checkout already built. This is likely the first of a few platform differences we'll be writing up. Choosing between the two, or inherited an Umbraco Commerce build you'd like checked for this sort of thing? Get in touch and we'll talk it through.