Build a payment customization user interface

In this tutorial, you'll learn how to do the following tasks:

• Add a server endpoint to your node app that creates the function owner.
• Create an App Bridge UI that enables merchants to create the function owner.
• Configure the UI paths for your function.

• You've completed the Add configuration to your payment customization tutorial.
• You created your app with the node app template and you are using the @shopify/shopify-app-express middleware.

You can't invoke the GraphQL Admin API directly from your app frontend, so you must first create an API layer for the app to invoke.

1. In web/shopify.js, update the version used for Shopify API calls to 2023-04.

2. In web/index.js, add an import for GraphqlQueryError under the existing import statements. This is helpful when trapping errors from the node GraphQL client.

3. Still in web/index.js, add the endpoint to create a payment customization directly after app.use(express.json()).

This example builds a React-based page that enables merchants to create and configure a new payment customization. The Shopify node app template uses file-based routing, so the file path of the page will determine its URL.

1. Under web/frontend/pages, create a new folder called payment-customization. This folder name isn't important, but it determines the URL that you configure later in Step 3.

2. Under payment-customization, create a new folder called [functionId]. The square brackets ([]) indicate that this is a route parameter, which you can access in your frontend through the useParams hook.

3. Create a new file in [functionId] called new.jsx with the following code.

   You now have a frontend page in your app that can invoke your app backend to create a payment customization.

In the previous tutorial, you used a metafield namespace that was accessible to any app, so that the metafield namespace could be populated using GraphiQL. To make your function ready for production, you should update the metafield namespace to use a reserved prefix so that other apps can't use your metafield.

Replace the code in the extensions/payment-customization/input.graphql file with the following code:

Settings in the shopify.function.extension.toml file define the URLs that Shopify uses for merchants to create and edit payment customizations based on your function. Shopify automatically fills in any dynamic tokens in these URLs.

1. In extensions/payment-customization/shopify.function.extension.toml, populate the two settings directly under [ui.paths].

2. To update this setting, deploy your app and function by running the following command from your app root folder:

   A message from the CLI displays and indicates that your payment-customization function is live.

You must request the write_payment_customizations access scope to invoke payment customization mutations in the Admin API.

1. In shopify.app.toml in the root of your app, add the write_payment_customizations scope.

2. Restart your app.

3. Use the URL provided by the CLI to open and re-install your app. You should be prompted to accept the new access scope permissions in your store.

1. From the Shopify admin, go to Settings > Payments.
2. Under the Payment customizations section, click Manage.
3. If you have existing customizations from previous tutorials, then click the checkbox next to each of them, and then click Deactivate.
4. Click Add a customization and then click payment-customization by {your app}.

5. Fill in the payment customization form, then click Save.

   • For Payment method, use Cash on Delivery.
   • For Cart total, use 200.

6. Open your development store and build a cart with a total (including shipping and tax) under 200. The Cash on Delivery payment method should display in checkout.

7. Add additional items to your cart to raise the total over 200. Your payment function should now hide the Cash on Delivery payment option.

8. To debug your function, or view its output, you can review its logs in your Partner Dashboard.

   1. Log in to your Partner Dashboard and navigate to Apps > {your app} > Extensions > payment-customization.
   2. Click on any function run to view its input, output, and any logs written to STDERR.

• Learn more about how Shopify Functions work and the benefits of using Shopify Functions.
• Consult the API references for Shopify Functions.

• Learn how to use variables in your input query.

• Review the UX guidelines to learn how to implement payment customizations in user interfaces.