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
The following diagram shows the steps you'll follow to complete the workflow:
- You've installed Shopify CLI.
- You've created a custom app. Shopify Scripts currently only supports custom apps.
- You've installed the custom app on a store.
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
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
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
- 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:
- In your store's Shopify admin, click Settings.
- Click Payments.
- In the Payment method customizations section, click Create customization.
- Select the script to enable and update its status to On.
- 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:
- In your Partner Dashboard, click Apps.
- Click the name of your app.
- Click Extensions.
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.
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.
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.logaccepts 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
login 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.
schema property determines whether the script has user-configurable properties. Configurations can accept single values or a list of values.
Add configurable values
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
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
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:
- Transform the string into a subunits value.
- Create a
Moneyobject 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.