Integrating with Shopify

Talon.One supports integrating with Shopify using a dedicated app.

Shopify integration features

The Talon.One Shopify app enables real-time data synchronization between Shopify and Talon.One.

By creating a bidirectional data flow, the integration enables store owners to do the following:

• Sync product data and customer profiles with Talon.One, for example, to create personalized coupons or award loyalty points.
• Send customer session data, including the customer's shopping cart.
• Receive customer data from Talon.One, for example, the number of loyalty points awarded.
• Receive strikethrough pricing updates from Talon.One.
• Receive discount effects in Shopify and apply them to the shopping cart.

Understanding the data flow

From Shopify to Talon.One

Product data

When you connect the app to a cart item catalog in Talon.One, it performs an initial product sync.

The app calls the Sync cart item catalog endpoint to add all products in Shopify to a cart item catalog in Talon.One.

note

• To re-trigger the product sync:

  1. On the Product data sync page, note the value in the Catalog ID field.
  2. Replace the value with 0, and click Save.
  3. Restore the previous value in the Catalog ID field, and click Save.

• When synchronizing SKUs between Shopify and Talon.One, the following applies:

  • The sku field in Talon.One is populated with the variant ID from Shopify.
  • The SKUs in Shopify are stored in a separate sku_shopify field in Talon.One.

  This is because SKUs can be empty or duplicate in Shopify, but must be unique in Talon.One.

The app does not delete any data, but replaces existing products with the same variant ID.

Then, whenever a product is created, updated, or deleted in Shopify, the app calls the same endpoint to update the cart item catalog.

If any of the product data operations trigger strikethrough pricing updates, Talon.One returns the effects of these updates to Shopify.

Customer profile data

When a customer profile is created or updated in Shopify, the app calls the Update customer profile endpoint to send customer data to Talon.One.

Also, when a customer completes their order, the profile of that customer is created or updated.

The app only sends the following customer data:

• The customer ID, which is stored as the customer integration ID in Talon.One.
• The tags associated with the customer, which are stored as a custom attribute named tags in Talon.One.

Customer session data

When a customer adds items to their shopping cart, the app calls the Update customer session endpoint to create or update a session in Talon.One. The state of the session is open, and the session ID is equal to the cart ID in Shopify. When a customer updates their cart, the app calls the same endpoint to update the session with the new cart data.

The response from the endpoint may contain discount effects that will be applied at checkout.

When a customer completes their order, the session is updated, and its state changes to closed.

When a return is initiated, the session state changes to cancelled (for fully returned orders) or partially returned (for partially returned orders).

From Talon.One to Shopify

Customer data

Theme-based stores

For theme-based stores, an app embed is used to fetch customer data.

Whenever a signed-in customer is accessing a page of your store, for example, a product page, the app embed calls the Retrieve customer data endpoint to fetch data of that customer from Talon.One.

note

To reduce data load, the app embed fetches data only once every 10 seconds.

The app embed always fetches all available customer data, including customer profile, referral, coupon, loyalty, giveaway, and achievement information. For example, the data may contain a coupon generated for the customer, and their total number of awarded loyalty points.

The data is stored in a customer metafield in Shopify. To reference it in your template, use the following Liquid code:

{{ customer.metafields.talon_one.data }}

You can also access the metafield data via JavaScript:

const customerData = window.TalonOne.customerProfile;

For more information, see our tutorial.

Headless stores

For headless stores, there's a dedicated Retrieve customer data endpoint to fetch customer data.

It is recommended to call this endpoint whenever a customer signs in, or returns to the site after a period of inactivity.

note

To reduce data load, this endpoint will not fetch data more than once every 10 seconds.

The endpoint always fetches all available customer data, including customer profile, referral, coupon, loyalty, giveaway, and achievement information. For example, the data may contain a coupon generated for the customer, and their total number of awarded loyalty points.

The data is returned as a response to your request, and is also stored in a customer metafield in Shopify.

For more information, see our tutorial.

Strikethrough pricing updates

Whenever the app receives a strikethrough pricing notification from Talon.One, it stores the pricing effects of the notification (changedItems.effects, see schema) in a product variant metafield in Shopify. For example, the pricing effect can be a $10 discount on all shoes in your store.

To reference the metafield in your template, use the following Liquid code:

{{ product.selected_or_first_available_variant.metafields.talon_one.effects }}

For more information, see our tutorial.

Discount effects

When customer session data is created or updated, Talon.One may return discount effects. These effects can include discounts on the order total, individual items, or shipping costs.

The app receives these effects and applies them at checkout in Shopify. For more information, see our applying discounts tutorial.

important

• Discount effects require network access for Shopify Functions, which is available with Shopify for enterprise. Shopify support must explicitly enable network access for Shopify Functions.
• Discounts are applied via the Storefront API using the @defer directive. If a store uses the Ajax API to manage the cart, discounts won't be visible until the customer reaches checkout.
• The Shopify integration only supports case insensitive coupons. In the Application settings, ensure the Case Insensitive, stored in uppercase (recommended) option is selected.
• You cannot apply multiple coupons offering the same type of discount to the same order. For example, you cannot apply two coupons that both offer shipping discounts to the same order.
• If you are using both shipping and order/item discounts, ensure your campaign evaluation order is set up so that shipping discounts are evaluated after order/item discounts.

Basic setup

1

Prerequisites

• You are an administrator user in Shopify.
• You have created a Third-party API key for use with Shopify.
• You have created an additional cost in Talon.One, with the following properties:
  • Scope: Cart (Session)
  • API name: shipping
• If you are using collections, you have created the following custom attribute in Talon.One:
  • Entity: Cart Item
  • Type: List of Strings
  • API name: collections

2

Install the app

1. Find the app in the Shopify App Store.
2. Click Install.
3. In your Shopify admin, to authorize the use of the app, click Install.

After the app is installed, you can view and use it from the Apps page in your Shopify admin.

3

Configure the app

1. In Shopify, open Apps > Talon One.
2. On the Talon.One Integration page, configure the following parameters:
   • API Key: Paste the Third-party API key you created.
   • Deployment URL: Type the base URL of your Talon.One deployment, for example, mycompany.europe-west1.talon.one.
3. To test the connection with the values provided, click Connect.
4. If the test is successful, click Save.

4

Configure product data sync

1. In Shopify, open Apps > Talon One > Product data sync.
2. Leave the Catalog ID option at 0. You'll set the ID when syncing your product inventory.
3. In Standard attributes and Metafields, specify the product attributes you want to sync across Shopify and Talon.One.
   note

   • Required attributes are preselected and cannot be changed.
   • Attributes that don't exist in Talon.One are created automatically on save.
   • The sku attribute is created as sku_shopify in Talon.One.
   • For metafields, the namespace is not included in the Talon.One attribute names. For example, a metafield with the namespace custom and the key color is synced as an attribute named color in Talon.One.
4. Click Save.

5

Configure customer data sync

1. In Shopify, open Apps > Talon One > Customer data sync.
2. In Standard attributes and Metafields, specify the customer attributes you want to sync across Shopify and Talon.One.
   note

   • Attributes that don't exist in Talon.One are created automatically on save.
   • For privacy reasons, some customer attributes are not available for syncing, for example, email or phone number.
   • The metafield namespace is not included in the Talon.One attribute names. For example, a metafield with the namespace custom and the key vip_status is synced as an attribute named vip_status in Talon.One.
3. Click Save.

note

We highly recommend carrying out this step before syncing any customer data. For existing customer data, the following limitations apply:

• Adding attributes does not update existing customer profiles in Talon.One. To apply the changes, you must manually update each existing profile.
• Removing attributes does not remove existing data in Talon.One, even if you manually update customer profiles later.

6

Enable the app embed

This step is only required for theme-based stores.

Enabling the Talon.One customer data app embed allows you to retrieve customer data from Talon.One for use in Shopify. For more information, see our tutorial.

1. Ensure the Talon.One Shopify app is installed.
2. In Shopify, open Online Store > Themes.
3. Find the theme that you want to edit and click Customize.
4. On the leftmost menu, click App embeds.
5. Next to the Talon.One customer data app embed, click the toggle button.
6. Click Save.

7

Next steps

You have completed the basic setup of the Talon.One Shopify app.

To use the app effectively, additional configuration steps are required, based on your specific use cases.

Read our tutorials to learn how to set up the app for your needs.