# Set up the Shopify app

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

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

## Basic setup

<StepsContainer>

### Prerequisites

:::important
- Discount effects require [network access for Shopify Functions](https://shopify.dev/docs/apps/build/functions/input-output/network-access),
  which is available with [Shopify for enterprise](https://www.shopify.com/enterprise).
  Shopify [support](https://help.shopify.com/en/) must explicitly enable network access for Shopify Functions.
- Discounts are applied via the [Storefront API](https://shopify.dev/docs/api/storefront)
  using the [`@defer` directive](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/defer).
  If a store uses the [Ajax API](https://shopify.dev/docs/api/ajax) 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](/docs/product/applications/manage-general-settings#code-case-sensitivity) 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](/docs/product/applications/manage-campaign-evaluation)
  is set up so that shipping discounts are evaluated after order/item discounts.
:::

- You are an [administrator](https://help.shopify.com/en/manual/your-account/staff-accounts/staff-roles/staff-roles-descriptions)
  user in Shopify.
- You have created a [Third-party API key](/docs/product/applications/manage-third-party-api-keys.md#create-a-third-party-api-key)
  for use with Shopify.
- You have created an [additional cost](/docs/product/account/dev-tools/manage-additional-costs.md#create-an-additional-cost)
  in Talon.One, with the following properties:
  - **Scope**: `Cart (Session)`
  - **API name**: `shipping`
- If you are using [collections][collections], you have created the following [custom attribute](/docs/product/account/dev-tools/manage-attributes.md#create-a-custom-attribute)
  in Talon.One:
  - **Entity**: Cart Item
  - **Type**: List of Strings
  - **API name**: `collections`

### Install the app

1. Find the app in the [Shopify App Store](https://apps.shopify.com/talon-one).
1. Click **Install**.
1. 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.

### Configure the app

1. In Shopify, open **Apps > Talon One**.
1. On the **Talon.One Integration** page, configure the following parameters:
   - **API Key**: Paste the Third-party API key you [created](/docs/product/applications/manage-third-party-api-keys.md#create-a-third-party-api-key).
   - **Deployment URL**: Type the base URL of your Talon.One deployment, for example,
     `mycompany.europe-west1.talon.one`.
1. To test the connection with the values provided, click **Connect**.
1. If the test is successful, click **Save**.

### Configure product data sync

1. In Shopify, open **Apps > Talon One > Product data sync**.
1. Leave the **Catalog ID** option at `0`. You'll set the ID when [syncing your product inventory](/docs/dev/technology-partners/shopify/sync-inventory-shopify).
1. 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.
   :::
1. Click **Save**.

### Configure customer data sync

1. In Shopify, open **Apps > Talon One > Customer data sync**.
1. 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.
   :::
1. 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.
:::

### Enable the app embed

This step is only required for [theme-based](https://shopify.dev/docs/storefronts/themes)
stores.

Enabling the **Loyalty sync** [app embed](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/apps#app-embeds)
allows you to retrieve customer data from Talon.One for use in Shopify.

1. Ensure the Talon.One Shopify app is [installed](#install-the-app).
1. In Shopify, open **Online Store** > **Themes**.
1. Find the theme that you want to edit and click **Edit theme**.
1. On the leftmost menu, click **App embeds**.
1. Next to the **loyalty-sync** app embed, click the toggle button.
1. Click **Save**.

For more information, see our
[tutorial](/docs/dev/technology-partners/shopify/add-loyalty-points-shopify.md).

### Enable POS support

This step is only required if you use [Shopify POS](https://www.shopify.com/pos) (Point of
Sale).

1. Ensure you have an existing POS [sales
   channel](https://help.shopify.com/en/manual/online-sales-channels/manage) in Shopify.
1. In Shopify, open **Sales channels > Point of Sale > Settings**.
1. In the **General** section, click **POS apps**.
1. Click **Talon.One POS integration**.
1. 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.

<details>
  <summary>**Considerations when using the POS integration**</summary>
  - 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](https://help.shopify.com/en/manual/sell-in-person/shopify-pos/order-management/custom-sales)
    are synced with Talon.One, but their SKU is `null`.
  - The Talon.One POS integration currently does not support [exchanges](https://help.shopify.com/en/manual/sell-in-person/shopify-pos/order-management/exchange).
  - 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](https://help.shopify.com/en/manual/sell-in-person/shopify-pos/order-management/save-retrieve-order)
    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.
</details>

### Enable Markets support

This step is only required if you use [Shopify
Markets](https://help.shopify.com/en/manual/markets) to sell in multiple countries or
regions.

1. In Shopify, open **Apps > Talon One > Markets**.
1. Click **Enable Shopify Markets**.
1. 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), for example, `US` or `AR`. |
| `shopify_market_currency` | String | Customer Session | Three-letter currency code following [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217), for example, `USD` or `ARS`.                |

<details>
  <summary>**Considerations when using Shopify Markets**</summary>
  - 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.
</details>

For more information, see our [tutorial](/docs/dev/technology-partners/shopify/apply-market-discounts-shopify.md).

### 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](/docs/dev/technology-partners/shopify.md#shopify-tutorials) to learn
how to set up the app for your needs.

</StepsContainer>

[collections]: /docs/dev/technology-partners/shopify/sync-inventory-shopify#considerations-when-syncing-collections