Choose headless Shopify when the proposed custom storefront has a clear job and an owner for its ongoing operation. Trace product display, cart state and the handover to checkout before committing to the architecture. Use the worksheet below to identify which system supplies each decision and who investigates a mismatch across the customer journey.
What is the custom storefront responsible for?
Begin with the experience the business wants to provide and why a custom frontend is appropriate to it. Identify the pages, interactions and content that need a different implementation. Keep the desired outcome explicit so the architecture decision can be reviewed against the work it creates.
Shopify Storefront API exposes products, collections and cart operations for custom storefronts. Documentation. Write the proposed relationship between the frontend and the commerce backend. Identify where catalogue information is maintained, which content is managed elsewhere and how the displayed product is connected to its purchaseable variant. Ask the implementer to show the source of every consequential field in the proposed journey.
Separate the creative brief from the operational brief. A distinctive interface still needs understandable error states, content updates and support ownership. Include the person who will maintain the storefront after delivery when deciding how much custom behaviour the business wants to own.
Which access belongs in the browser or on the server?
The Storefront API supports tokenless and token-based access. Documentation. Shopify describes public tokens as supporting client-side queries and mutations. Documentation. Shopify describes private tokens as supporting server-side queries and mutations. Documentation. Map the intended operations to the chosen access arrangement. The fact that one query works in a demonstration should not determine the architecture of every operation. Review the API version, required permissions and environment for the actual implementation.
Shopify instructs developers to keep private access tokens secret and off the client side. Documentation. Ask the developer to explain where configuration is held, what reaches the browser and how the deployment process supplies the relevant credentials. Keep secret values outside the brief and review evidence. The useful acceptance question is the boundary and its observed behaviour, not a screenshot exposing a token.
Include ownership of token rotation and access changes in the handover. Decide who can make those changes and how the storefront will be checked afterwards. Keep a route for investigating access failures that does not require broadening permissions merely to make an error disappear.
An original storefront-to-checkout responsibility worksheet
Use this practical checklist to define a representative buyer journey. Fill it with actual systems, record references and owners. It provides a common review document for frontend, commerce and operational decisions.
| Journey boundary | Record or decision to identify | Owner question |
|---|---|---|
| Product display | Product and variant source | Who maintains the information the buyer sees? |
| Editorial content | Page copy and asset source | Who approves and publishes changes? |
| Cart creation | Variant, quantity and resulting cart | Who investigates an incorrect line? |
| Buyer context | Relevant customer and delivery information | Which component establishes the intended context? |
| Checkout handover | Current checkout URL and observed destination | Who checks the transition into checkout? |
| Order follow-up | Resulting order and customer support reference | Who can trace the completed journey? |
| Recovery | Failed dependency and next action | Who restores the affected part of the service? |
Add the relevant environment and API version to the working copy. Include an ordinary route, an unavailable product and an interrupted handover. Ask each responsible team to explain what evidence they would use to locate a problem at their boundary.
Keep an explicit decision about duplicate or conflicting data sources. If the same product description can be edited in more than one system, agree which source supplies the public page and how a correction becomes visible. Document that choice so routine content work does not become a recurring engineering investigation.
What should the cart evaluation establish?
Shopify describes a cart as intended merchandise and its estimated cost. Documentation. Shopify cartCreate can create a cart and add a line item. Documentation. Use a controlled example with a clearly identified variant and quantity. Compare the returned cart with what the interface displays. Request checks for adding an item, changing its quantity and revisiting the cart after a relevant update.
Shopify cart costs can change at checkout. Documentation. Prepare the interface wording and support process with that distinction in mind. A cart display should help the buyer understand the next step, while the acceptance brief should compare the information presented before and during checkout. Keep any difference tied to the actual context and documented calculation.
Ask the developer how the proposed frontend handles a failed cart update. The buyer needs an understandable state and a safe next action. Record the expected response before testing, including how the interface avoids presenting an earlier cart state as though the latest change succeeded.
How does the buyer reach checkout?
The cart checkoutUrl sends customers through Shopify web checkout. Documentation. Shopify recommends requesting checkoutUrl when the buyer is ready to proceed. Documentation. Rehearse the transition from the intended cart and preserve the observed destination. Include the buyer context relevant to the proposed experience and ask how an interrupted or stale handover is recovered through the documented route.
Keep payment eligibility and provider configuration within their own review. A custom frontend and a working checkout link do not decide which payment arrangement a Zambian business can use. Use the Shopify payment eligibility guide for that separate decision.
Hypothetical example: the cart updates but the displayed state does not
Imagine a buyer changes a quantity and the backend cart is updated, while the custom interface continues to display the previous state. The subsequent checkout handover now needs investigation. This hypothetical case examines the responsibility between API result, frontend display and checkout.
Put the intended variant and quantity on the worksheet. Compare the request, returned cart and displayed state through the proposed test arrangement. Then follow the current checkout URL and examine whether the intended cart is represented. Record each observation at its boundary rather than describing the entire journey as simply working or broken.
Assign the correction to the responsible component and repeat the relevant checks after the change. Include the interrupted-update path in that repeat so the customer-facing recovery behaviour remains part of the acceptance decision.
A useful architecture brief leaves the business with named owners for content, frontend operation, commerce configuration and support. Discuss that brief through online stores and web development. Get started with the custom journey, source systems and operational responsibilities you want to assess.
By Spout Team. AI-assisted drafting by Codex using the linked primary documentation.