WooCommerce Subscription Renewal Reconciliation Guide

How to reconcile WooCommerce subscription renewals

WooCommerce subscription renewal reconciliation compares what the store expected to collect with what the payment gateway recorded. The process normalizes identifiers, amounts, currencies, statuses, and timestamps; matches records using explicit rules; and classifies exceptions for human review.

It should remain read-only. Reconciliation identifies candidates for investigation. It should not retry, capture, void, refund, edit an order, or change a subscription automatically.

WooCommerce explains that each recurring payment is recorded in a renewal order in its subscription orders documentation. Its Subscriptions troubleshooting framework emphasizes timelines, order relationships, and logs. The provider side must be obtained from the gateway's current documentation and authorized export or API.

Define both ledgers

The expected-renewal ledger represents the store's view. For each renewal, collect:

• renewal order ID;
• subscription ID;
• customer reference;
• expected amount and currency;
• due date;
• order creation and update times;
• local order and subscription statuses;
• payment gateway;
• saved non-secret payment reference;
• retry or scheduled-action state.

The gateway ledger represents provider events or transactions. Collect:

• transaction or event ID;
• merchant reference;
• order, renewal, or subscription reference;
• customer reference;
• amount and currency;
• provider status;
• authorization, capture, failure, void, and refund times where relevant;
• event creation and update times;
• settlement reference only if the reconciliation scope includes settlement.

Document export boundaries. A gateway file covering 1–15 July cannot prove that a 16 July transaction is missing.

Normalize before matching

The two systems often use different formats. Normalize without destroying source evidence.

Identifiers

Trim safe presentation whitespace and apply only documented case rules. Never remove meaningful prefixes just to force a match. Preserve the raw value beside the normalized value.

Money

Convert amounts to integer minor units using the correct currency scale. USD 49.00 becomes 4900 cents. Do not compare binary floating-point values or assume every currency uses two decimal places.

Time

Convert comparison timestamps to one named timezone while preserving originals. Decide which time represents occurrence, processing, capture, and settlement.

Status

Map provider and WooCommerce statuses into a small comparison vocabulary without erasing detail. For example:

• expected or pending;
• succeeded or captured;
• failed or declined;
• canceled or voided;
• refunded;
• unknown.

A provider authorization may not equal a captured payment. Keep both the normalized class and original status.

Use a matching hierarchy

Prefer deterministic matches over fuzzy guesses.

1. Exact renewal or order reference plus compatible amount and currency.
2. Exact subscription reference plus billing-period and amount agreement.
3. Exact gateway metadata written by the integration.
4. Customer, amount, currency, and a narrow time window as a manual-review candidate.

Do not automatically match on customer and amount alone. Many subscriptions share prices, and one customer can have several renewals.

Every rule should record why it matched, its tolerance, and whether manual review is required.

Exception classes

Missing provider transaction

An expected renewal has no compatible provider record in the complete search window. Causes can include scheduling failure, missing token, gateway failure before transaction creation, incomplete export, or a reference mismatch.

Orphan provider transaction

A provider record has no compatible expected renewal. It may belong to another store, a manual charge, an imported or deleted order, a duplicate process, or an incomplete store export.

Duplicate candidate

More than one provider transaction or renewal order appears compatible with one billing event. Do not decide which is valid solely by row order.

Amount or currency mismatch

Identifiers align, but money differs. Taxes, shipping, fees, plan changes, partial captures, currency configuration, or a wrong reference may explain it.

Schedule mismatch

The apparent match falls outside the documented time tolerance. Timezone, delayed processing, retries, early renewal, or incorrect dates may be involved.

State divergence

The gateway shows success while WooCommerce shows failed or pending, or the store shows paid while the provider does not show a compatible success. This class carries a high risk of harmful manual action.

Insufficient evidence

The exports are incomplete, identifiers are missing, or several candidates remain. Unknown is a valid result.

Worked synthetic reconciliation

Assume the store ledger contains:

The supplied gateway ledger contains:

The rules produce:

• R-100 / TX-1: exact reference and money match, but local failed versus provider succeeded. State-divergent candidate; do not retry.
• R-101: no provider transaction. Missing candidate, subject to export completeness, scheduler, and retry review.
• R-102 / TX-2: exact reference but currency mismatch. Do not call it paid based on the shared numeric amount.
• TX-3: orphan candidate because no expected record with R-999 exists in the supplied store ledger.

The output preserves all four questions. It does not claim USD 97 is recoverable or lost. Face value is not the same as financial outcome.

Reconciliation run checklist

Scope

• Define stores, gateways, currencies, and billing periods.
• Record extraction times and timezone.
• Include retries, refunds, voids, and delayed events required by the scope.
• Document excluded gateways and manual payment types.
• Verify pagination and export completeness.

Data protection

• Use least-privileged read access.
• Exclude full payment credentials.
• Minimize customer information.
• Protect files and audit access.
• Delete working exports under the approved retention rule.

Rule control

• Version matching and status-mapping rules.
• Define time tolerances per gateway behavior.
• Require currency equality.
• Preserve raw source values.
• Send ambiguous matches to manual review.

Review

• Check state-divergent records before any charge attempt.
• Check duplicate candidates before refund or void.
• Confirm provider state in the live authorized portal when required.
• Review WooCommerce notes, logs, retries, and scheduled actions.
• Record the authorized decision outside the read-only audit.

Closeout

• Re-run after approved remediation.
• Keep before-and-after evidence.
• Record known unresolved exceptions.
• Improve reference propagation where weak matching caused ambiguity.
• Schedule the next bounded run if ongoing reconciliation is needed.

Reconciliation versus native health checks

WooCommerce's Subscriptions Health Check can identify native conditions such as missing renewals or billing-mode issues. Use it. Reconciliation asks a cross-system question that a store-only scan cannot answer: does the provider ledger agree with the expected renewal ledger?

The safest operating model is:

1. use native diagnostics for subscription and scheduler state;
2. reconcile against gateway evidence;
3. have authorized finance or support reviewers decide remediation;
4. make changes through supported controls;
5. re-run the comparison.

Output design

For each exception, show:

• both source identifiers;
• match rule and confidence class;
• original and normalized amounts, currencies, times, and statuses;
• reason for the exception;
• evidence boundary;
• suggested investigation—not an automatic financial action;
• reviewer decision when supplied later.

Avoid a dashboard that exposes only a total “revenue at risk.” The rows and rules make the number reviewable.

Limits

Renewal reconciliation does not establish settlement, profit, tax treatment, refund validity, dispute outcome, customer intent, or recoverable revenue. Fees, partial refunds, chargebacks, authorization-versus-capture behavior, and gateway-specific asynchronous events need appropriate evidence.

To test these match and exception rules on synthetic ledgers, run the RebillLens sample and use the same page to request a paid renewal reconciliation audit. The audit does not move money or alter WooCommerce records.