Build a payment customization user interface
Merchants create and manage payment customizations in the Shopify admin. Shopify uses the URLs that you configure to render the payment customization creation and editing experience for the merchant. You can customize this UI for your function's configuration needs, or to meet other requirements of your app.
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to do the following tasks:
- Create an App Bridge UI that enables users to create a function owner.
- Configure the UI paths for your function.
Requirements
Anchor link to section titled "Requirements"- You've completed the Add configuration to your payment customization tutorial.
- You created your app with the Remix app template.
Step 1: Create the frontend UI for your function
Anchor link to section titled "Step 1: Create the frontend UI for your function"The following example builds a React-based page that enables merchants to create and configure a new payment customization. The code renders a frontend page in your app and uses the GraphQL Admin API to create a payment customization.
In
app/routes
, create a new file namedapp.payment-customization.$functionId.$id.jsx
.The Shopify Remix app template uses file-based routing, so the file name determines the page's URL. The
$
prefix indicatesfunctionId
andid
are dynamic segments. The path for this page is/app/payment-customization/{functionId}/{id}
.Add the following code in
app.payment-customization.$functionId.$id.jsx
:- The
loader
function handles fetching the data to populate the form and is used when this page has anid
value that is notnew
. - The
action
function handles submitting the form data to Shopify to create the payment customization. - The
PaymentCustomization
function renders the page and form components using Polaris components and Remix hooks.
- The
Step 2: Update your input query to use an app-owned namespace
Anchor link to section titled "Step 2: Update your input query to use an app-owned namespace"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. The query differs slightly in JavaScript and Rust due to code generation requirements.
Step 3: Configure the create UI path for your function
Anchor link to section titled "Step 3: Configure the create UI path for your function"Settings in the shopify.extension.toml
file define the URLs that Shopify uses for merchants to create and edit payment customizations using your function. Shopify automatically fills in any dynamic tokens in these URLs.
In extensions/payment-customization/shopify.extension.toml
, populate the two settings directly under [ui.paths]
. This change is automatically reflected.
Step 4: Update your app access scopes
Anchor link to section titled "Step 4: Update your app access scopes"You must request the write_payment_customizations
access scope to invoke payment customization mutations in the Admin API.
In
shopify.app.toml
in the root of your app, add thewrite_payment_customizations
scope.Push your updated configuration to Shopify:
Restart your app:
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.
Step 5: Create and test your payment customization
Anchor link to section titled "Step 5: Create and test your payment customization"- From the Shopify admin, go to Settings > Payments.
- Under the Payment customizations section, click Manage.
- If you have existing customizations from previous tutorials, then click the checkbox next to each of them, and then click Deactivate.
- Click Add a customization and then click payment-customization by {your app}.
Fill in the payment customization form, then click Save.
- For Payment method, use Cash on Delivery.
- For Cart total, use 200.
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.
Add additional items to your cart to raise the total over 200. Your payment function should now hide the Cash on Delivery payment option.
To debug your function, or view its output, you can review its logs in your Partner Dashboard.
- Log in to your Partner Dashboard and navigate to Apps > {your app} > Extensions > payment-customization.
- 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.