Shopify Guide (Public, OAuth App)

Shopify Configuration Guide (Public, OAuth App)

Create a public Shopify app and configure it so that you can process store data through Rutter. If you are going to use a Custom App (which does not require Shopify approval), please contact support@rutterapi.com.

Note: Shopify migrated app creation from the Partner Dashboard to the new Dev Dashboard at dev.shopify.com/dashboard. The old "Apps → All apps → Create app → Create app manually" flow no longer exists. Follow the steps below for the updated 2026 flow.

Before You Start

Make sure you have:

1. A Shopify Partners account — sign up at partners.shopify.com/signup if you don't have one
2. An active Rutter account with access to dashboard.rutterapi.com
3. Your Rutter Organization ID — found at dashboard.rutterapi.com/settings
4. Node.js installed on your machine (needed for the GDPR webhook step)

Part 1: Create the App

1. Go to dev.shopify.com/dashboard and log in with your Shopify Partners credentials
2. Select Apps in the left sidebar
3. Click Create app (top right corner)
4. Select "Start from Dev Dashboard" — do NOT select "Start from Shopify CLI"
5. Enter an app name (e.g. "YourCompanyName")
6. Click Create

Part 2: Configure a Version

After creating the app, you need to create a version before the app can be installed on any store. A version is a snapshot of the app's URLs, scopes, and settings.

1. Go to the Versions tab of your new app in the Dev Dashboard
2. Set the App URL to (replace YOUR_RUTTER_ORG_ID with your Rutter Org ID from dashboard.rutterapi.com/settings):
   • https://production.rutterapi.com/shopify/proxy/${YOUR_RUTTER_ORG_ID}/app-url
3. Add the Allowed redirection URL:
   • https://production.rutterapi.com/shopify/proxy/${YOUR_RUTTER_ORG_ID}/redirect-url
4. Select the newest Webhooks API version from the dropdown
5. Select the required scopes (see Part 3 below for which ones to choose)
6. Click Release

Part 3: Select the Right Scopes

Scopes define what store data the app can access. Choose based on your use case.

Standard Commerce Integration (default for most customers):

1
read_orders
2
read_customers
3
read_product_listings
4
read_products
5
read_locations

Fintech Use Case (full order history + payouts) — everything above, plus:

1
read_all_orders
2
read_shopify_payments_payouts

Write Access (if you need to create/update data) — add as needed:

1
write_orders
2
write_products
3
write_customers

Important notes on scopes:

• read_all_orders requires separate approval. By default, Shopify only provides access to the last 60 days of orders. To get full history: go to Partner Dashboard → Apps → click the app name → API access → Access requests → find "Read all orders scope" → click Request access and describe why historical order data is needed.
• read_customers falls under protected customer data. Customer data from non-development stores will not be returned until the app is approved for protected customer data use (handled during submission in Part 8).

Part 4: Configure GDPR Compliance Webhooks (Requires CLI)

Shopify requires three GDPR compliance webhook endpoints for every app. This step requires the Shopify CLI — there is no way to configure this through the dashboard UI.

Why the CLI is needed: The old Partner Dashboard had three paste fields for GDPR webhooks on the "App setup" page. Those fields no longer exist. Shopify now manages compliance webhooks exclusively through a TOML config file deployed via CLI. Without this step, the automated pre-submission check will fail with "Provides mandatory compliance webhooks" and the app cannot be submitted for review.

1. Install the Shopify CLI:

   1
   npm install -g @shopify/cli
   

2. Create a new folder and add a single file called shopify.app.toml with the following content (replace CLIENT_ID_FROM_DEV_DASHBOARD_SETTINGS with the Client ID from Dev Dashboard → Settings, and YOUR_RUTTER_ORG_ID with your Rutter Org ID):

   1
   client_id = "CLIENT_ID_FROM_DEV_DASHBOARD_SETTINGS"
   2
   
   3
   [webhooks]
   4
   api_version = "2026-01"
   5
   
   6
   [[webhooks.subscriptions]]
   7
   compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
   8
   uri = "https://production.rutterapi.com/shopify/proxy/YOUR_RUTTER_ORG_ID/hmacwebhooks"
   

3. Run the deploy command from that folder:

   1
   shopify app deploy
   

This is a one-time step.

Part 5: Get API Credentials

1. In the Dev Dashboard, go to Settings in the left nav of your app
2. Copy the Client ID and Client Secret
3. Go to dashboard.rutterapi.com/platforms/shopify
4. Paste the Client ID and Client Secret into the Shopify configuration fields
5. Click Save

Note: In the old flow, these were called "API Key" and "Secret API Key" on the app overview page. They are now called "Client ID" and "Client Secret" under Settings.

Part 6: Set Distribution Method

Distribution is managed in the Partner Dashboard, not the Dev Dashboard.

1. Go to partners.shopify.com
2. Navigate to App distribution in the left sidebar
3. Select your app from the list
4. Click Choose distribution
5. Select the appropriate method:
   • Public distribution — for listing on the Shopify App Store (requires review)
   • Custom distribution — for sharing via a direct install link to specific stores

Important: You cannot change the distribution method after selecting it.

Part 7: Test on a Development Store

1. In the Dev Dashboard, go to Stores in the left sidebar
2. Click Create store, enter a store name, and click Create store
3. Log into the new dev store
4. Go back to the app's Home page in the Dev Dashboard
5. Click Install app
6. Select the dev store you just created → click Install
7. Complete the Rutter OAuth flow
8. Check dashboard.rutterapi.com for the new Shopify connection (you may need to refresh)

If you have configured a "Direct App Install Redirect URL" at dashboard.rutterapi.com/platforms, you will be redirected there after successful authentication.

Part 8: Submit for Public App Approval

Only needed if you selected Public distribution in Part 6.

Pre-submission setup:

1. Go to Partner Dashboard → App distribution → select the app
2. Complete the Configuration setup section:
   • App icon — 1200×1200px, JPEG or PNG, no text in the icon
   • API contact email — cannot contain the word "Shopify"
   • Emergency contact — email and phone number for critical issues
3. If the app uses read_customers, apply for protected customer data access before submitting (this cannot be done while the app is under review)

Create a listing:

1. Set primary language to English
2. Fill out required listing fields: app name, tagline, description, screenshots
3. Set App Visibility: Listed (appears in App Store search) or Unlisted (accessible by direct link only)

Run checks and submit:

1. Run the automated pre-submission checks — all must pass
2. Optionally run the AI self-review tool to catch common issues before human review
3. Click Submit for review

After submission:

• Track requirement-level status in Partner Dashboard → App → Distribution
• You cannot resubmit until all flagged issues are resolved
• Invite onboarding@rutterapi.com as an owner on the Partner account so Rutter can assist with any issues

Tips to avoid rejection:

• Verify the full OAuth flow works end-to-end on a dev store before submitting
• Embedded app must be disabled
• Do not include "Shopify" in any URLs or contact emails
• For App Store review, Shopify validates these scopes in use: read_orders, read_customers, read_products

Old Flow vs. New Flow Reference