Migrate FOS off WooCommerce Legacy REST API → /wp-json/wc/v3 (deactivate legacy-rest-api plugin; final HPOS blocker)

# Migrate FOS off the WooCommerce Legacy REST API ## Objective Remove all dependence on the `woocommerce-legacy-rest-api` plugin (the one HPOS-**incompatible** plugin) so it can be deactivated on production — the final hard blocker before the WooCommerce HPOS migration can begin. ## Evidence base - Consumer map (file:line, verified): Solo scratchpad `legacy-rest-api-findings` (#1034). - HPOS context + full plugin compat scan: `HPOS_TRANSITION_NOTES.md` → "2026-07-01" section. - Separate/unrelated infra: brief #50 (nginx sites-enabled divergence). ## Surface (concentrated, not sprawled) - **LINCHPIN:** FOS Laravel `WooCommerceAPIWrapper` (`laravel/app/Acme/WooCommerceUtilities/WooCommerceAPIWrapper.php`) built on the legacy `WC_API_Client` (`afurculita/woocommerce-api-client`, `composer.json:21`). All order/customer traffic routes through it: `Order`/`Customer` models, webhook import (`ImportOrderFromWooCommerce` refetches via the wrapper), admin manual import, webhook delivery-log admin. - **Adjacent `?wc-api=` gateway consumers:** ShipStation (`woocommerce_api_wc_shipstation`, export+shipnotify — customer-facing shipping), Mailchimp (`woocommerce_api_create_coupon`). - **External/config:** Zapier/Fivetran keys in `wp_woocommerce_api_keys`; webhooks in `wp_wc_webhooks`. - **Removable / false-positive:** GF quick-view (`?wc-api=WC_Quick_View`), Advanced Order Export, tdr-fos `ApiHelper` (targets TDR app API, not Woo). - **tdr-fos** rides on the FOS `/api/mobile/*` layer — no direct Woo calls; migrates via Phase 1. - **Enabling asset:** `automattic/woocommerce ^2.0` is ALREADY in composer — modern client exists; the adapter is wiring, not a new dependency. ## Sequenced plan (phases + dependencies) ### Phase 0 — De-risk & runtime inventory (FIRST; read-only, no code) - **0.1** Read-only DB inventory on staging/prod: `wp_woocommerce_api_keys` (which external services, last_access), `wp_wc_webhooks` (topics, delivery_url, status, legacy-vs-modern delivery). Output: table of external consumers still on legacy. - **0.2** Query the FOS `wcapirequests` table for recent traffic grouped by endpoint — distinguishes LIVE consumers from dead code (tells us what actually needs migrating). - **0.3** ShipStation de-risk (the #1 unknown): on staging, toggle `woocommerce-legacy-rest-api` OFF and re-test ShipStation `export` + `shipnotify`. Determine whether the `?wc-api=wc_shipstation` gateway survives without the legacy plugin. - Gate: findings from 0.1–0.3 inform scope of all later phases; 0.3 gates Phase 5 regardless. ### Phase 1 — Modern client adapter (the bulk) — depends on Phase 0 - **1.1** Build a `/wp-json/wc/v3` adapter (using `automattic/woocommerce ^2.0`) exposing the SAME method surface as `WooCommerceAPIWrapper` (`getOrder`, `getOrders`, `getCustomer`, `getCustomerByEmail`, `createCustomer`, `getWebhooks`, …) and returning legacy-shaped objects at the boundary (`$wc_order->order`, `$woo_orders->orders`, legacy error codes e.g. `woocommerce_api_invalid_customer_email`) so downstream callers are untouched initially. - **1.2** Reuse `services.woocommerce` creds/URL (`WOOCOMMERCE_CONSUMER/SECRET/URL`); ensure keys are v3-scoped (Read/Write as needed). - **1.3** Switch `Order::initiateWoo()` / `Customer::initiateWoo()` to return the adapter. Keep `wcapirequests` logging (now modern endpoint names) as the cutover telemetry. - **1.4** Staging verify: order fetch/import, customer lookup/create. ### Phase 2 — Webhooks — depends on Phase 1 - **2.1** Configure the 6 topics (customer/order × created/updated/deleted) as MODERN-delivery webhooks pointing at the existing Laravel routes. - **2.2** Normalize modern payloads (bare resource) → internal shape, or update consumers of `data->order`/`data->customer`. Lower effort than it looks because import REFETCHES via the adapter (Phase 1) — the payload only needs the resource id. - **2.3** Move admin webhook inventory to `/wp-json/wc/v3/webhooks`; decide on delivery-log pages (modern API has no per-delivery log — drop the page or back it with local `WebhookPayload` records). ### Phase 3 — External consumers & dead code — partly parallel to Phase 2 (needs Phase 0.1/0.3) - **3.1** Migrate/reissue Zapier/Fivetran API keys to v3 scope; coordinate any vendor still hitting `/wc-api/vN`. - **3.2** ShipStation: act on Phase 0.3 result — no-op if it survives; else reconfigure/replace before prod. - **3.3** Mailchimp: verify coupon sync via `/wp-json/wc/v3/coupons` + normal hooks (legacy `create_coupon` action disappears with the plugin). - **3.4** Delete dead legacy code: `OrdersTableSeeder`, `WooCommerce_API_example.php` (**rotate its hardcoded creds if ever real**), remove `afurculita/woocommerce-api-client` from `composer.json`/lock. ### Phase 4 — tdr-fos contracts — depends on Phase 1 - **4.1** Migrate the FOS `/api/mobile/*` implementations behind tdr-fos's product/order/cart/payment calls to the adapter, preserving tdr-fos outward response contracts. ### Phase 5 — Cutover — depends on Phases 1–4 + Phase 0.3 - **5.1** Full staging smoke of every consumer (acceptance list below). - **5.2** Confirm zero legacy `WC_API_Client` traffic in `wcapirequests`. - **5.3** Deactivate `woocommerce-legacy-rest-api` on staging → full re-smoke. - **5.4** Production: DB backup → deactivate plugin → monitor. Plugin now off the HPOS-incompatible list. ## Dependency graph Phase 0 → Phase 1 → { Phase 2, Phase 4 } (parallel) → Phase 3 (partly parallel, needs 0.1/0.3) → Phase 5. Phase 0.3 (ShipStation) gates Phase 5 independently. ## Acceptance criteria - `woocommerce-legacy-rest-api` deactivated on production, no regressions. - HPOS compat scan → **0 incompatible plugins**. - All 6 webhook topics deliver + import correctly on modern payloads. - ShipStation export + shipnotify working. - Order/customer fetch, create, and admin manual import working. - tdr-fos product/order/cart/payment flows working. - `wcapirequests` shows only modern endpoints; `afurculita/woocommerce-api-client` removed from composer. ## Security side-item Rotate the hardcoded Woo consumer creds in `laravel/app/Acme/Samples/WooCommerce_API_example.php` if they were ever real (Phase 3.4). ## Notes - This is a prerequisite for the HPOS migration proper (which is its own effort: ~1.2M orders to sync, MySQL-version decision, staging-timed migration — see HPOS_TRANSITION_NOTES.md). - Static analysis only produced this plan; every `[needs runtime check]` item (ShipStation, Mailchimp, Zapier/Fivetran, webhook delivery, tdr-fos, `WooCommerceLocalRestAPIWrapper`'s in-process `/wc/v2`) is resolved in Phase 0 before code changes.

Sequenced work plan to migrate the FOS Laravel app off the WooCommerce **Legacy REST API** (`/wc-api/`) onto the modern `/wp-json/wc/v3/` API, so the HPOS-incompatible `woocommerce-legacy-rest-api` plugin can be safely deactivated — the last hard blocker for the WooCommerce HPOS migration. Derived from the consumer audit (Codex, 2026-07-01): full evidence map in Solo scratchpad `legacy-rest-api-findings` (#1034); HPOS context in `HPOS_TRANSITION_NOTES.md` (2026-07-01 section). The canonical sequenced plan is in this brief's spec. Related but separate infra item: brief #50 (nginx sites-enabled divergence).