> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/ecom-platforms/shopify/shopify-app-setup.md).

# Shopify App Setup

This guide walks through creating a custom app in Shopify Partner Dashboard for a merchant you want to onboard.

{% hint style="info" %}
**Don't have a Shopify Partner account?** You'll need one before proceeding. See [Prerequisites](https://docs.violet.io/ecom-platforms/shopify/prerequisites.md#1-shopify-partner-account) or visit [shopify.com/partners](https://www.shopify.com/partners) to sign up (free).
{% endhint %}

***

## Step 1: Open Shopify Partner Dashboard

Go to [partners.shopify.com](https://partners.shopify.com) and log in.

![Shopify Partners Dashboard](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-6fc0cd3f7268170226d65d6d5c22ae547cab3db5%2Fshopify-partners-dash.png?alt=media\&token=fb03a9c7-70c2-43fa-96c0-d2b46d4ec21d)

***

## Step 2: Navigate to Apps

Click **Apps** in the left sidebar, then click **Create app**.

![Shopify Dev Dashboard](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-845447fa9d6b17bdf89445680012ff0af74309df%2Fshopify-dev-dash.png?alt=media\&token=6c22e88a-b31a-4486-83ec-483346f71424)

***

## Step 3: Select Custom App

When prompted, select **Custom app** (also called "single-merchant app").

***

## Step 4: Configure the App

{% hint style="danger" %}
**Critical: Must uncheck "Embed app in Shopify admin"**

For a smoother merchant onboarding experience, uncheck the "Embed app in Shopify admin" option (it's checked by default). If left checked, merchants will need to manually re-navigate to Violet Connect via the link you provide them after installing the app, instead of being redirected automatically.

See [Send the Violet Connect Link](https://docs.violet.io/ecom-platforms/shopify/pre-registration.md#send-the-violet-connect-link) for more details on the merchant onboarding flow.
{% endhint %}

![Shopify App Creation](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-b2058c17ddb9ec955b5ce96dc80ae2c1687abffe%2Fshopify-create-app.png?alt=media\&token=976c26f0-0adf-4467-bde0-6d2f099e26eb)

### App Name

This helps you identify which app belongs to which merchant when managing multiple apps. Use a descriptive name that identifies both your channel and the merchant:

* Example: `YourChannel - Merchant Store Name`

### App URL

{% hint style="danger" %}
**Critical: Must use Violet's domain**

The App URL must be set to Violet's domain with your App Alias:
{% endhint %}

| Mode          | App URL                                       |
| ------------- | --------------------------------------------- |
| **Live Mode** | `https://connect.violet.io/{YOUR_APP_ALIAS}`  |
| **Test Mode** | `https://connect.violet.dev/{YOUR_APP_ALIAS}` |

{% hint style="danger" %}
**Example:** If your App Alias is `acme-shopping`, your Live Mode App URL is: `https://connect.violet.io/acme-shopping`

**Why this matters:** Shopify requires the App URL and Redirect URI to share the same host. Using your own domain causes a **404 error** during OAuth.

**Find your App Alias:** [Channel Dashboard](https://channel.violet.io) → App Settings → Violet Connect
{% endhint %}

### Redirect URI

The Redirect URI must match the App URL host and include the Shopify connect path:

| Mode          | Redirect URI                                                            |
| ------------- | ----------------------------------------------------------------------- |
| **Live Mode** | `https://connect.violet.io/{YOUR_APP_ALIAS}/platforms/shopify/connect`  |
| **Test Mode** | `https://connect.violet.dev/{YOUR_APP_ALIAS}/platforms/shopify/connect` |

**Example:** If your App Alias is `acme-shopping`, your Live Mode Redirect URI is: `https://connect.violet.io/acme-shopping/platforms/shopify/connect`

### Required API Scopes

Select all 26 required API scopes listed below. Missing scopes will cause features to fail after the merchant connects.

{% hint style="warning" %}
**Select all scopes upfront.** Changing scopes later requires the merchant to reinstall the app.
{% endhint %}

Scopes are not the only access Violet needs. Bulk operations are a separate grant that you enable after releasing the app. See [Step 7](#step-7-enable-bulk-operations).

```
read_customers,write_customers,read_locales,read_metaobject_definitions,read_metaobjects,read_price_rules,read_discounts,read_translations,write_draft_orders,read_draft_orders,read_fulfillments,read_inventory,read_legal_policies,read_locations,read_markets,write_merchant_managed_fulfillment_orders,read_orders,write_orders,read_products,read_publications,write_publications,read_returns,read_shipping,unauthenticated_write_checkouts,unauthenticated_read_product_inventory,unauthenticated_read_product_listings
```

<details>

<summary>Click to expand to learn more about the API scopes</summary>

### Products & Inventory

| Scope                         | Purpose                            |
| ----------------------------- | ---------------------------------- |
| `read_products`               | Read product catalog               |
| `read_inventory`              | Read inventory data                |
| `read_locations`              | Read inventory locations           |
| `read_metaobject_definitions` | Read metaobject definitions        |
| `read_metaobjects`            | Read metaobject data               |
| `read_publications`           | Read sales channel publications    |
| `write_publications`          | Publish products to sales channels |
| `read_locales`                | Read store locale data             |
| `read_translations`           | Read translation data              |

### Customers

| Scope             | Purpose                                  |
| ----------------- | ---------------------------------------- |
| `write_customers` | Create customers for non-guest checkouts |
| `read_customers`  | Read customer information                |

### Orders & Checkout

| Scope                                       | Purpose                         |
| ------------------------------------------- | ------------------------------- |
| `write_orders`                              | Create and update orders        |
| `read_orders`                               | Read orders submitted by Violet |
| `write_draft_orders`                        | Populate and submit orders      |
| `read_draft_orders`                         | Read draft order data           |
| `write_merchant_managed_fulfillment_orders` | Flag orders requiring review    |

### Fulfillment & Shipping

| Scope               | Purpose                   |
| ------------------- | ------------------------- |
| `read_fulfillments` | Read fulfillment statuses |
| `read_shipping`     | Read shipping policies    |
| `read_markets`      | Read shipping regions     |

### Pricing & Discounts

| Scope              | Purpose                |
| ------------------ | ---------------------- |
| `read_price_rules` | Read pricing rules     |
| `read_discounts`   | Read discount policies |

### Policies & Returns

| Scope                 | Purpose                     |
| --------------------- | --------------------------- |
| `read_legal_policies` | Read refund/return policies |
| `read_returns`        | Discover returned orders    |

### Cart Operations (Unauthenticated)

| Scope                                    | Purpose                               |
| ---------------------------------------- | ------------------------------------- |
| `unauthenticated_write_checkouts`        | Create carts without rate limits      |
| `unauthenticated_read_product_listings`  | Read product data without rate limits |
| `unauthenticated_read_product_inventory` | Read inventory without rate limits    |

</details>

***

## Step 5: Release your App

This will submit and create your new App.

***

## Step 6: Allow-List Violet IP Addresses

{% hint style="danger" %}
**Critical: Partner-created apps must have an IP allowlist that includes Violet's IP addresses**

Shopify requires an IP allowlist on custom apps that you install on stores outside your own organization, which includes the apps you create for your merchants. Starting November 20, 2026 at 11:59 PM ET, an app must have one before you can install it on a merchant's store. Starting January 1, 2027 at 11:59 PM ET, every app you've already installed on a store outside your organization must have one too, and a single app without one affects your ability to install any app on stores outside your organization, not just that one.

Once **Enforce IP allowlist** is on, Shopify checks the source IP address of every Admin API request made with the app's access tokens and rejects any request from an address that isn't on the allowlist with a `403` status. Violet makes its requests from the addresses below, so add them to the allowlist before you turn enforcement on.
{% endhint %}

1. Open your app in the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard/) and click **Settings**
2. In the **IP allowlist** section, click **Manage**
3. Under **IP addresses or CIDR ranges**, enter the addresses for the environment your app connects to, one per line. Use the [Sandbox IPs](#sandbox-ips-test-mode) if the app uses Test Mode, or the [Production IPs](#production-ips-live-mode) if it uses Live Mode
4. Turn on **Enforce IP allowlist**, then click **Save**

Repeat this for every merchant's app, including apps you created before this step existed. The allowlist belongs to the app, so each app you create needs its own.

### Sandbox IPs (Test Mode)

For apps that use Test Mode (`connect.violet.dev`):

```
52.13.161.135
52.27.63.53
44.226.121.166
```

### Production IPs (Live Mode)

For apps that use Live Mode (`connect.violet.io`):

```
44.235.99.169
44.236.104.65
44.236.6.9
```

See Shopify's [Restrict API access with an IP allowlist](https://shopify.dev/docs/apps/build/dev-dashboard/ip-allowlist) for more on how the allowlist works.

***

## Step 7: Enable Bulk Operations

{% hint style="danger" %}
**Critical: Partner-created apps must enable bulk operations**

Violet's catalog sync reads a merchant's products through Shopify's bulk operations. Shopify requires apps created by a Partner to enable bulk operations before they can use them, and the apps in this guide are Partner-created.

Skip this step and the app still installs with all 26 scopes granted, with no error and nothing in the Violet dashboard to show what is wrong. But Shopify refuses the bulk operation the catalog sync depends on, so the sync fails and the merchant's products stop updating in Violet.
{% endhint %}

1. In the [Shopify Partner Dashboard](https://partners.shopify.com), click **Apps** and select the app you just created
2. In the sidebar, click **API access requests**
3. Under **Run bulk operations**, click **Allow bulk queries**

**Allow bulk queries only.** Violet's catalog sync runs bulk queries and does not run bulk mutations, so you don't need to allow bulk mutations. Repeat this for every merchant's app.

Bulk operations are a separate grant, not an API scope. They aren't one of the 26 scopes in [Step 4](#required-api-scopes), and adding them to that list won't work.

{% hint style="warning" %}
**The grant lapses after 31 days.** Shopify requires an app that hasn't started a bulk query in 31 days to enable bulk queries again. A lapsed app loses bulk access with no warning. Catalog syncs start failing with `Access denied for bulkOperationRunQuery` and the merchant's products stop updating in Violet. Any app that goes quiet for a month can lapse, such as a low-volume or seasonal channel.

To restore access, repeat the steps above. See "Products Are Not Updating" in [Troubleshooting & FAQs](https://docs.violet.io/ecom-platforms/shopify/troubleshooting-faqs.md) for the symptoms and the fix.
{% endhint %}

***

## Step 8: Select Custom Distribution

After creating the app, you must select the distribution method to generate an Install Link.

![Select Distribution Method](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-32b0819decac117194a0a5e2adf147ee47ec403b%2Fselect-distribution-method.png?alt=media\&token=a7ec5521-5081-4ca1-9ed7-588adba27b7a)

Click **"Select custom distribution"** to confirm

{% hint style="warning" %}
**This step is required.** Without selecting "Custom distribution", you cannot generate the Install Link needed for merchant onboarding.
{% endhint %}

![Shopify Custom Distribution Choice](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-a66604ad38284433249fe98a254b3ae078537f1b%2Fshopify-custom-distribution-choice.png?alt=media\&token=2d43107c-84c9-442d-84dc-9052a7b659b1)

***

## Step 9: Add your store domain to generate the Install Link

{% hint style="info" %}
**What is the Install Link?** This is the URL merchants will use to install your custom app in their Shopify admin. Merchants must install the app via this link BEFORE completing Violet Connect onboarding.
{% endhint %}

After selecting custom distribution, add your store domain and select the CTA to generate the link. Upon success, you should see the Distribution page with your **Install Link**.

![Copy Custom Install Link](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-51aef87bd4f02ba25ed76ebb97a8ebc909b9a70c%2Fshopify-copy-custom-install-link.png?alt=media\&token=c0140657-1a62-468f-b83f-c273ddfbaed4)

1. Click the **Copy** button next to the Install Link
2. Use it in the pre-registration in Violet (Step 11), once the merchant is ready to install

The Install Link format should resemble this:

```
https://admin.shopify.com/store/{store}/oauth/install_custom_app?client_id=...
```

{% hint style="warning" %}
**The Install Link expires.** Shopify doesn't document a lifetime, but in practice a link stops working after roughly a week. The expiry is carried inside the link itself, so it isn't guaranteed and can vary from link to link.

Don't create the app and its Install Link weeks ahead of the merchant. Set it up when they are about to onboard, and send them their link soon after. The Client ID and Client Secret stay the same; the Install Link does not.

An expired link fails in Shopify, before any part of Violet's flow runs. The merchant sees `Oauth error invalid_link: This app can't be installed using this link. Contact the app developer for more information.` If you see it, open "Shopify Error: invalid\_link (Install Link Expired)" in [Troubleshooting & FAQs](https://docs.violet.io/ecom-platforms/shopify/troubleshooting-faqs.md).
{% endhint %}

***

## Step 10: Copy Credentials

After creating the app, go to "Settings" in the dev dashboard to reveal the **Client ID** and **Client Secret**. You will need this for the next step.

![Shopify App Credentials](https://2435497985-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZrOgj5n6PuU2r0Ya8Tzl%2Fuploads%2Fgit-blob-a9d789fd73dc33bbd219b3d68cb7086471b9393f%2Fshopify-dev-credentials.png?alt=media\&token=52308372-8262-4800-823d-bf853b4184b2)

***

## Step 11: Create Pre-Registration in Violet

Now that you have your Install Link, Client ID, and Client Secret, go to [Channel Dashboard](https://channel.violet.io) to create a pre-registration for this merchant.

***

## Summary

Before moving on, confirm you have:

* [ ] App URL set to `connect.violet.io/{YOUR_APP_ALIAS}` (or `.violet.dev` for Test Mode)
* [ ] Redirect URI set to `connect.violet.io/{YOUR_APP_ALIAS}/platforms/shopify/connect`
* [ ] All 26 API scopes selected
* [ ] Violet IP addresses allow-listed (**IP allowlist** under app **Settings**, with **Enforce IP allowlist** on)
* [ ] Bulk operations enabled (**Allow bulk queries** under API access requests)
* [ ] Custom distribution selected
* [ ] Install Link copied (it expires, so use it soon)
* [ ] Client ID copied
* [ ] Client Secret copied

Once you have completed all of these items, proceed to [Pre-Registration Process](https://docs.violet.io/ecom-platforms/shopify/pre-registration.md)

***

## Help

Have questions or running into issues? See [Troubleshooting & FAQs](https://docs.violet.io/ecom-platforms/shopify/troubleshooting-faqs.md) for common problems and solutions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/ecom-platforms/shopify/shopify-app-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
