update_customer_payment_method

Instructions

Implementation Reference

• src/tools/customers/updateCustomerPaymentMethod.ts:51-63 (handler)

  Handler function that validates inputs via Zod schema, maps billing address (resolving countryCode to countryId), and calls the service layer to update the payment method.

  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 { customerId, paymentMethodId, billingAddress } = parsed.data;
    const apiBillingAddress = await mapBillingAddressInputToApiBillingAddress(client, billingAddress);
    return handleToolCall(() =>
      customerService.updateCustomerPaymentMethod(client, customerId, paymentMethodId, {
        billingAddress: apiBillingAddress,
      })
    );
  }

• src/tools/customers/updateCustomerPaymentMethod.ts:18-22 (schema)

  Zod validation schema for the tool: requires customerId, paymentMethodId, and billingAddress (with countryCode, street1, city, state, zip, optional street2).

  const schema = z.object({
    customerId: z.string().min(1, "customerId is required"),
    paymentMethodId: z.string().min(1, "paymentMethodId is required"),
    billingAddress: billingAddressSchema,
  });

• src/tools/customers/updateCustomerPaymentMethod.ts:24-49 (schema)

  Tool definition including the name 'update_customer_payment_method', description, and JSON Schema input definition for MCP.

  const definition = {
    name: "update_customer_payment_method",
    description:
      "Update a payment method's billing address (gateway-agnostic). PUT /customers/{customerId}/paymentmethods/{paymentMethodId}. Required: customerId, paymentMethodId, billingAddress (countryCode, street1, city, state, zip). Optional: street2. No payment or gateway-specific fields.",
    inputSchema: {
      type: "object" as const,
      properties: {
        customerId: { type: "string", description: "Customer ID (required)" },
        paymentMethodId: { type: "string", description: "Payment method ID (required)" },
        billingAddress: {
          type: "object",
          description: "Billing address (required): countryCode, street1, city, state, zip; street2 optional",
          properties: {
            countryCode: { type: "string", description: COUNTRY_CODE_DESCRIPTION_CONST },
            street1: { type: "string", description: "Street line 1 (required)" },
            city: { type: "string", description: "City (required)" },
            state: { type: "string", description: "State (required)" },
            zip: { type: "string", description: "Postal code (required)" },
            street2: { type: "string", description: "Street line 2" },
          },
          required: ["countryCode", "street1", "city", "state", "zip"],
        },
      },
      required: ["customerId", "paymentMethodId", "billingAddress"],
    },
  };

• src/tools/customers/index.ts:31-56 (registration)

  The tool is registered in the customer tools array, returned by registerCustomerTools().

  export function registerCustomerTools(): Tool[] {
    return [
      listCustomersTool,
      getCustomerTool,
      createCustomerTool,
      updateCustomerTool,
      deleteCustomerTool,
      getCustomerInvoicesTool,
      getCustomerUnpaidInvoicesTool,
      getCustomerSubscriptionsTool,
      getCustomerLogsTool,
      listCustomerAddressesTool,
      getCustomerAddressTool,
      createCustomerAddressTool,
      updateCustomerAddressTool,
      deleteCustomerAddressTool,
      listCustomerPaymentMethodsTool,
      getCustomerPaymentMethodTool,
      createCustomerPaymentMethodTool,
      updateCustomerPaymentMethodTool,
      deleteCustomerPaymentMethodTool,
      listCustomerChargesCreditsTool,
      createCustomerChargeCreditTool,
      deleteCustomerChargeCreditTool,
    ];
  }

• src/services/customerServices.ts:421-431 (helper)

  Service function that makes the PUT /customers/{customerId}/paymentmethods/{paymentMethodId} API call with the billing address payload.

  export async function updateCustomerPaymentMethod(
    client: Client,
    customerId: string,
    paymentMethodId: string,
    body: UpdateCustomerPaymentMethodBody
  ): Promise<CustomerPaymentMethod> {
    return client.put<CustomerPaymentMethod>(
      `/customers/${customerId}/paymentmethods/${paymentMethodId}`,
      { billingAddress: body.billingAddress }
    );
  }