[gonzaloriestra]

WHY are these changes introduced?

Subscription migration JSON must follow the shared CLI conventions and expose a discoverable contract.

WHAT is this pull request doing?

Rename shopId to shopGid, validate an explicit subscription projection, and normalize instants to whole-second UTC while preserving calendar dates. Remove schemaVersion; result contracts follow CLI release versions. Update the schema, tests, and generated help together. These existing JSON contract changes include a major changeset.

How to manually test your changes?

shopify app subscription-migrations list --json
shopify app subscription-migrations list --json-schema

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing and includes a major changeset

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

packages/cli-kit/dist/public/node/error/serialization.d.ts

import type { JsonError } from './types.js';
/**
 * Projects an error into the shared JSON error contract, retaining only allowlisted fields.
 *
 * @param source - Error to project.
 * @returns The error classification, message, and available recovery information.
 */
export declare function errorToJson(source: unknown): JsonError;

Existing type declarations

packages/cli-kit/dist/private/node/json-error.d.ts

@@ -1,16 +1,3 @@
-interface FatalErrorLike {
-    type?: number;
-    message?: unknown;
-    formattedMessage?: unknown;
-    tryMessage?: unknown;
-    nextSteps?: unknown;
-    customSections?: unknown;
-    stack?: unknown;
-    command?: unknown;
-    args?: unknown;
-    details?: unknown;
-    code?: unknown;
-}
 /**
  * Writes the public JSON representation of a fatal error to stdout.
  *
@@ -19,5 +6,4 @@ interface FatalErrorLike {
  *
  * @param error - Fatal error to serialize.
  */
-export declare function renderFatalErrorAsJson(error: FatalErrorLike): void;
-export {};
\ No newline at end of file
+export declare function renderFatalErrorAsJson(error: unknown): void;
\ No newline at end of file

[github-actions]

⚠️ Potential Breaking Changes Detected

This PR contains changes that may break the existing contract.

@shopify/dev_experience — this PR contains breaking changes that require coordination for the next major release.

📦 Major Version Changesets

The following changesets request a major version bump:

Changeset	Package
normalize-migration-subscription-list-json.md	"@shopify/cli": major
normalize-subscription-migration-json.md	"@shopify/cli": major