Skip to content
Search Articles/

less than a minute read • Updated 11 minutes 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

  1. 1

    Navigate to your store's Shipping page in the Foxy admin.

  2. 2

    Under "Custom Shipping Code," toggle it to Active. A code editor will appear.

  3. 3

    Write your JavaScript and click Update (or the save/checkmark button).

  4. 4

    Foxy will display a "shipping code is being deployed" message. Wait about 15 to 20 seconds and refresh the page. If your code is still in the editor, deployment succeeded.

  5. 5

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

  6. 6

    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.