# Troubleshooting & FAQs
## Troubleshooting Common Issues
404 Redirect Error During OAuth
**Problem**: Merchant clicks the installation link and sees a 404 error from Shopify during the OAuth redirect.
**Cause**: The **App URL** in Shopify Partner Dashboard uses a different host than the **Redirect URI**. Shopify requires both URLs to share the same host.
**What went wrong:**
* ❌ App URL: `https://yourcompany.com` + Redirect URI: `https://connect.violet.io/...` → **Hosts don't match**
* ✅ App URL: `https://connect.violet.io/your-alias` + Redirect URI: `https://connect.violet.io/your-alias/...` → **Hosts match**
**Solution:**
1. Go to [Shopify Partner Dashboard](https://partners.shopify.com) → **App Distribution**
2. Navigate to your Custom App → select **View on Dev Dashboard** (far right link)
3. Click **Configuration** (or **App setup**)
4. Update the **App URL** field to:
* **Live Mode**: `https://connect.violet.io/{YOUR_APP_ALIAS}`
* **Test Mode**: `https://connect.violet.dev/{YOUR_APP_ALIAS}`
5. Verify the **Redirect URI** uses the same host as the App URL
6. Save changes
7. Have the merchant retry the installation link
**Finding Your App Alias:** [Channel Dashboard](https://channel.violet.io) → App Settings → Violet Connect
**Prevention:** See [Shopify App Setup](/ecom-platforms/shopify/shopify-app-setup.md#app-url) for correct configuration.
Install Link Missing or Invalid
**Problem**: Cannot find the Install Link in Shopify Partner Dashboard, or the Install Link field shows an error in Violet pre-registration.
**Cause**: Custom distribution was not selected for the app.
**Solution:**
1. Go to [Shopify Partner Dashboard](https://partners.shopify.com) → **App Distribution** → Your Custom App
2. Look for the **Distribution** section on the app overview page
3. Click **"Select distribution method"**
4. Choose **"Custom distribution"** and confirm
5. After selection, you'll see the Distribution page with the Install Link
6. Copy the Install Link and use it in your Violet pre-registration
**Prevention:** Always select "Custom distribution" immediately after creating your custom app. See [Shopify App Setup - Step 5](/ecom-platforms/shopify/shopify-app-setup.md#step-5-select-custom-distribution).
Merchant Clicked Violet Connect Before Installing App
**Problem**: Merchant clicked the Violet Connect link but sees an error because the app isn't installed.
**Cause**: The merchant needs to install the custom app via the Shopify Install Link BEFORE using Violet Connect.
**Solution:**
1. Ask the merchant to close the Violet Connect page
2. Send them the **Shopify Install Link** (Channel Dashboard → Pre-Registered → Actions → Copy Shopify Install Link)
3. Have them click the Install Link and complete app installation in Shopify admin
4. After installation is confirmed, send them the Violet Connect link again
5. They should now be able to complete onboarding successfully
**Prevention:** Always send the Shopify Install Link first and confirm the merchant has installed the app before sending the Violet Connect link.
Wrong Store URL
**Problem**: Merchant reports the Violet Connect link shows the wrong store name/URL.
**Cause**: Store URL was entered incorrectly during pre-registration.
**Solution**:
1. Delete the incorrect pre-registration (Actions menu → Delete)
2. Create a new pre-registration with the correct store URL
3. Copy and send the new Violet Connect link to merchant
Permission Errors - Features Don't Work
**Problem**: Merchant completes installation but features don't work (products missing, shipping rates not calculating, etc.)
**Cause**: Missing API scopes in the custom app configuration.
**Solution**:
1. Go to [Shopify Partner Dashboard](https://partners.shopify.com) → **App Distribution**
2. Navigate to your Custom App → select **View on Dev Dashboard** (far right link)
3. Check Configuration tab → Admin API access scopes
4. Add missing scopes from [Prerequisites](/ecom-platforms/shopify/prerequisites.md) section
5. Update pre-registration: Actions menu → Edit
6. Have merchant use new link and reinstall
Missing Credentials from Shopify Partner Dashboard
**Problem**: Can't pre-register merchant because you don't have credentials.
**Cause**: Haven't completed prerequisites in Shopify Partner Dashboard.
**Solution**:
1. Review the [Prerequisites](/ecom-platforms/shopify/prerequisites.md) section
2. Log in to [Shopify Partner Dashboard](https://partners.shopify.com)
3. Create custom app for this merchant
4. Configure required API scopes
5. Generate and copy credentials
6. Return to Channel Dashboard to pre-register
Merchant Already Connected
**Problem**: Merchant tries to connect but sees "store already connected" error.
**Cause**: This store is already connected to your channel (check "Connected Merchants" tab).
**Solution**:
* If merchant needs a fresh connection, delete the existing connection first
* Create a new pre-registration
* Send new link to merchant
***
## Frequently Asked Questions
### Migration & Timeline
Do we need to migrate all existing custom apps immediately?
**No.** Existing merchant-created custom apps continue working indefinitely. Only migrate when you need to:
* Change permissions
* Rotate credentials
* Set up a new merchant
Can merchants still access their existing custom apps?
**Yes.** They can view them in Settings > Apps and sales channels, and they can uninstall them if needed. They just can't create new ones after January 1, 2026.
What happens to my old Shopify integrations?
**Old integrations**: Merchants connected before January 2026 will continue to work as-is. No changes needed for existing merchants.
**New onboarding**: All new merchants must follow the pre-registration process in this guide.
Why did Shopify require this change?
Shopify deprecated the previous channel-controlled custom app model to give merchants better security and control. With single-merchant custom apps:
* Each merchant owns their app and credentials
* Merchants can revoke access at any time
* Merchants have full visibility into API permissions
* Better audit trail for data access
* Merchants have full control over their integrations
### Permissions & Scopes
What if a merchant needs additional permissions?
You must create a new single-merchant app with the expanded permissions and send them a new installation link. The old app will continue working until they're ready to switch.
Permission changes require:
1. Update the custom app in Shopify Partner Dashboard to include additional scopes
2. Create a new pre-registration with the updated credentials
3. Have merchant reinstall using the new link
Do we need to update our API version?
Not necessarily. Single-merchant apps work with any stable API version. However, it's good practice to use recent versions (2025-10 or later).
### App Management
Can one single-merchant app be installed on multiple stores?
**No.** Each single-merchant app is designed for exactly one merchant. You need to create separate apps for each merchant, even if they're owned by the same company.
How do we handle merchants who create new stores after January 1, 2026?
You'll need to create a new single-merchant app and send them the installation link for each new store.
Can we automate app creation via API?
Shopify doesn't currently provide an API to create single-merchant apps programmatically. You must create them through the Partner dashboard. Violet will proactively notify you if this changes.
What if we have hundreds of merchants?
This is time-intensive but manageable:
* Create apps in batches
* Prioritize based on need
* Remember that existing apps don't require immediate migration
* Establish a process for creating new apps efficiently
### Credentials & Security
I lost my Client Secret or forgot to copy it before navigating away
The Client Secret appears only once in Shopify. If you didn't copy it, you'll need to regenerate it:
1. Go to [Shopify Partner Dashboard](https://partners.shopify.com) → **App Distribution**
2. Navigate to your Custom App → select **View on Dev Dashboard** (far right link)
3. Navigate to the **API credentials** section
4. Find the Client Secret field and click **Rotate**
4. Copy the new Client Secret immediately
5. Return to Violet Channel Dashboard
6. Edit the pre-registration for this merchant (Actions menu → Edit)
7. Update the **Client Secret** field with the new value
8. Save the pre-registration
9. If the merchant already started installation with the old credentials, send them the updated installation link
What happens to our existing API credentials?
They continue working unchanged. The access tokens from merchant-created custom apps remain valid.
### Pre-Registration
Can I edit a pre-registration after creating it?
Yes. Use the **Edit** action in the Pre-Registered tab to update:
* Merchant Name
* Store URL
* Client ID
* Client Secret
**Important**: If a merchant has already started installation, editing credentials will require them to reinstall with updated credentials.
How do I know when a merchant has completed installation?
The merchant automatically moves from the "Pre-Registered" tab to the "Connected Merchants" tab. You'll see them appear in your Connected Merchants list, and their status will change from "Pending" to "Active".
Can I pre-register the same merchant multiple times?
No. Each store URL can only have one active pre-registration. If you need to create a new pre-registration:
1. Delete the existing one (Actions menu → Delete)
2. Create a new pre-registration with the updated credentials
3. Send new installation link
What is the Install Link and where do I find it?
The **Install Link** is a Shopify-generated URL that allows merchants to install your custom app directly in their Shopify admin.
**Format:** `https://admin.shopify.com/store/{store}/oauth/install_custom_app?client_id=...`
**Where to find it:**
1. Go to [Shopify Partner Dashboard](https://partners.shopify.com)
2. Navigate to **App Distribution** → Select your custom app
3. Click on the **Distribution** section
4. If you haven't selected a distribution method, click "Select distribution method" and choose "Custom distribution"
5. The Install Link appears on the Distribution page with a Copy button
**When you need it:** The Install Link is required when creating a pre-registration in Violet Channel Dashboard. It's also what you send to merchants FIRST, before the Violet Connect link.
Why do merchants need to install the app before using Violet Connect?
The two-step process (Install Link, then Violet Connect) is required because:
1. **Shopify requirement**: Custom apps must be installed in the merchant's Shopify admin before OAuth can complete
2. **App authorization**: The Install Link triggers Shopify's app installation flow, which grants the necessary permissions
3. **OAuth handshake**: Violet Connect then completes the OAuth process using the pre-registered credentials
**The correct order is:**
1. Channel sends Shopify Install Link to merchant
2. Merchant installs app in Shopify admin
3. Channel sends Violet Connect link to merchant
4. Merchant completes Violet onboarding
Skipping step 2 will cause errors during Violet Connect onboarding.
## Costs & Billing
Are there any cost changes?
Single-merchant apps (custom apps) remain free. There's no cost difference between old and new custom apps.
***
### Installation Flow Diagram
{% @mermaid/diagram content="graph TD
A\[Shopify Requires Change] --> B\[Access Shopify Partner Dashboard]
B --> C\[Create Custom App for Each Merchant]
C --> D\[Configure Required API Scopes]
D --> E\[Select Custom Distribution]
E --> F\[Copy Install Link]
F --> G\[Copy Credentials
Client ID & Secret]
G --> H\[Pre-register Merchant
in Channel Dashboard]
H --> I\[Send Install Link
to Merchant]
I --> J\[Merchant Installs App
in Shopify Admin]
J --> K\[Send Violet Connect Link
to Merchant]
K --> L\[Merchant Authenticates
with Violet]
L --> M\[Pre-filled Store Details
Displayed]
M --> N\[Merchant Clicks
Connect to Shopify]
N --> O\[Violet Completes
OAuth Handshake]
O --> P\[Merchant moves to
Connected Merchants Tab]
P --> Q\[✓ Onboarding Complete]" %}
***
### Additional Resources
#### Official Shopify Documentation
* [Partner Dashboard](https://partners.shopify.com/)
* [Custom Apps Guide](https://shopify.dev/docs/apps/build/authentication-authorization)
* [OAuth Documentation](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant)
* [API Scopes Reference](https://shopify.dev/docs/api/usage/access-scopes)
#### Violet Documentation
* [Violet Connect Overview](/prism/violet-connect.md)
* [Platform Integration Guides](https://github.com/violetio/docs/blob/main/channel-docs/ecom-platforms/README.md)
---
# 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/troubleshooting-faqs.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.