Shopify is an e-commerce platform that provides businesses with the essentials for creating and managing online stores. From customizable storefronts to seamless payment processing, shipping, and order management, Shopify has it all. When integrated with Antavo’s Loyalty Engine, Shopify's functionality can be further expanded.

Antavo’s loyalty app for Shopify, available in web-based version, enhances your ability to track and reward customer behavior. This integration elevates customer engagement, boosts retention, and drives revenue by rewarding purchases.

Moreover, The Antavo Shopify app extends beyond supporting a single shop. It has the capability to handle multiple shops; syncing data from more than one Shopify store to a single Antavo workspace. Each shop gets its own editing interface and new shops can be synced automatically as well.

📘

Note

Currently, each Antavo workspace can only synchronize with a single (main) currency. If you would like to send data in multiple currencies to the same Antavo workspace, please contact us for assistance.

In this guide, we'll walk you through configuring your shops and testing core functionalities.

The first section covers the steps to perform in Shopify to synchronize customer registrations and transactions. Then we’ll dive into common use cases, including signing up for the loyalty program, making orders, and updating profile attributes.

Prerequisites

To connect the two systems, you need the following:

• Antavo workspace with the Shopify module enabled
• Shopify store

Installing the Antavo app in Shopify

First, you need to install the Antavo app in Shopify:

• Log in to Shopify
• Find the Antavo Shopify app in the Shopify App Store
• Click Install
• Grant the listed permissions by clicking Install

With these steps, you have successfully installed the app.

Antavo connection settings in Shopify

After installing the app you’ll be redirected to the Antavo settings page where you can connect the two systems.

• Navigate to the Antavo connection settings section
• Stack name: Enter the Antavo environment to be connected to Shopify
  You can find it in the URL where you access it from your Antavo workspace: https://loyalty.{environment}.antavo.com. Make sure you enter the environment name in all lowercase letters.
• Provide the API credentials (API key and secret) of your Antavo workspace
• Select the transaction identifier used for data transmission to Antavo
• Select the customer identifier used for data transmission to Antavo
  If a customer's email address is modified in Shopify under the Edit Contact Information page, Antavo will automatically update its system to reflect the change. This ensures that modifications to the email address do not disrupt data synchronization between the two platforms.
• Enable Extract discount to subtract discounts from product subtotals
• Enable refund to manage refunds after a checkout has been fulfilled
  This requires that the Orders updates option is mapped with an Antavo event in the Shopify settings.
• Enable product composite ID for Antavo to generate IDs by combining product and variant IDs with a hyphen
  Enabling this is required if you have enabled refunds.
• Click Submit to save configurations and activate Shopify webhooks for data forwarding to Antavo based on your webhook settings.

If the connection is successful, a success message will be displayed, the webhooks will be activated and your Shopify stores will appear when you access the Shopify module in Antavo through the Modules menu.

If you need to re-connect the webhooks, click Register webhooks at the bottom of the Antavo settings in Shopify.

Configure the cronjob

To create a new cron job in Antavo for processing incoming webhooks from Shopify to Antavo, follow these steps:

• Navigate to the Settings menu in the Antavo Management UI
• Open the Jobs tab and click Create new job
• Name your job
• Configure the command settings as follows:
  • Task: shopify-incoming
  • Action: process
• Click Create at the bottom of the page

For detailed instructions on using the job editor, please refer to the user manual.

Antavo webhook settings

The fields under the Settings tab allow you to add the shops and pair the corresponding webhook responses, allowing for seamless management and utilization of their functionalities.

Shop domain

Here, list the names of the Shopify webstores you want to connect to Antavo.

Webhook settings

To configure webhook settings for mapping Shopify events to Antavo events and ensure they are registered in the customer event streams, follow these steps:

• Orders created: Choose whether to register an event when an order is placed in Shopify.
  Options include Do nothing, or registering a Checkout
• Orders updated: Select the event to register when a shop administrator modifies a transaction in Shopify, such as updating buyer details or adding new items to the cart. Refunds can also be managed through this webhook.
  Options vary based on the status of the Checkout accept module:
  • If enabled: Do nothing, Register partial or full refund
  • If disabled: Do nothing, Checkout update / Checkout reject / Register partial or full refund
• Orders fulfilled: Select the event to register upon order fulfillment in Shopify.
  Options vary based on the status of the Checkout accept module:
  • If enabled: Do nothing, Checkout, Checkout accept
  • If disabled: Do nothing, Checkout
• Orders cancelled: Select the event to register when an order is canceled in Shopify.
  Options vary based on the status of the Checkout accept module:
  • If enabled: Do nothing, Checkout reject
  • If disabled: Do nothing
• Orders deleted: Select the event to register when a shop administrator deletes an order in Shopify.
  Options vary based on the status of the Checkout accept module:
  • If the Checkout accept module module is enabled: Do nothing
  • If the Checkout accept module module is disabled: Do nothing, Checkout reject

📘

Note

To register checkout_accept and checkout_reject events, ensure the Checkout accept module is activated for validation and response handling. Contact Antavo Service Desk for assistance enabling this module.

Shopify API calls

Use the Enable Shopify API Call checkbox to control whether product details (like type, tags, and collections) are fetched from Shopify during webhook processing. Enable if you need these details; disable to minimize API calls.

Incoming queue

When Shopify sends webhook messages to Antavo, they undergo asynchronous processing through specific endpoints:

• customers/create
• customers/update
• orders/cancelled
• orders/create
• orders/delete
• orders/fulfilled
• orders/updated
• products/create
• products/delete
• products/update

Requests to these endpoints are queued for processing, enabling instant responses to Shopify regarding event registration. Any requests to unlisted endpoints are processed directly without queuing.

🚧

Note

Any requests to unlisted endpoints are processed directly without queuing.

In the Antavo Management UI under the Incoming queue tab, you can monitor queued items, including

• ID: Unique identifier of the request generated by Antavo.
• Target URI: The endpoint where the request was sent.
• Number of retries: Retry attempts (up to 5) for failed event registrations.
• Status:
  • Pending: The request is queued but has not yet been processed.
  • Failed: The request failed after 5 unsuccessful attempts.
• Timestamp: Date of request submission to Antavo.

Entries are automatically removed from the queue upon successful processing.

Customer journeys

This section explains a few scenarios that represent the most common customer journeys between Shopify and Antavo.

Enable loyalty registration

To enable customers to join the loyalty program when they create an account in your store, you need to edit your registration form.

Follow these steps:

• Go to the Antavo settings in Shopify
• Copy the HTML code snippet from the Installation section

• Navigate to the Online store channel and edit your theme
• Open the main-register.liquid file
• Paste the code snippet inside the form and customize the text as needed.
• Click Save

Once, done, the Sign me up to the loyalty program (or the customized text) checkbox will appear on the registration form. When customers join the loyalty program, an opt_in event will be recorded automatically in Antavo, and their status will be set to active, making them a member of the loyalty program.

To verify a new customer’s membership in the loyalty program through Antavo, follow these steps:

• Navigate to the Customer insights tab in Antavo’s left-hand-side menu bar
• The page will display the list of loyalty members, where the newly registered account should be listed.
• Select the customer’s profile and navigate to the Events tab.
• Confirm the registration by checking if the opt_in event is present in the event log.

Sending transactional data

When a customer makes a purchase, the transaction can be automatically registered in Antavo if the Orders created webhook is configured to be mapped to the checkout event.

Once the order appears under Orders in Shopify or after clicking the Fulfill button on the order page (depending on the Webhook settings) the checkout event will be triggered, registering it in the customer’s event stream in Antavo. Any loyalty program benefits (points or rewards) as per the program configuration, will be automatically assigned.

To verify a transaction registration, follow these steps:

• Navigate to the Customer insights tab in Antavo’s left-hand-side menu bar
• The page will display the list of loyalty members, where the newly registered account should be listed
• Select the customer’s profile and go to the Events tab
• Confirm the registration by checking if the checkout event is present in the event log

Managing profile changes

Antavo receives updated information whenever a profile attribute is updated in Shopify, including customer profile tags.

In Antavo’s system, the Customer profile has a Tags field, allowing updates based on the tags added to customers' Shopify profiles. These tags can be used for automatic segment creation.

The tags are then synchronized with Antavo, facilitating targeted reward campaigns and customer segmentation.

To verify customer tags in Antavo, follow these steps :

Open the customer’s profile in Customer insights and navigate to the Personal information tab

Go to the Additional fields section and compare the tags with those in Shopify
The synchronization is demonstrated in the screenshots below.

Widgets

Widgets allow you to display essential loyalty program elements directly on the storefront without coding. You can showcase active rewards, challenges, points, and other customer-specific information. This functionality makes it easy for customers to interact with your loyalty program and stay engaged.

Types of available widgets

There are seven types of widgets available:

• Customer Campaigns – Displays ongoing campaigns the customer can participate in (configured in the Workflows module).
• Customer Challenges – Lists challenges that the customer can complete (configured in the Challenges module).
• Customer Contests – Shows contests customers can join (configured in the Contest lite module).
• Customer Coupons – Displays coupons assigned to the customer.
• Customer Details – Provides a breakdown of points (spendable, spent, pending, reserved, expired) and tier-specific details if the Tiers module is configured.
• Customer Rewards – Shows available rewards for the customer to claim (configured in the Rewards module).
• Product Points – Displays points that can be earned by purchasing specific products (this widget can only be added to product pages).

Adding widgets to your storefront

To add a widget to your Shopify storefront, follow these steps:

• Navigate to Themes:
  • Go to the Online store admin panel.
  • Navigate to Themes, then click Customize.
• Customize the theme:
  • In the theme editor, go to the page where you want to add the widget (e.g., Customer account or Product page).
• Add the widget block or section:
  • Under Templates, click Add block or Add section (based on your preference).
  • Navigate to the Apps tab to select the widget you want to add.

📘

Note

Widget content is only visible in the editor if you are logged in as a user through the Customer login page.

• Save your changes:
  • Click Save in the upper right corner of the page to ensure the widget is visible on the selected page.

Widget settings

Under the Widget settings tab, you can configure which point accounts and tier structures are displayed for customers, and customize the widget design.

• In your Shopify store admin panel, go to Apps > Antavo Loyalty Cloud > Widget Settings.
• Account configuration
  Select the point account (configured in the Multi-accounts module) that should be considered when displaying information in the widgets.
• Tier structure configuration
  Select the tier structure that should be considered when displaying the customer's current tier status and points required to reach the next tier in the Customer Details widget. This is available only if the Tiers module is enabled.
• Customize widget appearance:
  • Button styling: Set the colors for CTA buttons (background, hover background, and button text).
  • Color: Set the background color and text color.
  • Border: Adjust the border width and radius using the slider, and select a color for the widget border.
  • Branding: Use the slider to set the padding between the widget content and the border.

📘

Note

Color codes can be entered in HSL or hexadecimal format.

• Click Submit at the bottom of the page to save settings.

After logging into the store, customers can see the widgets you’ve configured based on the settings applied. Images displayed in the widgets are sourced from the Antavo Management UI module configuration pages, where they are uploaded.

📘

Note

For further customization, you can edit the theme code directly to tailor additional aspects of your store’s appearance.