Shopify Payment Customization Functions: The Complete Guide

Summary & Key Technical Insights

• Legacy Scripts are Deprecated: Shopify's legacy checkout.liquid scripts and Ruby Scripts are deprecated in favor of Checkout Extensibility and Shopify Functions.
• What is the Payment Customization API?: A backend serverless execution API that allows apps to hide, rename, and reorder payment gateways during checkout calculation.
• Performance Impact: Shopify Functions run in isolated WebAssembly (Wasm) runtimes on Shopify's global edge network in under 5 milliseconds, creating zero frontend latency or Core Web Vitals degradation.
• No-Code Implementation: While writing a native Shopify Function requires Rust/JavaScript tooling and CLI deployments, apps like Lokally package these functions into an intuitive visual dashboard accessible on all Shopify plans.

With the deprecation of checkout.liquid, merchants and developers have transitioned to Shopify Functions for customizing the checkout experience.

One of the most widely used APIs in this new architecture is the Payment Customization API. In this guide, we explore how Payment Customization Functions work under the hood, the common use cases, and how you can implement dynamic payment rules on your store.

Why Shopify Functions Replaced Checkout Scripts

In the legacy Shopify architecture, merchants with Shopify Plus used Ruby scripts inside Script Editor or custom JavaScript tags injected into checkout.liquid to modify checkout options.

This legacy approach had major flaws:

1. Security & Reliability: Frontend JavaScript could be bypassed or blocked by ad blockers and extensions.
2. Speed: Client-side scripts caused layout shifts (CLS) and delayed payment rendering.
3. Plan Restriction: Script Editor was restricted exclusively to Shopify Plus merchants ($2,000+/mo).

Shopify Functions solved this by compiling logic into WebAssembly binaries (Wasm) that execute directly on Shopify's checkout servers. They execute alongside Shopify's core checkout processing, making them tamper-proof, instant, and available to all Shopify plans.

The Three Core Operations of Payment Customization

The Payment Customization GraphQL schema defines three primary mutations:

1. hide (Hide Payment Method)

Hides a specific payment gateway if conditions are met.

• Common Use Case: Hiding Cash on Delivery (COD) for high-RTO delivery pincodes, international orders, or orders exceeding ₹10,000.

2. rename (Rename Payment Method)

Dynamically alters the display label of a payment gateway on the checkout page.

• Common Use Case: Renaming "Razorpay / UPI" to "Instant UPI (Save ₹50 + Free Gift)" to drive prepaid adoption.

3. move (Reorder Payment Methods)

Changes the sorting order of payment methods to prioritize preferred gateways.

• Common Use Case: Moving UPI and One-Click Checkout to the top of the payment list while pushing higher-fee credit card options or COD to the bottom.

How Shopify Functions Execute (Architecture Diagram)

Shopper Enters Address / Pincode
              │
              ▼
Shopify Checkout Engine triggers Function
              │
              ▼
Wasm Runtime evaluates Payment Customization Rules (< 5ms)
              │
              ├─ Check 1: Is shipping address in High-Risk Pincode list?
              │     └─ YES ──► Emit `hide` operation for COD
              │
              ├─ Check 2: Is order value > ₹5,000?
              │     └─ YES ──► Emit `move` operation to prioritize Card / NetBanking
              │
              ▼
Shopify displays tailored payment methods instantly at checkout

Option A: Building a Custom Payment Function from Scratch

For development teams with Shopify CLI and Rust/TypeScript experience, scaffolding a function requires:

# 1. Scaffold the extension
shopify app generate extension --template payment_customization --flavor typescript

# 2. Define your input query in run.graphql
query RunInput {
  cart {
    cost {
      totalAmount {
        amount
      }
    }
    deliveryGroups {
      deliveryAddress {
        zip
        countryCode
      }
    }
  }
}

Then in src/run.ts, you return an operations array:

import type { RunInput, FunctionRunResult } from "../generated/api";

const NO_CHANGES: FunctionRunResult = { operations: [] };

export function run(input: RunInput): FunctionRunResult {
  const zip = input.cart.deliveryGroups[0]?.deliveryAddress?.zip;
  const BLOCKED_ZIPS = ["110006", "800001", "201301"];

  if (zip && BLOCKED_ZIPS.includes(zip)) {
    return {
      operations: [
        {
          hide: {
            paymentMethodId: "gid://shopify/PaymentCustomizationPaymentMethod/12345"
          }
        }
      ]
    };
  }

  return NO_CHANGES;
}

The Challenge of Custom Code:

• Every time your marketing or operations team wants to add 50 new pincodes or change a rule, a developer must edit the code, re-build the WebAssembly binary, and deploy via the Shopify CLI.
• There is no user-friendly merchant dashboard for non-technical team members.

Option B: Using Lokally (No-Code Pre-Built Payment Customization Engine)

For non-developers and growth teams, Lokally provides a pre-built Shopify Function with a visual admin interface:

1. Native Server-Side Speed: Compiles into Shopify Functions directly on your store.
2. Visual Dashboard: Create, update, or pause payment rules with toggle switches—no CLI needed.
3. CSV Bulk Import: Upload 1,000+ postal codes in seconds without touching code or JSON files.
4. Stacked Regional Rules: Combine payment customization with storefront pincode widgets and regional pricing from one single app.

Frequently Asked Questions

Do Payment Customization Functions work on one-page checkout?

Yes. Shopify Functions are fully compatible with Shopify's 1-page checkout, 3-page checkout, and Shop Pay accelerated checkout.

Are Shopify Functions available on the Shopify Basic plan?

Yes! Unlike legacy scripts which required a $2,000/month Shopify Plus plan, Shopify Functions are supported on Basic, Shopify, Advanced, and Plus plans.

Can I hide payment methods based on customer tags?

Yes. The Function input query can read customer tags (e.g. wholesale, vip, fraud_risk) and conditionally emit hide or move operations.

Related reading: PayRules vs Payfy vs Lokally Comparison and How to Block High-RTO Pincodes in Shopify Checkout.