Table of Contents
Custom Shipping Code API
The following are functions that are available for use within the Custom Shipping Code functionality available for Foxy stores.
Notes
- 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(id, price, carrier, service_name)
Add an additional shipping option
Parameters:
id
(Int) - The unique ID of the shipping rate, to a maximum of 11 digitsprice
(Float) - The price, to 2 decimal placescarrier
(String) - The carrier nameservice_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
andservice_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 least10000
. If you pass anid
less than that, it will be increased by10000
- if anid
of15
is passed, the resulting ID will be10015
. - At least the
method
orservice_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()
andaddHandlingAndFlatRate()
.
filter(selector)
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 1rates.filter('FedEx');
- Filter to any rate with a method of “FedEx”rates.filter('Overnight');
- Filter to any rate with the text “Overnight” presentrates.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
hide()
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 ratesrates.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
show()
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 ratesrates.filter("express").show();
- Show all rates with “express” in the name
exists(selector)
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 returntrue
if there are any rates in the current objectrates.exists('UPS');
- will returntrue
if there are any rates from UPSrates.exists([1,2,5]);
- will returntrue
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
count()
The number of rates in the current rates object
Returns: Int - The number of rates in the current rates object
Examples:
rates.count();
id()
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
id(value)
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 least10000
. If you pass anid
less than that, it will be increased by10000
- if anid
of15
is passed, the resulting ID will be10015
.
price()
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
price(modifier)
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 $5rates.price('*2');
- Will set all rates to double their current pricerates.filter('FedEx').price('+5');
- Will set all rates for FedEx to be $5 more than what they returned asrates.filter('Overnight').price('-5');
- Will set all rates with a service name that contains 'Overnight' to be $5 less than returnedrates.filter('USPS Express').price('=6');
- Will set any rates from USPS that contain the word 'Express' to be $6rates.filter([1,2,5,7]).price('/2');
- Will set rates with ID's 1, 2, 5 and 7 to be half their current pricerates.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.
carrier()
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
carrier(value)
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”
service()
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
service(value)
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
each(function)
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 expensiverates.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
first()
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 objectrates.filter("UPS").first();
- Returns the first UPS rate
last()
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 objectrates.filter("UPS").last();
- Returns the last UPS rate
sort(direction)
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 orderrates.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.
addHandling()
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 ratesrates.filter("FoxyPost").addHandling();
- Add handling fees to all FoxyPost rates
Notes:
- Native rates for USPS, FedEx and UPS will already include the handling fee
removeHandling()
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 ratesrates.filter("FoxyPost").removeHandling();
- Remove handling fees to all FoxyPost rates
Notes:
- Custom rates added with
add()
will not include the handling fee by default
addFlatRate()
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 ratesrates.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
removeFlatRate()
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 ratesrates.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
addHandlingAndFlatRate()
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 ratesrates.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
removeHandlingAndFlatRate()
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 ratesrates.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
removeDayTimeframes()
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
error()
Get the error message for the shipping rates
Returns:
String or Boolean - The current error message, or false
if none set
Examples:
rates.error();
error(message)
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
reset()
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