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

Screenshot that shows the first shipping method removed

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

A diagram showing the steps involved in building a shipping script to hide a shipping method

Requirements

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 .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 Shipping and delivery.
  3. In the Rate 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 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 filterShippingMethod function 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 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 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.

Next steps