Shopify API Integration Guide: Building Custom Commerce Solutions in 2026

Shopify powers over four million online stores worldwide, and the platform's true potential is unlocked through its robust suite of APIs. Whether you are synchronizing inventory with an ERP system, building a headless storefront, or creating a public app for the Shopify App Store, understanding the API landscape is essential. This guide provides a comprehensive, technical overview of Shopify API integration, covering authentication, rate limits, webhook architecture, and production-ready patterns that ECOSIRE engineers apply across client projects.

Key Takeaways

1. Shopify offers four primary APIs -- Admin, Storefront, Partner, and Payments Apps -- each serving distinct use cases with different authentication models.
2. GraphQL is the strategic direction. Shopify is deprecating REST endpoints incrementally; new features are GraphQL-only. Plan your integration accordingly.
3. Webhook architecture is mandatory for GDPR compliance and for keeping external systems in sync without polling.
4. Rate limiting follows a leaky bucket model for REST and a cost-based points system for GraphQL. Both require deliberate retry and backoff strategies.
5. HMAC verification on every webhook and OAuth callback is non-negotiable. Skipping signature validation exposes your application to spoofed payloads and data tampering.

The Shopify API Landscape

Shopify exposes multiple APIs, each designed for a specific audience and integration pattern.

For most custom commerce solutions, the Admin API and Storefront API cover ninety percent of requirements. The Admin API is your workhorse for server-side operations, while the Storefront API powers any customer-facing experience where you need product data, cart management, or checkout initiation.

If you are evaluating whether to build a custom Shopify integration, our team can help scope the project. Learn more about our Shopify app development services.

GraphQL vs REST

Shopify maintains both GraphQL and REST endpoints for the Admin API, but the trajectory is clear: GraphQL is the future. Since 2023, all new Admin API features have been GraphQL-exclusive.

Comparison

When to Use Which

Use REST when you have a simple, single-resource operation -- checking a single order status, for example -- and your existing codebase already has REST client infrastructure. Use GraphQL for everything else, especially when you need nested data (order with line items, products, and fulfillment status in one call), bulk exports, or access to newer platform features like metaobjects and functions.

Migration Path

If your integration currently relies on REST, prioritize migrating high-volume endpoints first. Bulk data exports, product catalog queries, and order list operations yield the largest performance gains when moved to GraphQL. Shopify's bulkOperationRunQuery mutation can export millions of records asynchronously, replacing what would otherwise require hundreds of paginated REST calls.

Authentication and Authorization

Shopify supports multiple authentication flows depending on the app type and deployment model.

OAuth 2.0 (Public and Custom Apps)

The standard flow for Shopify apps installed by merchants:

1. Merchant initiates install from the Shopify App Store or a direct install link.
2. Your app redirects to https://{shop}.myshopify.com/admin/oauth/authorize with your client_id, requested scopes, and redirect_uri.
3. Merchant approves the requested scopes.
4. Shopify redirects back with a temporary code.
5. Your server exchanges the code for a permanent access_token via POST /admin/oauth/access_token.

Access Scopes

Request the minimum scopes required. Shopify reviews scope requests for public apps, and excessive scope requests are a common rejection reason.

Session Tokens (Embedded Apps)

For apps embedded in the Shopify Admin, session tokens replace cookies. The Shopify App Bridge library issues a JWT that your backend validates using your app's API secret. This eliminates third-party cookie issues and simplifies the authentication flow for embedded experiences.

API Key Authentication (Custom/Private Apps)

For single-store integrations that do not require OAuth, custom apps created directly in the Shopify Admin provide an access token without the redirect flow. This is the simplest path for internal tools and private integrations.

Webhook Architecture

Polling APIs for changes is wasteful and slow. Shopify webhooks push events to your application in near real-time.

Event-Driven Integration

Register webhooks for the events your integration cares about. Common subscriptions include:

• orders/create, orders/updated, orders/paid -- Trigger fulfillment workflows, ERP sync, or notification pipelines.
• products/update, products/delete -- Keep external catalogs or search indexes current.
• inventory_levels/update -- Synchronize stock across channels and warehouses.
• app/uninstalled -- Clean up merchant data and revoke stored credentials.

Mandatory GDPR Webhooks

Shopify requires all apps to handle three GDPR-related webhooks:

1. customers/data_request -- Respond with all stored data for a given customer.
2. customers/redact -- Delete all stored data for a given customer.
3. shop/redact -- Delete all stored data for a shop that uninstalled your app.

Failure to implement these endpoints will block your app from Shopify App Store approval.

Delivery Guarantees and Idempotency

Shopify guarantees at-least-once delivery. Your webhook handler must be idempotent -- processing the same webhook payload twice should produce the same result. Use the X-Shopify-Webhook-Id header as a deduplication key. Store processed webhook IDs and skip duplicates.

If your endpoint returns a non-2xx status code, Shopify retries with exponential backoff for up to 48 hours before removing the subscription.

Rate Limits and Throttling

Understanding rate limits prevents your integration from being throttled during critical operations.

REST: Leaky Bucket

The REST Admin API uses a leaky bucket algorithm with a capacity of 40 requests and a leak rate of 2 requests per second. Each response includes X-Shopify-Shop-Api-Call-Limit (e.g., 32/40) so you can monitor bucket fill level in real time.

GraphQL: Cost-Based Throttling

GraphQL queries consume "cost points" based on query complexity. You receive 1,000 points per second with a bucket maximum of 2,000. Each response includes a throttleStatus extension with currentlyAvailable, maximumAvailable, and restoreRate fields. A simple single-object query might cost 1-2 points; a paginated list query requesting 250 items with nested connections could cost 500+ points.

Retry Strategies

Implement exponential backoff with jitter when you receive a 429 Too Many Requests (REST) or a THROTTLED error (GraphQL). A recommended pattern:

1. On throttle response, wait base_delay * 2^attempt + random_jitter.
2. Start with a base delay of 500ms.
3. Cap maximum retry delay at 30 seconds.
4. After 5 consecutive failures, log the error and alert your operations team.

For bulk data operations, always prefer GraphQL bulk operations over paginated queries. They run asynchronously on Shopify's infrastructure and are not subject to the same rate limits.

Common Integration Patterns

ERP Synchronization

The most frequent enterprise integration connects Shopify to an ERP system like Odoo for bidirectional data flow. Orders created in Shopify propagate to the ERP for fulfillment processing, and inventory updates in the ERP reflect back to Shopify in near real-time.

ECOSIRE specializes in this exact pattern. Our Odoo integration services include pre-built connectors for Shopify that handle order sync, inventory management, customer data mapping, and financial reconciliation.

Inventory Management

Multi-location inventory requires careful orchestration. Use the inventorySetQuantities GraphQL mutation (replacing the deprecated REST inventory adjustment endpoints) to update stock levels. Subscribe to inventory_levels/update webhooks to detect changes made through other channels or directly in the Shopify Admin.

Order Routing

For merchants with multiple warehouses or fulfillment partners, implement order routing logic that evaluates inventory availability, shipping proximity, and fulfillment cost. Shopify's Fulfillment Orders API provides the primitives for assigning fulfillment responsibility to specific locations or third-party services.

Customer Data Synchronization

Synchronizing customer records between Shopify and external CRM or marketing platforms requires handling merge conflicts, consent status, and data format differences. Use the customers/update webhook as the trigger and implement a conflict resolution strategy (e.g., last-write-wins with timestamp comparison, or source-of-truth designation).

Building Custom Shopify Apps

Public vs Custom Apps

App Extensions

Shopify's extension-only app architecture (introduced in 2024 and now the standard) encourages building UI extensions that render directly within the Shopify Admin, checkout, and storefront. Extensions are built with Shopify's UI component library and deployed as part of your app.

Key extension surfaces include:

• Admin action and block extensions for custom workflows within the Shopify Admin.
• Checkout UI extensions for adding custom fields, upsells, or loyalty program integrations at checkout.
• Theme app extensions for embedding app functionality in Online Store themes without liquid code changes.
• Function extensions for server-side logic (discounts, shipping rates, payment customization) that executes on Shopify's infrastructure.

Shopify CLI

The Shopify CLI (@shopify/cli) is the standard development tool for app scaffolding, local development, and deployment. Run shopify app dev to start a local development server with hot reloading, automatic ngrok tunneling, and OAuth handled automatically. It supports Remix (the default app framework), Node.js, PHP, and Ruby backends.

For teams getting started with Shopify development, our store setup services include development environment configuration and architecture planning.

Testing and Debugging

Local Development with Shopify CLI

shopify app dev starts your app locally and creates a secure tunnel. It handles OAuth redirect automatically, so you can test the full install flow against a development store without manual ngrok configuration.

Webhook Testing

Use shopify app webhook trigger to send test webhook payloads to your local endpoint. This is invaluable for testing GDPR webhooks and edge cases (e.g., partially fulfilled orders, refunds) without creating real transactions.

Development Stores

Create unlimited development stores through your Shopify Partner account. These stores have access to all Shopify features (including Plus features) for testing. Populate test data using the Shopify CLI's shopify populate commands or Faker-based seed scripts.

GraphQL Explorer

The Shopify Admin GraphQL Explorer (accessible from the Admin API docs) lets you build and test queries interactively against a real store. Use it to prototype queries before implementing them in code.

Logging and Observability

In production, log all API responses that return errors or unexpected status codes. Track rate limit headers on every response and expose them as metrics in your monitoring system. Set alerts for sustained throttling, which indicates your integration needs optimization.

Security Best Practices

HMAC Verification

Every webhook payload from Shopify includes an X-Shopify-Hmac-SHA256 header. Compute the HMAC-SHA256 of the raw request body using your app's API secret and compare it to the header value using a timing-safe comparison function. Never skip this step, even in development.

OAuth Callback Validation

Verify the hmac query parameter on OAuth callbacks. Reconstruct the query string (excluding the hmac parameter), compute the HMAC, and compare. Also validate the state parameter matches the nonce you generated at the start of the OAuth flow to prevent CSRF attacks.

API Credential Rotation

Rotate API credentials periodically. For custom apps, regenerate access tokens through the Shopify Admin. For public apps with OAuth, the access tokens are permanent but scoped -- if you suspect a token is compromised, revoke it by uninstalling and reinstalling the app.

Scope Minimization

Request only the access scopes your app actually needs. Avoid requesting write access when read is sufficient. Shopify's app review team scrutinizes scope requests, and over-scoped apps face rejection or additional review cycles.

Data Handling

Never store raw credit card data. Shopify handles PCI compliance for checkout, and your integration should never need direct access to payment card numbers. For customer PII, encrypt data at rest, implement access controls, and honor GDPR data deletion requests promptly.

Frequently Asked Questions

What is the difference between the Admin API and the Storefront API?

The Admin API provides full back-office access to store data (products, orders, customers, fulfillment) and requires authenticated access with specific scopes. The Storefront API is designed for customer-facing experiences and exposes a limited, read-heavy dataset (products, collections, cart, checkout) using a public access token that can safely be included in client-side code.

Can I use both REST and GraphQL in the same integration?

Yes. Many production integrations use both, especially during migration. However, be aware that REST and GraphQL rate limits are tracked separately, and some operations (like bulk exports) are only available via GraphQL. Plan to consolidate on GraphQL for long-term maintainability.

How do I handle Shopify API versioning?

Shopify releases a new API version quarterly (e.g., 2026-01, 2026-04). Each version is supported for approximately 12 months. Pin your integration to a specific version in the API URL (e.g., /admin/api/2026-01/graphql.json) and schedule quarterly reviews to adopt new versions before old ones are deprecated.

What happens if my webhook endpoint goes down?

Shopify retries failed webhook deliveries with exponential backoff for up to 48 hours. If all retries fail, the webhook subscription is automatically removed. Your app should periodically verify that its webhook subscriptions are active and re-register any that have been removed. Implement a health check that compares registered webhooks against expected subscriptions.

Do I need a Shopify Plus plan for API access?

No. All Shopify plans (including Basic) provide API access. However, certain features like the Multipass API for SSO, some checkout customization capabilities, and higher API rate limits are exclusive to Shopify Plus.

---

Build Your Shopify Integration with ECOSIRE

Whether you need a lightweight webhook integration, a full ERP connector, or a custom public app for the Shopify App Store, ECOSIRE's engineering team has the expertise to deliver production-grade solutions. We have built and maintained Shopify integrations across industries including retail, manufacturing, and wholesale distribution.

Contact ECOSIRE to discuss your Shopify integration requirements and get a detailed technical proposal.