Skip to main content

Shopify (GraphQL)

This connector captures data from Shopify's GraphQL Admin API into Estuary collections.

Supported data resources​

The following data resources are supported through the Shopify API:

By default, each resource is mapped to an Estuary collection through a separate binding.

Prerequisites​

  • One or more Shopify store IDs. Each store ID is the prefix of your admin URL. For example, https://{store_id}.myshopify.com/admin

You can authenticate each store via OAuth, with a Shopify access token, or with client credentials.

Authentication Methods​

Private App Credentials (Access Token)​

For existing custom apps with static access tokens (shpat_* tokens). The access token is configured directly in the connector and does not expire.

note

Shopify has deprecated the creation of legacy custom apps. Existing access tokens continue to work, but new apps must use Client Credentials. See Shopify's custom app documentation for details.

Client Credentials​

For custom apps created through the Shopify Dev Dashboard. Uses client_id and client_secret to obtain short-lived access tokens (~24 hours) that auto-refresh at runtime. This is the recommended authentication method for new integrations.

Required Permissions​

When authenticating with an access token or client credentials, ensure the following permissions are granted:

  • read_assigned_fulfillment_orders
  • read_checkouts
  • read_customers
  • read_fulfillments
  • read_inventory
  • read_locales
  • read_locations
  • read_marketing_events
  • read_marketplace_fulfillment_orders
  • read_markets
  • read_merchant_managed_fulfillment_orders
  • read_orders
    • If you want to read orders older than 60 days, extend the read_orders scope with read_all_orders
  • read_payment_terms
  • read_products
  • read_publications
  • read_returns
  • read_shopify_payments_disputes
  • read_users
  • read_own_subscription_contracts

Bulk Query Operation Limitations​

This connector submits and processes the results of bulk query operations to capture data. As of API version 2026-01, Shopify supports up to 5 concurrent bulk query operations. The connector takes advantage of this to run multiple bulk queries in parallel for improved performance.

The limit of 5 applies to each app on each store, so bulk queries submitted through a different app don't compete with the connector. If another system submits bulk queries through the same app as the connector, lower /advanced/max_concurrent_bulk_ops to leave slots free for it. The connector can't count that system's queries, so keep its usage within the slots you leave free, or the connector's bulk queries will be rejected. When a capture starts, it cancels bulk queries still running from its previous session and leaves other systems' bulk queries running. It recognises its own by a # Estuary Flow Managed Bulk Query comment it adds to each one.

Configuration​

You configure connectors either in the Estuary web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Shopify source connector.

Properties​

Endpoint​

The properties in the table below reflect manual authentication using the CLI. In the Estuary web app, you'll sign in directly and won't need the access token.

PropertyTitleDescriptionTypeRequired/Default
/storesShopify StoresOne or more Shopify stores to capture. Each store requires its own credentials.arrayRequired
/stores/[]/storeStore NameStore name (the prefix of your admin URL, e.g., mystore for mystore.myshopify.com)stringRequired
/stores/[]/credentialsAuthenticationStore credentials. See Authentication Methods.objectRequired
/start_dateStart DateUTC date and time in the format YYYY-MM-DDTHH:MM:SSZ. Any data before this date will not be replicated. Note that the read_all_orders scope is required when reading orders older than 60 days.string30 days before the present date
/advanced/window_sizeWindow SizeWindow size for incremental streams in ISO 8601 format (e.g., P30D means 30 days, PT6H means 6 hours).stringP30D
/advanced/should_use_composite_keyUse Composite KeyInclude store identifier (/_meta/store) in collection keys. Enabled by default for new captures. Set to true and backfill all bindings before adding stores to a legacy capture.booleantrue (new) / false (legacy)
/advanced/max_concurrent_bulk_opsMax Concurrent Bulk OperationsMaximum number of bulk query operations the connector runs at the same time for each store, from 1 to 5. Lower it to leave slots free for other systems that submit bulk queries through the same app. See Bulk Query Operation Limitations.integer5

Credential properties for Private App Credentials:

PropertyTitleDescriptionTypeRequired/Default
/stores/[]/credentials/credentials_titleCredentials TitleMust be Private App CredentialsstringRequired
/stores/[]/credentials/access_tokenAccess TokenShopify access tokenstringRequired

Credential properties for Client Credentials:

PropertyTitleDescriptionTypeRequired/Default
/stores/[]/credentials/credentials_titleCredentials TitleMust be Client CredentialsstringRequired
/stores/[]/credentials/client_idClient IDOAuth2 client IDstringRequired
/stores/[]/credentials/client_secretClient SecretOAuth2 client secretstringRequired

Bindings​

PropertyTitleDescriptionTypeRequired/Default
/nameData resourceName of the data resource.stringRequired
/intervalIntervalInterval between data syncsstring
/scheduleScheduleSchedule to automatically rebackfill this binding. Accepts a cron expression.string""

Sample​

captures:
  ${PREFIX}/${CAPTURE_NAME}:
    endpoint:
      connector:
        image: ghcr.io/estuary/source-shopify-native:v2
        config:
          stores:
            - store: primary-store
              credentials:
                credentials_title: Private App Credentials
                access_token: <secret>
            - store: secondary-store
              credentials:
                credentials_title: Client Credentials
                client_id: <client_id>
                client_secret: <secret>
          start_date: "2025-01-16T12:00:00Z"
    bindings:
      - resource:
          name: products
        target: ${PREFIX}/products
      - resource:
          name: orders
        target: ${PREFIX}/orders

Multi-Store Captures​

This connector supports capturing data from multiple Shopify stores in a single capture task. Each store authenticates independently and can use different credential types.

How it works​

  • Configure multiple stores in the stores array, each with its own store name and credentials
  • All documents include a /_meta/store field identifying which store they originated from
  • Resources from all stores are captured into the same collections
  • Collection keys include the store identifier (/_meta/store) to ensure uniqueness across stores

Adding stores to an existing capture​

If you have an existing single-store capture created before multi-store support was added, the should_use_composite_key advanced option will be set to false. To add additional stores:

  1. Set /advanced/should_use_composite_key to true
  2. Perform a backfill and dataflow reset for all bindings

This is required because the collection key structure must include the store identifier (/_meta/store) to ensure uniqueness between documents.

Limitations with Custom App Access Tokens​

If you authenticate using an access token from a custom app on a Shopify plan below the Grow tier, the following streams will not be discovered:

  • customers
  • fulfillment_orders
  • orders

This is due to Shopify API restrictions for lower-tier plans.