Hide a shipping method
In this tutorial, you'll use Shopify Scripts to create a shipping methods script that allows merchants to hide a shipping method offered to their customers at checkout based on a customer tag.
What you'll learn
After you've finished this tutorial, you'll have accomplished the following:
- Created a script that hides the first shipping 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:
Replace the contents of your shipping script in
src/script.ts with the code below. The script introduces a
filterShippingMethod function that returns a
ShippingMethods.FilterResponse. In this case, we are hiding the first shipping method.
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 shipping 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 is a single test that checks that only the first shipping method
Cheap Option is hidden.
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 Shipping and delivery.
- In the Rate 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 a customer tag and method name to hide:
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 shipping methods and hide the shipping method that matches the configured value if the customer tag matches.
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 Shipping 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.