Merge pull request #619 from Shopify/mg/04-28-update_payment_customization_function_templates

Update Payment Customization function templates

Author: ginmrt

checkout/javascript/payment-customization/default/schema.graphql

@@ -328,6 +328,17 @@ type CartLineCost {
   totalAmount: MoneyV2!
 }
 
+"""
+The `CartPaymentMethodsTransformRunResult` object is the output of the Function
+run target. The object contains the operations to apply to payment methods in checkout.
+"""
+input CartPaymentMethodsTransformRunResult {
+  """
+  The ordered list of operations to apply to the list of payment methods.
+  """
+  operations: [Operation!]!
+}
+
 """
 Whether the product is in the specified collection.
 
@@ -2778,6 +2789,45 @@ enum DeliveryMethod {
   SHIPPING
 }
 
+"""
+An operation to apply to the list of payment methods.
+"""
+input DeprecatedOperation @oneOf {
+  """
+  A request to hide a payment method during checkout.
+
+  When your Function returns this operation, it removes the specified payment method
+  from the available options shown to customers during checkout.
+
+  Use this operation when you want to conditionally hide payment methods based on
+  checkout attributes, customer data, or other business logic implemented in your Function.
+  """
+  hide: HideOperation @deprecated(reason: "Use `paymentMethodHide` instead.")
+
+  """
+  A request to move a payment method to a new position in the checkout display order.
+
+  When your Function returns this operation, it changes the display order of payment methods
+  by placing the specified payment method at the requested index position.
+
+  Use this operation when you want to prioritize certain payment methods based on
+  checkout context, customer preferences, or other business logic implemented in your Function.
+  """
+  move: MoveOperation @deprecated(reason: "Use `paymentMethodMove` instead.")
+
+  """
+  A request to change the displayed name of a payment method during checkout.
+
+  When your Function returns this operation, it replaces the default name of the
+  specified payment method with the custom name that's provided in the request.
+
+  Use this operation when you want to provide more context or clarity about
+  payment methods based on checkout details, locale, or other business logic
+  implemented in your Function.
+  """
+  rename: RenameOperation @deprecated(reason: "Use `paymentMethodRename` instead.")
+}
+
 """
 The output of the Function run target. The object contains the operations to
 apply to payment methods in checkout. In API versions 2023-10 and beyond, this
@@ -2787,7 +2837,7 @@ input FunctionResult {
   """
   The ordered list of operations to apply to the list of payment methods.
   """
-  operations: [Operation!]!
+  operations: [DeprecatedOperation!]!
 }
 
 """
@@ -2797,7 +2847,7 @@ input FunctionRunResult {
   """
   The ordered list of operations to apply to the list of payment methods.
   """
-  operations: [Operation!]!
+  operations: [DeprecatedOperation!]!
 }
 
 """
@@ -3772,7 +3822,7 @@ type Localization {
   """
   The market of the active localized experience.
   """
-  market: Market!
+  market: Market! @deprecated(reason: "This `market` field will be removed in a future version of the API.")
 }
 
 """
@@ -4040,7 +4090,7 @@ type MailingAddress {
   """
   The market of the address.
   """
-  market: Market
+  market: Market @deprecated(reason: "This `market` field will be removed in a future version of the API.")
 
   """
   The full name of the customer, based on firstName and lastName.
@@ -4220,6 +4270,16 @@ input MoveOperation {
 The root mutation for the API.
 """
 type MutationRoot {
+  """
+  Handles the Function result for the cart.payment-methods.transform.run target.
+  """
+  cartPaymentMethodsTransformRun(
+    """
+    The result of the Function.
+    """
+    result: CartPaymentMethodsTransformRunResult!
+  ): Void!
+
   """
   Handles the Function result.
   """
@@ -4254,7 +4314,7 @@ input Operation @oneOf {
   Use this operation when you want to conditionally hide payment methods based on
   checkout attributes, customer data, or other business logic implemented in your Function.
   """
-  hide: HideOperation
+  paymentMethodHide: PaymentMethodHideOperation
 
   """
   A request to move a payment method to a new position in the checkout display order.
@@ -4265,7 +4325,7 @@ input Operation @oneOf {
   Use this operation when you want to prioritize certain payment methods based on
   checkout context, customer preferences, or other business logic implemented in your Function.
   """
-  move: MoveOperation
+  paymentMethodMove: PaymentMethodMoveOperation
 
   """
   A request to change the displayed name of a payment method during checkout.
@@ -4277,7 +4337,7 @@ input Operation @oneOf {
   payment methods based on checkout details, locale, or other business logic
   implemented in your Function.
   """
-  rename: RenameOperation
+  paymentMethodRename: PaymentMethodRenameOperation
 }
 
 """
@@ -4343,6 +4403,70 @@ enum PaymentCustomizationPaymentMethodPlacement {
   PAYMENT_METHOD
 }
 
+"""
+A request to hide a payment method during checkout.
+
+When your Function returns this operation, it removes the specified payment method
+from the available options shown to customers during checkout.
+
+Use this operation when you want to conditionally hide payment methods based on
+checkout attributes, customer data, or other business logic implemented in your Function.
+"""
+input PaymentMethodHideOperation {
+  """
+  The identifier of the payment method to hide out.
+  """
+  paymentMethodId: ID!
+
+  """
+  Placement types to hide. If not provided, all placements will be hidden.
+  """
+  placements: [PaymentCustomizationPaymentMethodPlacement!]
+}
+
+"""
+A request to move a payment method to a new position in the checkout display order.
+
+When your Function returns this operation, it changes the display order of payment methods
+by placing the specified payment method at the requested index position.
+
+Use this operation when you want to prioritize certain payment methods based on
+checkout context, customer preferences, or other business logic implemented in your Function.
+"""
+input PaymentMethodMoveOperation {
+  """
+  The index to move the payment method to.
+  """
+  index: Int!
+
+  """
+  The identifier of the payment method to move.
+  """
+  paymentMethodId: ID!
+}
+
+"""
+A request to change the displayed name of a payment method during checkout.
+
+When your Function returns this operation, it replaces the default name of the
+specified payment method with the custom name that's provided in the request.
+
+Use this operation when you want to provide more context or clarity about
+payment methods based on checkout details, locale, or other business logic
+implemented in your Function.
+"""
+input PaymentMethodRenameOperation {
+  """
+  The new name for the payment method.
+  """
+  name: String!
+
+  """
+  The identifier of the payment method to rename.
+  """
+  paymentMethodId: ID!
+}
+
 """
 The goods and services that merchants offer to customers. Products can include details such as
 title, vendor, and custom data stored in [metafields](https://shopify.dev/docs/apps/build/custom-data).

checkout/javascript/payment-customization/default/shopify.extension.toml.liquid

@@ -1,4 +1,4 @@
-api_version = "2025-01"
+api_version = "2025-07"
 
 [[extensions]]
 name = "t:name"
@@ -8,9 +8,9 @@ type = "function"
 description = "t:description"
 
   [[extensions.targeting]]
-  target = "purchase.payment-customization.run"
-  input_query = "src/run.graphql"
-  export = "run"
+  target = "cart.payment-methods.transform.run"
+  input_query = "src/cart_payment_methods_transform_run.graphql"
+  export = "cart-payment-methods-transform-run"
 
   [extensions.build]
   command = ""

…omization/default/src/run.graphql.liquid …ent_methods_transform_run.graphql.liquidcheckout/javascript/payment-customization/default/src/run.graphql.liquid renamed to checkout/javascript/payment-customization/default/src/cart_payment_methods_transform_run.graphql.liquid checkout/javascript/payment-customization/default/src/run.graphql.liquid renamed to checkout/javascript/payment-customization/default/src/cart_payment_methods_transform_run.graphql.liquid

@@ -1,4 +1,4 @@
-query RunInput {
+query CartPaymentMethodsTransformRunInput {
   paymentCustomization {
     metafield(namespace: "$app:{{handle | replace: " ", "-" | downcase}}", key: "function-configuration") {
       value

checkout/javascript/payment-customization/default/src/cart_payment_methods_transform_run.liquid

@@ -0,0 +1,45 @@
+{%- if flavor contains "vanilla-js" -%}
+// @ts-check
+
+/**
+ * @typedef {import("../generated/api").CartPaymentMethodsTransformRunInput} CartPaymentMethodsTransformRunInput
+ * @typedef {import("../generated/api").CartPaymentMethodsTransformRunResult} CartPaymentMethodsTransformRunResult
+ */
+
+/**
+ * @type {CartPaymentMethodsTransformRunResult}
+ */
+const NO_CHANGES = {
+  operations: [],
+};
+
+/**
+ * @param {CartPaymentMethodsTransformRunInput} input
+ * @returns {CartPaymentMethodsTransformRunResult}
+ */
+export function cartPaymentMethodsTransformRun(input) {
+  const configuration = JSON.parse(
+    input?.paymentCustomization?.metafield?.value ?? "{}"
+  );
+
+  return NO_CHANGES;
+};
+{%- elsif flavor contains "typescript" -%}
+import type {
+  CartPaymentMethodsTransformRunInput,
+  CartPaymentMethodsTransformRunResult,
+} from "../generated/api";
+
+const NO_CHANGES: CartPaymentMethodsTransformRunResult = {
+  operations: [],
+};
+
+type Configuration = {};
+
+export function cartPaymentMethodsTransformRun(input: CartPaymentMethodsTransformRunInput): CartPaymentMethodsTransformRunResult {
+  const configuration: Configuration = JSON.parse(
+    input?.paymentCustomization?.metafield?.value ?? "{}"
+  );
+  return NO_CHANGES;
+};
+{%- endif -%}

…ustomization/default/src/run.test.liquid …ayment_methods_transform_run.test.liquidcheckout/javascript/payment-customization/default/src/run.test.liquid renamed to checkout/javascript/payment-customization/default/src/cart_payment_methods_transform_run.test.liquid checkout/javascript/payment-customization/default/src/run.test.liquid renamed to checkout/javascript/payment-customization/default/src/cart_payment_methods_transform_run.test.liquid

@@ -1,36 +1,36 @@
 {%- if flavor contains "vanilla-js" -%}
 import { describe, it, expect } from 'vitest';
-import { run } from './run';
+import { cartPaymentMethodsTransformRun } from './cart_payment_methods_transform_run';
 
 /**
- * @typedef {import("../generated/api").FunctionRunResult} FunctionRunResult
+ * @typedef {import("../generated/api").CartPaymentMethodsTransformRunResult} CartPaymentMethodsTransformRunResult
  */
 
 describe('payment customization function', () => {
   it('returns no operations without configuration', () => {
-    const result = run({
+    const result = cartPaymentMethodsTransformRun({
       paymentCustomization: {
         metafield: null
       }
     });
-    const expected = /** @type {FunctionRunResult} */ ({ operations: [] });
+    const expected = /** @type {CartPaymentMethodsTransformRunResult} */ ({ operations: [] });
 
     expect(result).toEqual(expected);
   });
 });
 {%- elsif flavor contains "typescript" -%}
 import { describe, it, expect } from 'vitest';
-import { run } from './run';
-import { FunctionRunResult } from '../generated/api';
+import { cartPaymentMethodsTransformRun } from './cart_payment_methods_transform_run';
+import { CartPaymentMethodsTransformRunResult } from '../generated/api';
 
 describe('payment customization function', () => {
   it('returns no operations without configuration', () => {
-    const result = run({
+    const result = cartPaymentMethodsTransformRun({
       paymentCustomization: {
         metafield: null
       }
     });
-    const expected: FunctionRunResult = { operations: [] };
+    const expected: CartPaymentMethodsTransformRunResult = { operations: [] };
 
     expect(result).toEqual(expected);
   });

checkout/javascript/payment-customization/default/src/index.liquid

@@ -1 +1 @@
-export * from './run';
+export * from './cart_payment_methods_transform_run';