Skip to content
Search Articles/

less than a minute read • Updated 2 days ago

Custom Shipping Code Overview

Write JavaScript in the Foxy admin to add, modify, or remove shipping rates.

Overview

Custom Shipping Code lets you enter JavaScript directly into your store's Foxy admin to control shipping rates. The code runs server side (Node.js) after all carrier rates and custom endpoint results have been collected, giving you the ability to add new rates, modify prices, rename services, hide or show rates, and return errors — all without hosting your own server.

How to enable

In your store's Shipping page, click Custom Shipping Code in the Shipping methods list, paste your code into the editor, and click Create, then Save. For a full walkthrough with each step, see [Add Custom Shipping Code].

Two things to set up alongside your code:

  • Enable "Prevent shipping rate tampering" (recommended) unless you have legacy browser side JavaScript that modifies rates.

  • Make sure any categories that should use custom code have their delivery type set to "Shipped using live shipping rates" with a default weight configured.

Runtime environment

Your code runs in a Node.js environment (server side, UTC timezone) with access to a set of pre installed Node modules. The code is isolated per store. async/await is supported for making external requests (for example, to query a third party API like Shippo). Note: the code editor's validation may show warnings on lines containing await; you can safely ignore these.

When you update your code, Foxy redeploys it behind the scenes. The Node.js version may be updated during redeployment, so avoid relying on version specific behavior.

Available globals

Two objects are available in your code environment:

  • rates — the rates collection, pre populated with any rates returned from carriers or the custom endpoint. This is the entry point to the Shipping API. See the [Custom Shipping Code API Reference] for the full method list.

  • cart — the same payload object that the Custom Shipping Endpoint receives. See the [Shipping Payload Reference] for the full structure.

A few Node modules are also available Node:

Examples

Here's a quick example to show how the rates and cart objects work together. This adds two rates and makes the standard option free when the cart total hits $40:

rates.add(10001, 5, 'FoxyPost', 'Standard');
rates.add(10002, 15, 'FoxyPost', 'Express');

if (cart['_embedded']['fx:shipment']['total_item_price'] >= 40) {
  rates.filter(10001).price(0).service('Free Shipping');
}

For many more ready to use examples (tiered rates, weight based pricing, coupon triggered free shipping, country tiers, label cleanup, and more), see [Custom Shipping Code Examples].

Need Help?

Did this article answer your questions? Need help with anything? Please click below to contact us.