Skip to main content

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

Install the official Fanfare app from the Shopify App Store:
  1. Visit the Fanfare app listing in the Shopify App Store
  2. Click “Add app” and authorize the permissions
  3. Connect your Fanfare organization in the app settings
  4. 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.
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:
  1. Navigate to Experiences > Create New
  2. Select experience type (Queue, Draw, or Auction)
  3. Configure timing and capacity
  4. Note the Experience ID for later use

Linking to Shopify Products

Connect experiences to specific products or collections:

Step 2: Theme App Extension

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

Adding to Product Pages

  1. Open Online Store > Themes > Customize
  2. Navigate to your product template
  3. Add the Fanfare Experience block
  4. Configure the block settings:

Block Configuration (Liquid)

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.

Include in Theme

Step 4: Cart Line Properties

Store Fanfare data in cart line properties for order processing:

Protecting Against Tampering

Validate tokens server-side in your checkout flow:

Step 5: Webhook Integration

Configure Webhooks in Shopify App

The Fanfare app automatically registers these webhooks:

Manual Webhook Setup

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

Webhook Handler

Step 6: Product Metafields

Store Fanfare configuration in Shopify metafields:

Using Shopify Admin

  1. Go to Settings > Custom data > Products
  2. Add metafield definition:
    • Namespace: fanfare
    • Key: experience_id
    • Type: Single line text

Using Admin API

Step 7: Checkout UI Extension (Shopify Plus)

For Shopify Plus stores, create a checkout UI extension:

Styling the Experience

CSS Customization

Best Practices

1. Handle Browser Back Button

2. Mobile Optimization

Troubleshooting

Experience Not Loading

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

Cart Properties Not Appearing

Shopify may strip properties starting with _ in some contexts:

Webhook Not Firing

  1. Verify webhook is registered in Shopify admin
  2. Check webhook delivery logs
  3. Ensure endpoint URL is publicly accessible
  4. Verify HMAC signature validation

Token Validation Failing

What’s Next