A WooCommerce Refund Is Not a Credit Note — and GSTR-1 Knows

The WooCommerce Refund button reverses order totals and optionally calls the Razorpay refund API. It does not emit a numbered credit note document, which is the only artifact the GST portal cares about. Here is what we had to build on top of WooCommerce to make partial refunds map cleanly to CDNR rows your CA will accept.

14 October 2026 · 10 min read

On 11 September a partial return of 2 units out of a 5-unit order went through our client's WooCommerce store as a ₹4,720 Razorpay refund. The order edit screen showed it neatly. Tally picked up the bank entry when the settlement landed four days later. Nothing in that chain produced a credit note document, and the CA found that out in the October GSTR-1 review when the CDNR table came up empty for a month in which there had definitely been returns. Painful backfill, and the kind that always costs more than you'd expect because by then the Razorpay statement is three settlement cycles downstream and the ops team has moved on to other things.

The WooCommerce Refund button does two things, and that's the whole of what it does. It reverses the order totals in wp_postmeta, and if you tick the box labelled "Refund via Razorpay", it fires the gateway's refund API. At no point in that flow does WooCommerce generate a document with a credit note serial number — which is the only artifact the GST portal actually cares about when you file GSTR-1. If you've been running a WooCommerce store on the Razorpay-plus-Tally stack for a year or two, your CA has probably already told you about this gap. Possibly in a tone of voice.

What WooCommerce calls a refund, and what GST law calls a credit note

A refund in WooCommerce is a database event. It's a child post of the order with post_type = shop_order_refund, carrying negative line items and a reference back to the parent order. Riya spotted this while we were digging through the schema trying to figure out where to hang our document number — she pointed out that the refund post is actually quite useful because it already stores line-level reversal data, it just has no document number field by default. No serial. No date-of-issue field distinct from the created-at timestamp. No place to record which original invoice it's reversing against.

The GST portal, meanwhile, has a CDNR table (Credit/Debit Notes Registered) in GSTR-1 that wants a very specific set of fields for every credit note you've issued in the return period: original invoice number, original invoice date, credit note number, credit note date, taxable value, and the tax amounts split across CGST, SGST or IGST as applicable. If any of those are missing or inconsistent — if two credit notes carry the same number, if the credit note number collides with an invoice number from the same series, if the original invoice reference points at an invoice that was never filed in a prior GSTR-1 — the row either rejects at upload or sails through and then shows up as a mismatch in the recipient's GSTR-2B. Neither is a good outcome.

And then there's Rule 53 of the CGST Rules, which is the bit that trips up most of the plugin implementations we've seen. Credit note numbering must be a separate monotonic series from invoice numbering. Not a shared counter, not a prefix on the invoice series — a genuinely separate sequence. On top of that, unlike invoice numbers (which many Indian businesses reset on 1 April for the new financial year, and which GST law tolerates because the fiscal-year prefix usually keeps them unique), credit note numbers are typically kept running across financial years. We've seen a few CAs argue the point either way, but the safer reading, and the one we've settled on, is: don't reset credit note serials on 1 April. Let them accumulate.

This is also why we stopped relying on the PDF Invoices & Packing Slips plugin's credit note add-on, incidentally. It's a perfectly decent plugin for the invoice side — we still use it on several client sites for the invoice PDF generation — but in one install (we think it was a configuration mistake rather than a plugin bug, honestly we never fully reproduced it) the credit note add-on silently reused the invoice number sequence. So we ended up with an invoice numbered INV-2024-0847 and three weeks later a credit note numbered INV-2024-0847 for a different order entirely. The CA found that one too. We rebuilt the credit note generation as our own thing after that.

WooCommerce fires two hooks that look, on first reading, like they do the same thing: woocommerce_order_refunded and woocommerce_refund_created. They don't, and the difference between the two is where the whole post really sits.

woocommerce_order_refunded fires after the order's refund totals have been updated and the parent order has been persisted. By the time it runs, the refund post exists, the parent order has been updated, and in most cases the gateway refund call has already resolved (or failed, in which case you may or may not know). It carries the order ID and the refund ID. It's convenient. It's also too late for what we want, because if the gateway call has failed we're about to issue a credit note document for a refund that didn't actually move money.

woocommerce_refund_created, on the other hand, fires at the point the refund child post is created but before the parent order totals are reconciled and — critically — before the gateway API is called in the default flow. We attach there. The reason is operational: we want to generate the credit note document as a first-class event tied to the refund record, independently of whether the Razorpay API call succeeds. If the gateway call fails, we still have an auditable document trail showing the credit note was intended, with a clear "refund pending" state we can reconcile later. If we hung off the "refunded" hook, we'd be coupling the document existence to the gateway outcome, which is the thing we're explicitly trying to decouple.

(This is the opposite of what the plugin add-ons we looked at do, by the way. Most of them hang off the later hook because it's "safer" — the money has moved, so you know you're issuing a credit note for a real event. We think that's wrong in an audit context, where the document is the primary artifact and the bank movement is secondary. But we've seen this go both ways and the honest answer is it depends on how much the client cares about the pending-state visibility.)

The credit note number itself we allocate from a counter stored in a dedicated row in wp_options — not the greatest storage choice, we know, there's a race condition under concurrent refunds that we handle with a DB-level lock, but moving the counter to its own table is on the list and never seems to get prioritised. The counter is incremented atomically, the credit note PDF is generated with the allocated number, the document is attached to the shop_order_refund post as meta, and only then does the Razorpay call fire. If the Razorpay call fails, we have a credit note document in a "payment pending" state, which the ops team resolves manually or via a retry queue that runs every 15 minutes and gives up after six attempts, at which point it pings the ops channel.

The Tally side picks up the credit note via the same export pipeline that handles invoices — we push both to Tally's CDNR voucher type with the appropriate reference to the original invoice voucher. The numbering discipline and the hook choice are doing most of the work here; the Tally export side is boring, which is how we want it.

The partial-return case we still haven't cleanly solved

Full-order refunds are straightforward. The original invoice reversed in full, one credit note document covering the entire taxable value, CDNR row writes cleanly. The place-of-supply classification carries over from the original invoice without any ambiguity.

Partial returns are where it gets interesting. The 11 September case we mentioned at the top was a partial — 2 units returned out of 5, so the credit note has to reference the original invoice but only reverse a proportional share of the taxable value and the tax amounts. That's fine arithmetically. What's less fine is the edge cases where the partial return changes something about the supply classification.

Two we've hit in the wild. The reverse-charge case: an original invoice issued to an unregistered recipient where the supply type was later reclassified (don't ask, there was a GSTIN provided late, the client's ops team updated it, the whole thing was a mess). When the partial return came in, the question was whether the credit note should follow the original classification or the corrected one. We went with the original on the reasoning that the credit note reverses the invoice as issued, not as it should have been issued, but we're genuinely not sure that's right. Second case: export of services, where the original was a zero-rated supply with LUT. The partial credit note here is theoretically simple — proportional reversal, zero tax — but the place-of-supply field in the CDNR row has to continue to reflect the overseas recipient, and if the Razorpay refund settles in INR against an INR-denominated payment that was originally recorded as foreign-currency equivalent, the FX gap between invoice date and refund date lands somewhere, and that somewhere is usually a tiny rounding entry in Tally that nobody notices until year-end.

Aside: the ops team at one client built a reconciliation spreadsheet to catch these FX gaps and it ran fine for about four months before someone put a SUMIF on a column that had changed format. Found that one at year-end too. Different post.

The case we actually don't have a clean answer for, and the reason we're writing this up at all, is the cross-financial-year return. Customer bought something on, say, 18 March. Invoice issued in FY 2023-24, filed in that year's GSTR-1 for March. Returns the item on 22 April. The credit note has to be issued in the current month's GSTR-1 (FY 2024-25, April return) but it has to reference an invoice from the closed prior year. The ITC reversal mechanics on the buyer side get strange in this scenario — their GSTR-2B for April will show a credit note referencing an invoice they already took credit for in March of the previous year, and the matching logic the portal uses across years is, let's say, not something we'd want to rely on without checking.

What we currently do: issue the credit note in the current (monotonic) series, reference the old invoice number and date exactly as they appeared in the original filing, add a footnote in the remarks field noting the original FY. It works. The CDNR row uploads. The buyer's CA, more often than not, has to raise a manual query because their 2B doesn't reconcile cleanly. If anyone has a cleaner pattern than this — specifically, one that doesn't force the recipient into a manual reconciliation step — we'd like to hear it.

Ready to build something that works?

Get a free website mockup for your business. No commitment, no fluff — just what it could look like.

WhatsApp replies in seconds.

WhatsApp Call Free mockup
WhatsApp us · replies in seconds