How it works

This section introduces you to "how JsRates works". Please read this section and watch the video at the end to understand how to use JsRates.

JsRates enables you to define custom shipping rules through JavaScript coding within the app's Editor page. Your main task is to develop a JavaScript module, named calculateShippingRates.js, which exports an asynchronous function calculateShippingRates().

This function is executed by the JsRates server to calculate shipping rates during customer checkout.

A sample code

The `calculateShippingRates()` Function

Function signature: async function calculateShippingRates(DATA, env)

DATA: A JSON object that contains information about the shipping request, including the shipping origin, destination, cart items, currency, and locale. Shopify sends this data to your JsRates app whenever your customers proceed to checkout an order.
env (optional): A Javascript object that contains encrypted environment variables that you defined in your JsRates app Settings page.

Your implementation of calculateShippingRates(DATA, env) should process the DATA object and return an array of shipping rates.

Sample DATA JSON object

"rate": {
    "origin": {
        "country": "CA",
        "postal_code": "K2P1L4",
        "province": "ON",
        "city": "Ottawa",
        "name": null,
        "address1": "150 Elgin St.",
        "address2": "",
        "address3": null,
        "phone": null,
        "fax": null,
        "email": null,
        "address_type": null,
        "company_name": "Jamie D's Emporium"
    },
    "destination": {
        "country": "CA",
        "postal_code": "K1M1M4",
        "province": "ON",
        "city": "Ottawa",
        "name": "Bob Norman",
        "address1": "24 Sussex Dr.",
        "address2": "",
        "address3": null,
        "phone": null,
        "fax": null,
        "email": null,
        "address_type": null,
        "company_name": null
    },
    "items": [
        {
            "name": "Short Sleeve T-Shirt",
            "sku": "",
            "quantity": 1,
            "grams": 1000,
            "price": 1999,
            "vendor": "Jamie D's Emporium",
            "requires_shipping": true,
            "taxable": true,
            "fulfillment_service": "manual",
            "properties": null,
            "product_id": 48447225880,
            "variant_id": 258644705304
        }
    ],
    "currency": "USD",
    "locale": "en"
}

In the calculateShippingRates(DATA, env) function, you will use the information in the input DATA, such as, the destination country, destination city, destination postcode, the item sku, the item gram, the item quantity, or the item price, to setup rules for your shipping rates. Moreover, you can add additional product information fields in the items object, such as, metafields or tags, using JsRates built-in function enrichItemDetails (see the example below for more information about this function).

The function calculateShippingRates() must return shipping rates array that will be displayed to your customers during checkout.

Sample returned shipping rates array

{
    "rates": [
        {
            "service_name": "canadapost-overnight",
            "service_code": "ON",
            "total_price": "1295",
            "description": "This is the fastest option by far",
            "currency": "CAD",
            "min_delivery_date": "2013-04-12 14:48:45 -0400",
            "max_delivery_date": "2013-04-12 14:48:45 -0400"
        },
        {
            "service_name": "fedex-2dayground",
            "service_code": "2D",
            "total_price": "2934",
            "currency": "USD",
            "min_delivery_date": "2013-04-12 14:48:45 -0400",
            "max_delivery_date": "2013-04-12 14:48:45 -0400"
        },
        {
            "service_name": "fedex-priorityovernight",
            "service_code": "1D",
            "total_price": "3587",
            "currency": "USD",
            "min_delivery_date": "2013-04-12 14:48:45 -0400",
            "max_delivery_date": "2013-04-12 14:48:45 -0400"
        }
    ]
}

For a shipping rate request sent from your checkout page, the returned shipping rates array must contain the required fields: service_name, service_code,total_price, description, and currency. It can also include optional fields: phone_required, min_delivery_date, and max_delivery_date.

Field	Description
`service_name`	The name of the rate, which customers see at checkout (e.g., Expedited Mail).
`description`	A description of the rate, which customers see at checkout (e.g., Includes tracking and insurance).
`service_code`	A unique code associated with the rate (e.g., expedited_mail).
`currency`	The currency of the shipping rate.
`total_price`	The total price expressed in subunits. If the currency doesn't use subunits, then the value must be multiplied by 100 (e.g., "total_price": 500 for 5.00 CAD, "total_price": 100000 for 1000 JPY).
`phone_required`	Whether the customer must provide a phone number at checkout.
`min_delivery_date`	The earliest delivery date for the displayed rate.
`max_delivery_date`	The latest delivery date for the displayed rate to still be valid.

A sample code

The following sample code accepts an input DATA JSON object, calculates the shipping rate based on the total items price, and returns an object RATES containing a shipping rate array. The code sets up a shipping rule that returns a free shipping if the total cart items price is greater than or equal to $100; or else it returns a shipping fee of $10 if total cart items price is less than $100.

//JsRates comes with a built-in module called "modules.js" that exports useful functions

import { print } from "./modules.js"; //a built-in function to print (log) variables for debugging purpose
import { enrichItemDetails } from "./modules.js"; //a built-in function to add additional product information 
//such as, tags and metafields, to the items in the input DATA JSON

export async function calculateShippingRates(DATA,env) { 
    let RATES = {};
    let rates_array = [];
    
    DATA = await enrichItemDetails(DATA);
    const currency = DATA.currency;
    const items = DATA.items;
    
    let shipping_cost = 0;
    let total_items_price = 0;
    let service_name = "";
    let service_code = "";
    
    for(let item of items){
        const item_price = parseFloat(item.itemPrice) * item.quantity;
        total_items_price += item_price;
    }
    
    print("Total item price",total_items_price); //this will be displayed inside the test output and logs
    
    if(total_items_price >= 100){
        shipping_cost = 0;  //set shipping rate to free if total items price is greater than or equal to $100
        service_name = "Free Shipping";
        service_code = "FS";
    }else{
        shipping_cost = 10; //else set shipping rate to $10
        service_name = "Standard Shipping";
        service_code = "SS";
    }
    
    rates_array.push({
        service_name: service_name,
        service_code: service_code,
        total_price: shipping_cost * 100,
        description: "This is the fastest and cheapest option by far",
        currency: currency,
        min_delivery_date: "",
        max_delivery_date: ""
    });
   
  
    RATES={rates:rates_array};
    return RATES;
}

Running the sample code

Use the following steps to run the above sample code:

Copy the above sample code, paste it into a blank calculateShippingRates.js module in your JsRates app Editor page. Save the code by pressing the Save button or using the shortcut Ctrl + S (Cmd + S on macOS) in the editor.
Ensure that the test input DATA JSON is correctly saved. To do this:
- Click the More actions button and select Test data from the drop-down menu.
- In the pop-up window, you'll find fields for test item, test origin, test destination, test currency, and test locale. These fields are automatically populated during installation. Confirm that they are accurate, complete, and correct. You can modify them as needed for testing different configurations or adding more test items. Remember to save any changes before closing the pop-up window.
Run the test code by clicking the Run button in the More actions drop-down menu. The code will be parsed and executed on the JsRates backend. The results will be displayed in a new window at the bottom of the page. You can expand this window using the "expand" icon located at the top right corner. In the video below, the test code was started with Validate button, which is the same as Run button.
Examine the resulting JSON object which includes the following fields:
- duration: This represents the time in seconds taken to process the request. It provides an indication of how quickly your shipping rates will appear to customers during checkout. Note that Shopify ignores shipping rate requests that take longer than 10 seconds.
- rates: This array contains the shipping rates and will be returned to requests sent from your checkout page.
- DATA: This is the request DATA JSON object with the items array enriched with additional fields that are fetched using the enrichItemDetails function.
- print: This object contains the values of variables you want to debug. In this example, the variable total_items_price is included. You can use the print() function to display the value of any variable within your code.

The following video demonstrates how to run the sample code.

How it works

The calculateShippingRates() Function

Sample DATA JSON object

Sample returned shipping rates array

A sample code

Running the sample code

The `calculateShippingRates()` Function