Headless storefronts

Cardigan and the Cardigan.js client library are fully compatible with headless storefront implementations.

As headless implementations vary considerably, we're not able to provide a "one size fits all" example, but reviewing the Cardigan.js documentation and pulling in the Cardigan configuration metafield via Shopify's Storefront API should give you a good starting point that can be adapted to your specific stack.

Choosing an approach

There are two ways to integrate, and headless builds often use both.

Cardigan.js gives you a browser-side wrapper around the API, handling configuration loading and request formatting for you. It's the quickest route if your storefront runs in a browser and you're happy to include a script.

The REST API lets you call Cardigan directly from wherever suits your stack - your own backend, an edge function, or a middleware layer. Use it when you want to keep gift card logic server-side, or when a JavaScript library doesn't fit your architecture.

Things to get right

A few points come up repeatedly in headless builds:

• Read your configuration rather than hard-coding it. Line item property names, PIN behaviour and card length are all merchant-configurable. Pull them from the configuration metafield or the store configuration endpoint so a merchant changing a setting doesn't break your integration.
• Release holds when a customer removes a card. Applying a card places a hold on it. If your storefront lets a customer change their mind, make sure it calls the remove endpoint - otherwise the funds stay held until the hold expires.
• Keep holds alive on long-lived pages. If a customer can sit on a checkout page for a while with a card applied, verify the authorization periodically. See How redemption works.
• Attach gift card metadata as line item properties. Provisioning depends on the recipient details arriving as properties on the line item, using the names from your store's configuration.