# 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](/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.
***
## Step 2: Navigate to Apps
Click **Apps** in the left sidebar, then click **Create app**.
***
## 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](/ecom-platforms/shopify/pre-registration.md#send-the-violet-connect-link) for more details on the merchant onboarding flow.
{% endhint %}
### 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
```
Click to expand to learn more about the API scopes
#### 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 |
***
## 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.
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 %}
***
## 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**.
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.
***
## 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](/ecom-platforms/shopify/pre-registration.md)
***
## Help
Have questions or running into issues? See [Troubleshooting & FAQs](/ecom-platforms/shopify/troubleshooting-faqs.md) for common problems and solutions.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.violet.io/ecom-platforms/shopify/shopify-app-setup.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.