Download the PHP package justinholtweb/craft-headdy without Composer

Headdy

A token-authenticated headless storefront API for Craft Commerce.

Craft Commerce has exposed products through GraphQL since version 2. It has never exposed a single cart or order mutation — craftcms/commerce discussion #2350 has been open for years, and the standing advice is to give up on GraphQL for the cart and POST form-encoded requests to actions/commerce/cart/update-cart with a PHP session cookie and a CSRF token.

That works for a Twig site posting to itself. For a Next, Nuxt or Astro front end on another origin it means credentials: 'include', a SameSite policy that survives your CDN, a round trip to fetch a CSRF token, responses shaped like Craft's internal element attributes, and a payment step that is simply unreachable because Craft hashes the return URL into a Twig form your JavaScript cannot produce.

WooCommerce has the Store API and CoCart. Craft has had nothing. Headdy is that layer.

No cookie. No CSRF token. Hold cart.token, send it back as X-Headdy-Cart, and you have a cart.

What you get

• A REST storefront API — carts, line items, addresses, coupons, shipping methods, checkout, payment, catalog, customer accounts. Versioned at /v1, with a documented JSON contract and stable machine-readable error codes.
• GraphQL cart mutations — headdyCartCreate, headdyCartAddItem, headdyCartApplyCoupon and the rest, registered on Craft's own GraphQL endpoint. (Pro)
• Payment that actually works headlessly — including off-site gateways, whose redirect comes back as JSON for your front end to act on rather than as a 302 it cannot follow.
• Bearer tokens instead of sessions — issued once, stored only as a SHA-256 hash, revocable, and rotated on checkout.
• Money you can trust — every amount is {amount, minorUnits, currency, formatted}, never a bare float.
• A configuration check that finds the misconfiguration before your front-end team does.

The one thing worth knowing about the design

services\Carts::update() is the only place a cart changes. Every REST endpoint, every GraphQL mutation and every console command builds a parameter array and hands it to that method. The granular verbs (POST /carts/current/items, PATCH …/items/{id}) exist because they read well — each is a few lines that assembles params and calls update().

So REST and GraphQL cannot drift apart, and there is exactly one place where stock checks, option signatures, recalculation order and validation happen.

Mutations are also applied in a fixed order regardless of the order you wrote them: clear → items → addresses → email → coupon → shipping → gateway → fields. Setting a shipping method before an address exists would pick from an empty option list; applying a coupon before the items are in would not meet the discount's minimum. One big patch and six small ones give the same answer.

Install

Then, in Settings → Plugins → Headdy, or from the command line:

That prints a public key and a secret. The secret is shown once — only its hash is stored.

Point your front end at https://your-site.com/api/storefront/v1 and send the public key in X-Headdy-Key.

Check the setup at any time:

Authentication, and why there is no CSRF token

Three modes:

A CSRF token defends a credential the browser attaches on its own. Headdy has no cookie: the cart token is only ever sent deliberately, which is the same defence a CSRF token provides. Requiring one would only add a round trip — exactly the friction that makes headless Commerce painful today.

Signing a customer in never logs them into Craft. Craft::$app->getUser() stays anonymous for every API request. A customer token identifies a shopper to Headdy's own endpoints and nothing else; it cannot be replayed against the control panel, and control panel accounts are refused outright.

Payment, and the return-URL problem

Craft's PaymentsController reads its return and cancel URLs with getValidatedBodyParam(), which only accepts a value Craft itself hashed into a Twig form. There is no endpoint that will mint that hash, so a JSON client cannot pay.

Headdy validates those URLs against an explicit allow-list instead. The hash exists to stop an attacker redirecting a shopper somewhere of their choosing after payment; an allow-list stops the same thing, and unlike the hash it can be satisfied from JavaScript.

The list is empty by default, so off-site gateways cannot be driven from the API until you say where returns may land. Relative paths are always accepted.

For an off-site gateway the response carries a redirect object rather than a 302:

Honour method: GET means navigate, POST means submit data as a form. Gateways that sign a POST body reject a customer who arrives by navigation.

CORS

An empty allowed-origins list reflects whatever origin asks. That is deliberate: CORS is not what protects this API — the bearer token is, and no cookie is ever sent — so a locked-down default would mean every new install starts broken for no security gain. Naming your front ends is still one less way for a leaked key to be used, and the Overview screen says so.

Access-Control-Allow-Credentials is off by default and cannot be combined with a * origin; browsers reject that pair, so Headdy refuses to save it.

Editions

Lite $99 · Pro $199.

Documentation

Full documentation is at justinholt.com/plugins/craft-headdy/docs, built from docs/. The API contract — every endpoint, every error code, the GraphQL schema, webhook signing — is docs/api.md.

Console commands

Requirements

Craft CMS 5.3+, Craft Commerce 5.0+, PHP 8.2+.

Tested against Craft 5.10 and Commerce 5.7.

Testing

Static analysis runs in the same container (cd /var/www/craft-headdy first): vendor/bin/phpstan analyse --memory-limit=1G && vendor/bin/ecs check (level 4, clean).

The suite includes live HTTP round-trips against the real endpoint — key rejection, CORS preflight, the whole cart lifecycle and a real gateway payment — so a green run means the wire protocol works, not just the units.

Licence

The Craft License. See LICENSE.md.