Normalize migration subscription list JSON contract

Author: gonzaloriestra

.changeset/normalize-migration-subscription-list-json.md

@@ -0,0 +1,5 @@
+---
+"@shopify/cli": major
+---
+
+Normalize migration subscription JSON with shopGid identifiers, whole-second UTC instants, and calendar dates.

packages/app/src/cli/commands/app/subscription-migrations/list.integration.test.ts

@@ -1,4 +1,5 @@
 import List from './list.js'
+import {projectMigratableSubscription} from '../../../services/subscription-migrations/result-codec.js'
 import {testAppLinked, testOrganizationApp} from '../../../models/app/app.test-data.js'
 import {linkedAppContext} from '../../../services/app-context.js'
 import {MigrationListProtocolError} from '../../../services/subscription-migrations/list-migratable-subscriptions.js'
@@ -273,8 +274,10 @@ describe('subscription migration list command output integration', () => {
     expect(jsonWrite).toBeGreaterThan(lastPageRequest)
 
     const output = stdoutWrites()[0]!
-    expect(output).toBe(JSON.stringify({subscriptions: [...pageOne, ...pageTwo]}, null, 2))
-    expect(JSON.parse(output)).toEqual({subscriptions: [...pageOne, ...pageTwo]})
+    expect(output).toBe(
+      JSON.stringify({subscriptions: [...pageOne, ...pageTwo].map(projectMigratableSubscription)}, null, 2),
+    )
+    expect(JSON.parse(output)).toEqual({subscriptions: [...pageOne, ...pageTwo].map(projectMigratableSubscription)})
   })
 
   test('writes an empty JSON document when there are no subscriptions', async () => {

packages/app/src/cli/services/subscription-migrations/list-output.test.ts

@@ -1,3 +1,4 @@
+import {projectMigratableSubscription} from './result-codec.js'
 import {migrationListJsonOutputSchema} from './types.js'
 import {outputMigrationList, serializeMigrationListCsv, serializeMigrationListJson} from './list-output.js'
 import {outputResult} from '@shopify/cli-kit/node/output'
@@ -22,7 +23,7 @@ const CSV_HEADER =
   'shop_id,status,manual_subscription_name,manual_subscription_price_amount,manual_subscription_price_currency_code,manual_subscription_interval,target_plan_handle,notification_kind,notification_opt_out_deadline,notification_sent_at,price_behavior,effective_date,last_failure_reason'
 
 const CSV_ROW =
-  'gid://shopify/Shop/1,SCHEDULED,Legacy plan,19.99,USD,EVERY_30_DAYS,standard,NONE,2026-04-01T00:00:00Z,2026-03-01T00:00:00Z,HONOR_BILLING_PRICE,2026-05-01T00:00:00Z,SCHEDULING_FAILED'
+  'gid://shopify/Shop/1,SCHEDULED,Legacy plan,19.99,USD,EVERY_30_DAYS,standard,NONE,2026-04-01T00:00:00Z,2026-03-01T00:00:00Z,HONOR_BILLING_PRICE,2026-05-01,SCHEDULING_FAILED'
 
 function subscription(overrides: Partial<MigratableSubscription> = {}): MigratableSubscription {
   return {
@@ -38,7 +39,7 @@ function subscription(overrides: Partial<MigratableSubscription> = {}): Migratab
       sentAt: '2026-03-01T00:00:00Z',
     },
     priceBehavior: 'HONOR_BILLING_PRICE',
-    effectiveDate: '2026-05-01T00:00:00Z',
+    effectiveDate: '2026-05-01',
     lastFailureReason: 'SCHEDULING_FAILED',
     ...overrides,
   }
@@ -84,7 +85,7 @@ describe('migration list serialization', () => {
     const expected = `{
   "subscriptions": [
     {
-      "shopId": "gid://shopify/Shop/1",
+      "shopGid": "gid://shopify/Shop/1",
       "status": "SCHEDULED",
       "manualSubscriptionName": "Legacy plan",
       "manualSubscriptionPrice": {
@@ -99,7 +100,7 @@ describe('migration list serialization', () => {
         "sentAt": "2026-03-01T00:00:00Z"
       },
       "priceBehavior": "HONOR_BILLING_PRICE",
-      "effectiveDate": "2026-05-01T00:00:00Z",
+      "effectiveDate": "2026-05-01",
       "lastFailureReason": "SCHEDULING_FAILED"
     }
   ]
@@ -109,6 +110,27 @@ describe('migration list serialization', () => {
     expect(serializeMigrationListJson(subscriptions)).not.toMatch(/\n$/)
   })
 
+  test('normalizes fractional instants and offsets while preserving calendar dates', () => {
+    const value = subscription({
+      notification: {kind: 'NONE', sentAt: '2026-03-01T01:00:00.999+01:00', optOutDeadline: null},
+      effectiveDate: '2026-05-01',
+    })
+    expect(JSON.parse(serializeMigrationListJson([value])).subscriptions[0]).toMatchObject({
+      effectiveDate: '2026-05-01',
+      notification: {sentAt: '2026-03-01T00:00:00Z', optOutDeadline: null},
+    })
+    expect(() =>
+      migrationListJsonOutputSchema.validate({
+        subscriptions: [
+          {
+            ...projectMigratableSubscription(value),
+            notification: {kind: 'NONE', sentAt: '2026-03-01T00:00:00.999Z', optOutDeadline: null},
+          },
+        ],
+      }),
+    ).toThrow()
+  })
+
   test('serializes CSV fields in the fixed header order without a trailing newline', () => {
     expect(serializeMigrationListCsv([subscription()])).toBe(`${CSV_HEADER}\n${CSV_ROW}`)
   })
@@ -247,7 +269,7 @@ describe('outputMigrationList JSON', () => {
     expect(outputResult).toHaveBeenCalledOnce()
     const output = vi.mocked(outputResult).mock.calls[0]![0] as string
     expect(output).toBe(serializeMigrationListJson([...pageOne, ...pageTwo]))
-    expect(JSON.parse(output)).toEqual({subscriptions: [...pageOne, ...pageTwo]})
+    expect(JSON.parse(output)).toEqual({subscriptions: [...pageOne, ...pageTwo].map(projectMigratableSubscription)})
   })
 
   test('writes an empty JSON document for an empty result', async () => {
@@ -279,7 +301,9 @@ describe('migration list JSON contract', () => {
       lastFailureReason: null,
     })
 
-    expect(serializeMigrationListJson([value])).toBe(JSON.stringify({subscriptions: [value]}, null, 2))
+    expect(serializeMigrationListJson([value])).toBe(
+      JSON.stringify({subscriptions: [value].map(projectMigratableSubscription)}, null, 2),
+    )
   })
 
   test.each([
@@ -288,7 +312,7 @@ describe('migration list JSON contract', () => {
   ])('rejects invalid subscription fields: %j', (fields) => {
     expect(() =>
       migrationListJsonOutputSchema.validate({
-        subscriptions: [{...subscription(), ...fields}],
+        subscriptions: [{...projectMigratableSubscription(subscription()), ...fields}],
       }),
     ).toThrow()
   })
@@ -299,7 +323,7 @@ describe('migration list JSON contract', () => {
     {manualSubscriptionInterval: 'MONTHLY'},
     {lastFailureReason: 'UNKNOWN'},
   ])('accepts unknown server-provided values for pass-through fields: %j', (fields) => {
-    const value = {...subscription(), ...fields}
+    const value = {...projectMigratableSubscription(subscription()), ...fields}
 
     const encoded = migrationListJsonOutputSchema.encode({subscriptions: [value]})
 

packages/app/src/cli/services/subscription-migrations/list-output.ts

@@ -1,3 +1,4 @@
+import {projectMigratableSubscription} from './result-codec.js'
 import {migrationListJsonOutputSchema} from './types.js'
 import {outputResult} from '@shopify/cli-kit/node/output'
 import type {MigratableSubscription} from '../../models/subscription-migrations.js'
@@ -11,7 +12,7 @@ interface MigrationListOutputOptions {
 }
 
 export function serializeMigrationListJson(subscriptions: MigratableSubscription[]): string {
-  return migrationListJsonOutputSchema.encode({subscriptions})
+  return migrationListJsonOutputSchema.encode({subscriptions: subscriptions.map(projectMigratableSubscription)})
 }
 
 export function serializeMigrationListCsv(subscriptions: MigratableSubscription[]): string {

packages/app/src/cli/services/subscription-migrations/result-codec.ts

@@ -1,4 +1,4 @@
-import type {MigrationOperation} from '../../models/subscription-migrations.js'
+import type {MigratableSubscription, MigrationOperation} from '../../models/subscription-migrations.js'
 import type {MigrationUserError} from './partners-api.js'
 
 export function projectMigrationOperation(operation: MigrationOperation) {
@@ -13,3 +13,39 @@ export function projectMigrationOperation(operation: MigrationOperation) {
 export function projectMigrationUserErrors(errors: MigrationUserError[]) {
   return errors.map(({message, field}) => ({message, fieldPath: field}))
 }
+
+export function projectMigratableSubscription(subscription: MigratableSubscription) {
+  return {
+    shopGid: subscription.shopId,
+    status: subscription.status,
+    manualSubscriptionName: subscription.manualSubscriptionName,
+    manualSubscriptionPrice:
+      subscription.manualSubscriptionPrice === null
+        ? null
+        : {
+            amount: subscription.manualSubscriptionPrice.amount,
+            currencyCode: subscription.manualSubscriptionPrice.currencyCode,
+          },
+    manualSubscriptionInterval: subscription.manualSubscriptionInterval,
+    targetPlanHandle: subscription.targetPlanHandle,
+    notification:
+      subscription.notification === null
+        ? null
+        : {
+            kind: subscription.notification.kind,
+            optOutDeadline: normalizeInstant(subscription.notification.optOutDeadline),
+            sentAt: normalizeInstant(subscription.notification.sentAt),
+          },
+    priceBehavior: subscription.priceBehavior,
+    effectiveDate:
+      subscription.effectiveDate === null || /^\d{4}-\d{2}-\d{2}$/.test(subscription.effectiveDate)
+        ? subscription.effectiveDate
+        : normalizeInstant(subscription.effectiveDate),
+    lastFailureReason: subscription.lastFailureReason,
+  }
+}
+
+function normalizeInstant(value: string | null): string | null {
+  if (value === null) return null
+  return new Date(value).toISOString().replace(/\.\d{3}Z$/, 'Z')
+}

packages/app/src/cli/services/subscription-migrations/types.ts

@@ -1,4 +1,4 @@
-import {defineJsonOutputSchema, type InferJsonOutputSchema} from '@shopify/cli-kit/node/json-output-schema'
+import {defineJsonOutputSchema} from '@shopify/cli-kit/node/json-output-schema'
 import {zod} from '@shopify/cli-kit/node/schema'
 import type {MigrationOperation} from '../../models/subscription-migrations.js'
 import type {MigrationUserError} from './partners-api.js'
@@ -80,38 +80,53 @@ export type MigrationCancellationOutcome =
   | {status: 'success'; operationId: string; operation: MigrationOperation}
   | {status: 'failed'; operationId: string; operation: MigrationOperation | null; userErrors: MigrationUserError[]}
 
-const MigratableSubscriptionPriceSchema = zod.object({
-  amount: zod.string(),
-  currencyCode: zod.string(),
-})
+const UtcInstantSchema = zod
+  .string()
+  .datetime()
+  .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/)
+const CalendarDateSchema = zod.string().date()
 
-const MigratableSubscriptionNotificationSchema = zod.object({
-  kind: zod.string().describe('Known values: NONE, OPT_OUT, WHEN_REQUIRED.'),
-  optOutDeadline: zod.string().nullable(),
-  sentAt: zod.string().nullable(),
-})
+const MigratableSubscriptionPriceSchema = zod
+  .object({
+    amount: zod.string().regex(/^-?\d+(?:\.\d+)?$/),
+    currencyCode: zod.string().regex(/^[A-Z]{3}$/),
+  })
+  .strict()
 
-// Server-provided values are typed as strings (with the known values documented) instead of enums, so a new
-// server-side value never makes `--json` output fail validation. Compatibility with the `MigratableSubscription`
-// model is enforced where `serializeMigrationListJson` passes the model into this schema's `encode`.
-const MigratableSubscriptionSchema = zod.object({
-  shopId: zod.string(),
-  status: zod.string().describe('Known values: UNSCHEDULED, SCHEDULED, MIGRATED.'),
-  manualSubscriptionName: zod.string().nullable(),
-  manualSubscriptionPrice: MigratableSubscriptionPriceSchema.nullable(),
-  manualSubscriptionInterval: zod.string().describe('Known values: EVERY_30_DAYS, ANNUAL.'),
-  targetPlanHandle: zod.string().nullable(),
-  notification: MigratableSubscriptionNotificationSchema.nullable(),
-  priceBehavior: zod.string().nullable().describe('Known values: HONOR_BILLING_PRICE, PLAN_PRICE.'),
-  effectiveDate: zod.string().nullable(),
-  lastFailureReason: zod.string().nullable().describe('Known values: SUPERSEDED, SCHEDULING_FAILED.'),
-})
+const MigratableSubscriptionNotificationSchema = zod
+  .object({
+    kind: zod.string().describe('Known values: NONE, OPT_OUT, WHEN_REQUIRED.'),
+    optOutDeadline: UtcInstantSchema.nullable(),
+    sentAt: UtcInstantSchema.nullable(),
+  })
+  .strict()
+
+const MigratableSubscriptionSchema = zod
+  .object({
+    shopGid: ShopGidSchema,
+    status: zod.string().describe('Known values: UNSCHEDULED, SCHEDULED, MIGRATED.'),
+    manualSubscriptionName: zod.string().nullable(),
+    manualSubscriptionPrice: MigratableSubscriptionPriceSchema.nullable(),
+    manualSubscriptionInterval: zod.string().describe('Known values: EVERY_30_DAYS, ANNUAL.'),
+    targetPlanHandle: zod.string().nullable(),
+    notification: MigratableSubscriptionNotificationSchema.nullable(),
+    priceBehavior: zod.string().nullable().describe('Known values: HONOR_BILLING_PRICE, PLAN_PRICE.'),
+    effectiveDate: zod
+      .union([CalendarDateSchema, UtcInstantSchema])
+      .nullable()
+      .describe('The upstream calendar date or whole-second UTC instant; date-only values retain their format.'),
+    lastFailureReason: zod.string().nullable().describe('Known values: SUPERSEDED, SCHEDULING_FAILED.'),
+  })
+  .strict()
+  .describe('All subscription projection fields are present; unavailable values are null.')
 
 export const migrationListJsonOutputSchema = defineJsonOutputSchema({
   name: 'MigrationListResult',
-  schema: zod.object({
-    subscriptions: zod.array(MigratableSubscriptionSchema),
-  }),
+  schema: zod
+    .object({
+      subscriptions: zod.array(MigratableSubscriptionSchema).describe('The complete list across every fetched page.'),
+    })
+    .strict(),
   definitions: {
     MigratableSubscription: MigratableSubscriptionSchema,
     MigratableSubscriptionPrice: MigratableSubscriptionPriceSchema,