Custom Shipping Code API Reference

Overview

The rates object is the primary interface for manipulating shipping rates in Custom Shipping Code. It's pre populated with any rates returned from carriers or the custom endpoint, and all methods are chainable (unless they return a value).

Adding rates

rates.add(id, price, method, service_name)

Adds a new rate. id must be 10000 or higher (if you pass a lower number, 10000 is added automatically). At least one of method or service_name is required. Pass an empty string for the one you don't need.

rates.add(10001, 5.99, 'FoxyPost', 'Standard');
rates.add(10002, 0, '', 'Free Shipping');

Custom rates added with rates.add() do not automatically include handling fees or flat rates from other categories. Use the handling/flat rate helpers (below) if you need to include them.

Filtering rates

rates.filter(selector)

Returns a new Rates object containing only matching rates. The original collection is not modified. The selector can be:

• A number — matches by service_id

• A string — matches against method and service_name (case insensitive)

• An array of numbers — matches multiple service_id values

rates.filter(10001).price(0);
rates.filter('fedex').hide();
rates.filter([10001, 10002]).price('+5');

Checking if rates exist

rates.exists([selector])

Returns true if rates exist. If a selector is provided, returns true only if matching rates exist. Selector works the same as filter().

if (!rates.exists()) {
  rates.add(10001, 15, '', 'Fallback Rate');
}

Showing and hiding rates

rates.hide() — hides the matched rates from the customer. Hidden rates remain in the collection and can still be filtered or shown later.

rates.show() — makes previously hidden rates visible again.

rates.filter('usps').hide();
rates.filter(10001).show();

Modifying prices

rates.price(modifier)

Sets or adjusts the price of matched rates. The modifier can be:

• A number — sets the price to that exact value

• A string with an operator prefix:

  • '+5' — adds 5 to the current price

  • '-5' — subtracts 5

  • '*2' — multiplies by 2

  • '/2' — divides by 2

  • '=15' — sets to exactly 15 (same as passing a number)

  • '+20%' — adds 20% of the current price

  • '-20%' — subtracts 20% of the current price

rates.filter('usps').price('+2.50');
rates.filter(10001).price(0);
rates.filter('fedex').price('-10%');

Modifying labels

rates.method(string) — sets the carrier/method name for matched rates.

rates.service(string) — sets the service name for matched rates.

When called without an argument inside an .each() callback, these return the current value.

rates.filter('usps').method('US Postal Service');
rates.filter(10001).service('Economy');

Note: HTML in method or service strings is not currently supported.

Iterating over rates

rates.each(fn)

Calls fn for each matched rate. Inside the callback, this refers to the individual rate and exposes .price(), .method(), .service(), .hide(), and .show().

rates.filter('fedex').each(function() {
  this.service(this.service() + ' (Signature Required)');
});

Sorting

rates.sort()

Sorts matched rates by price (ascending). Note that Foxy always re sorts rates ascending for display regardless of your code's ordering, so this is mainly useful if you need sorted iteration.

Handling fees and flat rates

Custom rates added via rates.add() do not automatically include handling fees or flat rates from other categories in the cart. These helpers let you add or remove them:

• rates.addHandling() — adds handling fees from other categories to matched rates

• rates.addFlatRate() — adds flat rate fees from other categories

• rates.addHandlingAndFlatRate() — adds both

• rates.removeHandling() — removes handling fees from matched rates

• rates.removeFlatRate() — removes flat rate fees

• rates.removeHandlingAndFlatRate() — removes both

Errors and resets

rates.error(message) — sets an error message. If set, the error is displayed to the customer instead of any rates (error takes precedence).

rates.reset() — clears all rates and any error message.

The cart object

The cart object available in Custom Shipping Code contains the same payload sent to the Custom Shipping Endpoint. See the [Shipping Payload Reference] for the full structure, field descriptions, and common access patterns.