Set up the Shopify app 

This guide describes how to set up the Talon.One Shopify app for use with your Shopify store.

Basic setup

1

Prerequisites

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.
• Discounts are managed in Talon.One and not synchronized to Shopify. They are applied and displayed in the storefront, but won't appear in the Discounts section of the Shopify admin.
• 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.

• 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 and product variant metafields 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 following applies:
     • Only product variant metafields are supported.
     • 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 Confirm and 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 Confirm and 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

Configure transaction data sync

1. In Shopify, open Apps > Talon One > Transaction data sync.
2. In Transaction Attributes, select the cart, checkout, and order attributes you want to sync across Shopify and Talon.One.
   Note

   • Attributes that don't exist in Talon.One are created automatically on save.
   • All of these attributes are created as session attributes in Talon.One, so they are part of the customer session.
   • The Cart, Checkout, and Order columns show which stages an attribute is populated in. For example, order_name is only populated once the order is placed, while shop_domain is populated from the cart stage onwards. Shared indicates that the attribute is populated in all stages.
   • Discount campaigns may not be able to reliably use attributes that only become available at the checkout or order stage. For example, if a campaign depends on channel, the discount function runs before the checkout webhook is processed, so the channel session attribute isn't available yet.
3. Click Confirm and save.

7

Enable the app embed

This step is only required for theme-based stores.

Enabling the Loyalty sync app embed allows you to retrieve customer data from Talon.One for use in Shopify.

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 Edit theme.
4. On the left side of the header, click App embeds.
5. Next to the loyalty-sync app embed, click the toggle button.
6. Click Save.

For more information, see our tutorial.

8

Enable POS support

This step is only required if you use Shopify POS (Point of Sale).

1. Ensure you have an existing POS sales channel in Shopify.
2. In Shopify, open Sales channels > Point of Sale > Settings.
3. In the General section, click POS apps.
4. Click Talon.One POS integration.
5. Next to Smart grid tile, click Add.

A Talon.One tile automatically displays in the smart grid of your POS app. Also, within the cart, the session ID is shown along with any discounts that apply to the transaction.

Considerations when using the POS integration

• In the POS app, if users remove all cart items individually, the current session remains active in Talon.One and receives updates. However, if users remove all items at once by clicking the delete button at the top right of the cart page, a new empty session is created in Talon.One, and the previous session is abandoned.
• Custom sale items are synced with Talon.One, but their SKU is null.
• The Talon.One POS integration currently does not support exchanges.
• If a customer is added to an order after it is completed, this data is not synced with Talon.One.
• A customer can be removed from an open or closed order. If the order is open, subsequent session updates no longer include the customer ID, but the customer remains linked to the session in Talon.One. If the order is closed, no data is synced.
• If a customer is changed for a closed order, the profile ID change is not synced with Talon.One.
• Saving and retrieving a cart has the following implications:
  • When saving a cart, users can link a customer to the cart, but the customer is not synced with the Talon.One session. Also, when retrieving the saved cart, Talon.One discounts are not visible in the app interface.
  • However, once the user proceeds to checkout and completes the order, the session data will include the discounts and the linked customer ID.
  • Saving or retrieving a cart does not trigger any events in Talon.One.

9

Configure custom error messages

By default, Shopify shows its own standard error messages when a customer enters an invalid discount code. You can configure the app to show custom messages instead, based on the error code returned by Talon.One.

1. In Shopify, open Apps > Talon One > Custom error messages.

2. Select Enable custom error messages.

3. In Accept all discount codes, configure whether to accept discount codes from Talon.One, Shopify, and third-party coupon providers, or only Talon.One codes. The following table shows how codes are handled in each case.

   Code	Option enabled	Option disabled
   Valid Talon.One code	Accepted	Accepted
   Valid Shopify or third-party code	Accepted	Rejected, custom CouponNotFound message or fallback message shown
   Invalid Talon.One code	Rejected, custom error message shown	Rejected, custom error message shown
   Invalid Shopify or third-party code	Rejected, standard Shopify error message shown	Rejected, custom CouponNotFound message or fallback message shown

   Note

   If Accept all discount codes is enabled, coupon validation occurs after the customer enters a shipping address, which is the standard Shopify behavior. If disabled, validation occurs directly at checkout.

4. In Fallback generic message, type the message to show when a specific message field is left blank, or when Talon.One returns an unknown error code.

5. For each error code you want to customize, in Custom error message, type the message to show to customers for that error code.

6. Click Confirm and save.

10

Enable Markets support

This step is only required if you use Shopify Markets to sell in multiple countries or regions.

1. In Shopify, open Apps > Talon One > Markets.
2. Click Enable Shopify Markets.
3. Click Save.

When Shopify Markets support is enabled for the first time, the Talon.One Shopify app creates the following attributes in Talon.One:

API name	Type	Entity	Format
shopify_market_country	String	Customer Session	Two-letter country code following ISO 3166-1 alpha-2, for example, US or AR.
shopify_market_currency	String	Customer Session	Three-letter currency code following ISO 4217, for example, USD or ARS.

Considerations when using Shopify Markets

• Shopify determines the customer's country once they enter their shipping address. As a result, shopify_market_country is only populated at checkout, not at the cart stage. shopify_market_currency is populated from the cart stage onwards.
• For merchants selling digital goods that don't require a shipping address, shopify_market_country is never populated.

For more information, see our tutorial.

11

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.