WooCommerce 11.0 adds a refunds value to v3 sales-report date buckets. That does not automatically update a spreadsheet, dashboard, connector, finance export, or custom API client. Each consumer needs a named version, field map, sign convention, date rule, timezone, owner, fixture, and rollback gate so the same refund is not omitted or subtracted twice.
Use this for stores with custom reports, agency dashboards, warehouse pipelines, finance exports, advertising reconciliation, mobile apps, or extensions that consume WooCommerce sales-report endpoints.
Quick answer
WooCommerce 11.0 Sales Report API Client Compatibility Contract should be handled with a narrow evidence-first workflow: inventory report clients, capture versioned responses, name every formula, then verify the result before making broader changes.
What to check first
- Inventory every client that reads a WooCommerce sales report and record endpoint, API version, authentication, owner, deployment path, and reporting purpose.
- Capture raw v1, v2, and v3 responses for one controlled ledger containing gross sales, tax, shipping, discounts, full refunds, partial refunds, and refunds on a later date.
- Write the client formula beside the exact field names, signs, currencies, timezone, order-date rule, refund-date rule, and rounding policy.
- Create a versioned fixture and expected totals for daily, weekly, and monthly periods, including a boundary at local midnight.
- Deploy one client at a time with a rollback rule and compare its output to the unchanged order and refund ledger.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Inventory report clients | Inventory every client that reads a WooCommerce sales report and record endpoint, API version, authentication, owner, deployment path, and reporting purpose. | Every report consumer has a named owner, endpoint version, and deployment location. |
| Capture versioned responses | Capture raw v1, v2, and v3 responses for one controlled ledger containing gross sales, tax, shipping, discounts, full refunds, partial refunds, and refunds on a later date. | Full and partial refunds appear exactly once in the expected period and sign. |
| Name every formula | Write the client formula beside the exact field names, signs, currencies, timezone, order-date rule, refund-date rule, and rounding policy. | Daily, monthly, timezone-boundary, and multi-currency fixtures reconcile to the source ledger. |
| Build controlled fixtures | Create a versioned fixture and expected totals for daily, weekly, and monthly periods, including a boundary at local midnight. | A rollback restores the previous client behavior without changing store orders or refund records. |
Why this usually happens
- API versions can represent the same economic event with different fields or signs.
- A downstream client may infer refunds from net sales while v3 also exposes an explicit refund value.
- Timezone and refund-date attribution can move the value into a different bucket.
- Undocumented spreadsheet formulas often outlive the developer who created them.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
client_contract:
client: finance_daily_export
endpoint_version: v3
timezone: America/Chicago
refund_attribution: refund_date
refund_sign: positive_magnitude
net_formula: gross_minus_refunds
fixture: sales-ledger-2026-07-a
owner: finance_ops
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Inventory report clients
- Capture versioned responses
- Name every formula
- Build controlled fixtures
- Roll out per client
Decision rule
A client may adopt v3 only when its raw response, transformation, expected fixture, and final total reconcile without double subtraction. Keep v1 and v2 consumers pinned until their owners approve a separate migration.
What to tell the client or owner
Provide client names, endpoint URLs and versions, raw responses, authentication scope, formulas, timezone, currency, controlled order and refund IDs, expected totals, actual totals, owner, and rollback method.
Production verification checklist
- Every report consumer has a named owner, endpoint version, and deployment location.
- Full and partial refunds appear exactly once in the expected period and sign.
- Daily, monthly, timezone-boundary, and multi-currency fixtures reconcile to the source ledger.
- A rollback restores the previous client behavior without changing store orders or refund records.
Mistakes to avoid
- Do not update all clients because one dashboard passed.
- Do not compare totals generated with different timezone or date-attribution rules.
- Do not assume an explicit refund field should always be subtracted from net sales.
- Do not rely on a live month with no controlled partial-refund fixture.
Questions teams ask during testing
Should every client move to v3 immediately?
No. Move a client when its owner, field map, fixture, and rollback are ready. An older pinned client can be safer than an untested automatic upgrade.
Why do two correct reports put a refund on different dates?
One may group by order date and the other by refund date. Both can answer valid but different questions. Name the rule in the contract and avoid comparing unlike periods.
When HandL WP should help
HandL WP should help when WooCommerce, finance, and marketing dashboards disagree after an API upgrade. We can trace each client from endpoint response through transformation and reconcile it against a controlled order ledger.
If this is active on a production site, reconcile WooCommerce reporting clients.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references