Shopify

This page contains the setup guide and reference information for the Shopify source connector.

Prerequisites

• An active Shopify store.
• If you are syncing data from a store that you do not own, you will need to request access to your client's store (not required for account owners).

• For Calabi Connect users: A custom Shopify application with read_ scopes enabled.

Setup guide

This connector supports OAuth2.0 and API Password (for private applications) authentication methods.

Set up Shopify

note

For existing Calabi Connect customers, if you are currently using the API Password authentication method, please switch to OAuth2.0, as the API Password will be deprecated shortly. This change will not affect Calabi Connect connections.

For Calabi Connect:

1. Log into your Calabi Connect account.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Shopify from the Source type dropdown.
4. Enter a name for the Shopify connector.

Connect using OAuth2.0

1. Choose a Source name.

2. Click Authenticate your Shopify account.

3. Click Install to install the Calabi Connect application. Log in to your account, if you are not already logged in. Select the store you want to sync and review the consent form. Click Install app to finish the installation.

4. Click Set up source and wait for the connection test to complete.

For Calabi Connect:

1. Navigate to the Calabi Connect dashboard.
2. Click Sources and then click + New source.
3. On the Set up the source page, select Shopify from the Source type dropdown.
4. Enter a name for the Shopify connector.

Create a custom app

Authentication to the Shopify API requires a custom application. Follow these instructions to create a custom app and find your Admin API Access Token.

1. Log in to your Shopify account.
2. In the dashboard, navigate to Settings > App and sales channels > Develop apps > Create an app.
3. Select a name for your new app.
4. Select Configure Admin API scopes.
5. Grant access to the following list of scopes. Only select scopes prefixed with read_, not write_ (e.g. read_locations,read_price_rules, etc ).
6. Click Install app to give this app access to your data.
7. Once installed, go to API Credentials to copy the Admin API Access Token. You are now ready to set up the source in Calabi Connect!

Connect using API Password

1. Enter a Source name.
2. Enter your Shopify Store name. You can find this in your URL when logged in to Shopify or within the Store details section of your Settings.
3. For API Password, enter your custom application's Admin API access token.
4. (Optional) You may set a Replication Start Date as the starting point for your data replication. Any data created before this date will not be synced. Please note that this defaults to January 1st, 2020.
5. Click Set up source and wait for the connection test to complete.

Custom app scopes

Add the following scopes to your custom app to ensure Calabi Connect can sync all available data. For more information on access scopes, see the Shopify docs.

• read_analytics
• read_assigned_fulfillment_orders
• read_content
• read_customers
• read_discounts
• read_draft_orders
• read_fulfillments
• read_gdpr_data_request
• read_gift_cards
• read_inventory
• read_legal_policies
• read_locations
• read_locales
• read_marketing_events
• read_merchant_managed_fulfillment_orders
• read_online_store_pages
• read_order_edits
• read_orders
• read_price_rules
• read_product_listings
• read_products
• read_publications
• read_reports
• read_resource_feedbacks
• read_script_tags
• read_shipping
• read_shopify_payments_accounts
• read_shopify_payments_bank_accounts
• read_shopify_payments_disputes
• read_shopify_payments_payouts
• read_themes
• read_third_party_fulfillment_orders
• read_translations

Supported sync modes

The Shopify source connector supports the following sync modes:

Feature	Supported?
Full Refresh Sync	Yes
Incremental Sync	Yes

The Shopify source supports both Full Refresh and Incremental syncs. You can choose if this connector will copy only the new or updated data, or all rows in the tables and columns you set up for replication, every time a sync is run.

This source can sync data for the Shopify REST API and the Shopify GraphQL API and the Shopify GraphQL BULK API

Supported Streams

• Abandoned Checkouts
• Articles
• Balance Transactions
• Blogs
• Collects
• Collection Products (GraphQL) - All products associated with each collection, including smart collection matches
• Collections (GraphQL)
• Countries (GraphQL)
• Custom Collections
• Customers
• Customer Journey Summary (GraphQL)
• Customer Address (GraphQL)
• Draft Orders
• Discount Codes (GraphQL)
• Disputes
• Fulfillments
• Fulfillment Orders (GraphQL) - By default, closed fulfillment orders are excluded. To include them, enable the Include Closed Fulfillment Orders option in the connector configuration.
• Inventory Items (GraphQL)
• Inventory Levels (GraphQL)
• Locations
• Metafields (GraphQL)
• Order Agreements (GraphQL)
• Orders
• Order Refunds
• Order Risks (GraphQL)
• Pages
• Price Rules
• Products (GraphQL)
• Deleted Products (GraphQL) - Product deletion events
• Product Images (GraphQL)
• Product Variants (GraphQL)
• Shop
• Smart Collections
• Transactions
• Transactions (GraphQL)
• Tender Transactions

Entity-Relationship Diagram (ERD)

Capturing deleted records

The connector captures deletions for records in the Articles, Blogs, CustomCollections, Orders, Pages, and PriceRules streams. When a record is deleted, the connector outputs a record with the ID of that record and the deleted_at, deleted_message, and deleted_description fields filled out. No other fields are filled out for the deleted records.

For deleted products, use the dedicated Deleted Products stream, which queries the Shopify GraphQL Events API for product deletion events. This stream returns records with id (the product ID), deleted_at, deleted_message, and shop_url fields.

Check the following Shopify documentation for more information about retrieving deleted records.

Marketing Attribution data

Data related to marketing attribution can be found across a few different streams. Sync these streams to understand marketing performance:

• Customer Journey Summary (firstVisit.source, firstVisit.sourcetype)
• Orders (referring_site, source_name)
• Abandoned Checkouts (referring_site, source_name)

Features

Feature	Supported?(Yes/No)
Full Refresh Sync	Yes
Incremental - Append Sync	Yes
Namespaces	No

Data type map

Integration Type	Calabi Connect Type
string	string
number	number
array	array
object	object
boolean	boolean

Limitations & Troubleshooting

Expand to see details about Shopify connector limitations and troubleshooting

Connector limitations

Rate limiting

Shopify has some rate limit restrictions. Typically, there should not be issues with throttling or exceeding the rate limits but, in some edge cases, you may encounter the following warning message:

"Caught retryable error '<some_error> or null' after <some_number> tries.
Waiting <some_number> seconds then retrying..."

This is expected when the connector hits a 429 - Rate Limit Exceeded HTTP Error. The sync operation will continue successfully after a short backoff period.

For all Shopify GraphQL BULK api requests these limitations are applied: https://shopify.dev/docs/api/usage/bulk-operations/queries#operation-restrictions. Please note that different requests have different limitations.

Troubleshooting

• If you encounter access errors while using OAuth2.0 authentication, please make sure you've followed this Shopify Article to request the access to the client's store first. Once the access is granted, you should be able to proceed with OAuth2.0 authentication.
• If you receive a "The BULK job couldn't be created at this time, since another job is running." error, please check your operation's progress with the Shopify GraphQL BULK api.
• If you need to cancel a Shopify GraphQL BULKjob, please follow these steps. You will need the current in-progress job ID to cancel.
• Check out common troubleshooting issues for the Shopify source connector on our Calabi Connect Forum here.