Restoring COD Split-Payment Workflows in a Headless Multi-Store WooCommerce Architecture

Project Overview

A Growing Indian E-commerce Retailer runs a multi-store WooCommerce architecture: several storefronts share one central WooCommerce installation, which manages the product catalog and all commerce logic. One of those storefronts is a custom, headless PHP storefront that talks to the central store exclusively through the WooCommerce Store API.

The platform supports prepaid checkout, Cash on Delivery (COD), and COD with an online advance payment, along with a COD processing fee, a COD handling fee, and payment gateway integration. After the headless storefront was migrated and redeployed in production, the COD split-payment workflow stopped behaving correctly. NIMU Technologies traced the issue to a missing Store API session hook in the central WooCommerce integration layer, restored it, and verified the fix against real Store API responses in production, without rewriting the existing COD calculation engine.

The Challenge

After the redeployment, most of the platform looked healthy:

• Products loaded correctly
• The cart API worked, and products could be added to the cart
• Payment gateways were available
• Selecting COD through the storefront's preview flow returned HTTP 200

But the COD-specific parts of the response were missing:

• No Advance Payment line
• No Processing Fee (3.54%)
• No COD Handling Fee

Without those values, the storefront could not determine COD eligibility or show customers what they would pay upfront. Importantly, the COD calculation code had not been removed. Every request succeeded; the results were simply incomplete. That is what made this more than a "COD button missing" problem: nothing was visibly failing, so the cause had to be found by following state through the system rather than by looking for an error.

Existing Architecture

The architecture is built on a clear separation of responsibilities:

• Central WooCommerce manages the catalog and is the single authoritative source for cart totals, fees, COD eligibility, available payment methods, and final order calculations.
• Storefronts, including the headless PHP storefront, handle presentation and customer interaction. They call the Store API with a store-specific context and display what WooCommerce returns.
• Custom WooCommerce plugins on the central installation implement the multi-store behaviour, including a checkout order-type field and the COD calculation logic.

The storefront does not calculate COD amounts itself. That design keeps money-related logic in one place, but it also means that if the central store does not calculate the COD fees, no storefront can show them.

Technical Investigation

The investigation traced the complete request path, one layer at a time:

The storefront's COD preview sends the selected order type to the Store API as an additional checkout field:

additional_fields: {
  "<store-namespace>/order-type": "cod"
}

(The plugin namespace is withheld for confidentiality.)

On the central store, the multi-store plugin's checkout order-type field stores the selected order type in the WooCommerce session. The COD calculation checks that session state through an is_cod_selected() method and runs only when the session says COD is active.

The plugin had registered the Store API hook for the checkout endpoint, woocommerce_store_api_checkout_update_customer_from_request. The headless storefront's COD preview flow, however, used the Store API cart endpoint /cart/update-customer, and the corresponding cart-update hook, woocommerce_store_api_cart_update_customer_from_request, was missing from the master plugin.

Root Cause

Because the cart-update hook was missing, the selected order type never reached the session state that the COD calculation reads:

The request succeeded (HTTP 200), the cart recalculated, and the response was valid. It simply did not contain COD fees: the WooCommerce Store API flow did not persist the COD selection into the session, so the existing COD calculation logic was not activated.

Solution

The fix was made at the master WooCommerce integration layer, where the gap was. The existing COD calculation engine was not rewritten. Instead, the missing Store API cart-update session hook was restored, so the selected order type is persisted into the WooCommerce session before the cart fees are recalculated.

• Restored: the missing woocommerce_store_api_cart_update_customer_from_request session hook
• Not rewritten: the COD calculation engine
• Not added: any financial calculations in the storefront
• Not duplicated: any business rules in the headless frontend

WooCommerce remains the authoritative source for COD calculations.

The fix preserves the platform's core principle: one authoritative source of truth for commerce calculations. The storefront stays responsible for presentation and interaction; WooCommerce stays responsible for COD eligibility, fees, totals, payment methods, and order calculation.

COD & Split-Payment Logic

The platform's existing business rules were preserved exactly as implemented:

• Product value up to ₹50,000: 5% advance payment
• Product value from ₹50,001 to ₹99,999: 50% advance payment
• Product value above ₹99,999: COD unavailable
• Processing fee: 3.54%
• COD handling fee: ₹50
• Shipping / store margin: remains part of the pay-now calculation, as in the existing implementation

These are the retailer's existing commercial rules. The engineering work made sure they are applied again for storefront COD selections; the rules themselves were not changed.

Technical Architecture

COD and COD-with-advance path

Prepaid path

In both paths, every financial calculation happens inside central WooCommerce. The storefront never computes an amount on its own; it renders the totals, fees, and payment methods that the Store API returns.

Implementation Approach

This was not simply a "COD button missing" problem. The correct behaviour depends on state staying consistent across six parts of the system:

1. The headless storefront
2. The WooCommerce Store API
3. Additional checkout fields
4. The WooCommerce session
5. The custom COD calculation hooks
6. Payment gateway availability

Just as important is the order in which things happen. Each step depends on the one before it:

If the session is not updated before the cart recalculates, every later step works on the wrong state, while still returning a successful response. The approach was therefore to:

• Debug the root cause at the API and session level instead of patching the storefront UI
• Keep calculations server-side and authoritative, rather than adding fallback maths to the storefront
• Preserve the existing business rules and COD engine unchanged
• Make the smallest change that restores correct behaviour, in the layer where the gap existed
• Troubleshoot in a production-safe way and confirm results through real Store API responses

Validation & Testing

After the fix, the production Store API was tested again end to end:

• Product addition: successful
• COD selection: HTTP 200
• COD fees: returned
• Advance Payment: returned
• Processing Fee (3.54%): returned
• COD Handling Fee: returned
• Payment method: the configured bank payment gateway was returned for the COD advance-payment flow

A production Store API validation confirmed that the existing COD calculation returned the expected fee components (Advance Payment, Processing Fee (3.54%), and COD Handling Fee) without changing the underlying business rules. The Store API test example below returned:

These figures are a single Store API validation example, used only to confirm that the existing fee components were returned correctly. They do not describe an advance amount or customer payment behaviour, and they are not business performance metrics.

Results & Outcome

• COD, COD-with-advance-payment, processing fee, and handling fee lines are returned by the Store API again
• The headless storefront can determine COD eligibility and display COD details from WooCommerce's own calculations
• The configured payment gateway is returned for the COD advance-payment flow
• The existing COD calculation engine and business rules remain unchanged
• Financial calculations remain centralized in WooCommerce, with no duplicate logic added to the storefront

Engineering Highlights

• Root-cause debugging: the fault was traced to a missing hook in the central integration layer, not masked in the storefront
• API-level validation: every conclusion was checked against real Store API responses
• Server-side authoritative calculations: WooCommerce remains the single source of truth for money
• Minimal change: one missing session hook restored; the COD engine was not rewritten
• Separation of concerns: presentation stays in the storefront, commerce logic stays in WooCommerce
• Session and state consistency: order type is persisted before cart recalculation
• Production-safe troubleshooting: investigation and verification without disturbing live commerce logic

Technology Stack

• Platform: WordPress, WooCommerce
• API: WooCommerce Store API, REST APIs
• Language: PHP
• Extensions: Custom WooCommerce plugins (multi-store, checkout order type, COD calculation)
• Storefront: Custom headless PHP storefront
• State: WooCommerce session-based checkout state
• Payments: Payment gateway integration

Why This Matters for E-commerce Platforms

Headless and multi-store WooCommerce setups are powerful because the storefront and the commerce engine are separated. The same separation creates a new class of problems: a storefront can call a REST API endpoint that works perfectly and still get the wrong result, because the server-side state it depends on was never set. These issues don't show up as errors; they show up as missing fees, wrong totals, or unavailable payment options.

For businesses running COD, split payments, or custom fees, two lessons stand out:

• Keep financial logic in one place. When the commerce engine is the only system that calculates money, fixing it once fixes every storefront.
• Treat every Store API endpoint as its own integration point. A hook that works for checkout does not automatically cover cart updates. After any migration or redeployment, test each flow through the actual API responses, not just the UI.

NIMU Technologies' Role

NIMU Technologies acted as the engineering partner for the investigation and fix:

• Traced the COD flow end to end across the headless storefront, Store API, custom plugins, WooCommerce session, and payment gateway
• Identified the missing Store API cart-update session hook as the root cause
• Restored the hook in the master WooCommerce integration layer without rewriting the COD engine
• Validated the fix against the production Store API and confirmed the COD fees, advance payment, and payment gateway were returned correctly

Need Help With a Complex WooCommerce Integration?

If your WooCommerce store uses a headless storefront, multiple stores, custom checkout fields, COD or split payments, and something isn't adding up, NIMU Technologies can trace it to the root cause and fix it where it belongs. Explore our WooCommerce development, payment gateway integration, and bug fixing services.

Discuss Your WooCommerce Project Explore WooCommerce Development