> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up the Shopify extension

> Install the Omneo Shopify app and configure Omneo Profile, order, and product sync.

Install the Omneo Shopify app, then configure it to sync profiles, orders, and products between Shopify and Omneo.

## Before you start

You need access to your Omneo CX Manager instance at `{tenant}.manager.getomneo.com` and admin access to the Shopify store you want to connect.

## Install the Shopify app

<Steps>
  <Step title="Open the Omneo CX listing">
    Go to [apps.shopify.com/omneo-cx](https://apps.shopify.com/omneo-cx) in the Shopify App Store.
  </Step>

  <Step title="Install the app">
    Select **Install** and choose the storefront you want to connect to Omneo.
  </Step>

  <Step title="Approve the Shopify permissions">
    Approve the requested permissions to finish installation. The app appears under **Apps** in your Shopify admin once installed.
  </Step>
</Steps>

<Info>
  All data sync settings are enabled by default after installation. You do not need to turn anything on to start syncing profiles, orders, and products between Shopify and Omneo.
</Info>

## Disable data sync (optional)

Data sync can be turned off during setup or at any time afterwards. There are two independent controls, one on each side:

| Direction        | Where to disable                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| Shopify to Omneo | In the Omneo CX Shopify app, go to **Settings → General** and disable the Shopify webhooks back to Omneo. |
| Omneo to Shopify | In Omneo CX Manager, go to **Settings → Webhooks** and disable the `shopify-{tenant}` webhooks.           |

Disable both sides to fully pause sync. Disable one side to pause only that direction.

## Configure sync settings

Configure the following settings in the Shopify extension after installation.

### Profile sync settings

| Setting             | Description                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Identity Handle** | The Omneo identity handle used to link Omneo Profiles to Shopify Accounts (default: `shopify`). Do not change this after Profiles have started syncing. |
| **Tag Whitelist**   | Only tags in this list are synced from Shopify to Omneo.                                                                                                |
| **Tag Prefix**      | Prefix applied to Omneo tags when synced to Shopify (default: `cx-`).                                                                                   |
| **Field Mapping**   | Override the default field mapping between Omneo Profile fields and Shopify Account fields.                                                             |

### Order and transaction sync

Configure the **Transaction Order Status** threshold to the order status at which you consider a Shopify order complete (e.g. `fulfilled`, `paid`). Orders reaching this status are created as Transactions in Omneo.

### Product sync

Configure **Product Sync Level** as `Header` (default, recommended) or `Variant` depending on how your product data is structured.

#### Field mapping

Product fields are mapped from Shopify to Omneo using a configurable mapping. Each mapped field has a **format** that determines how its value is resolved:

| Format       | Behaviour                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| **Direct**   | Copies the source Shopify field value straight onto the Omneo field.                                           |
| **Template** | Resolves the field value from a Handlebars template that can reference any field on the Shopify source object. |

#### Template format

When a mapping uses the **Template** format, the value is rendered with [Handlebars](https://handlebarsjs.com/). You can use standard Handlebars syntax (variables, `{{#if}}`/`{{else}}`, partials, built-in helpers) together with two custom helpers provided by the extension:

| Helper | Purpose                                                                |
| ------ | ---------------------------------------------------------------------- |
| `eq`   | Returns `true` when both arguments are strictly equal (`a === b`).     |
| `ne`   | Returns `true` when both arguments are not strictly equal (`a !== b`). |

These helpers let you build conditional mappings. For example, a variant title template can fall back to the parent product title when the variant title matches the product title, and otherwise combine the two with a separator — all expressed as a single Handlebars `if` block using the `eq` helper against `title` and `product.title`.

Template format is available on every template-capable field in the product mapping.

#### Variant title handling

When mapping a variant title from Shopify to Omneo, Omneo treats Shopify's default variant title of `Default Title` as a placeholder and uses the parent **product title** instead. This avoids variants being labelled `Default Title` in Omneo for products that have no real variants in Shopify.

<Note>
  For front-end authentication from Shopify Liquid themes or App UI Extensions, see [Shopify Authentication](/extensions/shopify/authentication).
</Note>