Built-in Modules > USPS Class

USPS 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.

Overview

The USPS class is designed to acquire real-time shipping rates from the United States Postal Service (USPS).

Class Definition

class USPS {
  constructor(origin, destination, order_processing_days) {
    // Class constructor
  }

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

Arguments

origin (Object): Represents the "origin" data from the DATA JSON object used in the calculateShippingRates function.
destination (Object): Represents the "destination" data in the same DATA JSON object.
order_processing_days (Number): The number of days until parcels are ready for pickup.

Usage Example

import { USPS } from "./modules.js"

const usps = new USPS(DATA.origin, DATA.destination, 3);
const parcels = [
  { length: 15, width: 10, height: 5, metricUnit: "CM", weight: 10, weightUnit: "KG", declaredValue: 120, quantity: 2 },
  // ... more parcels
];
const rates = await usps.getRates(parcels);

In this usage example, the USPS class is initiated with origin, destination, and order processing days. The getRates method calculates shipping rates for a collection of parcels, each defined by dimensions, weight, declared value, and quantity.

Notes

For metric system, the values for metricUnit and weightUnit should be 'CM' and 'KG', respectively.
For imperial system, the values should be 'IN' and 'LB', respectively.
The output rates currency is "USD".
For domestic deliveries, the origin and destination postal codes (zip codes) are required.

The format of the returned rates aligns with the standard format of Shopify's shipping rates.

The rates are based on the information on USPS website.

Sample AI Prompt

I'd like a shipping rate calculator that uses the USPS rates.
The parcels will be ready for pick up in 3 days.
The dimension, the declared value and weight of the parcels are contained in the items metafield namespace object called "parcel". Get the first 15 values in the namespace.
It uses the metric unit system.

Sample AI Output

import { enrichItemDetails, USPS } from './modules.js';

export async function calculateShippingRates(DATA, env) {
    try {
        // Enriching DATA with additional parcel information
        DATA = await enrichItemDetails(DATA, [{ namespace: "parcel", size: 15 }]);

        // Extracting parcels information from enriched DATA
        const parcels = DATA.items.map(item => ({
            length: item.metafields.parcel.length,
            width: item.metafields.parcel.width,
            height: item.metafields.parcel.height,
            metricUnit: "CM",  // Using metric units
            weight: item.metafields.parcel.weight,
            weightUnit: "KG",  // Weight in kilograms
            declaredValue: item.metafields.parcel.declaredValue,
            quantity: item.quantity
        }));

        // Setting up USPS module with necessary arguments
        const usps = new USPS(DATA.origin, DATA.destination, 3);

        // Fetching rates from USPS
        const rates = await usps.getRates(parcels);

        // Returning rates in the expected Shopify format
        return { rates };
    } catch (error) {
        // In case of any error, return a rate with price equals to null and other fields set to empty string
        return {
            rates: [{
                service_name: "",
                service_code: "",
                total_price: null,
                description: "",
                currency: "",
                min_delivery_date: "",
                max_delivery_date: ""
            }]
        };
    }
}