Non-Shopify headless storefront guide

Purpose

This guide explains how a non-Shopify headless storefront should prepare a signed config payload, expose it to the Tern storefront module, and mount <tern-trade-in>.

This path supports merchant-signed headless bootstrap without Shopify customer authentication.

If the storefront belongs to a Shopify shop and you need logged-in customer support, use Shopify Headless Storefront Integration Guide.

If you cannot use headless authentication at all, use Standalone Storefront Integration Guide.

Recommendation First

This guide is for non-Shopify headless storefronts that can still generate merchant-signed bootstrap payloads on their backend.

It is stronger than the standalone no-proof flow because the request is signed server-side, but it does not include Shopify customer authentication.

Summary

The implementation has three steps:

1. Get the merchant shared secret from Tern.

2. Use that shared secret on your backend to sign the bootstrap request payload.

3. Expose window.ternStorefrontConfig before mounting <tern-trade-in>.

What Is Different From Shopify Headless

This guide uses the same merchant-signed proof type as the Shopify guide, but with these restrictions:

1. No logged-in Shopify customer context.

2. No proof.customer object.

3. The signature must always use an empty email value.

4. The signature must always use id=0.

Shared Secret

Before implementing the bootstrap call, obtain the merchant shared secret from the Tern admin interface for the relevant shop.

Implementation guidance:

1. Generate or copy the shared secret from the Tern admin interface.

2. Store the shared secret on your backend.

3. Do not expose the shared secret in browser code.

4. Use the shared secret only on the server when generating the HMAC signature.

Config Format

Expose window.ternStorefrontConfig with these fields:

1. shopDomain

2. locale

3. proof

Browser config uses shopDomain. The storefront runtime converts that to the API field shop_domain before calling the bootstrap endpoint.

Example:

{
  "shopDomain": "example-store.com",
  "locale": "en",
  "proof": {
    "type": "merchant_signed",
    "timestamp": 1710000000,
    "signature": "hex-hmac-signature"
  }
}

How To Sign The Request

When using merchant_signed, your backend must sign the full canonical string shown below with HMAC-SHA256 using the merchant shared secret.

Only these four values are part of the signature:

1. email

2. shop_domain

3. id

4. timestamp

Sign this exact canonical string:

email=<normalized-email>&id=<id-or-0>&shop_domain=<shop-domain>&timestamp=<unix-seconds>

For non-Shopify headless bootstrap:

1. email must be an empty string.

2. shop_domain must be the configured shop domain for the storefront.

3. id must be 0.

4. timestamp must be a Unix timestamp in seconds.

5. The signature must be lowercase hex.

6. Generate the signature on your backend, never in browser code.

Node.js Example

import { createHmac } from 'node:crypto';

const sharedSecret = process.env.TERN_SHARED_SECRET;
const timestamp = Math.floor(Date.now() / 1000);

const canonical = [
  ['email', ''],
  ['shop_domain', 'example-store.com'],
  ['id', '0'],
  ['timestamp', String(timestamp)]
].map(([key, value]) => `${key}=${value}`).join('&');

const signature = createHmac('sha256', sharedSecret)
  .update(canonical, 'utf8')
  .digest('hex')
  .toLowerCase();

const payload = {
  shopDomain: 'example-store.com',
  locale: 'en',
  proof: {
    type: 'merchant_signed',
    timestamp,
    signature
  }
};

Do not include proof.customer in this flow.

Bootstrap Response

After the storefront module initializes, it obtains a bootstrap response that includes:

1. token

2. locale

3. ga_measurement_id

shopify_customer is not expected in this flow.

Example response:

{
  "token": "tern-jwt",
  "locale": "en",
  "ga_measurement_id": ""
}

The returned token is a Tern storefront session token. It is not proof of Shopify customer identity.

Browser Runtime And Mount

Use the same runtime loading and mount pattern as Shopify Headless Storefront Integration Guide.

The only difference is the config payload. Use this body snippet instead:

<body>
  <div id="tern-storefront-root"></div>

  <script>
    window.ternStorefrontConfig = {
      shopDomain: 'example-store.com',
      locale: 'en',
      proof: {
        type: 'merchant_signed',
        timestamp: 1710000000,
        signature: 'hex-hmac-signature'
      }
    };

    const element = document.createElement('tern-trade-in');
    document.getElementById('tern-storefront-root').appendChild(element);
  </script>
</body>

For shared prerequisites, see What The JavaScript Example Assumes.

Implementation Checklist

1. Obtain the merchant shared secret from the Tern admin interface.

2. Store the shared secret on your backend.

3. Build the canonical payload with empty email and id=0.

4. Sign the payload on your backend.

5. Expose shopDomain, locale, and proof in window.ternStorefrontConfig before mounting the storefront.

6. Load the storefront browser bundle.

7. Mount <tern-trade-in> after window.ternStorefrontConfig is defined.

8. Let the storefront module initialize the storefront session from that config.

9. Use the returned token as the storefront session token.

10. If you later need authenticated customer context, move to Shopify Headless Storefront Integration Guide.