Scope headless WooCommerce around the complete shopping journey: product display, cart identity, checkout state, payment handling and operational ownership. Use the Store API for the customer-facing work it documents, then verify the selected payment integration separately. A custom storefront needs an explicit contract with the commerce backend at every step the customer can take.
Begin with a journey map that includes the awkward cases: a cart reopened after navigation, an address corrected during checkout, an unsuccessful payment and a customer returning from a payment page. Ask who owns the visible message and the backend interpretation at each point. These decisions make the implementation brief more useful than a list of frontend screens.
Which API should own the storefront journey?
WooCommerce’s Store API overview establishes its intended scope. The Store API supports customer-facing cart, checkout and product functionality. Store API responses use JSON. Plan how the storefront will turn those responses into clear product information, editable cart details and understandable next steps for the customer.
WooCommerce customer sessions are cookie-based. Include session behaviour in the architecture discussion, especially when the frontend and backend use different deployment arrangements. Ask the implementer to document the intended customer identity and cart route, then demonstrate that route in the proposed test environment.
The Store API cannot retrieve other customers and orders by identifier. The Store API cannot write store settings. Keep administration requirements distinct from the public shopping interface, and identify the appropriate authenticated route when staff need broader operations. A customer-facing endpoint should not become a substitute for designing the administrative boundary.
Write an endpoint inventory beside the journey map. For each interaction, record what the frontend requests, what the backend is expected to return and who interprets an error. Include the intended response to unavailable products or an interrupted cart update. This gives the acceptance reviewer a concrete sequence to inspect.
How should cart and checkout state be verified?
WooCommerce’s checkout endpoint documentation provides the next boundary. Checkout endpoints require a nonce token or cart token. Record the chosen method and the implementation owner in the technical brief. Keep secrets and live customer information out of screenshots and shared acceptance notes.
The checkout data response includes a draft order from the current cart. Treat that state according to its actual meaning in the journey. Ask the team to show what the visitor sees before payment processing and which backend record exists at that point. The handover should make a draft distinguishable from the business’s successful-order state.
The checkout update endpoint can persist checkout fields for the current order. Include a corrected address or delivery instruction in the demonstration so the frontend and backend can be compared after an edit. Record the field value actually returned and displayed rather than assuming that a successful button interaction persisted the intended change.
| Journey point | Contract to define | Proposed evidence |
|---|---|---|
| Product selection | Item and variant identity | Displayed selection matches the requested item |
| Cart update | Quantity and current cart state | Returned cart agrees with the next screen |
| Address correction | Current order field persistence | Saved value remains visible after the agreed navigation |
| Checkout preparation | Draft order interpretation | Frontend message matches the backend state |
| Payment return | Result handling and next action | Customer sees the correct outcome and recovery route |
Use the table to define observable outcomes. Give a named owner to any transformation between API data and visible content. A disagreement between the backend state and the message shown to a customer should remain an implementation issue until its cause and correction are understood.
What must be agreed with the payment integration owner?
The checkout payment operation attempts payment and returns its result. Payment gateways expect different payment_data. Ask the selected gateway’s publisher for the applicable integration documentation and supported test route. Keep its availability, account eligibility and country requirements as separate verified questions rather than inferring them from a sample request.
Agree how the storefront presents a pending, unsuccessful or interrupted attempt. The customer needs to understand whether to wait, correct information or seek help. Use the gateway’s documented states and the store’s actual order process to define those messages, and retain the source for any consequential interpretation.
Also decide who investigates a disagreement between the customer’s experience and the backend record. Record the references support staff can safely use, the information they should avoid collecting and the route for technical escalation. The developer responsible for the frontend and the person operating the store should be able to follow the same incident record.
Keep gateway-specific behaviour out of a general API acceptance result. A working catalogue and cart can demonstrate those parts of the journey while payment compatibility remains unresolved. Make the acceptance matrix show each part’s status explicitly so the release decision reflects the evidence available for the actual configuration.
Original address-change and payment-return exercise
Consider a fictional store selling a notebook with a selectable cover. In a separate test environment, prepare an approved sample product and the gateway’s documented test configuration. The exercise follows a customer selecting the cover, correcting a delivery address and returning from a payment attempt.
First, record the expected product identity and the selected option. Add it to the cart and compare the returned cart with the visible summary. Change the sample quantity through the intended interface and repeat the comparison. Retain the relevant request context and observed result without including sensitive credentials in the evidence.
Next, enter a sample address and correct it before the payment step. Inspect the current order data and the storefront’s summary. Navigate through the agreed route and check that the intended correction remains. If the displayed value and backend value differ, identify which layer owns the transformation before changing the acceptance expectation.
Then follow the documented payment test path and inspect the returned result alongside the store’s record. Repeat the relevant unsuccessful or interrupted scenario supported by that test route. Record the visible message, order reference and available next action, keeping each scenario’s outcome separate.
Finally, review the evidence with the store operator, frontend owner and payment integration owner. Mark demonstrated, unresolved and excluded work against the journey map. Agree who maintains the contract when an API, plugin or checkout requirement changes. This makes ongoing ownership part of the decision to adopt the headless approach.
For wider scope, see website development and online payments. Get started with the customer journey, proposed deployment arrangement and payment questions that need evidence.
By Spout Team. AI-assisted drafting by Codex using the linked primary documentation.