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

# Shopify

> Keep your storefront up-to-date with the latest customer and product info from your data warehouse

> [!NOTE]
>
> Shopify will be [deprecating their REST
> API](https://shopify.dev/docs/apps/build/graphql/migrate) and recommends their
> new [GraphQL API](https://shopify.dev/docs/api/admin-graphql). Hightouch
> supports using these new GraphQL endpoints for new syncs, and existing syncs
> can be updated to use the GraphQL endpoints.

## Overview

This destination lets you send customer, product, and fulfillment information from your data warehouse to Shopify so you never have to worry about stale inventory information or incorrect customer or product details.

## GraphQL vs REST API

Shopify will be deprecating their REST API in favor of their new GraphQL API. For more detailed information on this update, and how object types and inputs have changed, refer to this [Shopify resource](https://shopify.dev/docs/apps/build/graphql/migrate). Hightouch allows syncs to use either protocol for the time being, and you can change between the two protocols to see the differences between them. Most notably, the GraphQL endpoints use new object types **Product Variant** and **Product Option** that were previously coupled together for the REST API. They are now separate Object types to sync to based on existing **Products** in your shop.

## Supported syncing

| Sync type | Description | Supported sync modes | API reference |
| - | - | - | - |
| [**Objects**](#objects) | Sync data from any source to customer, discount, inventory item, inventory level, and product objects | Varies depending on object | [GraphQL Admin API ↗](https://shopify.dev/docs/api/admin-graphql) |
| [**Events**](#events) | Send fulfillment events to Shopify | Insert | [Create fulfillment event ↗](https://shopify.dev/docs/api/admin-rest/2024-01/resources/fulfillmentevent#post-orders-order-id-fulfillments-fulfillment-id-events) |
| [**Actions**](#actions) | Sync data from any source to various Shopify actions | Insert | [Fulfillment order actions ↗](https://shopify.dev/docs/api/admin-graphql/2024-01/mutations/fulfillmentOrderCancel) |

## Connect to Shopify

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button. Select **Shopify**.

To connect your Hightouch app to Shopify, you need to create a **custom app** in your Shopify account.

> [!NOTE]
>
> Shopify requires that custom apps made after January 1, 2026 be authenticated
> to using **Client credentials**. Custom apps made before January 1, 2026 can
> be authenticated to using an **Admin API access token**. If you are creating a
> new custom app, please use the Client credentials flow. If you have an
> existing custom app, you may use the Admin API access token flow.

You then need to provide your **Store name** and either the set of **Client credentials** or an **Admin API access token** of your custom app.

### Create Client credentials for your custom app

1. In your Shopify store's home page, click **Apps** on the sidebar.

   ![Creating an app in the Shopify home page](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-home-page-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d03347aa7d9334009f0df95ac0113edf)

2. Click on **Develop apps** and then select **Build apps in Dev Dashboard**.

   ![Develop apps button in Shopify](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-develop-apps.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=712cf204e0dfc879502d551c76e6e5fa)

   ![Build apps in Dev Dashboard button in Shopify](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-dev-dashboard-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e905679bf94f6c9c242acf4334e39991)

3. Click **Create app** and go through the flow using the **Start from Dev Dashboard** option.

   ![Shopify apps page](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-apps-page.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a2bca7130506a0652132aee145a6d79a)

   ![Shopify create an app page](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-create-an-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7539006aeaa59f7b623ab969b57bab5d)

4. Add to the **Access > Scopes** section the scopes:

```
write_customers,
read_customers,
write_discounts,
read_discounts,
write_inventory,
read_inventory,
write_price_rules,
read_price_rules,
write_products,
read_products,
read_locations,
write_assigned_fulfillment_orders,
read_assigned_fulfillment_orders,
write_merchant_managed_fulfillment_orders,
read_merchant_managed_fulfillment_orders,
write_fulfillments,
read_fulfillments,
write_orders,
read_orders
```

5. Click **Release** and under the **Settings** tab you will find your **Client ID** and **Client secret**.

   ![Shopify Custom app client credentials](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-custom-app-client-credentials.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b834561bf76fd435bcc7a255a3f48678)

### Create an Admin API access token for your custom app

1. In your Shopify store's admin, click **Apps** in the left sidebar.
2. From the dropdown which appears, select **Apps and sales channel settings**.

![Creating an app in the Shopify admin](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-add-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a956fe5373ffa02385bc0a05ae735913)

3. Click **Develop apps for your store**.
4. On the next screen, click **Create an App** in the top right corner. Give it a descriptive name, for example, "Hightouch integration." Then click **Create app**.
5. Under **Configuration** tab, select **Configure** to configure the Admin API Integration.

![Configuring an Admin API token](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-configure.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1d257464608e02a08522c0101671d5b1)

6. Select the following **Admin API access scopes**:
   * `write_customers`
   * `read_customers`
   * `write_discounts`
   * `read_discounts`
   * `write_inventory`
   * `read_inventory`
   * `write_price_rules`
   * `read_price_rules`
   * `write_products`
   * `read_products`
   * `read_locations`
   * `write_assigned_fulfillment_orders`
   * `read_assigned_fulfillment_orders`
   * `write_merchant_managed_fulfillment_orders`
   * `read_merchant_managed_fulfillment_orders`
   * `write_fulfillments`
   * `read_fulfillments`
   * `write_orders`
   * `read_orders`

     ![Required scopes in the Shopify Admin](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-shopify-api-access-scopes.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d36cbe65a8842984fae2c71122267356)
7. Click **Save** in the bottom right of the screen.
8. In **API Credentials** tab, click **Install app**, and then **Install** in the modal that appears.
9. Your **Admin API Access Token** is now available. Copy and save your Admin API access token in a secure place.

## Sync configuration

Once you've set up your Shopify destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the Shopify destination you want to sync to.

### Objects

Hightouch supports syncing to these Shopify objects with the following sync modes:

| Sync Type | Supported Sync Modes |
| - | - |
| **Customers** | Upsert, Update, and Insert |
| **Discounts** | Update and Insert |
| **Inventory Item** | Update only |
| **Inventory Level** (REST API only) | Upsert, Update, and Insert |
| **Products** | Upsert, Update, and Insert |

Check out the [sync modes docs](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) to learn more.

#### Record matching

Based on the Shopify object, database records can be matched from your source to your Shopify workspace by a unique property.

| Sync Type | Supported Identifiers |
| - | - |
| **Customers** | Email, ID, or phone |
| **Discounts** | ID |
| **Inventory Item** | Inventory item ID |
| **Inventory Level** | Inventory item ID |
| **Products** | Handle |

#### Field mapping

You can sync columns from your source to Shopify's default and custom fields.

> [!TIP]
>
> You must provide a **Price Rule ID** from an existing **PriceRule** when
> syncing **Discounts**. Similarly, you must provide an **Inventory Item ID**
> from an existing **Product** when syncing either **Inventory Item** or
> **Inventory Level**.

#### Delete behavior

For **Products** (for the **REST API** protocol only), you can choose what Hightouch's behavior is when a record leaves the query result set.

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the product in your shop |
| **Delete the Shopify product** | Remove the product from your shop |

### Events

Hightouch supports syncing to these Shopify events with the following sync modes:

| Sync Type | Supported Sync Modes |
| - | - |
| **Fulfillment event** | Insert only |

> [!WARNING]
>
> To ensure syncs send each event, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-syncs) documentation for more information.

#### Field mapping

You need to include at least the **Fulfillment ID**, **Order ID**, and **Status** in your sync. Other field mappings are optional.

### Actions

Hightouch supports syncing to these Shopify events with the following sync modes:

| Sync Type | Supported Sync Modes |
| - | - |
| **Cancel fulfillment orders** | Insert only |
| **Mark fulfillment orders as incomplete** | Insert only |
| **Apply fulfillment hold on fulfillment orders with status `Open`** | Insert only |
| **Move fulfillment orders to another location** | Insert only |
| **Mark fulfillment orders as open** | Insert only |
| **Release the fulfillment hold on fulfillment orders** | Insert only |
| **Reschedule the time of scheduled fulfillment orders** | Insert only |

> [!WARNING]
>
> To ensure syncs send each action, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-syncs) documentation for more information.

#### Field mapping

Each action requires you to include at least the **Fulfillment Order ID**. Some actions require additional fields:

| Action | Additional required fields |
| - | - |
| **Apply fulfillment hold on fulfillment orders with status `Open`** | Reason |
| **Move fulfillment orders to another location** | New Location ID |
| **Reschedule the time of scheduled fulfillment orders** | New Fulfill At |

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

> [!NOTE]
>
> For Hightouch platform error codes related to destinations, see [Error
> codes](https://docs.hightouch.com/developer-tools/error-codes.md#other-destinations).

### Validate your setup

After you configure your sync, run a test to confirm data flows correctly:

1. Start with a small test audience or a single record.
2. Trigger a manual sync from the [Syncs overview](https://app.hightouch.com/syncs?from=docs) page.
3. After the sync completes, verify the data in Shopify:
   * For customer syncs, go to **Customers** in Shopify Admin and search for the test customer. Confirm that the mapped fields appear with the expected values.
   * For product syncs, go to **Products** and verify the synced product attributes.
4. If the sync shows errors, check the sync run log in Hightouch for specific API error messages.

### Tag sync behavior

When syncing tags to Shopify, Hightouch replaces the entire tag list on the resource with the tags in your sync payload. This means that if you sync a single tag, any existing tags not included in the payload are removed. To preserve existing tags, include all desired tags in your model's tag column — not just the new ones you want to add.

### Variants field formatting

When syncing product variants, the **Variants** field expects an array of objects. In your model, ensure the column is cast to the **Object/Array** data type — not **String**. Each object in the array represents a single variant.

For example, the column value should look like:

```json theme={null}
[
  { "option1": "Red", "option2": "Small", "price": "19.99", "sku": "RED-SM" },
  { "option1": "Blue", "option2": "Large", "price": "24.99", "sku": "BLU-LG" }
]
```

If the column is a string, cast it to **Object/Array** in your [model configuration](https://docs.hightouch.com/models/data-types-casting.md#casting-from-your-model-configuration), or use your warehouse's JSON functions to construct the array in your SQL model.