@shopify/shopify-api 13.0.0 → 14.0.0

package/lib/__test-helpers__/graphql-base-request.ts

@@ -5,6 +5,6 @@ export const ACCESS_TOKEN = 'access-token';
 export const GRAPHQL_BASE_REQUEST = {
   method: 'POST',
   domain: DOMAIN,
-  path: `/admin/api/${ApiVersion.July25}/graphql.json`,
+  path: `/admin/api/${ApiVersion.July26}/graphql.json`,
   headers: {'X-Shopify-Access-Token': ACCESS_TOKEN},
 };

package/lib/auth/oauth/create-session.ts

@@ -31,7 +31,7 @@ export function createSession({
     new Date(Date.now() + expires_in * 1000);
 
   const getOnlineSessionProperties = (responseBody: OnlineAccessResponse) => {
-    const {access_token, scope, ...rest} = responseBody;
+    const {access_token: _access_token, scope: _scope, ...rest} = responseBody;
     const sessionId = config.isEmbeddedApp
       ? getJwtSessionId(config)(
           shop,

package/lib/auth/oauth/nonce.ts

@@ -1,15 +1,7 @@
+import {asHex} from '../../../runtime/crypto';
+
 export type Nonce = () => string;
 
 export function nonce(): string {
-  const length = 15;
-
-  const bytes = crypto.getRandomValues(new Uint8Array(length));
-
-  const nonce = bytes
-    .map((byte: number) => {
-      return byte % 10;
-    })
-    .join('');
-
-  return nonce;
+  return asHex(crypto.getRandomValues(new Uint8Array(32)));
 }

package/lib/auth/oauth/oauth.ts

@@ -217,11 +217,15 @@ export function callback(config: ConfigInterface): OAuthCallback {
     });
 
     if (!config.isEmbeddedApp) {
+      const cookiePath =
+        typeof config.cookiePath === 'function'
+          ? config.cookiePath(session)
+          : (config.cookiePath ?? '/');
       await cookies.setAndSign(SESSION_COOKIE_NAME, session.id, {
         expires: session.expires,
         sameSite: 'lax',
         secure: true,
-        path: '/',
+        path: cookiePath,
       });
     }
 

package/lib/auth/oauth/safe-compare.ts

@@ -23,7 +23,10 @@ export const safeCompare: SafeCompare = (strA, strB) => {
 };
 
 // Buffer must be same length for this function to be secure.
-function timingSafeEqual(bufA: ArrayBuffer, bufB: ArrayBuffer): boolean {
+function timingSafeEqual(
+  bufA: ArrayBuffer | Uint8Array,
+  bufB: ArrayBuffer | Uint8Array,
+): boolean {
   const viewA = new Uint8Array(bufA);
   const viewB = new Uint8Array(bufB);
   let out = 0;

package/lib/base-types.ts

@@ -3,6 +3,7 @@ import {ShopifyRestResources} from '../rest/types';
 
 import {AuthScopes} from './auth/scopes';
 import {BillingConfig} from './billing/types';
+import {Session} from './session/session';
 import {ApiVersion, DomainTransformation, LogSeverity} from './types';
 
 /**
@@ -135,6 +136,33 @@ export interface ConfigParams<
    * @private
    */
   _logDisabledFutureFlags?: boolean;
+  /**
+   * The path to use for the OAuth session cookie in non-embedded apps.
+   *
+   * By default the cookie is written with `path: '/'`, making it domain-wide.
+   * This means that when a user authenticates multiple shops in separate tabs,
+   * each OAuth callback overwrites the previous cookie, causing all tabs to use
+   * the most-recently-authenticated shop.
+   *
+   * Set this to a string or a function returning a string to scope the cookie to
+   * a URL path prefix that is unique per shop. The browser will then maintain
+   * one cookie per shop and deliver only the matching one per request.
+   *
+   * **Requirement:** the configured path must match the actual URL structure of
+   * your app — e.g. if each shop lives under `/shops/:shop/`, use that prefix.
+   * The library cannot derive this automatically.
+   *
+   * @example
+   * // Static path (single-shop apps or apps with no shop-specific routing)
+   * cookiePath: '/'
+   *
+   * @example
+   * // Factory function (multi-shop non-embedded apps)
+   * cookiePath: (session) => `/shops/${session.shop}/`
+   *
+   * @defaultValue `'/'`
+   */
+  cookiePath?: string | ((session: Session) => string);
   /**
    * Whether the app is initialised for local testing.
    */

package/lib/billing/types.ts

@@ -66,8 +66,7 @@ export interface BillingConfigSubscriptionPlanDiscount {
 }
 
 export type BillingConfigItem =
-  | BillingConfigOneTimePlan
-  | BillingConfigSubscriptionLineItemPlan;
+  BillingConfigOneTimePlan | BillingConfigSubscriptionLineItemPlan;
 
 // Type this as an interface to improve TSDoc support for it.
 
@@ -590,8 +589,7 @@ export interface SinglePaymentResponse {
 }
 
 export type RequestResponseData =
-  | AppSubscriptionCreate
-  | AppPurchaseOneTimeCreate;
+  AppSubscriptionCreate | AppPurchaseOneTimeCreate;
 
 export interface SubscriptionResponse {
   currentAppInstallation?: ActiveSubscriptions;

package/lib/config.ts

@@ -53,7 +53,7 @@ export function validateConfig<Params extends ConfigParams>(
     throw new ShopifyError(
       `Cannot initialize Shopify API Library. Missing values for: ${missing.join(
         ', ',
-      )}. For apiVersion, please specify an explicit API version (e.g., ApiVersion.July25). See https://shopify.dev/docs/api/usage/versioning for more information.`,
+      )}. For apiVersion, please specify an explicit API version (e.g., ApiVersion.July26). See https://shopify.dev/docs/api/usage/versioning for more information.`,
     );
   }
 
@@ -85,7 +85,7 @@ export function validateConfig<Params extends ConfigParams>(
     isCustomStoreApp: isCustomStoreApp ?? config.isCustomStoreApp,
     adminApiAccessToken: adminApiAccessToken ?? config.adminApiAccessToken,
     userAgentPrefix: userAgentPrefix ?? config.userAgentPrefix,
-    logger: {...config.logger, ...(logger || {})},
+    logger: {...config.logger, ...logger},
     privateAppStorefrontAccessToken:
       privateAppStorefrontAccessToken ?? config.privateAppStorefrontAccessToken,
     billing: billing ?? config.billing,

package/lib/types.ts

@@ -13,6 +13,8 @@ export enum ApiVersion {
   October25 = '2025-10',
   January26 = '2026-01',
   April26 = '2026-04',
+  July26 = '2026-07',
+  October26 = '2026-10',
   Unstable = 'unstable',
 }
 
@@ -25,7 +27,6 @@ export enum ShopifyHeader {
   Domain = 'X-Shopify-Shop-Domain',
   Hmac = 'X-Shopify-Hmac-Sha256',
   Topic = 'X-Shopify-Topic',
-  SubTopic = 'X-Shopify-Sub-Topic',
   WebhookId = 'X-Shopify-Webhook-Id',
   Name = 'X-Shopify-Name',
   TriggeredAt = 'X-Shopify-Triggered-At',
@@ -42,6 +43,7 @@ export const ShopifyEventsHeader = {
   Domain: 'shopify-shop-domain',
   ApiVersion: 'shopify-api-version',
   EventId: 'shopify-event-id',
+  WebhookId: 'shopify-webhook-id',
   Handle: 'shopify-handle',
   Action: 'shopify-action',
   ResourceId: 'shopify-resource-id',

package/lib/utils/hmac-validator.ts

@@ -23,8 +23,15 @@ import {
 } from './types';
 
 const HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC = 90;
+const APP_PROXY_SINGLE_VALUE_PARAMS = new Set([
+  'hmac',
+  'shop',
+  'signature',
+  'timestamp',
+]);
 
 export type HMACSignator = 'admin' | 'appProxy';
+type HmacQuery = AuthQuery | URLSearchParams;
 
 export interface ValidateParams extends AdapterArgs {
   /**
@@ -63,7 +70,7 @@ export function generateLocalHmac(config: ConfigInterface) {
     params: AuthQuery,
     signator: HMACSignator = 'admin',
   ): Promise<string> => {
-    const {hmac, signature, ...query} = params;
+    const {hmac: _hmac, signature: _signature, ...query} = params;
 
     const queryString =
       signator === 'admin'
@@ -76,30 +83,73 @@ export function generateLocalHmac(config: ConfigInterface) {
 
 export function validateHmac(config: ConfigInterface) {
   return async (
-    query: AuthQuery,
+    query: HmacQuery,
     {signator}: {signator: HMACSignator} = {signator: 'admin'},
   ): Promise<boolean> => {
-    if (signator === 'admin' && !query.hmac) {
+    const normalizedQuery = normalizeQuery(query, signator);
+
+    if (signator === 'admin' && !normalizedQuery.hmac) {
       throw new ShopifyErrors.InvalidHmacError(
         'Query does not contain an HMAC value.',
       );
     }
 
-    if (signator === 'appProxy' && !query.signature) {
+    if (signator === 'appProxy' && !normalizedQuery.signature) {
       throw new ShopifyErrors.InvalidHmacError(
         'Query does not contain a signature value.',
       );
     }
 
-    validateHmacTimestamp(query);
+    validateHmacTimestamp(normalizedQuery);
 
-    const hmac = signator === 'appProxy' ? query.signature : query.hmac;
-    const localHmac = await generateLocalHmac(config)(query, signator);
+    const hmac =
+      signator === 'appProxy'
+        ? normalizedQuery.signature
+        : normalizedQuery.hmac;
+    const localHmac = await generateLocalHmac(config)(
+      normalizedQuery,
+      signator,
+    );
 
     return safeCompare(hmac as string, localHmac);
   };
 }
 
+function normalizeQuery(query: HmacQuery, signator: HMACSignator): AuthQuery {
+  if (!(query instanceof URLSearchParams)) {
+    if (signator === 'appProxy') {
+      for (const key of APP_PROXY_SINGLE_VALUE_PARAMS) {
+        if (Array.isArray(query[key])) {
+          throw new ShopifyErrors.InvalidHmacError(
+            `Query parameter "${key}" must not appear more than once.`,
+          );
+        }
+      }
+    }
+
+    return query;
+  }
+
+  const normalizedQuery = Object.create(null) as AuthQuery;
+  for (const [key, value] of query.entries()) {
+    const existingValue = normalizedQuery[key];
+    if (existingValue === undefined) {
+      normalizedQuery[key] = value;
+    } else if (
+      signator === 'appProxy' &&
+      APP_PROXY_SINGLE_VALUE_PARAMS.has(key)
+    ) {
+      throw new ShopifyErrors.InvalidHmacError(
+        `Query parameter "${key}" must not appear more than once.`,
+      );
+    } else {
+      normalizedQuery[key] = `${existingValue},${value}`;
+    }
+  }
+
+  return normalizedQuery;
+}
+
 export async function validateHmacString(
   config: ConfigInterface,
   data: string,
@@ -151,8 +201,28 @@ export function validateHmacFromRequestFactory(config: ConfigInterface) {
 }
 
 function validateHmacTimestamp(query: AuthQuery) {
+  const {timestamp} = query;
+
+  if (
+    timestamp === undefined ||
+    timestamp === null ||
+    Array.isArray(timestamp)
+  ) {
+    throw new ShopifyErrors.InvalidHmacError(
+      'HMAC timestamp is missing or invalid',
+    );
+  }
+
+  const parsedTimestamp = Number(timestamp);
+
+  if (!Number.isInteger(parsedTimestamp)) {
+    throw new ShopifyErrors.InvalidHmacError(
+      'HMAC timestamp is missing or invalid',
+    );
+  }
+
   if (
-    Math.abs(getCurrentTimeInSec() - Number(query.timestamp)) >
+    Math.abs(getCurrentTimeInSec() - parsedTimestamp) >
     HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC
   ) {
     throw new ShopifyErrors.InvalidHmacError(

package/lib/utils/processed-query.ts

@@ -47,7 +47,7 @@ export default class ProcessedQuery {
   }
 
   stringify(omitQuestionMark = false): string {
-    const queryString = this.processedQuery.toString();
+    const queryString = this.processedQuery.toString().replace(/\+/g, '%20');
     return omitQuestionMark ? queryString : `?${queryString}`;
   }
 }

package/lib/version.ts

@@ -1 +1 @@
-export const SHOPIFY_API_LIBRARY_VERSION = '13.0.0';
+export const SHOPIFY_API_LIBRARY_VERSION = '14.0.0';

package/lib/webhooks/process.ts

@@ -143,7 +143,7 @@ async function callWebhookHandlers(
         response,
       });
     }
-    const {webhookId, subTopic} = webhookCheck;
+    const {webhookId} = webhookCheck;
 
     try {
       await handler.callback(
@@ -152,7 +152,6 @@ async function callWebhookHandlers(
         rawBody,
         webhookId,
         webhookCheck.apiVersion,
-        ...(subTopic ? subTopic : ''),
         context,
       );
     } catch (error) {

package/lib/webhooks/register.ts

@@ -414,11 +414,6 @@ function buildMutation(
       params.metafieldNamespaces = JSON.stringify(handler.metafieldNamespaces);
     }
 
-    if (handler.subTopic) {
-      const subTopicString = `subTopic: "${handler.subTopic}",`;
-      mutationArguments.MUTATION_PARAMS = subTopicString;
-    }
-
     const paramsString = Object.entries(params)
       .map(([key, value]) => `${key}: ${value}`)
       .join(', ');

package/lib/webhooks/types.ts

@@ -17,7 +17,6 @@ export const WEBHOOK_HEADER_NAMES = {
     domain: ShopifyHeader.Domain,
     apiVersion: ShopifyHeader.ApiVersion,
     webhookId: ShopifyHeader.WebhookId,
-    subTopic: ShopifyHeader.SubTopic,
     name: ShopifyHeader.Name,
     triggeredAt: ShopifyHeader.TriggeredAt,
     eventId: ShopifyHeader.EventId,
@@ -27,6 +26,7 @@ export const WEBHOOK_HEADER_NAMES = {
     topic: ShopifyEventsHeader.Topic,
     domain: ShopifyEventsHeader.Domain,
     apiVersion: ShopifyEventsHeader.ApiVersion,
+    webhookId: ShopifyEventsHeader.WebhookId,
     eventId: ShopifyEventsHeader.EventId,
     handle: ShopifyEventsHeader.Handle,
     action: ShopifyEventsHeader.Action,
@@ -47,7 +47,6 @@ export type WebhookHandlerFunction = (
   body: string,
   webhookId: string,
   apiVersion?: string,
-  subTopic?: string,
   context?: any,
 ) => Promise<void>;
 
@@ -55,7 +54,6 @@ interface BaseWebhookHandler {
   id?: string;
   includeFields?: string[];
   metafieldNamespaces?: string[];
-  subTopic?: string;
   context?: any;
 }
 
@@ -126,9 +124,7 @@ interface WebhookPubSubEndpoint {
 }
 
 type WebhookEndpoint =
-  | WebhookHttpEndpoint
-  | WebhookEventBridgeEndpoint
-  | WebhookPubSubEndpoint;
+  WebhookHttpEndpoint | WebhookEventBridgeEndpoint | WebhookPubSubEndpoint;
 
 export interface WebhookCheckResponseNode<
   T = {
@@ -184,13 +180,13 @@ interface BaseWebhookFields {
 export interface WebhooksWebhookFields extends BaseWebhookFields {
   webhookType: typeof WebhookType.Webhooks;
   webhookId: string;
-  subTopic?: string;
   name?: string;
   eventId?: string;
 }
 
 export interface EventsWebhookFields extends BaseWebhookFields {
   webhookType: typeof WebhookType.Events;
+  webhookId: string;
   eventId: string;
   handle?: string;
   action?: string;

package/lib/webhooks/validate.ts

@@ -133,9 +133,6 @@ function checkWebhooksHeaders(
     webhookId: webhookId!,
   };
 
-  const subTopic = getHeader(headers, headerNames.subTopic);
-  if (subTopic) fields.subTopic = subTopic;
-
   const name = getHeader(headers, headerNames.name);
   if (name) fields.name = name;
 
@@ -162,6 +159,11 @@ function checkEventsHeaders(
     headerNames.apiVersion,
     missingHeaders,
   );
+  const webhookId = getRequiredHeader(
+    headers,
+    headerNames.webhookId,
+    missingHeaders,
+  );
   const eventId = getRequiredHeader(
     headers,
     headerNames.eventId,
@@ -182,6 +184,7 @@ function checkEventsHeaders(
     topic: topicForStorage(topic!),
     domain: domain!,
     apiVersion: apiVersion!,
+    webhookId: webhookId!,
     eventId: eventId!,
   };
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shopify/shopify-api",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "Shopify API Library for Node - accelerate development with support for authentication, graphql proxy, webhooks",
   "types": "./dist/ts/lib/index.d.ts",
   "module": "./dist/esm/lib/index.mjs",
   "main": "./dist/cjs/lib/index.js",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "exports": {
     ".": {
@@ -71,24 +71,24 @@
     "Storefront API"
   ],
   "dependencies": {
-    "@shopify/admin-api-client": "^1.1.2",
-    "@shopify/graphql-client": "^1.4.2",
-    "@shopify/storefront-api-client": "^1.0.10",
+    "@shopify/admin-api-client": "^2.0.0",
+    "@shopify/graphql-client": "^2.0.0",
+    "@shopify/storefront-api-client": "^2.0.0",
     "compare-versions": "^6.1.1",
-    "isbot": "^5.1.34",
+    "isbot": "^5.2.0",
     "jose": "^5.9.6",
     "lossless-json": "^4.3.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260124.0",
+    "@cloudflare/workers-types": "^4.20260702.1",
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
     "jest-environment-miniflare": "^2.14.4",
-    "miniflare": "^4.20260120.0",
-    "rollup": "^4.57.0",
+    "miniflare": "^4.20260708.1",
+    "rollup": "^4.62.2",
     "supertest": "^7.2.2",
-    "wrangler": "^4.60.0"
+    "wrangler": "^4.111.0"
   },
   "files": [
     "dist/*",
@@ -112,7 +112,6 @@
     "pretest:adapters": "pnpm rollup -c adapters/__e2etests__/rollup.test-apps.config.js",
     "test:adapters": "jest --selectProjects adapters:mock adapters:node adapters:cf-worker adapters:web-api",
     "test:rest_resources": "jest --selectProjects rest_resources",
-    "lint": "eslint .",
     "test:dev": "jest --selectProjects library",
     "build": "pnpm rollup -c rollup.config.js && pnpm tsc -p ./tsconfig.build.json",
     "tsc": "tsc",

package/rest/admin/2026-04/abandoned_checkout.ts

@@ -0,0 +1,112 @@
+/***********************************************************************************************************************
+* This file is auto-generated. If you have an issue, please create a GitHub issue.                                     *
+***********************************************************************************************************************/
+
+import {Base} from '../../base';
+import {ResourcePath, ResourceNames} from '../../types';
+import {Session} from '../../../lib/session/session';
+import {ApiVersion} from '../../../lib/types';
+
+import {Currency} from './currency';
+import {Customer} from './customer';
+import {DiscountCode} from './discount_code';
+
+interface CheckoutsArgs {
+  [key: string]: unknown;
+  session: Session;
+  since_id?: unknown;
+  created_at_min?: unknown;
+  created_at_max?: unknown;
+  updated_at_min?: unknown;
+  updated_at_max?: unknown;
+  status?: unknown;
+  limit?: unknown;
+}
+
+export class AbandonedCheckout extends Base {
+  public static apiVersion = ApiVersion.April26;
+
+  protected static hasOne: {[key: string]: typeof Base} = {
+    "currency": Currency,
+    "customer": Customer
+  };
+  protected static hasMany: {[key: string]: typeof Base} = {
+    "discount_codes": DiscountCode
+  };
+  protected static paths: ResourcePath[] = [
+    {"http_method": "get", "operation": "checkouts", "ids": [], "path": "checkouts.json"},
+    {"http_method": "get", "operation": "checkouts", "ids": [], "path": "checkouts.json"}
+  ];
+  protected static resourceNames: ResourceNames[] = [
+    {
+      "singular": "abandoned_checkout",
+      "plural": "abandoned_checkouts"
+    }
+  ];
+
+  public static async checkouts(
+    {
+      session,
+      since_id = null,
+      created_at_min = null,
+      created_at_max = null,
+      updated_at_min = null,
+      updated_at_max = null,
+      status = null,
+      limit = null,
+      ...otherArgs
+    }: CheckoutsArgs
+  ): Promise<unknown> {
+    const response = await this.request<AbandonedCheckout>({
+      http_method: "get",
+      operation: "checkouts",
+      session: session,
+      urlIds: {},
+      params: {"since_id": since_id, "created_at_min": created_at_min, "created_at_max": created_at_max, "updated_at_min": updated_at_min, "updated_at_max": updated_at_max, "status": status, "limit": limit, ...otherArgs},
+      body: {},
+      entity: null,
+    });
+
+    return response ? response.body : null;
+  }
+
+  public abandoned_checkout_url: string | null;
+  public billing_address: {[key: string]: unknown} | null;
+  public buyer_accepts_marketing: boolean | null;
+  public buyer_accepts_sms_marketing: boolean | null;
+  public cart_token: string | null;
+  public closed_at: string | null;
+  public completed_at: string | null;
+  public created_at: string | null;
+  public currency: Currency | null | {[key: string]: any};
+  public customer: Customer | null | {[key: string]: any};
+  public customer_locale: string | null;
+  public device_id: string | null;
+  public discount_codes: DiscountCode[] | null | {[key: string]: any};
+  public email: string | null;
+  public gateway: string | null;
+  public id: string | null;
+  public landing_site: string | null;
+  public line_items: {[key: string]: unknown} | null;
+  public location_id: string | null;
+  public note: string | null;
+  public phone: string | null;
+  public presentment_currency: string | null;
+  public referring_site: string | null;
+  public shipping_address: {[key: string]: unknown} | null;
+  public shipping_lines: {[key: string]: unknown} | null;
+  public sms_marketing_phone: string | null;
+  public source_name: string | null;
+  public subtotal_price: string | null;
+  public tax_lines: {[key: string]: unknown} | null;
+  public taxes_included: boolean | null;
+  public token: string | null;
+  public total_discounts: string | null;
+  public total_duties: string | null;
+  public total_line_items_price: string | null;
+  public total_price: string | null;
+  public total_tax: string | null;
+  public total_weight: number | null;
+  public updated_at: string | null;
+  public user_id: string | null;
+}

package/rest/admin/2026-04/access_scope.ts

@@ -0,0 +1,48 @@
+/***********************************************************************************************************************
+* This file is auto-generated. If you have an issue, please create a GitHub issue.                                     *
+***********************************************************************************************************************/
+
+import {Base, FindAllResponse} from '../../base';
+import {ResourcePath, ResourceNames} from '../../types';
+import {Session} from '../../../lib/session/session';
+import {ApiVersion} from '../../../lib/types';
+
+interface AllArgs {
+  [key: string]: unknown;
+  session: Session;
+}
+
+export class AccessScope extends Base {
+  public static apiVersion = ApiVersion.April26;
+
+  protected static hasOne: {[key: string]: typeof Base} = {};
+  protected static hasMany: {[key: string]: typeof Base} = {};
+  protected static customPrefix: string | null = "/admin/oauth";
+  protected static paths: ResourcePath[] = [
+    {"http_method": "get", "operation": "get", "ids": [], "path": "access_scopes.json"}
+  ];
+  protected static resourceNames: ResourceNames[] = [
+    {
+      "singular": "access_scope",
+      "plural": "access_scopes"
+    }
+  ];
+
+  public static async all(
+    {
+      session,
+      ...otherArgs
+    }: AllArgs
+  ): Promise<FindAllResponse<AccessScope>> {
+    const response = await this.baseFind<AccessScope>({
+      session: session,
+      urlIds: {},
+      params: {...otherArgs},
+    });
+
+    return response;
+  }
+
+  public handle: string | null;
+  public access_scopes: {[key: string]: unknown}[] | null;
+}