Custom Shipping Code API

The following are functions that are available for use within the Custom Shipping Code functionality available for Foxy stores.

• Chainable Functions: The javascript API is designed to be chainable - allowing you to string different function calls together to make more complex calls in a single line.
• Node.js: Note that we do update versions of Node regularly. If you have questions about the specific version we're using at a certain point in time, just ask. But when you update your code, be aware that updating your code will trigger a re-deploy behind the scenes, which may use a newer version of Node than your code previously used.

Add an additional shipping option

Parameters:

• id (Int) - The unique ID of the shipping rate, to a maximum of 11 digits
• price (Float) - The price, to 2 decimal places
• carrier (String) - The carrier name
• service_name (String) - The service name

Returns: Rates - The current rates object with the new rate included

Errors:

• A non-integer is passed for the id
• A non-float is passed for the price
• Both the carrier and service_name parameters are missing
• A rate with the specified id already exists

Examples:

• rates.add(10001, 15.95, 'FoxyPost', 'Standard');
• rates.add(10002, 40, '', 'Express Shipping');

Notes:

• The id needs to be at least 10000. If you pass an id less than that, it will be increased by 10000 - if an id of 15 is passed, the resulting ID will be 10015.
• At least the method or service_name needs to be included, but including both is optional.
• Any handling fees or flat rates from the categories present in the cart are not automatically added onto the specified price. To add those to your rates, see addHandling(), addFlatRate() and addHandlingAndFlatRate().

Filters the current rates object using the provided selector

Parameters:

• selector (Number, String or Array) - Can be the ID of a rate, a string containing the method and/or the service name (or a subset of) or an array of ID's.

Returns: Rates - A new rates object, filtered based on the provided selector

Examples:

• rates.filter(1); - Filter to the rate with an ID of 1
• rates.filter('FedEx'); - Filter to any rate with a method of “FedEx”
• rates.filter('Overnight'); - Filter to any rate with the text “Overnight” present
• rates.filter('USPS Ground'); - Filter to any “USPS” rates with a method containing “Ground”
• rates.filter([1,2,5,7]); - Filter to rates with an ID of 1,2,5 and 7

Notes:

• Strings are case-insensitive when matching

Set the rates in the current object to be hidden, preventing them from returning to the customer

Returns: Rates - The current rates object

Examples:

• rates.hide(); - Hide all rates
• rates.filter("express").hide(); - Hide all rates with “express” in the name

Notes:

• Hidden rates are still present to work with within the code (eg. still included if you filter for them later), but won't be included when returned to the customer if still hidden

Set the rates in the current object to be shown, ensuring they're returned to the customer

Returns: Rates - The current rates object

Examples:

• rates.show(); - Show all rates
• rates.filter("express").show(); - Show all rates with “express” in the name

Checks if rates exist in the current rates object, or if a given selector is present if one is passed

Returns: Boolean - true or false depending if any matching rates are found

Parameters:

• selector (Number, String or Array) [optional] - Can be the ID of a rate, a string containing the carrier and/or the service name (or a subset of) or an array of ID's.

Examples:

• rates.exists(); - will return true if there are any rates in the current object
• rates.exists('UPS'); - will return true if there are any rates from UPS
• rates.exists([1,2,5]); - will return true if at least a rate exists with an ID of either 1, 2 or 5

Notes:

• If passing an array of ID's, the match will return true if only one of the rates are present

The number of rates in the current rates object

Returns: Int - The number of rates in the current rates object

Examples:

• rates.count();

Get the current rate's ID

Returns: Int - The ID of the current rate

Examples:

• rates.filter("UPS Ground").id(); - Returns the ID for “UPS Ground”

Notes:

• If executed on a rates object with multiple rates, the ID of the first rate is returned

Set the current rate's ID

Parameters:

• value (Int) - the new ID for the rate

Returns: Rates or Rate - Either the individual rate or current rates object

Errors:

• Setting the ID on a rates object with multiple rates
• Setting the ID to one that already exists
• Setting the ID on a native rate (from USPS, FedEx or UPS)

Examples:

• rates.filter(10002).id(10003); - Updates the rate with an ID of 10002 to now have an ID of 10003

Note:

• It's not possible to change the ID of a rate from one of our native integrations, including USPS, FedEx or UPS.
• The id needs to be at least 10000. If you pass an id less than that, it will be increased by 10000 - if an id of 15 is passed, the resulting ID will be 10015.

Get the current rate's price

Returns: Float - The price of the current rate

Examples:

• rates.filter("UPS Ground").price(); - Returns the price for “UPS Ground”

Notes:

• If executed on a rates object with multiple rates, the price of the first rate is returned

Set the current rate or rate's price

Parameters:

• modifier String or Number - Can either be a number (which sets the price to match) or a string containing the operator and a number eg '+20' , '-10' , '*2' , '/2.5' , '=15'. You can also append the string with a % sign to make the operation based on a percentage, eg '+20%' - add 20%, '-20%' - less 20%, '/20%' - divide by 20%, '*20%' - multiply by 20%.

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.filter(1).price(5); - Will set rate with an ID of 1 to be $5
• rates.price('*2'); - Will set all rates to double their current price
• rates.filter('FedEx').price('+5'); - Will set all rates for FedEx to be $5 more than what they returned as
• rates.filter('Overnight').price('-5'); - Will set all rates with a service name that contains 'Overnight' to be $5 less than returned
• rates.filter('USPS Express').price('=6'); - Will set any rates from USPS that contain the word 'Express' to be $6
• rates.filter([1,2,5,7]).price('/2'); - Will set rates with ID's 1, 2, 5 and 7 to be half their current price
• rates.filter('USPS').price('+20%'); - Will add 20% of the price to each of the USPS rates

Notes:

• If a modification takes a rate's price to below 0, the rate will have a price of $0.

Get the current rate's carrier name

Returns: String - The carrier of the current rate

Examples:

• rates.filter(1).carrier(); - Returns the carrier name for a rate with an ID of 1

Notes:

• If executed on a rates object with multiple rates, the carrier of the first rate is returned

Set the current rate's carrier name

Parameters:

• value (String) - the new carrier name for the rate

Returns: Rates or Rate - Either the individual rate or current rates object

Errors:

• Setting to blank if the carrier name is already blank

Examples:

• rates.carrier('FoxyPost'); - Updates all rates to have a carrier of “FoxyPost”
• rates.filter([1,2,5]).carrier('FoxyPost'); - Updates rates with an ID of 1, 2 or 5 to have a carrier of “FoxyPost”

Get the current rate's service name

Returns: String - The service name of the current rate

Examples:

• rates.filter(1).service(); - Returns the service name for a rate with an ID of 1

Notes:

• If executed on a rates object with multiple rates, the service name of the first rate is returned

Set the current rate's service name

Parameters:

• value (String) - the new service name for the rate

Returns: Rates or Rate - Either the individual rate or current rates object

Errors:

• Setting to blank if the carrier is already blank

Examples:

• rates.service('Standard'); - Updates all rates to have a service name of “Standard”
• rates.filter("fedex home delivery").service('Ground'); - Updates the “Fedex Home Delivery” rate to have a service name of “Ground” instead

Iterate over the current rates object, executing a function on each individual rate.

Parameters:

• function (Function) - the function to execute for each rate

Returns: Rates - The current rates object

Examples:

• rates.each(function() { if (this.id() < 10) { this.price("+5"); } }); - Updates any rate with an ID less than 10 to be $5 more expensive
• rates.filter("FedEx").each(function() { if (this.price() > 100) { this.hide(); } }); - Hides any FedEx rate that has a price over $100

Notes:

• In the function passed to each(), this represents the individual rate object

Returns the first shipping rate from the current object

Returns: Rate - An individual Rate object

Examples:

• rates.first(); - Returns the first rate in the current rates object
• rates.filter("UPS").first(); - Returns the first UPS rate

Returns the last shipping rate from the current object

Returns: Rate - An individual Rate object

Examples:

• rates.last(); - Returns the last rate in the current rates object
• rates.filter("UPS").last(); - Returns the last UPS rate

Sorts the current rates object by price, allowing you to sort the rates into a known order when interacting with them in your custom code.

Parameters:

• direction (String) [Optional] - the direction to sort, either 'asc' (default) or 'desc'.

Returns: Rates - The current rates object

Examples:

• rates.sort(); - Sorts the rates in ascending price order
• rates.filter("ups").sort("desc").first(); - Return the most expensive UPS rate

Notes:

• No matter how the rates are sorted within the custom code, they will always be displayed in ascending order based on the price when shown to the customer.

Adds the category handling fees to the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.addHandling(); - Add handling fees to all rates
• rates.filter("FoxyPost").addHandling(); - Add handling fees to all FoxyPost rates

Notes:

• Native rates for USPS, FedEx and UPS will already include the handling fee

Removes the category handling fees from the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.removeHandling(); - Remove handling fees to all rates
• rates.filter("FoxyPost").removeHandling(); - Remove handling fees to all FoxyPost rates

Notes:

• Custom rates added with add() will not include the handling fee by default

Adds flat rate shipping fees if present from other categories in the cart to the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.addFlatRate(); - Add flat rate shipping fees to all rates
• rates.filter("FoxyPost").addFlatRate(); - Add flat rate shipping fees to all FoxyPost rates

Notes:

• Native rates for USPS, FedEx and UPS will already include any flat rate shipping fees

Removes flat rate shipping fees if present from other categories in the cart from the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.removeFlatRate(); - Remove flat rate shipping fees to all rates
• rates.filter("FoxyPost").removeFlatRate(); - Remove flat rate shipping fees to all FoxyPost rates

Notes:

• Custom rates added with add() will not include flat rate shipping fees if present in the cart by default

Adds the category handling and flat rate shipping fees if present from other categories in the cart to the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.addHandlingAndFlatRate(); - Add handling and flat rate shipping fees to all rates
• rates.filter("FoxyPost").addHandlingAndFlatRate(); - Add handling and flat rate shipping fees to all FoxyPost rates

Notes:

• Native rates for USPS, FedEx and UPS will already include any handling and flat rate shipping fees

Removes the category handling and flat rate shipping fees if present from other categories in the cart from the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.removeHandlingAndFlatRate(); - Remove handling and flat rate shipping fees to all rates
• rates.filter("FoxyPost").removeHandlingAndFlatRate(); - Remove handling and flat rate shipping fees to all FoxyPost rates

Notes:

• Custom rates added with add() will not include handling and flat rate shipping fees if present in the cart by default

Removes the “1-Day”, “2-Day” etc text from service names for the current rates

Returns: Rates or Rate - Either the individual rate or current rates object

Examples:

• rates.removeDayTimeframes(); - Removes any day timeframes in services names from all rates

Notes:

• This matches specifically the format of #-Day that USPS uses in some of its service names

Get the error message for the shipping rates

Returns: String or Boolean - The current error message, or false if none set

Examples:

• rates.error();

Set the error message for the shipping rates

Parameters:

• message (String) - The error message you want to set

Returns: Rates - The current rates object

Examples:

• rates.error("Sorry, we can't ship to your location");

Notes:

• If any error message is set, the error will be passed back to the customer instead of any rates that may be present

Resets the shipping rates and error message to blank

Returns: Rates - An empty rates object

Examples:

• rates.reset();

Notes:

• This will clear all rates, including any from native integrations like USPS, FedEx and UPS