adding-api-versions

name	adding-api-versions
description	Use when adding a new API version to the shopify-api package, creating REST resource files for a new version, updating API version constants, or handling breaking changes like removed or modified resources between versions.

Adding a New API Version

Step-by-step process for adding a new API version to packages/apps/shopify-api. Uses 2025-07 as a reference example.

Prerequisites

• Know which resources are removed or modified in the new version

Step 1: Update API Version Constants

Edit packages/apps/shopify-api/lib/types.ts:

export enum ApiVersion {
  // ... existing versions ...
  April25 = '2025-04',
  July25 = '2025-07',      // New version
  October25 = '2025-10',   // Release candidate (next version)
}

Naming convention: {Month}{YY} (e.g., April25, July25). Value format: YYYY-MM.

Also add the next quarterly version as a release candidate enum value (no REST resources needed yet).

Step 2: Create Directory Structure

mkdir packages/apps/shopify-api/rest/admin/{YYYY-MM}/
mkdir packages/apps/shopify-api/rest/admin/__tests__/{YYYY-MM}/

Step 3: Copy and Update Resource Files

Copy from the most recent version:

cp -r packages/apps/shopify-api/rest/admin/{PREVIOUS_VERSION}/* \
      packages/apps/shopify-api/rest/admin/{NEW_VERSION}/

cp -r packages/apps/shopify-api/rest/admin/__tests__/{PREVIOUS_VERSION}/* \
      packages/apps/shopify-api/rest/admin/__tests__/{NEW_VERSION}/

In every resource file, update the apiVersion property:

// From
public static apiVersion = ApiVersion.April25;
// To
public static apiVersion = ApiVersion.July25;

Step 4: Update Test Files

Two changes in every test file:

1. testConfig calls:

   testConfig({apiVersion: ApiVersion.July25, restResources})
   

2. URL paths in expectations:

   `https://test-shop.myshopify.com/admin/api/2025-07/...`
   

Step 5: Update Index File

Edit packages/apps/shopify-api/rest/admin/{NEW_VERSION}/index.ts:

• Import all resources (except removed ones)
• Update RestResources interface
• Update restResources export

For removed resources, delete their imports and exports:

// Remove from interface and export
export interface RestResources extends ShopifyRestResources {
  // CustomerAddress: typeof CustomerAddress;  // Removed in 2025-07
}

Step 6: Handle Breaking Changes

For removed resources (e.g., CustomerAddress in 2025-07):

1. Delete the resource file from rest/admin/{NEW_VERSION}/
2. Delete the test file from rest/admin/__tests__/{NEW_VERSION}/
3. Remove imports/exports from index.ts

For modified resources:

1. Update class properties
2. Modify paths array if endpoints changed
3. Update method signatures if parameters changed
4. Adjust tests accordingly

Step 7: Run Tests and Build

# Test the new version
pnpm test -- packages/apps/shopify-api/rest/admin/__tests__/{NEW_VERSION}

# Run all tests
pnpm test

Checklist

• New enum value in ApiVersion (packages/apps/shopify-api/lib/types.ts)
• Next quarterly release candidate enum value added (no REST resources needed)
• Source directory created: rest/admin/{NEW_VERSION}/
• Test directory created: rest/admin/__tests__/{NEW_VERSION}/
• All resource files copied and apiVersion updated
• All test files updated (testConfig + URL paths)
• index.ts updated with correct imports/exports
• Removed resources and their tests deleted
• Modified resources updated
• All tests pass
• Package builds without errors