Ctrlk

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 → 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 → App Settings → Violet Connect

Prevention: See Shopify App Setup 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 → 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

Select Distribution Method

Prevention: Always select "Custom distribution" immediately after creating your custom app. See Shopify App Setup - Step 5.

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 → 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 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 section

  2. Log in to Shopify Partner Dashboard

  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 → 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

Shopify App Credentials

  1. Copy the new Client Secret immediately

  2. Return to Violet Channel Dashboard

  3. Edit the pre-registration for this merchant (Actions menu → Edit)

  4. Update the Client Secret field with the new value

  5. Save the pre-registration

  6. 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

  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.

Copy Custom Install 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

spinner

Additional Resources

Official Shopify Documentation

Violet Documentation

PreviousMerchant OnboardingNextBigCommerce

Last updated

Was this helpful?