Skip to main content

Shopify App Setup

Get the Resonance loyalty app running on your Shopify store.

Prerequisites​

  • A Shopify store (any plan)
  • A Resonance Partner Portal account
  • Your Brand ID (from Partner Portal → Settings → Account)

Installation​

Install the app from the Shopify App Store or via the Partner Portal integrations page. The app will request these permissions:

  • Read orders (for reward calculation)
  • Read customers (for identity mapping)
  • Write discounts (for perk redemptions)
  • Read products (for product-specific rules)

Onboarding Wizard​

After installation, the app walks you through a 4-step setup:

Step 1: Brand Configuration​

  • Display Name — Your brand name as shown to customers
  • Brand ID — Your Resonance wallet address (starts with 0x, 42 characters). Find this in Partner Portal → Settings → Account
  • Security Key — Optional but recommended. Used for HMAC signing of API requests. Minimum 8 characters

Step 2: First Earning Rule​

Create your initial earning rule:

  • Rule Type — Purchase (earn credits on orders)
  • Credits Per Dollar — How many RSNC credits per $1 spent (1-10,000)

This creates a default "Standard Purchase Reward" rule. You can add more rules later.

Step 3: Fund Your Account (Optional)​

Add RSNC credits to your brand balance via Stripe. You can skip this and fund later from the dashboard.

Step 4: Activation​

The app marks setup as complete and notifies the Partners Bridge. You're redirected to your dashboard.

Storefront Widget Setup​

After onboarding, add the loyalty widget to your store:

Main Embed Script​

Add to your theme (via Settings → Embed Scripts in the app):

<script src="https://widgets.rsnc.network/v1/embed.js"
  data-brand-id="YOUR_BRAND_ID"
  data-customer-email="{{ customer.email }}"
  defer></script>

Thank-You Page Script​

Show customers their rewards after checkout:

<script src="https://widgets.rsnc.network/v1/embed.js"
  data-brand-id="YOUR_BRAND_ID"
  data-customer-email="{{ checkout.email }}"
  data-page="thank-you"
  defer></script>

How Webhooks Work​

Once installed, the app automatically receives Shopify webhooks:

  1. Order created → App matches earning rules → Credits awarded to customer
  2. Customer created → App creates customer mapping → Signup event sent
  3. App uninstalled → App cleans up merchant data

Webhooks are rate-limited to 200 per 60 seconds per shop.

Database​

The app uses Cloudflare D1 with these tables:

TablePurpose
merchantsStore configuration, Brand ID, security key
earning_rulesEarning rule definitions
customer_mappingsShopify customer → email mappings
webhook_eventsAudit log with idempotency

Security​

  • Webhook verification — All Shopify webhooks verified via HMAC signature
  • HMAC signing — Outbound API calls signed with security key
  • Customer identity — Email verified from Shopify authenticated sessions (not user input)
  • Idempotency — Duplicate webhooks are detected and skipped
  • Rate limiting — Per-shop webhook rate limits via Cloudflare KV

Next Steps​

Last updated on