Shopify

​

At a glance

npx @deploybaseline/cli start --service shopify

import { createEmulator } from "@deploybaseline/cli";

const shopify = await createEmulator({ service: "shopify" });
// shopify.url is http://localhost:4000

{
  "shopify": {
    "shop": {
      "domain": "baseline-store.myshopify.com",
      "name": "Baseline Store",
      "currency": "USD"
    },
    "apps": [
      {
        "name": "My app",
        "api_key": "my-app-key",
        "api_secret_key": "my-app-secret",
        "scopes": ["write_products", "write_orders", "write_customers"],
        "redirect_urls": ["http://localhost:3000/auth/callback"],
        "application_url": "http://localhost:3000",
        "access_token": "shpat_baseline_admin_token"
      }
    ],
    "products": [
      {
        "title": "Snowboard",
        "options": [
          {
            "name": "Size",
            "values": ["154", "158"]
          }
        ],
        "variants": [
          {
            "options": ["154"],
            "price": "600.00",
            "sku": "SB-154",
            "inventory_quantity": 10
          },
          {
            "options": ["158"],
            "price": "650.00",
            "sku": "SB-158",
            "inventory_quantity": 4
          }
        ]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service shopify

import { createAdminApiClient } from "@shopify/admin-api-client";

const shop = "baseline-store.myshopify.com";
const client = createAdminApiClient({
  storeDomain: shop,
  apiVersion: "2026-10",
  accessToken: "shpat_baseline_admin_token",
  customFetchApi: (url, init) => fetch(String(url).replace(`https://${shop}`, process.env.SHOPIFY_EMULATOR_URL!), init),
});
const { data } = await client.request(`{ products(first: 5) { nodes { id title } } }`);

import "@shopify/shopify-api/adapters/web-api";
import { setAbstractFetchFunc } from "@shopify/shopify-api/runtime";

setAbstractFetchFunc((input, init) => {
  const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
  if (url.hostname.endsWith(".myshopify.com")) {
    const emulator = new URL(process.env.SHOPIFY_EMULATOR_URL!);
    url.protocol = emulator.protocol;
    url.host = emulator.host;
  }
  return fetch(url, init);
});

​

URL mapping

​

Auth

• Tokens seeded as an app’s access_token act as that app (installed, with its scopes).
• Any other token the CLI accepts acts as the first app with every scope, so a quick start needs no setup.
• An unknown, revoked, or expired token answers HTTP 401 {"errors":"[API] Invalid API key or access token (unrecognized login or wrong password)"}.
• A field outside the token’s scopes answers ACCESS_DENIED (Access denied for productCreate field. Required access: \write_products` access scope.`). A write scope includes its read scope.

​

API versions

​

OAuth

• GET /admin/oauth/authorize — Install screen: the app, the scopes it asks for, and a button per staff member. client_id must be a seeded app and redirect_uri one of its redirect_urls (or under its application_url when it has none). grant_options[]=per-user asks for an online token.
• POST /admin/oauth/authorize — Approve install: installs the app with the scopes and redirects to redirect_uri with code, host, shop, state, timestamp, and hmac.
• POST /admin/oauth/access_token — Get access token: JSON or form body with client_id and client_secret. Grants below.
• GET /admin/oauth/access_scopes.json — List access scopes: {"access_scopes":[{"handle":"write_products"}]} for the token in X-Shopify-Access-Token.
• GET /admin/apps/<api key or handle> — Open app: as the Shopify admin does, a redirect to its application_url with the signed query, plus embedded=1, id_token (a session token), session, and locale for embedded apps. An app that is not installed yet is installed with its configured scopes first (managed installation). ?staff=<email> picks the user.

• Authorization code: code from the redirect, once, within ten minutes. An offline token (shpat_) never expires; with expiring=1 it lasts an hour and comes with a refresh_token that lasts 90 days. An online token (shpua_) lasts a day and carries associated_user and associated_user_scope.
• Token exchange (grant_type=urn:ietf:params:oauth:grant-type:token-exchange): a session token as subject_token with subject_token_type=urn:ietf:params:oauth:token-type:id_token, for an online or offline token (requested_token_type). The session token must be signed with the app’s client secret (HS256), be for the app’s client ID (aud) and this shop (dest), and not be expired. A non-expiring offline token as subject_token with the offline token type migrates it to an expiring one and revokes the old token.
• Refresh token (grant_type=refresh_token): a new expiring offline token; the old token and refresh token stop working.
• Client credentials (grant_type=client_credentials): a 24 hour offline token for an installed app.

​

GraphQL

• Products: products, productsCount, product, productByHandle, productByIdentifier, productVariants, productVariantsCount, productVariant, inventoryItem.
• Product mutations: productCreate (with productOptions and media), productUpdate, productDelete, productVariantsBulkCreate (with the REMOVE_STANDALONE_VARIANT and PRESERVE_STANDALONE_VARIANT strategies), productVariantsBulkUpdate, productVariantsBulkDelete, productOptionsCreate. Problems come back in userErrors with Shopify’s messages and codes (Title can't be blank, VARIANT_ALREADY_EXISTS, CANNOT_DELETE_LAST_VARIANT).
• Customers: customers, customersCount, customer, customerByIdentifier, customerCreate, customerUpdate, customerDelete, customerAddressCreate, customerAddressUpdate, customerAddressDelete, customerUpdateDefaultAddress.
• Orders: orders, ordersCount, order, orderByIdentifier, orderCreate, orderUpdate, orderCancel, orderClose, orderOpen, orderMarkAsPaid, orderCapture, refundCreate, tagsAdd, tagsRemove.
• Fulfillment: fulfillmentOrders, fulfillmentOrder, fulfillment, fulfillmentCreate, fulfillmentCancel, fulfillmentTrackingInfoUpdate, fulfillmentOrderHold, fulfillmentOrderReleaseHold.
• Shop: shop, app, appInstallation, currentAppInstallation, currentStaffMember, staffMember, locations, locationsCount, location, node, nodes, job, appUninstall.
• Webhooks: webhookSubscriptions, webhookSubscriptionsCount, webhookSubscription, webhookSubscriptionCreate, webhookSubscriptionUpdate, webhookSubscriptionDelete. See Webhooks.

​

Customers

​

Orders

• orderCapture captures part or all of an authorization (finalCapture voids the rest) and refuses more than is left.
• orderMarkAsPaid records a manual sale for the outstanding amount.
• refundCreate refunds line items (RETURN, CANCEL, and LEGACY_RESTOCK put stock back), shipping, and money through REFUND transactions, up to the net payment received.
• orderCancel returns a Job (done when polled with job), and with refundMethod: { originalPaymentMethodsRefund: true } refunds the net payment, voids open authorizations, restocks when asked, closes the order and its fulfillment orders, and sets cancelledAt, cancelReason, and cancellation.staffNote. Orders with fulfillments cannot be cancelled.
• orderClose and orderOpen archive and unarchive; a cancelled order cannot be reopened.

​

Fulfillment orders

​

Unmodeled fields

​

Pagination

​

Search syntax

{
  "path": ["products"],
  "query": "colour:red",
  "parsed": { "field": "default", "match_all": "colour:red" },
  "warnings": [{ "field": "colour", "message": "Invalid search field for this query." }]
}

​

Query cost

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 2,
      "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1998, "restoreRate": 100 }
    }
  }
}

​

Webhooks

• includeFields cuts the payload to the named fields; nested fields use dots (line_items.title).
• filter takes the search syntax over the payload’s fields, with dots for nested fields (total_price:>100, variants.price:>=10.00). A payload that does not match is not sent.
• A subscription needs the topic’s read scope (read_orders for orders, transactions, refunds, and fulfillments), else userErrors explains which scope is missing. The same address twice for a topic is Address for this topic has already been taken. Pub/Sub and EventBridge addresses and the XML format are refused.
• A delivery fails when the address does not answer 2xx within five seconds. Failed deliveries are retried eight times, after 1, 2, 4, 8, 16, 32, 60, and 60 seconds (Shopify spreads them over four hours).
• An app sees and changes only its own subscriptions.
• Uninstalling an app (appUninstall, or the inspector’s Uninstall button) sends its app/uninstalled webhooks with the shop as payload, then revokes its tokens and deletes its subscriptions.

​

Seed config

{
  "shopify": {
    "shop": {
      "domain": "baseline-store.myshopify.com",
      "name": "Baseline Store",
      "currency": "USD",
      "throttle": {
        "maximum": 2000,
        "restore_rate": 100
      }
    },
    "apps": [
      {
        "name": "My app",
        "api_key": "my-app-key",
        "api_secret_key": "my-app-secret",
        "scopes": ["write_products", "write_orders", "write_customers"],
        "redirect_urls": ["http://localhost:3000/auth/callback"],
        "application_url": "http://localhost:3000",
        "embedded": true,
        "access_token": "shpat_baseline_admin_token",
        "webhooks": [
          {
            "topic": "orders/create",
            "uri": "http://localhost:3000/webhooks",
            "include_fields": ["id", "total_price"]
          }
        ]
      }
    ],
    "locations": [
      {
        "name": "Warehouse",
        "city": "Ottawa",
        "country_code": "CA"
      }
    ],
    "products": [
      {
        "title": "Snowboard",
        "vendor": "Hydrogen",
        "tags": ["winter"],
        "options": [
          {
            "name": "Size",
            "values": ["154", "158"]
          }
        ],
        "variants": [
          {
            "options": ["154"],
            "price": "600.00",
            "sku": "SB-154",
            "inventory_quantity": 10
          },
          {
            "options": ["158"],
            "price": "650.00",
            "sku": "SB-158"
          }
        ],
        "images": [
          {
            "src": "https://cdn.example.com/snowboard.png",
            "alt": "Snowboard"
          }
        ]
      }
    ],
    "customers": [
      {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "[email protected]",
        "tags": ["vip"],
        "addresses": [
          {
            "address1": "12 Analytical Row",
            "city": "London",
            "country_code": "GB"
          }
        ]
      }
    ],
    "orders": [
      {
        "customer": "[email protected]",
        "line_items": [
          {
            "sku": "SB-154",
            "quantity": 1
          },
          {
            "title": "Wax",
            "price": "15.00",
            "quantity": 2
          }
        ],
        "shipping_lines": [
          {
            "title": "Standard",
            "price": "10.00"
          }
        ],
        "financial_status": "PAID",
        "fulfillment_status": "FULFILLED",
        "tags": ["seeded"]
      }
    ]
  }
}

​

Inspector

​

Limits

​

Conformance