Shopify Integration Guide

Learn how to integrate Fanfare experiences with your Shopify store, from installation to checkout completion.

Overview

Fanfare provides a native Shopify app that integrates virtual queues, draws, and auctions directly with your Shopify storefront. This guide covers both app installation and custom theme integration. What you’ll learn:

Installing and configuring the Fanfare Shopify app
Embedding experiences in your theme
Connecting experiences to products
Handling checkout with Shopify’s native cart
Processing order webhooks

Complexity: Intermediate Time to complete: 45 minutes

Prerequisites

Shopify store (Basic plan or higher)
Fanfare account with active organization
Access to Shopify theme editor

Installation Options

Option 1: Fanfare Shopify App (Recommended)

Install the official Fanfare app from the Shopify App Store:

Visit the Fanfare app listing in the Shopify App Store
Click “Add app” and authorize the permissions
Connect your Fanfare organization in the app settings
Configure your first experience

The app handles:

OAuth authentication with Shopify
Automatic webhook registration
Theme app extension for embedding
Order completion notifications

Option 2: Custom Integration

For stores requiring custom implementations, bundle the current Fanfare SDK into your theme or storefront app and render from the public journey state. Do not rely on the deprecated global CDN snippet.

<!-- In your theme's product.liquid or collection.liquid -->
<div id="fanfare-experience" data-experience-id="{{ product.metafields.fanfare.experience_id }}"></div>
{{ "fanfare-integration.js" | asset_url | script_tag }}

Your bundled script should initialize @fanfare-io/fanfare-sdk-core, call sdk.journeys.get(experienceId), render from journey.view$, and hand the admissionGrant to your cart or checkout flow when the sequence reaches admitted. See Custom Platform Integration for the framework-agnostic pattern.

Step 1: Configure Experience in Admin

Create your experience in the Fanfare admin panel:

Navigate to Experiences > Create New
Select experience type (Queue, Draw, or Auction)
Configure timing and capacity
Note the Experience ID for later use

Linking to Shopify Products

Connect experiences to specific products or collections:

// Using the Fanfare Admin API
const experience = await fanfareAdmin.experiences.create({
  name: "Limited Sneaker Drop",
  type: "queue",
  config: {
    capacity: 500,
    admissionWindow: 600, // 10 minutes
  },
  metadata: {
    shopifyProductId: "gid://shopify/Product/1234567890",
    shopifyVariantIds: ["gid://shopify/ProductVariant/111", "gid://shopify/ProductVariant/222"],
  },
});

Step 2: Theme App Extension

The Fanfare Shopify app includes a theme app extension for easy embedding.

Adding to Product Pages

Open Online Store > Themes > Customize
Navigate to your product template
Add the Fanfare Experience block
Configure the block settings:

Setting	Description
Experience Source	Product metafield or manual ID
Display Mode	Inline, modal, or full-page
Auto-redirect	Redirect to cart on admission
Show countdown	Display time remaining

Block Configuration (Liquid)

{% comment %} sections/fanfare-experience.liquid {% endcomment %}
{% schema %}
{
  "name": "Fanfare Experience",
  "settings": [
    {
      "type": "text",
      "id": "experience_id",
      "label": "Experience ID",
      "info": "Leave blank to use product metafield"
    },
    {
      "type": "select",
      "id": "display_mode",
      "label": "Display Mode",
      "options": [
        { "value": "inline", "label": "Inline" },
        { "value": "modal", "label": "Modal" },
        { "value": "fullpage", "label": "Full Page" }
      ],
      "default": "inline"
    },
    {
      "type": "checkbox",
      "id": "auto_redirect",
      "label": "Auto-redirect to cart on admission",
      "default": true
    }
  ]
}
{% endschema %}

<div
  id="fanfare-experience-{{ section.id }}"
  class="fanfare-experience"
  data-experience-id="{{ section.settings.experience_id | default: product.metafields.fanfare.experience_id }}"
  data-display-mode="{{ section.settings.display_mode }}"
  data-auto-redirect="{{ section.settings.auto_redirect }}"
  data-product-id="{{ product.id }}"
  data-variant-id="{{ product.selected_or_first_available_variant.id }}"
></div>

Step 3: JavaScript Integration

Initialize the SDK

Build assets/fanfare-integration.js with the current core SDK package. The script should render from journey.view$ and only offer actions exposed by the current public view.

import initFanfare from "@fanfare-io/fanfare-sdk-core";

const sdk = await initFanfare({
  organizationId: window.FanfareConfig.organizationId,
  publishableKey: window.FanfareConfig.publishableKey,
});

document.querySelectorAll(".fanfare-experience").forEach((container) => {
  const journey = sdk.journeys.get(container.dataset.experienceId);

  journey.view$.listen((view) => {
    if (view.journeyStage === "routed" && view.sequence.phase === "granted") {
      showCheckoutButton(container, view.sequence.grant.token);
    }
  });

  const initialView = journey.view$.get();
  if (initialView.journeyStage === "ready") {
    void initialView.start();
  }
});

function showCheckoutButton(container, admissionGrant) {
  const button = document.createElement("button");
  button.className = "fanfare-checkout-btn";
  button.textContent = "Complete Purchase";
  button.onclick = () => addToCartAndCheckout(container.dataset.variantId, admissionGrant);
  container.appendChild(button);
}

function addToCartAndCheckout(variantId, admissionGrant) {
  return fetch("/cart/add.js", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      items: [{ id: variantId, quantity: 1, properties: { _fanfare_token: admissionGrant } }],
    }),
  }).then(() => {
    window.location.href = "/checkout";
  });
}

Include in Theme

{% comment %} layout/theme.liquid {% endcomment %}
<script>
  window.FanfareConfig = {
    organizationId: "{{ shop.metafields.fanfare.organization_id }}",
    publishableKey: "{{ shop.metafields.fanfare.publishable_key }}",
  };
</script>
{{ "fanfare-integration.js" | asset_url | script_tag }}

Step 4: Cart Line Properties

Store Fanfare data in cart line properties for order processing:

// When adding to cart with admission token
const cartData = {
  items: [
    {
      id: variantId,
      quantity: 1,
      properties: {
        _fanfare_token: admission.token,
        _fanfare_experience_id: experienceId,
        _fanfare_consumer_id: admission.consumerId,
        _fanfare_distribution_type: admission.distributionType,
        _fanfare_admitted_at: new Date().toISOString(),
      },
    },
  ],
};

fetch("/cart/add.js", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(cartData),
});

Protecting Against Tampering

Validate tokens server-side in your checkout flow:

{% comment %} In checkout.liquid or via Shopify Functions {% endcomment %}
{% for item in checkout.line_items %}
  {% if item.properties._fanfare_token %}
    {% comment %} Token will be validated via webhook {% endcomment %}
    <input type="hidden" name="fanfare_token" value="{{ item.properties._fanfare_token }}">
  {% endif %}
{% endfor %}

Step 5: Webhook Integration

Configure Webhooks in Shopify App

The Fanfare app automatically registers these webhooks:

Webhook Topic	Purpose
`orders/create`	Validate admission and complete
`orders/paid`	Confirm successful transaction
`orders/cancelled`	Handle cancellations
`refunds/create`	Track refund events

Manual Webhook Setup

If using custom integration, register webhooks via Shopify Admin API:

// Register order webhook
const webhook = await shopifyAdmin.webhook.create({
  topic: "orders/create",
  address: "https://api.fanfare.io/webhooks/shopify/orders",
  format: "json",
});

Webhook Handler

// Your webhook endpoint (or Fanfare's built-in handler)
app.post("/webhooks/shopify/orders", async (req, res) => {
  const hmac = req.headers["x-shopify-hmac-sha256"];

  // Verify webhook signature
  if (!verifyShopifyWebhook(req.body, hmac)) {
    return res.status(401).send("Invalid signature");
  }

  const order = req.body;

  // Extract Fanfare data from line items
  for (const item of order.line_items) {
    const fanfareToken = item.properties?.find((p: { name: string }) => p.name === "_fanfare_token")?.value;

    if (fanfareToken) {
      const experienceId = item.properties?.find((p: { name: string }) => p.name === "_fanfare_experience_id")?.value;
      const consumerId = item.properties?.find((p: { name: string }) => p.name === "_fanfare_consumer_id")?.value;
      const distributionType = item.properties?.find(
        (p: { name: string }) => p.name === "_fanfare_distribution_type"
      )?.value;

      // Complete the admission in Fanfare
      await fanfareApi.completeAdmission({
        experienceId,
        consumerId,
        distributionType,
        orderId: order.id.toString(),
        orderAmount: order.total_price,
        metadata: {
          platform: "shopify",
          shopDomain: order.shop_domain,
          orderNumber: order.order_number,
          currencyCode: order.currency,
        },
      });
    }
  }

  res.status(200).send("OK");
});

Step 6: Product Metafields

Store Fanfare configuration in Shopify metafields:

Using Shopify Admin

Go to Settings > Custom data > Products
Add metafield definition:
- Namespace: fanfare
- Key: experience_id
- Type: Single line text

Using Admin API

// Set experience ID on a product
await shopifyAdmin.metafield.create({
  namespace: "fanfare",
  key: "experience_id",
  value: "exp_abc123xyz",
  type: "single_line_text_field",
  owner_resource: "product",
  owner_id: productId,
});

// Set organization-level config on shop
await shopifyAdmin.metafield.create({
  namespace: "fanfare",
  key: "organization_id",
  value: "org_xyz789abc",
  type: "single_line_text_field",
  owner_resource: "shop",
});

Step 7: Checkout UI Extension (Shopify Plus)

For Shopify Plus stores, create a checkout UI extension:

// extensions/fanfare-checkout/src/Checkout.tsx
import { reactExtension, Banner, useCartLines, useApplyCartLinesChange } from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => <FanfareCheckoutValidation />);

function FanfareCheckoutValidation() {
  const cartLines = useCartLines();
  const applyCartLinesChange = useApplyCartLinesChange();

  // Check for Fanfare tokens in cart
  const fanfareItems = cartLines.filter((line) => line.attributes?.some((attr) => attr.key === "_fanfare_token"));

  if (fanfareItems.length === 0) {
    return null;
  }

  // Validate tokens are still valid
  const [validationStatus, setValidationStatus] = useState<"pending" | "valid" | "invalid">("pending");

  useEffect(() => {
    validateFanfareTokens(fanfareItems).then((isValid) => {
      setValidationStatus(isValid ? "valid" : "invalid");
    });
  }, [fanfareItems]);

  if (validationStatus === "invalid") {
    return (
      <Banner status="critical" title="Access Expired">
        Your access to purchase these items has expired. Please return to the product page to rejoin the experience.
      </Banner>
    );
  }

  if (validationStatus === "valid") {
    return (
      <Banner status="success" title="Access Verified">
        Your exclusive access has been verified. Complete your purchase before the timer expires.
      </Banner>
    );
  }

  return null;
}

async function validateFanfareTokens(items: CartLine[]): Promise<boolean> {
  for (const item of items) {
    const token = item.attributes?.find((a) => a.key === "_fanfare_token")?.value;
    if (!token) continue;

    const response = await fetch("https://api.fanfare.io/v1/admission/validate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token }),
    });

    if (!response.ok) {
      return false;
    }
  }
  return true;
}

Styling the Experience

CSS Customization

/* assets/fanfare-custom.css */
.fanfare-experience {
  padding: 20px;
  border-radius: 8px;
  background: var(--color-background);
}

.fanfare-queue-position {
  font-size: 2rem;
  font-weight: bold;
  text-align: center;
}

.fanfare-timer {
  font-size: 1.5rem;
  color: var(--color-primary);
}

.fanfare-checkout-btn {
  width: 100%;
  padding: 16px 24px;
  background: var(--color-primary);
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 1.1rem;
  cursor: pointer;
  transition: background 0.2s;
}

.fanfare-checkout-btn:hover {
  background: var(--color-primary-dark);
}

.fanfare-error {
  padding: 12px;
  background: #fee;
  color: #c00;
  border-radius: 4px;
}

Best Practices

1. Handle Browser Back Button

// Prevent users from losing their place
window.addEventListener("popstate", function (event) {
  if (sessionStorage.getItem("fanfare_admission")) {
    if (!confirm("Leaving may forfeit your place in the experience. Continue?")) {
      history.pushState(null, "", location.href);
    }
  }
});

2. Mobile Optimization

{% comment %} Responsive container {% endcomment %}
<style>
  @media (max-width: 768px) {
    .fanfare-experience {
      position: fixed;
      bottom: 0;
      left: 0;
      right: 0;
      z-index: 1000;
      border-radius: 16px 16px 0 0;
      box-shadow: 0 -4px 20px rgba(0, 0, 0, 0.15);
    }
  }
</style>

Troubleshooting

Experience Not Loading

Check that organization ID metafield is set on shop
Verify experience ID is correct in product metafield
Check browser console for SDK errors
Ensure SDK script is loading (check network tab)

Cart Properties Not Appearing

Shopify may strip properties starting with _ in some contexts:

// Use non-underscore prefixed properties if needed
properties: {
  fanfare_token: admission.token,
  fanfare_experience_id: experienceId,
}

Webhook Not Firing

Verify webhook is registered in Shopify admin
Check webhook delivery logs
Ensure endpoint URL is publicly accessible
Verify HMAC signature validation

Token Validation Failing

// Debug token validation
async function debugTokenValidation(token) {
  const response = await fetch("https://api.fanfare.io/v1/admission/validate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token }),
  });

  const data = await response.json();
  console.log("Validation response:", data);

  if (!response.ok) {
    console.error("Validation failed:", data.error);
    console.error("Token may be expired or already used");
  }

  return response.ok;
}

What’s Next

WooCommerce Integration - WordPress/WooCommerce setup
Custom Platform - Build for any platform
Webhooks Guide - Advanced webhook handling
Order Completion - Complete order processing

​Shopify Integration Guide

​Overview

​Prerequisites

​Installation Options

​Option 1: Fanfare Shopify App (Recommended)

​Option 2: Custom Integration

​Step 1: Configure Experience in Admin

​Linking to Shopify Products

​Step 2: Theme App Extension

​Adding to Product Pages

​Block Configuration (Liquid)

​Step 3: JavaScript Integration

​Initialize the SDK

​Include in Theme

​Step 4: Cart Line Properties

​Protecting Against Tampering

​Step 5: Webhook Integration

​Configure Webhooks in Shopify App

​Manual Webhook Setup

​Webhook Handler

​Step 6: Product Metafields

​Using Shopify Admin

​Using Admin API

​Step 7: Checkout UI Extension (Shopify Plus)

​Styling the Experience

​CSS Customization

​Best Practices

​1. Handle Browser Back Button

​2. Mobile Optimization

​Troubleshooting

​Experience Not Loading

​Cart Properties Not Appearing

​Webhook Not Firing

​Token Validation Failing

​What’s Next