Shopify GraphQL

Description‍

Shopify GraphQL is an eCommerce platform that allows users to set up an online store and sell products or services directly to their customers.

Setup guide

Follow our setup guide to connect Shopify GraphQL to Improvado.

1Click the Make a new Connection on the Connections page.
‍‍Categories on the Data sources page group all available platforms. Use a search to find the required one.

2Click on the Shopify GraphQL tile.

3Choose authorization option:

Connect your own Shopify App (via Client Credentials, recommended)

To authorize your account you need to fill in the required fields below following steps 3.1 - 3.4:

• Shop name
• Client ID
• Client Secret

To do these steps you need to have at least Apps Developer role or ask the user with that permission to follow through.

Note

Collaborators don't have access to the Dev Dashboard.

3.1Create a new app from your Dev Dashboard.

1. 1From 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.
2. 2Select Start from Dev Dashboard.
3. 3Name your app, then select Create.

3.2Create a version.

Once you've created the app, you can create a version. Your app must have at least one version before it can be installed on a store.

From the Versions tab of your app in the Dev Dashboard, complete your desired fields, including:

4. 4Defining your app URL. Use the default URL https://shopify.dev/apps/default-app-home
5. 5Selecting a Webhooks API version (newest version).
6. 6Selecting your app scopes. These define the data and features your app can access within the Shopify platform.

Access scope name	Permission
read_products	View products, variants, and collections
read_customers	View customers, customer addresses, order history, and customer groups
read_all_orders	View all orders, transactions, fulfillments, abandoned checkouts and refunds. How to obtain this permission
read_orders	View orders created within the last 60 days. Required for read_all_orders to function.
read_locations	View locations and their properties
read_shopify_payments_payouts	View Shopify Payments payouts and the account's current balance
read_returns	View information related to order returns
read_gift_cards	View information related to gift cards

4. 4Select Release.

3.3Complete the following steps to install your app on a store:

8. 8From your app, select Home in the left panel of the Dev Dashboard.
9. 9Scroll down and select Install app.
10. 10Select or create the store for your app.
11. 11Select Install.

Your app is now installed.

3.4Copy Client ID and Client secret

Shop data is accessed via client credentials grant:

12. 12From your app in the Dev Dashboard, select Settings.
13. 13Copy your Client ID and Client secret.
14. 14Paste these credentials to Authorization page in Improvado UI.

Connect your own Shopify App (via Access Token, legacy)

To authorize your account you need to fill in the required fields below following steps 3.1 - 3.10:

• Shop name
• Admin API access token

To do these steps you need to have Develop apps permission or ask the user with that permission to follow through.
‍

3.1In Shopify Admin, click Apps, and then click Develop apps to create your app.

3.2Click Allow custom app development.

3.3Click Allow legacy custom app development.

3.4Click Create a legacy custom app.

3.5Enter your App name, and click Create app.

3.6After app is created, go to Configuration tab and press Configure for Admin API Integration.

3.7Select the following permission scopes:

‍

Access scope name	Permission
read_products	View products, variants, and collections
read_customers	View customers, customer addresses, order history, and customer groups
read_all_orders	View all orders, transactions, fulfillments, abandoned checkouts and refunds. How to obtain this permission
read_orders	View orders created within the last 60 days. Required for read_all_orders to function.
read_locations	View locations and their properties
read_shopify_payments_payouts	View Shopify Payments payouts and the account’s current balance
read_returns	View information related to order returns
read_gift_cards	View information related to gift cards

3.8Go to API credentials tab and press Install app.

‍

3.9Confirm installation by clicking Install.

3.10Once app is installed, click on Reveal token once to copy and paste to Improvado authorization form.

Also, you can find the additional information and in-depth step-by-step guide at the links here:

• ‍Creating and installing custom app in Shopify | Docs‍
• Official video guide‍
• Get the API credentials for a custom app | Docs

4After the connection process is completed successfully, the Shopify GraphQL connection will appear in your Connected sources list.

5When the connection status is Active, and the account status column shows a number of accounts, you can move on to data extraction.

6To extract data from the connected sources, check the instruction on how to set up data extraction.

How to obtain read_all_orders permission:

The read_all_orders scope allows access to orders older than 60 days. It requires an additional approval step in the Shopify Partners dashboard before it can be added to your app scopes.

1. 1Go to https://partners.shopify.com/YOUR_ORGANIZATION_ID/apps
2. 2Click on your app.
3. 3Select the API access requests tab (you'll be redirected to https://partners.shopify.com/YOUR_ORGANIZATION_ID/apps/YOUR_APP_ID/api_access).
4. 4Under "Read all orders scope," click Request access.
5. 5Enter the following reason: "Merchant requires requesting data for orders older than 60 days."
6. 6Click Request access.

Scope should be granted immediately and can be added to your app scopes.

Schema information

The schema information shows all report types you can use to extract data from Shopify GraphQL.

Limits

Where sessions, visitors and traffic sources come from

Shopify’s store analytics — sessions, online store visitors, page views, bounce rate, cart and checkout progression — are not part of the Order or Customer Journey object graph. Looking for them there is the usual wrong turn, because orders carry UTM parameters and it is tempting to assume the visit data sits alongside them. It does not: orders describe purchases, not visits.

Those metrics come from ShopifyQL instead, and Improvado exposes them as their own report types:

• Sessions ShopifyQL — sessions, online store visitors, page views, page views per session, bounces and bounce rate, average session duration, sessions with cart additions, sessions that reached and completed checkout, and the matching conversion rates.
• Campaign Sessions ShopifyQL — the same session behaviour broken out by campaign, for tying traffic to marketing rather than to orders.

If you have a ShopifyQL query that works in the Shopify admin, these are the report types that reproduce it.

Sales Agreement by Order does not contain Shopify’s sales metrics

Sales Agreement by Order returns Shopify’s raw agreement amounts and nothing else: total amount, total tax amount, and total discount amount before and after taxes, each in both shop and presentment currency. There is no gross sales, net sales, returns or total sales field in it, so summing it will not reproduce the Sales report in the Shopify admin.

Two ways forward, depending on what you need:

• If you want Shopify’s own sales figures, use the Sales ShopifyQL report type. It returns them ready-made — gross sales, net sales, discounts, duties, taxes, sales reversals, total sales, cost of goods sold, gross profit and margin — computed by Shopify with the same definitions as the admin.
• If you need agreement or line-item grain, derive what you need from the raw amounts using the line type and action type fields on each sale. Order-level money fields cannot be pushed down to that grain, because one order can hold several agreements and each agreement several sales.

Release notes

You can find information about the latest API changes in the official Release notes.