Shopify payment customizations explained

A payment customization is a small program, called a Shopify Function, that an app adds to your store to change the payment step of checkout. It can hide, rename or reorder payment methods for a checkout while the shopper is on it. It doesn't change your payment settings, and it doesn't run in the Shopify admin or on POS. A store can have up to 25 active at once.

What is a payment customization?

Shopify describes the Payment Customization Function API as a way to rename, reorder and hide the payment methods available to customers during checkout. Two parts work together:

1. The function. An app supplies the logic, for example "hide Cash on Delivery when the cart total is above a limit". Shopify runs it during checkout.
2. The customization. This is the record in your store that switches the function on. In Shopify's API, each one has a title and an enabled status. Its settings, such as the limit you typed in the app, are usually saved in a metafield on the customization.

The function returns instructions ("hide this method", "rename that one") and checkout applies them. Your methods stay set up exactly as they are in Settings > Payments. That is why a payment customization can hide COD for one cart and show it for the next.

What can a payment customization change?

Hiding a method in only one place, such as only the express buttons at the top of checkout, is also limited to Shopify Plus. On other plans, hiding a method hides it everywhere in checkout.

What can a payment customization look at?

A function only receives the data it asks for. Shopify's documentation lists what it can ask for, including:

• the cart: its total, its items, and the products in it (with their tags)
• the customer, when the checkout is linked to one: tags, number of orders, amount spent, and whether they are signed in
• the delivery address and the checkout's country, language and market
• the list of payment methods, with their names
• settings the app saved in metafields

This is what makes rules like "hide COD for customers tagged cod-refused" or "show an Arabic name on the Arabic checkout" possible. For the practical choices (which app type, which plan, what to hide), see how to hide a payment method on Shopify.

Where do payment customizations run, and where don't they?

The draft order line is easy to miss. If you collect payment for a draft order inside the admin, you see every method. If you open the draft order's checkout link, the customization runs. To check a rule, always use the link: how to test checkout payment rules with draft orders.

What are the limits?

• 25 active per store. Shopify allows at most 25 active payment customization functions on each store. One app usually needs only one, so this matters when you stack many payment apps.
• Shop Pay. Inside Shop Pay, payment customizations only affect the gift card field.
• Wallets. Wallets such as Apple Pay and Google Pay can be removed, but not reordered.
• Names shown as logos. Shop Pay, Apple Pay, Google Pay, other wallets and the gift card field can't be renamed.
• Restricted methods. Shopify says plan and geographical restrictions apply. When a method is restricted, instructions that target it don't take effect at checkout.
• Card fields in the US and Canada. On plans below Plus, stores in these two countries can only customize non-card methods.

Which Shopify plans can use payment customizations?

Shopify says stores on any plan can use public apps from the Shopify App Store that contain Functions. Its checkout customization help page adds that you need at least the Basic plan and a compatible app.

Custom apps are different. Only stores on Shopify Plus can use custom apps that contain Function APIs. So a store on Basic can use a payment customization from a public app, but can't have a developer build a private one.

How do you see the payment customizations on your store?

Shopify's steps for adding one also show you where they live:

1. From your Shopify admin, go to Settings > Payments.
2. In the Payment customizations section, click Manage.
3. To add one, click Add customization, choose it, configure it and click Save.
4. Select the customizations you want to use and click Activate.

The same list is where to look if a method disappears from checkout and you don't know why. Each entry comes from an installed app, so the app that created it is where you change its rules.

Khaleeji COD adds one payment customization for all of its rules, and it only ever touches Cash on Delivery.

How is a payment customization different from similar Shopify terms?

If your store used payment Scripts, read from Shopify Scripts to Functions: what changed for payment rules. To rename Cash on Delivery with a customization, see how to rename Cash on Delivery at Shopify checkout.