> 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](/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 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 %}
```
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
```
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 |
| `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 |
***
## 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. Use it in the pre-registration in Violet (Step 8), 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](/ecom-platforms/shopify/troubleshooting-faqs.md).
{% endhint %}
***
## 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 26 API scopes selected
* [ ] 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](/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
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=&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.