Skip to main content

​
Installation instructions

If you have access to the Shopify store as a User, please follow the steps below in the Store Account-tab. If you have access to the Shopify store as a Partner, please follow the steps in the Partner Account-tab.
1

Create a custom Shopify app

  1. Go to the Shopify Developer Portal
  2. From the Dev Dashboard, be sure you’re on Apps in the left-panel navigation and select Create app in the top, right corner of the screen, then Create app manually.
create-app
  1. Fill in the Create an app form:
  • App name: e.g. Converge Server-side Integration
  • App URL: https://app.runconverge.com
  • Clear the Embed app in Shopify admin checkbox.
  • Allowed redirection URL(s): https://app.runconverge.com/api/datasources/shopify/partner/auth
  • Leave the Use legacy install flow checkbox cleared.
  • Scopes: paste the following text:
Don’t add read_all_orders yet. Shopify rejects it on a new app with “Contains invalid scopes: read_all_orders”. You’ll add it in the next step.
  1. Click Create app, then click Release to release the first version.
2

Give Converge access to your full order history

Without the read_all_orders scope, Shopify only shares orders created in the last 60 days. Returning customers whose earlier orders are older then count as new customers.
  1. Click on Versions in the left-panel navigation and Create version.
create-version
  1. Under API access > Scopes, add , read_all_orders to the end of the scopes, so the textbox reads:
  1. In the bottom right corner, click Release and then click Release again to confirm. You don’t need to provide a version name.
scopes-release
release-confirmation
If Shopify still rejects read_all_orders, your app belongs to a Shopify Partner organization. Follow the steps in the Partner Account-tab instead.
  1. In the left-panel navigation, click on Settings for the app you just created. In the Credentials card, note down the Client ID and Client secret, you’ll need to enter them in Converge later.
settings-credentials
3

Install the app in your Shopify store

  1. Open your app and click Install app at the top of the Installs card.
manage-custom-install-link
  1. Select the store you want to install the app, and click “Install”. You’ll then be redirected to Converge.
manage-custom-install-link
4

Create the Shopify source in Converge

  1. In Converge, go to Event sources and click on Create a new source.
  2. Name your source: e.g. {Storename} Store Backend
  3. Pick Server-side from the modal and choose the Shopify app from the dropdown menu.
  4. Enter the Shopify Store Name of the store you want to use Converge for, this is the string before myshopify.com in the Shopify URL.
  5. Paste the Client ID and Client Secret from the Dev Dashboard in the respective fields.
  6. Click Authorize Shopify Custom App.
  7. Click on Create Source.
Your source only holds orders created in the 60 days before you connected it.
  1. Follow steps 5 to 7 above to release a version with read_all_orders.
  2. In your Shopify admin, open the app from Apps and approve the updated access. Shopify doesn’t apply new scopes until you do.
  3. In Converge, open your Shopify source, click Authorize Shopify Custom App again, and save the source.
  4. Contact Converge support to resync your order history.
The installation instructions previously relied on creating a custom Shopify app through the admin panel. This is no longer supported by Shopify and is now replaced by the Developer Portal. Please follow the new installation instructions above for any new installations.If you already have a custom app for Converge from before Jan 1st, 2026, you can still use the legacy instructions below.
1

Create a custom Shopify app

  1. Navigate to the Shopify Admin dashboard, and click on Settings
  2. Click on Apps and sales channels in the Settings modal.
  3. Click on Develop apps, you might have to choose allow custom app development in a pop-up
  4. Click on Create an app, give the app the name Converge and choose your own email address as the developer.
2

Configure the correct scopes

  1. Choose Configure Admin API scopes and mark the following 4 scopes (i) read_customer_events, (ii) read_customers, (iii) read_orders (iv) read_products
3

Install the custom app to get the token

  1. Click on Save and then Install app. Reveal and copy the Admin API access token
4

Create a new Server-side source in Converge

  1. In Converge, go to Event sources
  2. Click on Create a new source
  3. Pick Server-side from the modal
  4. Name your source: e.g. {Storename} Store Backend
5

Connect the Source

  1. Enter the store name, this is the string before myshopify.com in the Shopify URL. E.g. For convergestore.myshopify.com the store name would be convergestore
  2. Paste the Shopify Access Token in the Converge web app under Shopify API Password. Do not fill in a starting date, just click on Create source
  3. Click on Create Source.
You should see the Source syncing all historical order data, or only the last 60 days without the read_all_orders scope. No need to wait before it’s fully synced to create destinations. We’ll automatically check which orders are historic and new and forward only the new ones in case a destination is active while historically syncing.

​
Post-Purchase Upsells

Many Shopify stores use post-purchase upsells such as . After placing an order, the customer will be prompted to add a new item to the order. If the customer accepts the upsell, the original order will be modified by the upsell app. For this reason, the only way to track these post-purchase upsells reliably is server-side (as the order is modified server-side). The Shopify Server Integration supports upsell tracking by introducing an optional delay in the integration settings. If you turn on this delay, Converge will wait 10 minutes for the upsell to come in before forwarding it to destinations. You can turn this option on in the configuration of the integration:
upsell app intro
Please contact Converge support before enabling this feature.
This will only work with Destinations that support server-side events. Client-side destinations will not track the upsell.

​
Filtering out certain orders at ingestion

You might want to make sure certain order types never make it into Converge (e.g. test orders). The Converge Shopify source allows you to configure order exclusions based on their channel or applied tag. E.g. You can filter out all pos orders or filter out all orders with an Exclude tag. To configure, navigate to and click on your Shopify source. Then, under configuration mark the exact criteria by which you want to exclude orders from arriving in Converge.
source-filters

​
Event spec

This integration auto-tracks the following events on the server with all properties available according to the Converge event spec. This integration also auto-tracks some additional events that are not part of the Converge event spec.

​
Sales channels

Events received by Converge from Shopify are automatically mapped to Converge’s sales channels types whenever possible. Shopify’s various sales channels, such as the web, shop app, and marketplace integrations, are translated into Converge’s standardized sales channels types based on the context and source of each event. For example, events originating from Shopify checkout are mapped to the web sales channel, while those from POS systems or third-party marketplaces (like Amazon) are categorized as pos and marketplace, respectively. More on sales channels can be found here.
Due to the extensive nature of Shopify’s sales channels and tight integration with third-party apps, it may be difficult to get an accurate sales channels mapping. As such, Converge falls back to “web” if a mapping cannot be found.
An example of how Converge maps Shopify sales channels: