create_subscription

Instructions

Implementation Reference

• src/tools/subscriptions/createSubscription.ts:36-44 (handler)

  The handler function that executes the create_subscription tool logic. It validates args using Zod schema, then calls subscriptionService.createSubscriptionFromProductRatePlan.

  async function handler(client: Client, args: Record<string, unknown> | undefined) {
    const parsed = schema.safeParse(args);
    if (!parsed.success) {
      return errorResult(parsed.error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join("; "));
    }
  
    const payload = parsed.data;
    return handleToolCall(() => subscriptionService.createSubscriptionFromProductRatePlan(client, payload));
  }

• src/tools/subscriptions/createSubscription.ts:7-34 (schema)

  Input validation schema for create_subscription using Zod. Validates productRatePlanId, customerId, customerPaymentMethodId, billingAddressId (positive integers) and effectiveStartDate (YYYY-MM-DD format string).

  const dateSchema = z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, "effectiveStartDate must be in YYYY-MM-DD format");
  
  const definition = {
    name: "create_subscription",
    description:
      "Create a subscription from a product rate plan. POST /subscriptions/from-product-rateplan. Required: productRatePlanId, customerId, customerPaymentMethodId, billingAddressId, effectiveStartDate.",
    inputSchema: {
      type: "object" as const,
      properties: {
        productRatePlanId: { type: "number", description: "Product rate plan ID" },
        customerId: { type: "number", description: "Customer ID" },
        customerPaymentMethodId: { type: "number", description: "Customer payment method ID" },
        billingAddressId: { type: "number", description: "Billing address ID" },
        effectiveStartDate: { type: "string", description: "Effective start date YYYY-MM-DD" },
      },
      required: ["productRatePlanId", "customerId", "customerPaymentMethodId", "billingAddressId", "effectiveStartDate"],
    },
  };
  
  const schema = z.object({
    productRatePlanId: z.number().int().positive("productRatePlanId is required"),
    customerId: z.number().int().positive("customerId is required"),
    customerPaymentMethodId: z.number().int().positive("customerPaymentMethodId is required"),
    billingAddressId: z.number().int().positive("billingAddressId is required"),
    effectiveStartDate: dateSchema,
  });

• src/tools/subscriptions/createSubscription.ts:11-26 (schema)

  MCP tool definition (name, description, JSON Schema input schema) for create_subscription, used for tools/list responses. All 5 fields are required.

  const definition = {
    name: "create_subscription",
    description:
      "Create a subscription from a product rate plan. POST /subscriptions/from-product-rateplan. Required: productRatePlanId, customerId, customerPaymentMethodId, billingAddressId, effectiveStartDate.",
    inputSchema: {
      type: "object" as const,
      properties: {
        productRatePlanId: { type: "number", description: "Product rate plan ID" },
        customerId: { type: "number", description: "Customer ID" },
        customerPaymentMethodId: { type: "number", description: "Customer payment method ID" },
        billingAddressId: { type: "number", description: "Billing address ID" },
        effectiveStartDate: { type: "string", description: "Effective start date YYYY-MM-DD" },
      },
      required: ["productRatePlanId", "customerId", "customerPaymentMethodId", "billingAddressId", "effectiveStartDate"],
    },
  };

• src/services/subscriptionServices.ts:155-160 (helper)

  The underlying service function createSubscriptionFromProductRatePlan that makes the POST /subscriptions/from-product-rateplan API call.

  export async function createSubscriptionFromProductRatePlan(
    client: Client,
    body: CreateSubscriptionFromProductRatePlanBody
  ): Promise<unknown> {
    return client.post<unknown>("/subscriptions/from-product-rateplan", body);
  }

• src/tools/subscriptions/index.ts:26-49 (registration)

  Registration of createSubscriptionTool in the subscription tools array returned by registerSubscriptionTools(), which is consumed in src/tools/index.ts.

  /** All 19 subscription tools. */
  export function registerSubscriptionTools(): Tool[] {
    return [
      listSubscriptionsTool,
      getSubscriptionTool,
      createSubscriptionTool,
      updateSubscriptionTool,
      deleteSubscriptionTool,
      updateSubscriptionStatusTool,
      getSubscriptionUpcomingChargesTool,
      getSubscriptionInvoicesTool,
      getSubscriptionLogsTool,
      getSubscriptionExternalInvoicesTool,
      listSubscriptionRatePlansTool,
      getSubscriptionRatePlanTool,
      addSubscriptionRatePlanTool,
      updateSubscriptionRatePlanTool,
      removeSubscriptionRatePlanTool,
      getSubscriptionRatePlanChargeTool,
      addSubscriptionRatePlanChargeTool,
      updateSubscriptionRatePlanChargeTool,
      removeSubscriptionRatePlanChargeTool,
    ];
  }