====== Custom Shipping Code API ====== The following are functions that are available for use within the [[v:2.0:shipping:custom_code|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 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()''. ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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 rates * ''%%rates.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 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 ---- ===== 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 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''. ---- ===== 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 $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. ---- ===== 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 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 ---- ===== 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 object * ''%%rates.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 object * ''%%rates.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 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. ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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 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 ---- ===== 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