WooCommerce documents public enum classes for order statuses, product types, stock states, payment features, and settings values. Blind replacement can break older supported versions or confuse unprefixed API values such as completed with database post_status values such as wc-completed.
Use this for custom plugins, themes, integrations, payment gateways, shipping extensions, reporting jobs, SQL helpers, REST clients, and codebases supporting several WooCommerce versions.
Quick answer
Inventory comparison, switch, query, array, SQL, REST, and JavaScript literals that represent WooCommerce domain values. Map each literal to the authoritative enum class, note whether the context expects a prefixed or unprefixed value, and record the first WooCommerce version that provides the constant. Replace only where the project minimum version guarantees availability or add a safe class_exists compatibility path. Prove that database values, API payloads, hook arguments, reports, caches, and tests remain byte-for-byte compatible.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Order API | completed | OrderStatus constant |
| Database post_status | wc-completed | OrderInternalStatus constant |
| Old version | Class unavailable | Compatibility path |
| JavaScript payload | Plain string expected | Serialized value unchanged |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Inventory domain literals | Record minimum and maximum supported WooCommerce and PHP versions, autoload timing, namespace conventions, build targets, database contexts, REST contexts, and JavaScript boundaries. | Oldest supported WooCommerce and 11.1 both load without fatal errors. |
| Map prefix and version context | Search for status, type, stock, tax, visibility, unit, currency-position, gateway-feature, and settings literals while excluding labels, translations, fixtures, and unrelated prose. | Stored statuses, API payloads, queries, hooks, and reports remain unchanged. |
| Migrate one domain at a time | Create a mapping with file, line, literal, context, expected prefix, enum class, constant, resulting string, first available version, owner, and test. | Prefixed and unprefixed contexts use the correct constant families. |
| Test oldest and current versions | Run static analysis and fixtures on the oldest supported WooCommerce version, 11.1, HPOS, legacy orders where supported, REST, CLI, cron, and background workers. | Static analysis flags new domain literals without blocking valid labels and fixtures. |
What to check first
- Record minimum and maximum supported WooCommerce and PHP versions, autoload timing, namespace conventions, build targets, database contexts, REST contexts, and JavaScript boundaries.
- Search for status, type, stock, tax, visibility, unit, currency-position, gateway-feature, and settings literals while excluding labels, translations, fixtures, and unrelated prose.
- Create a mapping with file, line, literal, context, expected prefix, enum class, constant, resulting string, first available version, owner, and test.
- Run static analysis and fixtures on the oldest supported WooCommerce version, 11.1, HPOS, legacy orders where supported, REST, CLI, cron, and background workers.
- Ship small groups by domain, verify stored values and payloads have not changed, then add a rule or reviewed allowlist to prevent new fragile literals.
Field notes
- Write the pass condition before changing anything and keep one repeatable synthetic fixture for the full test window.
- Record exact versions and UTC timestamps because deployments, caches, retries, scheduled actions, and background jobs can change the evidence.
- Test the public path and the stored server-side result, not only an admin preview, isolated command, or API response.
- Repeat verification after the relevant cache, queue, cron, webhook, and observation window has completed.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
rg -n "'(wc-)?(pending|processing|on-hold|completed|cancelled|refunded|failed)'" wp-content/plugins/my-extension
# Record context before replacing any literal.
# Verify the constant returns the exact string expected by that layer.
Why this usually happens
- The same concept uses prefixed and unprefixed forms in different layers.
- A constant was added after the extension's minimum WooCommerce version.
- An automated replacement changes labels or SQL fragments that are not API values.
- A class reference is evaluated before WooCommerce autoloading is ready.
Decision rule
Replace a literal only when the constant exists in the supported version range, resolves at the required load point, and produces the exact value expected by storage, API, hook, or query context.
Production verification checklist
- Oldest supported WooCommerce and 11.1 both load without fatal errors.
- Stored statuses, API payloads, queries, hooks, and reports remain unchanged.
- Prefixed and unprefixed contexts use the correct constant families.
- Static analysis flags new domain literals without blocking valid labels and fixtures.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Inventory domain literals
- Map prefix and version context
- Migrate one domain at a time
- Test oldest and current versions
- Prevent new unreviewed literals
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, a stable fixture, the expected result, and a tested rollback point.
- Treating one successful screen as proof while stored records, logs, queues, caches, emails, APIs, and downstream systems remain unchecked.
- Testing only as an administrator instead of using the role, device, locale, cache state, and failure branch that real users reach.
- Leaving temporary exclusions, debug output, helper accounts, broad permissions, or one-off repair code active after verification.
Questions teams ask during testing
Can I run this directly in production?
Begin with read-only evidence and use staging for package, code, database, form, or permission changes. If a production canary is necessary, make it identifiable, reversible, monitored, and unable to expose personal data or charge a customer.
How do I avoid a false positive?
Repeat the same fixture with the same versions, role, URL, locale, cache state, and downstream integrations. Compare browser, stored, and log evidence instead of relying on one screen.
What should the evidence packet contain?
Keep UTC time, exact versions, synthetic record ID, expected result, actual result, relevant log lines, change made, rollback point, owner, and final verification. Redact secrets and personal data.
When is the test complete?
Close the work when the primary path passes, failure branches are understood, stored and downstream records reconcile, temporary changes are removed, and monitoring covers the next update.
What to tell the client or owner
Give the owner a concise packet with the affected workflow, exact versions, UTC test time, fixture ID, expected result, actual result, key logs, change made, rollback point, final result, unresolved risks, owner, and next review date. Remove credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP review a WooCommerce extension upgrade.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references