Shopify 

What does the Shopify Connection provide? 

Looking to connect Gadget and Shopify?

Follow our tutorials and learn how to connect Gadget and Shopify in just a few minutes!

  • Gadget handles the OAuth process for merchants installing your application out of the box. See Shopify OAuth
  • All objects in Shopify's API can be synced into your Gadget app as models. Connected models provide data access to any installing store's data, with no rate limit. Connected models can be extended in Gadget with additional fields to store extra information, though these fields will not sync back with Shopify by default.
  • Gadget automatically registers webhooks for all Shopify API scopes you care about, mapping the events to your models to keep data in sync by running actions when webhooks are received. Actions can be used to react to changes within Shopify, make API calls back to Shopify to update data, or do anything else you can do with JavaScript.
  • Gadget provides an easy-to-use API client for working with the Shopify API in backend code that manages rate limits and authentication. See Accessing the Shopify API
  • Missed webhooks from bugs or infrastructure issues are recovered using a daily background sync, as per Shopify's recommended best practices. You can also manually sync your app to Shopify at any time or trigger syncs with the Sync API.
  • Historical data (old products, orders, customers, etc) can be easily synced when a shop installs your app
  • Gadget provides an embedded Shopify Admin frontend out of the box, as soon as you connect to Shopify in your development environment
  • Gadget has easy-to-use facilities for billing your merchants

Currently, Gadget uses Shopify's 2024-01 API version for new connections.

Setting up the Shopify Connection 

If you are looking to connect Gadget with Shopify, follow the Connecting to Shopify tutorial.

Available models 

Gadget receives webhooks and syncs data from Shopify for the following models:

Model NameRequired ScopesWebhook Topics
AppAlways availablesynced only
App CreditAlways availablesynced only
Shopify App Credits (and other billing resources) are only available to OAuth apps created via the Shopify CLI or in the Shopify Partners dashboard that are marked for Public distribution. To successfully receive webhooks or sync this model, you must mark your app for Public distribution. Find more instructions in the Shopify docs.
App InstallationAlways availablesynced only
Companyread_customerscompanies/create, companies/update, companies/delete
Shopify Company and its related models are only available for apps installed on Shopify Partners Plus stores. To successfully sync and receive webhooks for these models, you must have access to a Shopify Partners Plus store. Access to these models also grant you access to special fields in Shopify Order and Shopify Draft Order models that are only available for Plus stores only. Find more information in the Shopify docs.
Company Addressread_customersSent within Company Location model
Company Contactread_customerscompany_contacts/create, company_contacts/update, company_contacts/delete
Company Locationread_customers, read_marketscompany_locations/create, company_locations/update, company_locations/delete
Company Contact Roleread_customerssynced only
Company Contact Role Assignmentread_customerssynced only
App Purchase One TimeAlways availableapp_purchases_one_time/update
Shopify App Purchase One Time (and other billing resources) are only available to OAuth apps created via the Shopify CLI or in the Shopify Partners dashboard that are marked for Public distribution. To successfully receive webhooks or sync this model, you must mark your app for Public distribution. Find more instructions in the Shopify docs.
App SubscriptionAlways availableapp_subscriptions/update
Shopify App Subscription (and other billing resources) are only available to OAuth apps created via the Shopify CLI or in the Shopify Partners dashboard that are marked for Public distribution. To successfully receive webhooks or sync this model, you must mark your app for Public distribution. Find more instructions in the Shopify docs.
App Usage RecordAlways availablesynced only
Blogread_contentsynced only
Shopify blogs support Metafields but do not provide a REST or GraphQL mechanism for syncing them. Gadget does not support Metafields on Shopify Blog models.
Articleread_contentsynced only
Shopify blog posts support Metafields but do not provide a REST or GraphQL mechanism for syncing them. Gadget does not support Metafields on Shopify Article models.
Commentread_contentsynced only
Themeread_themesthemes/create, themes/update, themes/delete
Gadget only syncs themes and assets that a store owns for each Shopify store, which excludes demo themes. Themes and assets for themes with role: "demo" in the Shopify API are not synced as API clients don't have permission to access individual asset values.
Assetread_themessynced only
Gadget syncs the Theme and Asset resources from Shopify using the REST API. Gadget does not sync the value column of the Asset resource. Syncing the value field can be done with a custom code effect, but Shopify requires one API call per asset to retrieve asset values, which often stresses Shopify API rate limits too much. Shopify Theme assets are often also quite large, including images and large JS files that are generally not important for applications to sync and store again.
Gadget recommends avoiding syncing the Asset and Theme model if possible, and instead making API calls directly to Shopify to work with assets using the connections.shopify.current API client.
Gadget only syncs themes and assets that a store owns for each Shopify store, which excludes demo themes. Themes and assets for themes with role: "demo" in the Shopify API are not synced as API clients don't have permission to access individual asset values.
Balance Transactionread_shopify_payments_payoutssynced only
Checkoutread_checkouts, read_orderscheckouts/create, checkouts/update
The read_checkouts scope will allow Gadget to process checkout related webhooks, but does not provide a mechanism to sync all existing checkouts.

Adding the read_orders scope, while also including the Checkout model in your application, will result in all Abandoned Checkouts that aren't handled via webhooks (failed delivery, checkouts that already exist) being imported during nightly or manual syncs.
Billing Addressread_checkouts, read_ordersSent within Checkout model
Checkout Applied Gift Cardread_checkouts, read_orderssynced only
Checkout Line Itemread_checkouts, read_ordersSent within Checkout model
Checkout Shipping Rateread_checkouts, read_orderssynced only
Shipping Addressread_checkouts, read_ordersSent within Checkout model
Bulk OperationAlways availablebulk_operations/finish
Carrier Serviceread_shippingsynced only
Cartread_orderscarts/create, carts/update
Cart Line Itemread_ordersSent within Cart model
Collectionread_productscollections/create, collections/update, collections/delete
Gadget uses the Collection model to represent both Custom Collections and Smart Collections from Shopify.
Collectread_productssynced only
Countryread_shippingsynced only
Provinceread_shippingsynced only
Customerread_customerscustomers/create, customers/update, customers/delete
Customer Addressread_customersSent within Customer model
Customer Mergeableread_customerssynced only
Customer Payment Methodread_customer_payment_methodscustomer_payment_methods/create, customer_payment_methods/update, customer_payment_methods/revoke
Discount Coderead_discountssynced only
Discountread_discountsdiscounts/create, discounts/update, discounts/delete
Disputeread_shopify_payments_disputesdisputes/create, disputes/update
Dispute data is only available for Shopify merchants using Shopify Payments.
Dispute Evidenceread_shopify_payments_disputessynced only
Dispute File Uploadread_shopify_payments_disputessynced only
Dispute Evidence Fulfillmentread_shopify_payments_disputessynced only
DomainAlways availabledomains/create, domains/update, domains/destroy
Shopify Domain delete and update webhooks are missing key data, so Gadget does an inline sync of the Domain REST API resource when these webhooks arrive to properly discover updates and deletes.
Draft Orderread_draft_ordersdraft_orders/create, draft_orders/update, draft_orders/delete
Draft Order Line Itemread_draft_ordersSent within Draft Order model
Orderread_ordersorders/create, orders/updated, orders/delete
Dutyread_ordersSent within Order Line Item model
Fulfillment Eventread_ordersfulfillment_events/create, fulfillment_events/delete
Fulfillmentread_ordersfulfillments/create, fulfillments/update
Fulfillment Line Itemread_ordersSent within Fulfillment model
Order Adjustmentread_ordersSent within Refund model
Order Line Itemread_ordersSent within Order model
Order Riskread_orderssynced only
Order Transactionread_ordersorder_transactions/create
Refund Dutyread_ordersSent within Refund model
Refundread_ordersrefunds/create
Refund Line Itemread_ordersSent within Refund model
Shipping Lineread_ordersSent within Order model
Tender Transactionread_orderstender_transactions/create
Eventread_content, read_products, read_price_rules, read_orderssynced only
Fileread_files, read_themessynced only
This model tracks files uploaded by the merchant in the Files section of the Shopify Admin. Shopify doesn't expose webhooks for the File resource, so files are only updated in Gadget on sync. Files can be accessed via the read_files or read_themes scopes.
Fulfillment Orderread_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_ordersfulfillment_orders/order_routing_complete, fulfillment_orders/fulfillment_request_submitted, fulfillment_orders/fulfillment_request_accepted, fulfillment_orders/fulfillment_request_rejected, fulfillment_orders/placed_on_hold, fulfillment_orders/cancellation_request_accepted, fulfillment_orders/cancellation_request_rejected, fulfillment_orders/cancelled, fulfillment_orders/fulfillment_service_failed_to_complete, fulfillment_orders/moved, fulfillment_orders/split, fulfillment_orders/merged
Fulfillment Order Line Itemread_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orderssynced only
Fulfillment Serviceread_fulfillmentssynced only
GDPR RequestAlways availableshop/redact, customers/redact, customers/data_request
This model tracks incoming GDPR webhook requests from Shopify to delete merchant or customer data. These GDPR webhooks are required to be supported by Public applications for the Shopify app store, which you can read more about in the Shopify Docs. This model doesn't correspond to an API endpoint within Shopify.
Gift Cardread_gift_cardssynced only
This model tracks issued gift cards for a Shopify store. Shopify only allows access to the read_gift_cards scope on Shopify Plus stores, and only for Custom apps provisioned within the Shopify Admin.

Shopify doesn't offer gift card webhooks, so gift card data is only refreshed on sync.
Inventory Itemread_inventoryinventory_items/create, inventory_items/update, inventory_items/delete
Inventory Items are synced using the REST API endpont for Inventory Levels for each Location to get a list of inventory levels, and then using the REST API endpoint to get a list of inventory items for each level.
Inventory Levelread_inventoryinventory_levels/connect, inventory_levels/update, inventory_levels/disconnect
Inventory Levels are synced using the REST API endpoint for Inventory Levels at a Location.
Locationread_locationslocations/create, locations/update, locations/activate, locations/deactivate, locations/delete
Marketread_marketsmarkets/create, markets/update, markets/delete
Market Regionread_marketsSent within Market model
Market Web Presenceread_marketsSent within Market model
Pageread_contentsynced only
Shopify pages support Metafields but do not provide a REST or GraphQL mechanism for syncing them. Gadget does not support Metafields on Shopify Page models.
Payoutread_shopify_payments_payoutssynced only
Price Ruleread_price_rulessynced only
Productread_productsproducts/create, products/update, products/delete
Product Imageread_productsSent within Product model
Product Optionread_productsSent within Product model
Product Variantread_productsSent within Product model
Redirectread_contentsynced only
Script Tagread_script_tagssynced only
ShopAlways availableshop/update, app/uninstalled
Selling Plan Groupread_productsselling_plan_groups/create, selling_plan_groups/update, selling_plan_groups/delete
Selling Plan Group Productread_productsSent within Selling Plan Group model
Selling Plan Group Product Variantread_productsSent within Selling Plan Group model
Selling Planread_productsSent within Selling Plan Group model
Subscription Contractread_own_subscription_contractssubscription_contracts/create, subscription_contracts/update
Subscription Billing Attemptread_own_subscription_contractssubscription_billing_attempts/success, subscription_billing_attempts/failure, subscription_billing_attempts/challenged
Subscription Lineread_own_subscription_contractssynced only
Subscription Manual Discountread_own_subscription_contractssynced only

Troubleshooting 

The sync between Shopify and my Gadget app failed.

Do you have any custom code running within the create action on the Shopify Sync model? A custom action with errors will prevent the sync from completing successfully. Try removing or editing the code within actions and running a manual sync.

Actions aren't updating my records in Shopify.

You need to explicitly call out to the Shopify client in your action to manipulate data in Shopify. See accessing the Shopify API.

Webhooks aren't being registered with Shopify.

If you see that some webhooks aren't being registered even after clicking Register Webhooks on the Installs page, it is possible that your app has not requested access to Protected Customer Data. See here for more details.

Frequently asked questions 

How do I make calls back to Gadget from a Shopify storefront?

You can call your Gadget app's API client in the storefront's Shopify theme. To do so, you can use the Direct Script Tag option in the Installation section of your app's API Reference.

How do I make an embedded Shopify app using Gadget?

Gadget supports being used as a backend for an app embedded in the Shopify Admin. You can read the docs for setting up the Gadget app client and Provider and go through the tutorial that walks you through setting up an embedded app with the Shopify CLI and Gadget.

When does Gadget automatically sync my Shopify Connection?

Gadget will fully sync your Shopify Connection on demand when you request a sync from the Connections view. Gadget will also automatically fetch all recent data from Shopify in the background in a scheduled daily sync. To see when your app was last synced with Shopify, you can visit the Connections view or view the Shopify Sync data editor.

Building Shopify apps using the Gadget connection 

For more information on how to build Shopify apps using the Gadget Shopify connection, check out our guide here.