Talking to Shopify from your systems

If you've integrated with any platform before, the mental model here is familiar. A Shopify store is a hosted system that owns your commerce data — products, inventory, orders, customers, fulfillment. Your job, as an integration engineer, is to connect that system to the rest of your world: an ERP, a warehouse system, a CRM, a data warehouse, custom pricing logic, and so on.

"Integration layers" is just the set of surfaces where data and control cross the boundary between Shopify and everything else. There are only a few of them, and they each answer a different question:

A useful way to hold all four in your head: the first two are about moving data across the boundary (pull vs push), the third is about injecting logic into Shopify, and the fourth is about getting data out for analysis without abusing the transactional APIs.

One more framing that pays off immediately: in Shopify, almost everything you build attaches to an "app." Even a private integration that only your company uses is technically a custom app. The app is the thing that holds your credentials, your permission scopes, your webhook subscriptions, and your deployed Functions. Keep that in mind as you read — "create an app" keeps showing up because it's the container for all of it.

The Admin API is your main read/write channel into a store. When your backend needs to know about or change something in Shopify, this is almost always how it happens. Typical jobs:

• Sync products and prices from an ERP/PIM into Shopify.
• Pull orders into a data warehouse or accounting system.
• Push inventory levels from a WMS when stock changes.
• Sync customers out to a CRM, or enrich Shopify customers from one.
• Create fulfillments, issue refunds, manage discounts, and so on.

GraphQL vs REST — and the important 2024 change

The Admin API comes in two flavors, but they are no longer equal footing, and this is the single most important thing to internalize as a newcomer:

• GraphQL Admin API — the modern, primary API. You ask for exactly the fields you want in one request, which avoids over-fetching and reduces round-trips. Shopify is investing all new capabilities here (including the larger product/variant limits).
• REST Admin API — the older, familiar resource-per-endpoint style. As of October 1, 2024 it is officially "legacy." Since April 1, 2025, new public apps must be built on GraphQL. Existing/custom apps can still call REST for now, but it receives no new features and Shopify is steering everyone off it.

A tiny GraphQL request looks like this — note you name the fields you want back:

# POST /admin/api/2025-10/graphql.json
query {
  orders(first: 10, query: "financial_status:paid") {
    edges { node {
      id
      name
      createdAt
      totalPriceSet { shopMoney { amount currencyCode } }
    } }
  }
}

When polling is fine vs when you want events

The Admin API is a pull mechanism, so you decide how often to pull. Simple scheduled polling ("sync every 5–15 minutes") is perfectly acceptable when near-real-time is good enough — nightly catalog syncs, periodic reconciliation, batch exports. But polling for things that need to feel instant (e.g. reacting the second an order is placed) is wasteful and laggy. That's exactly what webhooks are for. A very common, healthy pattern is webhooks for "react now" + a periodic poll as a safety net to catch anything missed.

GraphQL in depth — how it actually works

Every GraphQL request — query or mutation — is a single POST to one endpoint:

POST https://{shop}.myshopify.com/admin/api/2026-04/graphql.json
X-Shopify-Access-Token: {your_token}
Content-Type: application/json

The body carries a query string and optionally a variables map. Shopify resolves only the fields you asked for and returns them under a data key. Any server-side problems land in an errors array — the HTTP status can still be 200, so always check errors in the response body, not just the status code.

Queries vs mutations vs subscriptions

Pagination — cursor-based

Shopify GraphQL uses cursor-based pagination. Every list field wraps results in a connection with edges / node and a pageInfo block:

query {
  orders(first: 50, after: "cursor_from_prev_page", query: "financial_status:paid") {
    edges { node { id name createdAt } }
    pageInfo { hasNextPage endCursor }
  }
}

When hasNextPage is true, pass endCursor as the next after argument. Never use offset-based counting — results are not stable across pages that way.

Mutations and userErrors

mutation FulfillOrder($fulfillment: FulfillmentInput!) {
  fulfillmentCreate(fulfillment: $fulfillment) {
    fulfillment { id status trackingInfo { number url } }
    userErrors { field message }
  }
}

userErrors is non-null when Shopify accepts the HTTP request but rejects the business logic (e.g. order already fulfilled, invalid location). Always check it before treating a mutation as successful.

Cost-based rate limiting (calculated query cost)

Unlike REST's request-count bucket, GraphQL uses a point-cost system. Each field and connection depth adds to the cost of a query. The response extensions tell you exactly how much you spent:

// extensions block in every GraphQL response
"extensions": {
  "cost": {
    "requestedQueryCost": 42,
    "actualQueryCost": 38,
    "throttleStatus": {
      "maximumAvailable": 2000,
      "currentlyAvailable": 1962,
      "restoreRate": 100
    }
  }
}

The bucket refills at 100 points/second up to a maximum of 2 000. If currentlyAvailable drops to zero, Shopify returns a THROTTLED error. Back off and retry — do not hammer. In HotWax, the Moqui service that calls GraphQL should read extensions.cost.throttleStatus and insert a sleep when headroom is low.

Bulk operations — for large data pulls

When syncing a full catalog or large order history, individual queries hit cost limits fast. Shopify's Bulk Operations API is the right tool: you kick off an async bulkOperationRunQuery mutation, Shopify processes it server-side, and you download the result as a .jsonl file from a signed URL once the job finishes. HotWax uses this pattern for initial catalog imports from Shopify.

mutation {
  bulkOperationRunQuery(
    query: """
    { products { edges { node { id title variants { edges { node { sku price } } } } } }
    """
  ) {
    bulkOperation { id status }
    userErrors { field message }
  }
}

Poll with { currentBulkOperation { id status url } } until status is COMPLETED, then fetch the url. Each line of the .jsonl is one GraphQL node — parse with a streaming reader to avoid memory pressure.

Key namespaces HotWax uses via GraphQL

Webhooks flip the direction. Instead of you asking Shopify "anything new?", Shopify proactively sends an HTTP POST to a URL you control the moment something happens — an order is created, a product is updated, an order is paid or cancelled, inventory changes, and so on.

You subscribe to specific event topics (like orders/create or products/update) and give Shopify a destination. When the event fires, your endpoint receives a JSON payload describing what changed. A payload skeleton for an order looks roughly like:

// POST from Shopify → https://api.yourco.com/hooks/shopify
{
  "id": 820982911946154500,
  "name": "#1001",
  "financial_status": "paid",
  "line_items": [ { "sku": "ABC-01", "quantity": 2 } ],
  "customer": { "id": 115310627314723950 }
}
// Header: X-Shopify-Hmac-SHA256: <signature you MUST verify>

Webhooks vs polling

Polling is conceptually simpler and stateless-feeling, but it's less real-time and less efficient at scale. Most mature integrations use both: webhooks for immediacy, plus a low-frequency poll to heal any gaps.

Webhooks in depth — subscription methods & HotWax integration

Two ways to register subscriptions

[webhooks]
api_version = "2026-04"

[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated", "orders/cancelled"]
uri    = "https://api.yourco.com/hooks/shopify"

[[webhooks.subscriptions]]
topics = ["inventory_levels/update"]
uri    = "pubsub://your-project:your-topic"

mutation webhookSubscriptionCreate(
  $topic: WebhookSubscriptionTopic!,
  $webhookSubscription: WebhookSubscriptionInput!
) {
  webhookSubscriptionCreate(
    topic: $topic,
    webhookSubscription: $webhookSubscription
  ) {
    webhookSubscription { id topic format uri }
    userErrors { field message }
  }
}

Payload filtering & field trimming

Two customization tools Shopify provides that reduce noise in your handlers:

[[webhooks.subscriptions]]
topics = ["products/update"]
uri    = "https://api.yourco.com/hooks/product-update"
filter = "status:active AND product_type:Apparel"

[[webhooks.subscriptions]]
topics         = ["customers/delete"]
uri            = "https://api.yourco.com/hooks/customer-delete"
include_fields = ["id", "email"]

Key topics HotWax subscribes to

Delivery reliability & retries

Shopify retries failed deliveries (non-2xx or timeout) with exponential backoff for up to 48 hours. This means your handler will see duplicate events. The standard pattern in HotWax's Moqui services is:

1. Acknowledge 200 OK immediately (within 5 seconds).
2. Write the raw payload to a queue / WebhookEvent entity.
3. Abackground service picks it up, checks if the id was already processed (X-Shopify-Webhook-Id header), and skips if so.
4. Otherwise, run the business logic (order import, catalog update, etc.).

HMAC verification — mandatory

Every Shopify webhook carries an X-Shopify-Hmac-SHA256 header — a base64-encoded HMAC-SHA256 of the raw request body, keyed with your app's client secret. Verify it before processing:

// Groovy / Moqui equivalent logic
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

def rawBody    = request.inputStream.bytes
def secret     = "your_client_secret"
def mac        = Mac.getInstance("HmacSHA256")
mac.init(new SecretKeySpec(secret.bytes, "HmacSHA256"))
def computed   = mac.doFinal(rawBody).encodeBase64().toString()
def shopifyHdr = request.getHeader("X-Shopify-Hmac-SHA256")

if (computed != shopifyHdr) return [status: "error", message: "Invalid signature"]

Functions are different in kind from the first two surfaces. Instead of moving data across the boundary, you're shipping a small piece of your logic to run inside Shopify, right in the middle of critical flows where calling out to an external service would be too slow or too risky.

They're how you customize Shopify's own decisions: discount calculations, shipping/delivery option logic, payment method ordering, cart and checkout validations, and similar. Shopify hands your Function a defined input, your code runs in milliseconds, and it returns a decision.

What they're great at — and what they're not

The healthy division of labor: keep complex/heavy logic in your external systems (kept in sync via the Admin API and webhooks), and push only the fast, in-flow decision into a Function. Don't try to make a Function the brain of your integration.

Reporting and BI are a separate concern from your transactional integrations, and conflating them is a classic early mistake. Shopify gives you purpose-built ways to query and export data for analysis, so you don't end up scanning the transactional Admin API to build dashboards.

The main paths:

• ShopifyQL — Shopify's commerce-focused, SQL-like query language for analytics (sales, orders, products, customers, sessions), with built-in time-series and period-comparison support. Historically it lived in the admin's report editor; as of October 2025 you can also run ShopifyQL programmatically via a shopifyqlQuery field on the GraphQL Admin API (and there's a Python SDK for analytics workflows).
• Built-in reports & exports — the admin's own analytics, plus CSV/data exports of orders, customers, products for ad-hoc needs.
• A data warehouse — for anything serious, you move Shopify data (via Admin API / bulk operations / webhooks) into a warehouse and treat Shopify as one source among many.

-- ShopifyQL: monthly sales this year
FROM sales
SHOW total_sales
GROUP BY month
SINCE startOfYear(0y)
ORDER BY month

Built-in reporting vs your own stack

Two concrete architectures a new team can actually ship. Both are intentionally modest — you can layer more on later.

If you remember nothing else: pull with the Admin API, get pushed to via webhooks, inject in-flow decisions with Functions, and pull analytics out separately. Get the four non-negotiables right (rate limits, webhook verification + idempotency, never block checkout, secure secrets) and you'll have a foundation that scales cleanly from your first sync to a full commerce platform integration.