Shopify API: GraphQL, Authentication and Your First Integration

An order is created in Shopify, but the accounting system doesn't know about it. The warehouse changes availability, yet the online store keeps offering the last item. The Shopify API lets you connect these systems programmatically. Just sending a request isn't enough, though: the integration has to understand identifiers, permissions, errors and which system has the final say for each piece of data.

This guide helps online store owners brief their first integration and helps technical teams pick the right starting point. We explain the differences between the APIs, show a short read query in GraphQL and go through the operational checks before the first data write.

Key takeaways

• The GraphQL Admin API is used to manage products, orders and inventory.
• The Admin API token belongs on the server. Don't put it in public JavaScript or the store's theme.
• Your first test should only read a small amount of data. Add writes only after verifying the result.
• HTTP 200 alone doesn't confirm that the whole GraphQL operation succeeded.
• A repeated delivery of an event must not create a second order or deduct stock twice.

Table of contents

• Which Shopify API to use
• GraphQL and API versions
• Authentication and permissions
• A first read query for products
• How to verify the response and errors
• Pagination, limits and webhooks
• Designing an ERP integration
• Pre-launch checks
• Frequently asked questions

Which Shopify API to use

GraphQL Admin API: running and managing the store

The Admin API exposes store data according to the app's permissions. It's used, for example, to connect an ERP, a product information system or a fulfillment solution. The integration can read data and, with the right permission, also make changes. That's why it must run in an environment where you can protect credentials and monitor writes.

Storefront API: the customer's shopping experience

The Storefront API is used for customer-facing interfaces, such as a custom catalog and cart handling. It's relevant when building a custom storefront or a shopping app. It's not a replacement for admin access for syncing internal business data. It has its own access rules; the different types of tokens can't be swapped at will.

Customer Account API: the logged-in customer

The Customer Account API works with an authenticated customer's account, profile and orders. It's useful when building your own customer portal. A specific buyer's access to their own data is a different problem from a server-side connection between the store and an ERP.

For your first integration brief, write one sentence: "We need to transfer this specific data between these systems in this direction." If the team instead starts by choosing a token and only then looks for a use, it's missing an important decision about the purpose of the integration.

Why GraphQL and how to choose a Shopify API version

In a GraphQL request, you specify which fields you need returned. To check the catalog, you can load just the product ID and title; for another task, you add more data according to the documentation. A read operation is called a query, an operation that changes data is a mutation. Both are usually sent via HTTP POST, so the POST method alone doesn't tell you whether the request writes.

The REST Admin API is marked as legacy. Design new integrations on the GraphQL Admin API. That's no reason to switch off a working older integration without preparation. First find out its scope, support and migration plan, so shipping or invoicing doesn't break during the change.

Shopify releases API versions quarterly. For production, choose a supported stable version and state it explicitly in your configuration. In the example, we use version 2026-10. Release candidate and unstable are for evaluating upcoming changes, not an automatic default for everyday operation.

Also record the version in the integration's technical documentation. Decide who monitors changes, when an upgrade will be tested and how you'll roll back to the previous deployment. Compare the requested version with the X-Shopify-API-Version header in the response; a different value can signal a fallback from an old, unavailable version to a supported one.

Authentication, tokens and minimal permissions

Authentication proves who is sending the request. Permissions determine what data that access may read or change. With the Admin API, the server uses an access token passed in the appropriate request header. A person logging in to the Shopify admin is not the same as authenticating an app.

For an initial product read, you need the right access, typically the read_products scope. Don't add permissions for customers, orders or writes just in case. Every extension must have a specific purpose and the store owner's approval. Additional requirements may apply to protected customer data.

New apps and older guides

For a new project, start from the current Dev Dashboard and the app type. An old guide to creating a legacy custom app directly in the admin may not match the current process. How you obtain a token also depends on whether you're connecting your own stores or building an app for other merchants.

The client credentials grant is not a universal shortcut for any client store. The documentation limits it to an app and a store in the same Shopify organization; other scenarios require the appropriate authorization flow. Also include token validity and renewal in your design. Don't rely on the assumption that access, once obtained, works forever.

• Store the token and client secret in server-side secrets management.
• Separate test and production credentials and store configurations.
• Keep diagnostics in logs, but remove tokens and unnecessary personal data.
• Define a procedure for a credential leak, a change of vendor or uninstalling the app.

A first read query: five products from Shopify

The following query is based on the official products example and limits the output to five items. It's an example from the documentation, not the result of our own call against a specific store. To verify it, use a development store and an authorized app with access to read products.

query FirstProducts {
  products(first: 5) {
    nodes {
      id
      title
    }
  }
}

Send the query as a GraphQL operation with the POST method to your own development store's address. The path structure is /admin/api/2026-10/graphql.json. The host is the relevant myshopify.com domain, not the public domain of your customer-facing website. In your HTTP client, set the content type to JSON and the Admin API access token in the X-Shopify-Access-Token header.

If you use a GraphQL editor, you paste the query itself. If you use a generic HTTP client, the JSON body contains this query under the query key. Don't combine examples from different tools without checking their format. There's no mutation in the example, so its only purpose is to read data.

What a successful result should mean

In the full GraphQL Admin API response, expect the requested data in data.products.nodes. Each returned item contains id and title. The count may be less than five, for example when the test store has fewer products. So an empty list doesn't automatically mean a bad token.

The identifier may look like gid://shopify/Product/…. Store the full identifier actually returned, and don't use the product title as a substitute for it. To connect to an ERP, you need a separate mapping to the internal code; moreover, a product and its variants are not the same object. The short query above doesn't return SKUs, inventory or the information needed to change them.

How to recognize success, an error and an unclear result

Check the response, not just the HTTP status. GraphQL can return errors in the errors field along with partial data. With mutations, also evaluate errors for the specific operation, often in userErrors. The app must not mark a sync as complete just because the server responded.

For the first read, compare the loaded titles and identifiers with selected products in the admin. Record the store, API version, time and check result, without credentials. For the first write later on, also verify the actual state of the target object, not just a message that the request was accepted.

If a write times out, you may not know whether the server made the change. Don't blindly repeat such an operation. First look up the result by stored identifiers or another reliable key. The design must account for idempotency, meaning that processing the same business operation again doesn't cause an additional change.

Pagination, limits and webhooks

Five products are not the whole catalog

The first: 5 limit is for a small start. For an actual export, continue with cursor-based pagination and the pageInfo information. Also check nested lists, such as variants. If you get the first page of products and the first page of variants, you may not yet have complete data even for a single product.

The GraphQL Admin API manages load through query cost. Fewer requests don't necessarily mean less load if you load extensive relationships in one request. Monitor the cost and limit information in the response, use a queue and reasonable backoff on retries. For large transfers, also consider bulk operations depending on the task.

A webhook announces an event; it doesn't complete your process

A webhook helps you react to a change without the integration constantly downloading the whole catalog. After receiving it, though, you still have to verify the event, queue it for processing and reflect it in the target system. For HTTPS delivery, verify the HMAC over the raw request body; modifying or parsing the body before the check can invalidate the verification.

Expect repeated deliveries. X-Shopify-Webhook-Id is used to detect duplicate individual deliveries. Events from the same business action can be correlated via X-Shopify-Event-Id. Besides tracking deliveries, also protect the business operation itself from being executed twice.

Complement webhooks with regular comparison of the actual state of the systems. For example, a list of unprocessed orders helps detect an outage that the event receiver alone wouldn't catch. Handle long-running tasks in a queue, so the receiver's response doesn't depend on the availability of the entire ERP.

How to design your first Shopify API integration with an ERP

Start with one limited flow, for example transferring new orders to the ERP. Don't open up two-way changes to products, prices and inventory at the same time if you haven't verified the mapping yet. The business role of the systems is explained in our overview What Is an ERP System and How to Connect It to an Online Store.

Before development, fill in the following rules. The master system determines the authoritative value; the other one takes it over according to the agreed logic. Different systems can be the master for different data.

In the model scenario, Shopify sends one order to the queue and the integration stores the ID of the resulting ERP document with it. When the same delivery arrives again, it doesn't create another document. If the ERP doesn't respond, the task remains traceable and is resolved based on the actual result. This example describes a design, not a finished implementation for a specific accounting system.

For invoicing, also check the moment of issue, currencies, credit notes and accounting rules. The options of specific tools are covered in connecting accounting to Shopify. The general availability of an API doesn't by itself guarantee that a ready-made app supports all your processes.

What to verify before launching the integration

1. Scope and access: the selected store, a supported version and only the necessary permissions.
2. Reading: the right objects, variants and complete pagination.
3. First write: one controlled change and verification of the result in the target system.
4. Outages: behavior with an invalid token, API limits, a timeout and an unavailable ERP.
5. Duplicates: repeated delivery and an uncertain response without executing the same operation twice.
6. Handover to operations: monitoring, credential renewal, API upgrades and an incident contact.

Evaluate a finished integration based on these results. An example of a loaded product proves basic access, not reliable inventory sync. Also include mapping documentation, an operating procedure and how a failed task is handled in the brief.

If a standard app doesn't cover your process, you can use our app and integration development for Shopify. For the first consultation, prepare the names of your systems, the data flows you need, the transfer volume and examples of errors you currently handle manually.

Frequently asked questions about the Shopify API

Is the Shopify API the same as GraphQL?

Shopify offers several APIs for different purposes. GraphQL is a query language used by the Admin API, among others. For an integration, first choose the right API, then the specific operations and permissions.

Can I use an Admin API token in theme code?

No. Visitors can read public code. Keep the Admin token on the server; design customer-facing interfaces with the API and access intended for that purpose.

Why does a query return HTTP 200 and still not work?

Look at the entire response body, especially GraphQL errors and, for change operations, the errors of the specific mutation. The HTTP status alone doesn't confirm that the task was completed correctly.

Is the short query shown enough to transfer products?

It's for a first read of IDs and titles. A full integration needs the required fields, variants, pagination, mapping and error handling. Inventory and prices can't be derived from the product title.

When should you choose a ready-made app and when a custom integration?

Evaluate a ready-made app based on the specific data flows, support and operational checks. Custom development makes sense if you need features or rules that the available solution doesn't cover.

Sources

• Shopify: GraphQL Admin API documentation