Rename a payment method

In this tutorial, you'll use Shopify Scripts to create a payment methods script that lets merchants customize the payment method names offered to their customers at checkout.

What you'll learn

After you've finished this tutorial, you'll have accomplished the following:

  • Created a script that renames the first payment method
  • Tested your script's logic
  • Deployed your script to the Shopify platform and associated it with a custom app
  • Enabled the script in a Shopify store
  • Viewed your script's run time in your Partner Dashboard
  • Familiarized yourself with adding configurations to make your code reusable

Screenshot that shows a renamed payment method

The following diagram shows the steps you'll follow to complete the workflow:

A diagram showing the steps involved in building a payment script to hide payment methods


Step 1: Create the script

Using Shopify CLI, run the following command:

Update the payment script

Replace the contents of your payment script in src/script.ts with the code below. It introduces a renamePaymentMethod function that returns an array of PaymentMethods.RenameProposal. In this case, we are renaming the first payment method to be Hello Payments.

Step 2: Test the script

To test your script's logic, you create unit tests in script.spec.ts and then run them using the npm test command.

Add some tests by replacing the contents of your payment script test/script.spec.ts with the code below. The createPurchaseProposal function is used to create a test cart with a single line item which is used in the tests. There's a single test that checks that only the first payment method name has changed to Hello Payments.

In your terminal, run the test suite:

Step 3: Deploy the script

To deploy a script to the Shopify platform and associate it with an app, run the following command:

When you deploy a script, it's uploaded to the Shopify platform and registered to the app. When you deploy your script again using the shopify script push --force command, it overwrites the current live version of the script. If the script is enabled in a store, then it stays enabled after it's overwritten. If the script had configuration values set, then the new script continues to use those values.

Redeploy a script

The next time that you run the shopify script push command, Shopify CLI reads the .env file and does the following:

  • Connects to the app that is listed in .env
  • Checks the app for a script that matches the UUID

Deploy a script to a different app

If you want to deploy the script to a different app, then delete the .env file and run shopify script push.

Step 4: Enable the script

By default, scripts are available to be used on a store with the app installed, but they aren't enabled. To alter the behavior of checkout, you need to enable the script:

  1. In your store's Shopify admin, click Settings.
  2. Click Payments.
  3. In the Payment method customizations section, click Create customization.
  4. Select the script to enable and update its status to On.
  5. Click Save.

Step 5: Monitor and debug the script

You can monitor your script and investigate errors from the app's Extensions section in your Partner Dashboard:

  1. In your Partner Dashboard, click Apps.
  2. Click the name of your app.
  3. Click Extensions.
  4. Click Checkout and then click the name of your script.

    The script's run times and errors information displays. It can take up to two minutes for run results to display in your Partner Dashboard.

Error types

All script errors are labelled as RunErrors in the Partner Dashboard. You might experience the following types of errors:

  • Execution timeouts - These errors occur when your script takes too long to run. For example, an error might occur that causes a script to run indefinitely, such as an infinite loop:

  • Runtime errors - These errors are general errors that can't be identified at compile time. This includes the following errors:

    • stack overflow
    • integer divide by zero
    • unreachable, including any thrown errors that you added to your code

Debug a script

You can add message logs to your scripts to help debug them when errors occur.

Use Console.log and as-pect’s log function to log messages from your script and tests. Before you use either, review the following considerations:

  • In AssemblyScript, Console.log accepts only strings as its argument.
  • as-pect’s log function is easier to use because it accepts multiple data types and its output is better formatted. You can use log in unit tests and in scripts as long as you remove them from the scripts before you push them.

Avoid breaking changes

When you push a new script, it replaces the current live script on the app. If the new script's configuration schema isn't backward compatible, then make sure that the configuration values are also updated.

Common runtime errors related to configurations involve the following issues:

  • Missing configuration values
  • Type casting errors
  • Renaming configuration keys

You can minimize a script's downtime by contacting the store and working with their staff to delete and recreate their customizations. You can also include checks in your script to better handle errors. For example, if a configuration value doesn't exist, then your script could use a default value instead.

Delete scripts and apps

You can delete your scripts from apps by using the Partner Dashboard. Before you delete a script, make sure that the script's status is turned off in all stores.

Don't delete any app that you add scripts to.

Step 6: Add configurations

To make the code reusable, you can replace hard-coded variables in your script with configurations. Configurations let merchants and staff customize your script by entering values and options in the Shopify admin. When your script runs, these values are passed to your script as input in key-value pairs.

The script's schema property determines whether the script has user-configurable properties. Configurations can accept single values or a list of values.

Add configurable values

In script.json, include the payment gateway to rename and the new gateway name as your two configurable values:

Retrieve configuration values

In your script, use the configuration.get method to retrieve the configuration values. You accomplish this by passing in configuration to the renamePaymentMethod function and getting the configured values by key. You now can iterate over all payment methods and rename the payment method that matches the configured value.

Test the configurations

Update your tests by copying the code below to test/script.spec.ts:

In your terminal, run the test suite:

Re-deploy the script

Deploy the updated code to Shopify with the push command. This time, you need to use the --force option to overwrite the existing script:

In the Payment settings page, you can now enter the two new configuration values for your script and test in checkout. Currently, it can take up to 5 minutes before your changes take effect at checkout.

Money and currency tips

The following section outlines some tips for using currency and money values in your scripts.

International pricing and multi-currency aren't supported

Your store can't use international pricing or multi-currency with Shopify Scripts. All money values use the customer's currency (also referred to as the presentment currency). Because Shopify doesn't support international or multi-currency, the presentment currency is the same as the store currency.

Use configurations to provide money values

Don't hard code money amounts into your scripts. Use configurations instead to provide the monetary amounts to your script. Because configuration values are saved as strings, you need to do the following:

  1. Transform the string into a subunits value.
  2. Create a Money object with the transformed subunits value. The currency needs to be the same as the store currency.


Order of operations for Money objects

Money objects override common binary operations like multiplication, division, and addition. You can also apply these binary operations with a Money object and a numeric value, such as float. When you do this, the order of operations matters. The order matters because the binary operation is just a plain method call in the Money class that expects a numeric value as a parameter. As a result, Money * 4 works but 4 * Money doesn't.

Use SafeParseInt instead of ParseInt

AssemblyScript has some special cases when parsing strings into numeric values. For example, I32.parseInt("bad") returns 0, but F64.parseInt("bad") returns NaN. F64 is the most flexible numeric type in AssemblyScript and you're encouraged to use it.

To avoid the complexity of parseInt, use the safeParseInt function. safeParseInt throws an exception when the passed string is not a number. safeParseInt is defined in the Scripts library, so it's available for use in all scripts.

Next steps