Main site

Built-in Modules > CouriersPlease Class

CouriersPlease Class

Important: This plugin relies on third-party resources. The resources might change or be discontinued without notice. Ensure you test the plugin extensively before production use, implement error handling with a try-catch block, have a backup shipping rate ready, and reach out to our support with detailed descriptions of any unexpected issues.


The CouriersPlease class provides functionality to fetch real-time shipping rates from "Couriers Please".

Class Definition

class CouriersPlease {
  constructor(origin, destination, is_origin_residential, is_destination_residential) {
    // Class constructor

  async getRates(parcels) {
    // Method to fetch rates


  • origin (Object): Represents the "origin" field in the input DATA JSON object used in the calculateShippingRates function.
  • destination (Object): Represents the "destination" field in the same DATA JSON object.
  • is_origin_residential (String): Indicates if the origin address is residential ("Y") or not ("N").
  • is_destination_residential (String): Indicates if the destination address is residential ("Y") or not ("N").

Usage Example

import { CouriersPlease } from "./modules.js"
const couriersPlease = new CouriersPlease(DATA.origin, DATA.destination, "N", "N"); // Non-residential addresses
const parcels = [
  { length: 15, width: 30, height: 30, weight: 15, quantity: 1 },
  { length: 10, width: 25, height: 25, weight: 10, quantity: 3 },
  // ... additional parcels
const rates = await couriersPlease.getRates(parcels);

This example demonstrates initializing the CouriersPlease class with origin and destination details, along with residential status for both. The getRates method is utilized to calculate shipping rates for a set of parcels, each defined by their dimensions (in cm), weight (in kg), and quantity. The structure of the returned rates is compatible with the shipping rates format used by Shopify.

The rates are based on the information on the CouriersPlease website, for domestic rates and for international rates .

Sample AI Prompt

I'd like a shipping rate calculator that uses the Couriers Please rates.
The dimensions of the parcels are contained in the items metafield namespace object called "carton". Get the first 15 values in the namespace.
The origin address type is not a residential address. The destination address type is a residential address. 

Sample AI Output

import { enrichItemDetails } from './modules.js';
import { CouriersPlease } from './modules.js';

export async function calculateShippingRates(DATA, env) {
    try {
        // Enrich item details with 'carton' metafield
        DATA = await enrichItemDetails(DATA, [{ namespace: "carton", size: 15 }]);

        // Prepare parcels array for Couriers Please
        const parcels = => {
            const cartonMetafield = item.metafields && item.metafields.carton;
            return {
                length: cartonMetafield ? parseInt(cartonMetafield.length, 10) : 0,
                width: cartonMetafield ? parseInt(cartonMetafield.width, 10) : 0,
                height: cartonMetafield ? parseInt(cartonMetafield.height, 10) : 0,
                weight: item.grams, // Assuming weight is already in grams
                quantity: item.quantity
        }).filter(parcel => parcel.length > 0 && parcel.width > 0 && parcel.height > 0 && parcel.weight > 0);

        // Initialize Couriers Please
        // Assuming origin is not residential and destination is residential
        const couriersPlease = new CouriersPlease(DATA.origin, DATA.destination, "N", "Y");

        // Get rates from Couriers Please
        const rates = await couriersPlease.getRates(parcels);

        return { rates };
    } catch (error) {
        // Return a rate with price equals to null in case of errors
        return { rates: [{ service_name: "", service_code: "", total_price: null, description: "", currency: "", min_delivery_date: "", max_delivery_date: "" }] };