@flexprice/mcp-server 2.1.24 → 2.1.26

package/manifest.json

@@ -48,7 +48,7 @@
       "sensitive": true
     }
   },
-  "version": "2.1.24",
+  "version": "2.1.26",
   "tools": [
     {
       "name": "update-customer",
@@ -300,7 +300,7 @@
     },
     {
       "name": "execute-subscription-plan-change-v2",
-      "description": "Execute a plan change (v2, swap in place)\n\nChange a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction."
+      "description": "Execute a plan change (v2, swap in place)\n\nChange a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.\n\nchange_at controls timing. Omitted or 'immediate' applies the change now. 'end_of_period' records a pending schedule that executes at the subscription's current period end: the response returns is_scheduled, schedule_id and scheduled_at instead of a completed change, and nothing is swapped or billed until the boundary.\n\nscheduled_at is resolved from the subscription's current period end at request time. If that period end is already in the past (a backdated start date, a resumed pause, or worker downtime can all leave a subscription behind), the change is due immediately and fires on the next billing scan rather than a period away — inspect scheduled_at to see this.\n\nOnly one plan change may be pending per subscription. By default (on_conflict_policies.on_pending_schedule = 'reject') a second request returns 400; cancel the existing schedule via POST /subscriptions/schedules/{schedule_id}/cancel first. Pending schedules are listable via GET /subscriptions/{id}/schedules.\n\nSet on_conflict_policies.on_pending_schedule to 'supersede' to replace the queued change instead: the pending schedule is cancelled and this request applied in the same transaction, so both land or neither does. The cancelled schedule ids are returned in superseded_schedules, and preview reports the same list without writing."
     },
     {
       "name": "preview-subscription-plan-change-v2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flexprice/mcp-server",
-  "version": "2.1.24",
+  "version": "2.1.26",
   "author": "flexprice",
   "type": "module",
   "sideEffects": false,

package/src/funcs/subscriptionsExecuteSubscriptionPlanChangeV2.ts

@@ -30,6 +30,14 @@ import { Result } from "../types/fp.js";
  *
  * @remarks
  * Change a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.
+ *
+ * change_at controls timing. Omitted or 'immediate' applies the change now. 'end_of_period' records a pending schedule that executes at the subscription's current period end: the response returns is_scheduled, schedule_id and scheduled_at instead of a completed change, and nothing is swapped or billed until the boundary.
+ *
+ * scheduled_at is resolved from the subscription's current period end at request time. If that period end is already in the past (a backdated start date, a resumed pause, or worker downtime can all leave a subscription behind), the change is due immediately and fires on the next billing scan rather than a period away — inspect scheduled_at to see this.
+ *
+ * Only one plan change may be pending per subscription. By default (on_conflict_policies.on_pending_schedule = 'reject') a second request returns 400; cancel the existing schedule via POST /subscriptions/schedules/{schedule_id}/cancel first. Pending schedules are listable via GET /subscriptions/{id}/schedules.
+ *
+ * Set on_conflict_policies.on_pending_schedule to 'supersede' to replace the queued change instead: the pending schedule is cancelled and this request applied in the same transaction, so both land or neither does. The cancelled schedule ids are returned in superseded_schedules, and preview reports the same list without writing.
  */
 export function subscriptionsExecuteSubscriptionPlanChangeV2(
   client$: FlexpriceCore,

package/src/lib/config.ts

@@ -69,8 +69,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0",
-  sdkVersion: "2.1.24",
-  genVersion: "2.931.0",
+  sdkVersion: "2.1.26",
+  genVersion: "2.932.9",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 2.1.24 2.931.0 1.0 @flexprice/mcp-server",
+    "speakeasy-sdk/mcp-typescript 2.1.26 2.932.9 1.0 @flexprice/mcp-server",
 } as const;

package/src/mcp-server/mcp-server.ts

@@ -21,7 +21,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "2.1.24",
+    currentVersion: "2.1.26",
   },
 });
 

package/src/mcp-server/server.ts

@@ -105,7 +105,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "Flexprice",
-    version: "2.1.24",
+    version: "2.1.26",
   });
 
   const getClient = deps.getSDK || (() =>

package/src/mcp-server/tools/subscriptionsExecuteSubscriptionPlanChangeV2.ts

@@ -16,7 +16,15 @@ export const tool$subscriptionsExecuteSubscriptionPlanChangeV2: ToolDefinition<
   name: "execute-subscription-plan-change-v2",
   description: `Execute a plan change (v2, swap in place)
 
-Change a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.`,
+Change a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.
+
+change_at controls timing. Omitted or 'immediate' applies the change now. 'end_of_period' records a pending schedule that executes at the subscription's current period end: the response returns is_scheduled, schedule_id and scheduled_at instead of a completed change, and nothing is swapped or billed until the boundary.
+
+scheduled_at is resolved from the subscription's current period end at request time. If that period end is already in the past (a backdated start date, a resumed pause, or worker downtime can all leave a subscription behind), the change is due immediately and fires on the next billing scan rather than a period away — inspect scheduled_at to see this.
+
+Only one plan change may be pending per subscription. By default (on_conflict_policies.on_pending_schedule = 'reject') a second request returns 400; cancel the existing schedule via POST /subscriptions/schedules/{schedule_id}/cancel first. Pending schedules are listable via GET /subscriptions/{id}/schedules.
+
+Set on_conflict_policies.on_pending_schedule to 'supersede' to replace the queued change instead: the pending schedule is cancelled and this request applied in the same transaction, so both land or neither does. The cancelled schedule ids are returned in superseded_schedules, and preview reports the same list without writing.`,
   scopes: ["write"],
   annotations: {
     "title": "",

package/src/models/billingperiodbehaviour.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const BillingPeriodBehaviour = {
+  Unchanged: "unchanged",
+  AnchorAtEffect: "anchor_at_effect",
+  AnchorAtConfig: "anchor_at_config",
+} as const;
+export type BillingPeriodBehaviour = ClosedEnum<typeof BillingPeriodBehaviour>;
+
+export const BillingPeriodBehaviour$zodSchema = z.enum([
+  "unchanged",
+  "anchor_at_effect",
+  "anchor_at_config",
+]);

package/src/models/billingperiodconfig.ts

@@ -0,0 +1,22 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { BillingCycle, BillingCycle$zodSchema } from "./billingcycle.js";
+import { BillingPeriod, BillingPeriod$zodSchema } from "./billingperiod.js";
+
+export type BillingPeriodConfig = {
+  billing_anchor?: string | undefined;
+  billing_cycle?: BillingCycle | undefined;
+  billing_period_count?: number | undefined;
+  billing_period_unit?: BillingPeriod | undefined;
+};
+
+export const BillingPeriodConfig$zodSchema: z.ZodType<BillingPeriodConfig> = z
+  .object({
+    billing_anchor: z.iso.datetime({ offset: true }).optional(),
+    billing_cycle: BillingCycle$zodSchema.optional(),
+    billing_period_count: z.int().optional(),
+    billing_period_unit: BillingPeriod$zodSchema.optional(),
+  });

package/src/models/creditgrantapplicationresponse.ts

@@ -24,7 +24,7 @@ export type CreditGrantApplicationResponse = {
   created_at?: string | undefined;
   created_by?: string | undefined;
   credit_grant_id?: string | undefined;
-  credits?: number | undefined;
+  credits?: string | undefined;
   environment_id?: string | undefined;
   failure_reason?: string | undefined;
   id?: string | undefined;
@@ -51,7 +51,7 @@ export const CreditGrantApplicationResponse$zodSchema: z.ZodType<
   created_at: z.iso.datetime({ offset: true }).optional(),
   created_by: z.string().optional(),
   credit_grant_id: z.string().optional(),
-  credits: z.number().optional(),
+  credits: z.string().optional(),
   environment_id: z.string().optional(),
   failure_reason: z.string().optional(),
   id: z.string().optional(),

package/src/models/entitlementgrantallocationbehavior.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const EntitlementGrantAllocationBehavior = {
+  FirstUsage: "first_usage",
+  UnitStart: "unit_start",
+} as const;
+export type EntitlementGrantAllocationBehavior = ClosedEnum<
+  typeof EntitlementGrantAllocationBehavior
+>;
+
+export const EntitlementGrantAllocationBehavior$zodSchema = z.enum([
+  "first_usage",
+  "unit_start",
+]);

package/src/models/entitlementgrantdurationunit.ts

@@ -9,6 +9,7 @@ export const EntitlementGrantDurationUnit = {
   Hour: "hour",
   Day: "day",
   Week: "week",
+  SubscriptionPeriod: "subscription_period",
 } as const;
 export type EntitlementGrantDurationUnit = ClosedEnum<
   typeof EntitlementGrantDurationUnit
@@ -18,4 +19,5 @@ export const EntitlementGrantDurationUnit$zodSchema = z.enum([
   "hour",
   "day",
   "week",
+  "subscription_period",
 ]);

package/src/models/entitlementresponse.ts

@@ -12,6 +12,10 @@ import {
   EntitlementEntityType,
   EntitlementEntityType$zodSchema,
 } from "./entitlemententitytype.js";
+import {
+  EntitlementGrantAllocationBehavior,
+  EntitlementGrantAllocationBehavior$zodSchema,
+} from "./entitlementgrantallocationbehavior.js";
 import {
   EntitlementGrantDurationUnit,
   EntitlementGrantDurationUnit$zodSchema,
@@ -46,10 +50,11 @@ export type EntitlementResponse = {
   feature?: FeatureResponse | undefined;
   feature_id?: string | undefined;
   feature_type?: FeatureType | undefined;
+  grant_allocation_behavior?: EntitlementGrantAllocationBehavior | undefined;
   grant_duration_unit?: EntitlementGrantDurationUnit | undefined;
   grant_duration_value?: number | undefined;
   grant_measure?: EntitlementGrantMeasure | undefined;
-  grant_quota?: number | undefined;
+  grant_quota?: string | undefined;
   id?: string | undefined;
   is_enabled?: boolean | undefined;
   is_soft_limit?: boolean | undefined;
@@ -81,10 +86,12 @@ export const EntitlementResponse$zodSchema: z.ZodType<EntitlementResponse> = z
     feature: FeatureResponse$zodSchema.optional(),
     feature_id: z.string().optional(),
     feature_type: FeatureType$zodSchema.optional(),
+    grant_allocation_behavior: EntitlementGrantAllocationBehavior$zodSchema
+      .optional(),
     grant_duration_unit: EntitlementGrantDurationUnit$zodSchema.optional(),
     grant_duration_value: z.int().optional(),
     grant_measure: EntitlementGrantMeasure$zodSchema.optional(),
-    grant_quota: z.number().optional(),
+    grant_quota: z.string().optional(),
     id: z.string().optional(),
     is_enabled: z.boolean().optional(),
     is_soft_limit: z.boolean().optional(),

package/src/models/entitychangebehaviour.ts

@@ -8,10 +8,12 @@ import { ClosedEnum } from "../types/enums.js";
 export const EntityChangeBehaviour = {
   Carry: "carry",
   Drop: "drop",
+  Add: "add",
 } as const;
 export type EntityChangeBehaviour = ClosedEnum<typeof EntityChangeBehaviour>;
 
 export const EntityChangeBehaviour$zodSchema = z.enum([
   "carry",
   "drop",
+  "add",
 ]);

package/src/models/entitychangepolicy.ts

@@ -18,6 +18,6 @@ export const EntityChangePolicy$zodSchema: z.ZodType<EntityChangePolicy> = z
     default_behaviour: EntityChangeBehaviour$zodSchema.optional(),
     overrides: z.record(z.string(), EntityChangeBehaviour$zodSchema).optional()
       .describe(
-        "Overrides is keyed by addon_associations.id (instance), not catalogue addon_id.",
+        "Overrides is keyed by addon_associations.id (instance), not catalogue addon_id.\nThat is the id an EntityChangeResult reports as EntityID.",
       ),
   });

package/src/models/entitychangeresult.ts

@@ -8,14 +8,14 @@ import {
   EntityChangeBehaviour$zodSchema,
 } from "./entitychangebehaviour.js";
 import {
-  SubscriptionLineItemEntityType,
-  SubscriptionLineItemEntityType$zodSchema,
-} from "./subscriptionlineitementitytype.js";
+  SubscriptionChangeEntityType,
+  SubscriptionChangeEntityType$zodSchema,
+} from "./subscriptionchangeentitytype.js";
 
 export type EntityChangeResult = {
   behaviour?: EntityChangeBehaviour | undefined;
   entity_id?: string | undefined;
-  entity_type?: SubscriptionLineItemEntityType | undefined;
+  entity_type?: SubscriptionChangeEntityType | undefined;
   reference_id?: string | undefined;
 };
 
@@ -23,6 +23,6 @@ export const EntityChangeResult$zodSchema: z.ZodType<EntityChangeResult> = z
   .object({
     behaviour: EntityChangeBehaviour$zodSchema.optional(),
     entity_id: z.string().optional(),
-    entity_type: SubscriptionLineItemEntityType$zodSchema.optional(),
+    entity_type: SubscriptionChangeEntityType$zodSchema.optional(),
     reference_id: z.string().optional(),
   });

package/src/models/integrationentitytype.ts

@@ -17,6 +17,7 @@ export const IntegrationEntityType = {
   ItemPrice: "item_price",
   Price: "price",
   InvoiceLineItem: "invoice_line_item",
+  SubscriptionLineItem: "subscription_line_item",
 } as const;
 export type IntegrationEntityType = ClosedEnum<typeof IntegrationEntityType>;
 
@@ -32,4 +33,5 @@ export const IntegrationEntityType$zodSchema = z.enum([
   "item_price",
   "price",
   "invoice_line_item",
+  "subscription_line_item",
 ]);

package/src/models/onpendingschedulepolicy.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const OnPendingSchedulePolicy = {
+  Reject: "reject",
+  Supersede: "supersede",
+} as const;
+export type OnPendingSchedulePolicy = ClosedEnum<
+  typeof OnPendingSchedulePolicy
+>;
+
+export const OnPendingSchedulePolicy$zodSchema = z.enum([
+  "reject",
+  "supersede",
+]);

package/src/models/planpricesyncstatusresponse.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+export type PlanPriceSyncStatusResponse = {
+  current_sequence?: number | undefined;
+  synced?: boolean | undefined;
+  unsynced_subscription_count?: number | undefined;
+};
+
+export const PlanPriceSyncStatusResponse$zodSchema: z.ZodType<
+  PlanPriceSyncStatusResponse
+> = z.object({
+  current_sequence: z.int().optional(),
+  synced: z.boolean().optional(),
+  unsynced_subscription_count: z.int().optional(),
+});

package/src/models/planresponse.ts

@@ -11,6 +11,10 @@ import {
   EntitlementResponse,
   EntitlementResponse$zodSchema,
 } from "./entitlementresponse.js";
+import {
+  PlanPriceSyncStatusResponse,
+  PlanPriceSyncStatusResponse$zodSchema,
+} from "./planpricesyncstatusresponse.js";
 import { PriceResponse, PriceResponse$zodSchema } from "./priceresponse.js";
 import { Status, Status$zodSchema } from "./status.js";
 
@@ -26,6 +30,7 @@ export type PlanResponse = {
   lookup_key?: string | undefined;
   metadata?: { [k: string]: string } | undefined;
   name?: string | undefined;
+  price_sync_status?: PlanPriceSyncStatusResponse | undefined;
   prices?: Array<PriceResponse> | undefined;
   status?: Status | undefined;
   tenant_id?: string | undefined;
@@ -45,6 +50,7 @@ export const PlanResponse$zodSchema: z.ZodType<PlanResponse> = z.object({
   lookup_key: z.string().optional(),
   metadata: z.record(z.string(), z.string()).optional(),
   name: z.string().optional(),
+  price_sync_status: PlanPriceSyncStatusResponse$zodSchema.optional(),
   prices: z.array(z.lazy(() => PriceResponse$zodSchema)).optional().describe(
     "TODO: Add inline addons",
   ),

package/src/models/pricefeatureresponse.ts

@@ -0,0 +1,15 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ReportingUnit, ReportingUnit$zodSchema } from "./reportingunit.js";
+
+export type PriceFeatureResponse = {
+  reporting_unit?: ReportingUnit | undefined;
+};
+
+export const PriceFeatureResponse$zodSchema: z.ZodType<PriceFeatureResponse> = z
+  .object({
+    reporting_unit: ReportingUnit$zodSchema.optional(),
+  });

package/src/models/priceresponse.ts

@@ -16,6 +16,10 @@ import {
   PriceEntityType,
   PriceEntityType$zodSchema,
 } from "./priceentitytype.js";
+import {
+  PriceFeatureResponse,
+  PriceFeatureResponse$zodSchema,
+} from "./pricefeatureresponse.js";
 import {
   PriceJSONBTransformQuantity,
   PriceJSONBTransformQuantity$zodSchema,
@@ -48,6 +52,7 @@ export type PriceResponse = {
   entity_id?: string | undefined;
   entity_type?: PriceEntityType | undefined;
   environment_id?: string | undefined;
+  feature?: PriceFeatureResponse | undefined;
   group?: GroupResponse | undefined;
   group_id?: string | undefined;
   id?: string | undefined;
@@ -117,6 +122,7 @@ export const PriceResponse$zodSchema: z.ZodType<PriceResponse> = z.object({
   environment_id: z.string().optional().describe(
     "EnvironmentID is the environment identifier for the price",
   ),
+  feature: PriceFeatureResponse$zodSchema.optional(),
   group: GroupResponse$zodSchema.optional(),
   group_id: z.string().optional().describe(
     "GroupID references the group this price belongs to",

package/src/models/subscriptionchangebillingperiodresult.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  BillingPeriodBehaviour,
+  BillingPeriodBehaviour$zodSchema,
+} from "./billingperiodbehaviour.js";
+
+export type SubscriptionChangeBillingPeriodResult = {
+  behaviour?: BillingPeriodBehaviour | undefined;
+  billing_anchor?: string | undefined;
+  current_period_end?: string | undefined;
+  current_period_start?: string | undefined;
+};
+
+export const SubscriptionChangeBillingPeriodResult$zodSchema: z.ZodType<
+  SubscriptionChangeBillingPeriodResult
+> = z.object({
+  behaviour: BillingPeriodBehaviour$zodSchema.optional(),
+  billing_anchor: z.iso.datetime({ offset: true }).optional(),
+  current_period_end: z.iso.datetime({ offset: true }).optional(),
+  current_period_start: z.iso.datetime({ offset: true }).optional(),
+});

package/src/models/subscriptionchangeconflictpolicies.ts

@@ -0,0 +1,19 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  OnPendingSchedulePolicy,
+  OnPendingSchedulePolicy$zodSchema,
+} from "./onpendingschedulepolicy.js";
+
+export type SubscriptionChangeConflictPolicies = {
+  on_pending_schedule?: OnPendingSchedulePolicy | undefined;
+};
+
+export const SubscriptionChangeConflictPolicies$zodSchema: z.ZodType<
+  SubscriptionChangeConflictPolicies
+> = z.object({
+  on_pending_schedule: OnPendingSchedulePolicy$zodSchema.optional(),
+});

package/src/models/subscriptionchangeentitytype.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const SubscriptionChangeEntityType = {
+  Plan: "plan",
+  Addon: "addon",
+  CreditGrant: "credit_grant",
+  Entitlement: "entitlement",
+  EntitlementGrant: "entitlement_grant",
+} as const;
+export type SubscriptionChangeEntityType = ClosedEnum<
+  typeof SubscriptionChangeEntityType
+>;
+
+export const SubscriptionChangeEntityType$zodSchema = z.enum([
+  "plan",
+  "addon",
+  "credit_grant",
+  "entitlement",
+  "entitlement_grant",
+]);

package/src/models/subscriptionchangev2request.ts

@@ -3,19 +3,36 @@
  */
 
 import * as z from "zod";
+import {
+  BillingPeriodBehaviour,
+  BillingPeriodBehaviour$zodSchema,
+} from "./billingperiodbehaviour.js";
+import {
+  BillingPeriodConfig,
+  BillingPeriodConfig$zodSchema,
+} from "./billingperiodconfig.js";
 import {
   ProrationBehavior,
   ProrationBehavior$zodSchema,
 } from "./prorationbehavior.js";
+import { ScheduleType, ScheduleType$zodSchema } from "./scheduletype.js";
+import {
+  SubscriptionChangeConflictPolicies,
+  SubscriptionChangeConflictPolicies$zodSchema,
+} from "./subscriptionchangeconflictpolicies.js";
 import {
   SubscriptionChangeEntityPolicies,
   SubscriptionChangeEntityPolicies$zodSchema,
 } from "./subscriptionchangeentitypolicies.js";
 
 export type SubscriptionChangeV2Request = {
+  billing_period_behaviour?: BillingPeriodBehaviour | undefined;
+  billing_period_config?: BillingPeriodConfig | undefined;
+  change_at?: ScheduleType | undefined;
   entity_policies?: SubscriptionChangeEntityPolicies | undefined;
   idempotency_key?: string | undefined;
   metadata?: { [k: string]: string } | undefined;
+  on_conflict_policies?: SubscriptionChangeConflictPolicies | undefined;
   proration_behavior: ProrationBehavior;
   target_plan_id: string;
 };
@@ -23,9 +40,13 @@ export type SubscriptionChangeV2Request = {
 export const SubscriptionChangeV2Request$zodSchema: z.ZodType<
   SubscriptionChangeV2Request
 > = z.object({
+  billing_period_behaviour: BillingPeriodBehaviour$zodSchema.optional(),
+  billing_period_config: BillingPeriodConfig$zodSchema.optional(),
+  change_at: ScheduleType$zodSchema.optional(),
   entity_policies: SubscriptionChangeEntityPolicies$zodSchema.optional(),
   idempotency_key: z.string().optional(),
   metadata: z.record(z.string(), z.string()).optional(),
+  on_conflict_policies: SubscriptionChangeConflictPolicies$zodSchema.optional(),
   proration_behavior: ProrationBehavior$zodSchema,
   target_plan_id: z.string(),
 });

package/src/models/subscriptionchangev2response.ts

@@ -12,6 +12,10 @@ import {
   EntityChangeResult$zodSchema,
 } from "./entitychangeresult.js";
 import { PlanSummary, PlanSummary$zodSchema } from "./plansummary.js";
+import {
+  SubscriptionChangeBillingPeriodResult,
+  SubscriptionChangeBillingPeriodResult$zodSchema,
+} from "./subscriptionchangebillingperiodresult.js";
 import {
   SubscriptionChangeType,
   SubscriptionChangeType$zodSchema,
@@ -22,13 +26,18 @@ import {
 } from "./subscriptionresponse.js";
 
 export type SubscriptionChangeV2Response = {
+  billing_period?: SubscriptionChangeBillingPeriodResult | undefined;
   change_type?: SubscriptionChangeType | undefined;
   changed_resources?: ChangedResources | undefined;
   effective_at?: string | undefined;
   entity_changes?: Array<EntityChangeResult> | undefined;
   from_plan?: PlanSummary | undefined;
+  is_scheduled?: boolean | undefined;
   metadata?: { [k: string]: string } | undefined;
+  schedule_id?: string | undefined;
+  scheduled_at?: string | undefined;
   subscription?: SubscriptionResponse | undefined;
+  superseded_schedules?: Array<string> | undefined;
   to_plan?: PlanSummary | undefined;
   warnings?: Array<string> | undefined;
 };
@@ -36,13 +45,22 @@ export type SubscriptionChangeV2Response = {
 export const SubscriptionChangeV2Response$zodSchema: z.ZodType<
   SubscriptionChangeV2Response
 > = z.object({
+  billing_period: SubscriptionChangeBillingPeriodResult$zodSchema.optional(),
   change_type: SubscriptionChangeType$zodSchema.optional(),
   changed_resources: ChangedResources$zodSchema.optional(),
   effective_at: z.iso.datetime({ offset: true }).optional(),
   entity_changes: z.array(EntityChangeResult$zodSchema).optional(),
   from_plan: PlanSummary$zodSchema.optional(),
+  is_scheduled: z.boolean().optional().describe(
+    "IsScheduled is true when the change was deferred to the period end instead\nof being applied immediately.",
+  ),
   metadata: z.record(z.string(), z.string()).optional(),
+  schedule_id: z.string().optional(),
+  scheduled_at: z.iso.datetime({ offset: true }).optional(),
   subscription: SubscriptionResponse$zodSchema.optional(),
+  superseded_schedules: z.array(z.string()).optional().describe(
+    "SupersededSchedules lists the plan-change schedules this request cancelled under\non_conflict_policies.on_pending_schedule. Preview reports what execute would cancel.",
+  ),
   to_plan: PlanSummary$zodSchema.optional(),
   warnings: z.array(z.string()).optional(),
 });

package/src/tool-names.ts

@@ -250,7 +250,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "execute-subscription-plan-change-v2",
-    "description": "Execute a plan change (v2, swap in place)\n\nChange a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction."
+    "description": "Execute a plan change (v2, swap in place)\n\nChange a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.\n\nchange_at controls timing. Omitted or 'immediate' applies the change now. 'end_of_period' records a pending schedule that executes at the subscription's current period end: the response returns is_scheduled, schedule_id and scheduled_at instead of a completed change, and nothing is swapped or billed until the boundary.\n\nscheduled_at is resolved from the subscription's current period end at request time. If that period end is already in the past (a backdated start date, a resumed pause, or worker downtime can all leave a subscription behind), the change is due immediately and fires on the next billing scan rather than a period away — inspect scheduled_at to see this.\n\nOnly one plan change may be pending per subscription. By default (on_conflict_policies.on_pending_schedule = 'reject') a second request returns 400; cancel the existing schedule via POST /subscriptions/schedules/{schedule_id}/cancel first. Pending schedules are listable via GET /subscriptions/{id}/schedules.\n\nSet on_conflict_policies.on_pending_schedule to 'supersede' to replace the queued change instead: the pending schedule is cancelled and this request applied in the same transaction, so both land or neither does. The cancelled schedule ids are returned in superseded_schedules, and preview reports the same list without writing."
   },
   {
     "name": "preview-subscription-plan-change-v2",