Developer DocsLoyalty ConsoleSupport

Shopify app

The WLL Shopify app enables you to seamlessly integrate a customised loyalty program powered by the Loyalty Engine into your Shopify store. This integration allows you to embed a Loyalty Microsite, automatically report purchase events, and enable points redemption at checkout.

Key features

The WLL Shopify app allows you to enable a number of features within your Shopify store, depending on your exact use case. You onboarding manager will advise you on your setup. Highlights of the key features includes:

  • Loyalty Microsite integration: Embed a loyalty experience directly within your Shopify store.

  • Seamlessly authenticate Shopify users as Loyalty Microsite users: Customers use their Shopify login credentials for easy access.

  • Report Shopify purchases as events in the Loyalty Engine: Transactions are automatically reported to the Loyalty Engine.

  • Points redemption at checkout: Customers can redeem points for discounts directly within the Shopify checkout (optional and only available for Shopify Plus merchants).

Getting started

Installing the App

  1. Install the WLL Shopify app from the Shopify App Store.

  2. Follow the guided prompts to complete the installation.

  3. You'll need your WLL API key (found in Loyalty Console > Settings > Tenant) and some auth credentials (a client ID and secret), which you can request from your onboarding manager.

  4. Head to the 'Dashboard' section in the app's sidebar and follow the Get started checklist.

Configuration & setup

These steps should be completed with support from WLL:

  1. Set up a custom domain for the loyalty microsite matching the Shopify store’s domain.

  2. Choose an account enrolment method:

    • Auto-enrol (default) – all Shopify customers are automatically added to the loyalty program.

    • Opt-in – customers must explicitly sign up to join.

  3. Select the user authentication ID:

    • By default, user email addresses are used as the loyalty account identifier.

    • Optionally, you can configure the system to use Shopify account IDs.

  4. Embed the loyalty microsite:

    1. Select the microsite you want to embed on the app's dashboard within the Getting started checklist.

    2. Go to the theme editor and create a template.

    3. Under 'Apps' in the sidebar, over White Label Loyalty choose + Add block and add the relevant block.

    4. Use the Shopify app block to add the microsite to a Shopify page.

    5. Assign the template to a Shopify page.

  5. Set up loyalty rules:

    • Configure a reactor in the Loyalty Console to award points on purchases.

    • Set up a reactor to deduct points when redeeming at checkout (if applicable).

  6. Test & launch: Verify the setup and go live!

How it works

User accounts & authentication

The app is based around Shopify’s own accounts system, meaning that the app communicates to the WLL API on behalf of the user (with an administrative token) instead of any requests coming directly from the user.

Once installed, the Shopify app creates Loyalty Engine accounts to represent each Shopify user account at any of several key points throughout the Shopify customer journey. The account creation can happen as either an auto-enrol process (the default setup after app installation), or an opt-in process:

Default setup – Auto-enrol

The default setup is an auto-enrol process whereby all Shopify users and enrolled in the loyalty program. In this scenario, the WLL user account is created when a user either:

  1. Opens the microsite: When a user visits the Shopify page containing the microsite whilst logged in, a Loyalty Engine account will be created just in time as the page loads.

  2. Makes a purchase: When a user makes a purchase in the Shopify store whilst logged in, a Loyalty Engine account will be created when the purchase completes (for the purpose of sending the purchase event to the Loyalty Engine.

  3. Clicks a referral link: When a user clicks on a WLL referral link which directs to the Shopify store a WLL account will be created for the user immediately when they create their Shopify account for the purposes of referral tracking.

Alternative setup – Opt-in

You can optionally choose to use an ‘opt-in’ setup, whereby users must explicitly opt in to be part of the loyalty program (and thus do not earn points or have a Loyalty Engine account created until or unless they opt in).

To find out more about using the opt-in approach, speak to your onboarding manager.

WLL Auth Identifier

The app uses the user’s email address as stored in Shopify as the WLL user authIdentifier by default, but also supports using the Shopify account ID.

To use the Shopify account ID instead, speak to your onboarding manager.

Loyalty Microsite

Once installed, the Shopify app allows you to embed your WLL microsite into your storefront on a page of your choosing. This is done by means of a Shopify App Block which you can add to one of your theme’s page templates, you can use Shopify’s drag and drop visual editor to customize its placement.

Once added to a template, you can create a page in your store front using that template — the page itself should be blank since the actual functionality is handled by the template.

When rendering the microsite the app uses embedded auth to generate a session for the user automatically. The microsite is loaded using an admin auth token with user impersonation.

For authentication to reliably work, the microsite must be served from a custom domain which matches the domain of the Shopify store it is embedded in.

Earning points

Once installed, the app automatically reports events of the event type PURCHASED_FROM_SHOPIFY whenever a user makes a purchase on the store which includes the standard Shopify order data.

A reactor must then be configured in the Loyalty Console to award points based on the desired event payload data (i.e. transaction value or basket data).

Example payload: PURCHASED_FROM_SHOPIFY
{
  "shop": "46a563-2.myshopify.com",
  "currency": "BGN",
  "total_tax": 0,
  "line_items": [
      {
          "id": 12857643040822,
          "sku": "",
          "name": "The Collection Snowboard: Liquid",
          "price": 749.95,
          "quantity": 1,
          "product_id": 7028679049270,
          "variant_id": 41030714032182
      }
  ],
  "total_price": 747.95,
  "checkout_token": "d9cf8439345786a0be3a46cd9a8d83bd",
  "subtotal_price": 747.95,
  "note_attributes": [
      {
          "name": "WLL_points",
          "value": "20"
      }
  ],
  "total_discounts": 2,
  "total_outstanding": 0
}

Spending points

This functionality is only available to merchants who pay for Shopify Plus because the checkout screen customization feature is only available in that Shopify plan. All other functionality described elsewhere on this page is available for all Shopify plans.

Once installed, the Shopify app allows you to place a WLL widget on your checkout page. This widget shows customers how many points they have and allows them to apply points as a discount to their order.

In the Shopify app’s settings, you can configure the:

  1. Point value: The currency value of points in discounts.

  2. Minimum points criteria: The minimum number of points required to apply a discount.

The widget does not tell users how much their points are worth based on the point value setting, so this must be communicated to the customer manually somewhere.

When redeeming points during checkout, after a customer presses the Apply button, the specified points are immediately debited from the customer’s loyalty account balance by sending an APPLIED_POINTS_SHOPIFY event to the WLL API.

Example payload: APPLIED_POINTS_SHOPIFY
{
  "shop": "wll-perkscoffee.myshopify.com",
  "points": 100,
  "checkout_token": "68b87fd0e52727473d487de241216c40",
  "primary_domain": "https://wll-perkscoffee.myshopify.com"
}

A reactor must be setup in the tenant to ensure these points are debited from the user’s loyalty account. To prevent fraud, points are debited as soon as they are applied, as Shopify does not support locking points during checkout.

Alternative approaches to spending points

WLL vouchers can be used to distribute Shopify discount codes via the microsite as WLL rewards.

Whilst not a part of the functionality of the WLL Shopify app, you can use a Shopify app like Bulk Discount Code Bot to create a discount of your choosing within the Shopify discount constraints (i.e. $10 off a $20 purchase, 30% off etc.) and distribute these in a WLL code pool voucher.

Speak to your onboarding manager if you need more information about this use case.

PreviousIntegrationsNextMarketing

Last updated

Was this helpful?