Shopify

​

Setup Guide

​

Setting Up Your Shopify Environment

​

1. Create a Partner account

​

2. Create a development store

​

3. Install Shopify CLI

npm install -g @shopify/cli@latest

​

Creating a Shopify App

1

Create the app

Open the Dev Dashboard and select Apps > Create app > Start from Dev Dashboard. Name your app and select Create.

If you prefer to scaffold a local project first, run shopify app init instead. That command creates both the app and a shopify.app.toml file, so you can skip the next step.

2

Link a local configuration file

In an empty directory (or your app project), run:

shopify app config link

Select the app you just created. This generates a shopify.app.toml file you will use for the rest of setup.

3

Configure URLs, scopes, and compliance webhooks

Copy the Webhook URL from Integrations > Shopify > Settings in the Paragon dashboard. If Shopify is not in your catalog yet, add it first so the Settings tab is available.

Open shopify.app.toml and set the following values. Keep any client_id that shopify app config link already wrote.

shopify.app.toml

name = "Your App Name"
application_url = "https://your-app.example.com"
embedded = false

[access_scopes]
scopes = "read_products,write_products,read_customers,write_customers,read_orders,write_orders"

[auth]
redirect_urls = [
  "https://passport.useparagon.com/oauth"
]

[webhooks]
api_version = "2026-04"

[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "YOUR_PARAGON_WEBHOOK_URL"

Setting	Value
application_url	While testing, use your app’s root URL. When you set up redirect pages to go live, change this to your Initial Redirect URL.
redirect_urls	While testing, use https://passport.useparagon.com/oauth. When you go live, add your Redirect Callback URL.
scopes	The access scopes your app will request. Use the same list in Paragon in the next section.
uri	The Webhook URL you copied from Paragon. Paragon routes all three compliance events from this single URL.

If your file already has a [webhooks] section, keep its api_version and add only the [[webhooks.subscriptions]] block.

For on-premise installations, use https://passport.[Your Base URL]/oauth as the redirect URL.

Learn more in Shopify’s app configuration and privacy compliance docs.

4

Deploy the configuration

From the directory that contains shopify.app.toml, run:

shopify app deploy

Shopify registers your OAuth URLs, scopes, and compliance webhook subscriptions when you deploy. Repeat this step whenever you change those values.

5

Install the app on your development store

In the Dev Dashboard, open your app, go to Home, and select Install app. Choose the development store you created earlier and install.You must be the store owner or have a staff account on the store to install.

​

Add Your Shopify App to Paragon

​

Testing Your Setup

​

Connecting to Shopify

// You can find your project ID in the Overview tab of any Integration

// Authenticate the user
paragon.authenticate(<ProjectId>, <UserToken>);

// Create Customer
await paragon.request("shopify", "/admin/api/2020-10/customers.json", { 
  method: "POST",
  body: { 
    "first_name": "John",
    "last_name": "Norman",
    "email": "[email protected]",
    "phone": "+16135551111",
    "note": "Creating customer for testing",
    "tags": ["tag1","tag2"]
   }
});


// Query Customers
await paragon.request("shopify", "/admin/api/2020-10/customers.json", { 
  method: "GET"
});
  

​

Building Shopify workflows

• Get Customers
• Search Customers
• Create Customer
• Update Customer
• Get Orders
• Create Order
• Update Order
• Get Abandoned Carts
• Get Products
• Create Product
• Update Product

​

Using Webhook Triggers

• New Order
• Order Updated
• New Customer
• Customer Updated
• New Product
• Product Updated
• Customer Data Request
• Customer Data Erasure Request
• Shop Data Erasure Request

​

Publishing your Shopify app

​

Setting up Redirect Pages in your app

• Initial Redirect: This page will take in a shop query parameter and redirect to Shopify’s OAuth flow.
• Redirect Callback: This page will receive the OAuth authorization code after the Shopify user grants consent and call paragon.completeInstall to save the user’s account connection.

• Example Initial Redirect
• Example Redirect Callback

​

Initial Redirect

• Accept and read the query parameter shop. If the query parameter is present, redirect to the following URL to start the Shopify OAuth flow:

https://{shopQueryParam}/admin/oauth/authorize?client_id={SHOPIFY_CLIENT_ID}&redirect_uri={REDIRECT_CALLBACK_URL}&scope={SHOPIFY_SCOPES}

• The SHOPIFY_CLIENT_ID should match the Client ID that you use in your Shopify integration settings.
• The REDIRECT_CALLBACK_URL should be the URL of the Redirect Callback page in your app.
• The SHOPIFY_SCOPES should match the scopes that you use in your Shopify integration settings.

​

Redirect Callback

• Import the Paragon SDK and authenticate a user.
  • Note: If a user is not yet logged into your app, you can redirect to a login form, while preserving the intended URL to redirect to upon successful login. In other words, after logging in, your user should see your Redirect Page.
• Accept and read query parameters, which will be:
  • code and shop in case of a successful installation
  • error in case of an unsuccessful installation or denied consent
• If the code query parameter is present,
  • Read the shop query parameter and capture the shop name in the pattern {shop}.myshopify.com. See the regular expression used below.
  • Call paragon.completeInstall to complete the OAuth exchange and save a new connected Shopify account.

let params = new URLSearchParams(window.location.search);
let authorizationCode = params.get("code");
let [, shopName] = params.get("shop").match(/^([a-zA-Z0-9][a-zA-Z0-9\-]*).myshopify.com/);

if (authorizationCode && shopName) {
   paragon.completeInstall("shopify", {
    authorizationCode: authorizationCode,
    redirectUrl: "https://your-app.url/shopify-redirect",
    integrationOptions: {
      SHOP_NAME: shopName,
    }
  }).then(() => {
     // Redirect to your app's integrations page
  });
} else {
  let error = params.get("error");
  // Handle error
}

• If the error query parameter is present,
  • Show this error in your app and allow your user to retry the process.

​

Updating your app’s redirect and app URLs

1. Set application_url to your app’s Initial Redirect URL.
2. Add your Redirect Callback URL to redirect_urls.
3. Run shopify app deploy.

application_url = "https://your-app.url/integrations"

[auth]
redirect_urls = [
  "https://passport.useparagon.com/oauth",
  "https://your-app.url/shopify-redirect"
]

​

Creating workflows to respond to privacy webhooks

• Customer data request
• Customer data erasure
• Shop data erasure

• Customer data request: If your app has been granted access to customer or order data, then it will receive a data request webhook. The webhook contains the resource IDs of the customer data that you need to provide to the store owner. It’s your responsibility to provide this data to the store owner directly.
  • Note: This request does not require the data to be provided in a response to the webhook. This process happens outside of Shopify and should be provided to the user who connected this Shopify account directly, e.g. through email, within 30 days of receiving the request.
• Customer data erasure: Shopify store owners can request that data is deleted on behalf of a customer. When this happens, Shopify sends a Customer Data Erasure event to the apps installed on that store so that you can erase any data for a certain customer of a store from your database.
• Shop data erasure: 48 hours after a store owner uninstalls your app, Shopify sends a Shop Data Erasure event. This webhook provides the store’s shop_id and shop_domain so that you can erase data for that store from your database.

Example Implementation

Example implementationAdd a Request step under the Trigger to send the privacy event information to your API. We recommend including the following values in the request body for your reference:

• {{1.result}}: This is the full event payload received from Shopify. You will see an example of the event in your workflow Test Data. See Shopify’s documentation on event payloads for more details.
• {{userSettings.userId}}: This is the User ID of the Connected User that received the event. You can use this ID to relate the event to a user in your application.

• Click the context menu in the Workflow Editor toolbar and click Edit Connect Portal Workflow Settings.
• Switch on Default to enabled and Hide workflow from Portal for all users.

• Repeat for each workflow that has a Shopify privacy event trigger.

​

Testing and validating privacy webhooks

• Verify that your shopify.app.toml compliance subscriptions have been deployed with shopify app deploy.
• Verify that each of your workflows are deployed.
• In your application, connect a Shopify store to the Connect Portal. Remember the store and account that you have connected.
• In the Shopify Admin page for the same store, request or erase a customer’s data (see Shopify documentation). These actions will trigger the “Customer data request” and “Customer data erasure” events, respectively.
• In the Paragon dashboard, visit the Monitoring > Workflows page and verify that your workflow has executed.