# 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/prerequisites#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)

***

## 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)

***

## 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/pre-registration#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)

### 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 20 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 %}

```
read_customers,write_customers,read_price_rules,read_discounts,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_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 |

#### 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: 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)

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)

***

## Step 6: 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)

1. Click the **Copy** button next to the Install Link
2. Save this link — you'll need it when creating the pre-registration in Violet

The Install Link format should resemble this:

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

***

## Step 7: 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)

***

## Step 8: 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 20 API scopes selected
* [ ] Custom distribution selected
* [ ] Install Link copied
* [ ] 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)

***

## Help

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