shipping-rate-calculator

What this skill does

# Shipping Rate Calculator

## Overview

Showing real-time shipping rates at checkout — from UPS, FedEx, USPS, DHL — lets customers choose their preferred service and prevents you from under- or overcharging for shipping. Every major platform supports carrier-calculated rates natively or through apps, and a multi-carrier rate shopping tool can save you 15–40% on shipping costs by automatically selecting the cheapest option.

## When to Use This Skill

- When adding real-time carrier rate quotes to checkout
- When building a multi-carrier shipping rate comparison feature
- When implementing free shipping thresholds or tiered flat-rate shipping
- When you need to calculate dimensional weight for accurate carrier pricing
- When setting up shipping zones and rate tables for international shipping

## Core Instructions

### Step 1: Determine your platform and choose the right shipping rate tool

| Platform | Recommended Tool | Why |
|----------|-----------------|-----|
| **Shopify** | Shopify Shipping (built-in) or Easyship / ShipStation for rate shopping | Shopify Shipping gives discounted USPS, UPS, DHL rates; Easyship adds 250+ carrier options and rate shopping |
| **WooCommerce** | WooCommerce Shipping (USPS/DHL) + Table Rate Shipping for custom rules | WooCommerce Shipping handles basic carrier rates; Table Rate Shipping adds weight/zone-based rule tables |
| **BigCommerce** | ShipperHQ or Easyship | ShipperHQ is the most powerful rate management tool for BigCommerce with dimensional rate calculation |
| **Custom / Headless** | EasyPost or Shippo as a carrier meta-API | Both aggregate UPS, FedEx, USPS, DHL into a single API call — far simpler than integrating each carrier directly |

### Step 2: Set up carrier-calculated rates

#### Shopify

**Shopify Shipping (built-in, free, recommended starting point):**

1. Go to **Settings → Shipping and delivery → Manage rates**
2. Under your domestic zone, click **Add rate**
3. Select **Use carrier or app to calculate rates**
4. Choose from: USPS, UPS, DHL Express
5. Check the services you want to offer (e.g., USPS Priority Mail, USPS Ground Advantage, UPS Ground, UPS 2nd Day Air)
6. Optionally add a markup or discount percentage on top of carrier rates (useful to offset packing material costs)
7. Save — rates will now appear dynamically at checkout based on the order's actual weight and destination

**For more carrier options (FedEx, regional carriers, international):**
1. Install **Easyship** or **ShipStation** from the Shopify App Store
2. Both integrate as Shopify "carrier-calculated shipping" providers and appear natively at checkout
3. Easyship's free tier shows live rates from 50+ carriers at checkout
4. **Note:** Carrier-calculated rates at checkout require Shopify's **Advanced plan** ($299/mo) or higher, OR purchasing the carrier-calculated shipping add-on ($20/month on lower plans)

**For flat-rate and free-shipping rules:**
- In Shopify Shipping, you can create flat-rate options ($5.99 standard shipping, $14.99 express) in addition to or instead of carrier-calculated rates
- Combine with a free shipping threshold: add a free shipping rate with a minimum order condition (see @free-shipping-thresholds skill)

#### WooCommerce

**WooCommerce Shipping (USPS + DHL, free):**
1. Install the **WooCommerce Shipping** plugin (free, by WooCommerce)
2. Go to **WooCommerce → Settings → Shipping → Add shipping zone** for each region
3. Under each zone, click **Add shipping method** → select USPS or DHL Express
4. Configure which services to display at checkout (Priority Mail, Ground Advantage, etc.)
5. Add your package dimensions and weights to products for accurate rate calculation

**WooCommerce Table Rate Shipping (for complex rules, e.g., weight tiers, custom zones):**
1. Purchase the **WooCommerce Table Rate Shipping** extension from WooCommerce.com
2. Create rate tables: e.g., 0–1lb = $4.99, 1–5lb = $7.99, 5–20lb = $12.99
3. Create separate tables for domestic vs. international zones

**ShipStation for WooCommerce (multi-carrier rate shopping):**
1. Install the **ShipStation for WooCommerce** plugin
2. ShipStation can be configured to use your negotiated carrier rates and display them at checkout via WooCommerce's shipping method API
3. Note: ShipStation shows rates in your ShipStation dashboard, not always directly at customer checkout — check ShipStation documentation for the specific WooCommerce checkout rate display feature

#### BigCommerce

**ShipperHQ (most powerful option for BigCommerce):**
1. Install **ShipperHQ** from the BigCommerce App Marketplace
2. Connect your UPS, FedEx, USPS, DHL accounts to ShipperHQ (or use ShipperHQ's built-in carrier accounts)
3. ShipperHQ handles dimensional weight calculations automatically based on your product dimensions
4. Configure rate shopping rules: "Show cheapest option", "Show all options", or "Show cheapest per delivery speed tier"
5. Set markup rules: +$2 per shipment for handling, or -15% discount on all FedEx rates

**BigCommerce built-in real-time rates:**
1. Go to **Store Setup → Shipping → Add a shipping zone**
2. Under the zone, add a real-time carrier method (UPS, FedEx, USPS via Endicia)
3. Enter your carrier account credentials
4. BigCommerce will display live carrier rates at checkout

#### Custom / Headless

Use EasyPost or Shippo as a meta-API to get rates from all carriers in one call — far simpler than integrating UPS, FedEx, USPS, and DHL separately:

```typescript
import EasyPost from '@easypost/api';
const easypost = new EasyPost(process.env.EASYPOST_API_KEY);

// Get multi-carrier rates for a shipment
async function getShippingRates(params: {
  originZip: string;
  destinationZip: string;
  destinationCountry: string;
  weightOz: number;
  lengthIn: number;
  widthIn: number;
  heightIn: number;
}): Promise<{ carrier: string; service: string; rateCents: number; estimatedDays: number }[]> {
  const shipment = await easypost.Shipment.create({
    from_address: {
      zip: params.originZip,
      country: 'US',
    },
    to_address: {
      zip: params.destinationZip,
      country: params.destinationCountry,
    },
    parcel: {
      length: params.lengthIn,
      width: params.widthIn,
      height: params.heightIn,
      weight: params.weightOz, // EasyPost uses oz
    },
  });

  return shipment.rates.map(rate => ({
    carrier: rate.carrier,
    service: `${rate.carrier} ${rate.service}`,
    rateCents: Math.round(parseFloat(rate.rate) * 100),
    estimatedDays: rate.est_delivery_days ?? 5,
  })).sort((a, b) => a.rateCents - b.rateCents);
}

// Apply store-level rules on top of carrier rates
function applyShippingRules(params: {
  carrierRates: { carrier: string; service: string; rateCents: number; estimatedDays: number }[];
  cartSubtotalCents: number;
  freeShippingThresholdCents: number;
}): { label: string; rateCents: number; estimatedDays: number }[] {
  const rates = [...params.carrierRates];

  // Add free shipping option if eligible
  if (params.cartSubtotalCents >= params.freeShippingThresholdCents) {
    rates.unshift({ carrier: 'store', service: 'Free Shipping', rateCents: 0, estimatedDays: 7 });
  }

  // Show max 3 options to avoid choice paralysis:
  // 1. Free (if available)
  // 2. Cheapest paid option
  // 3. Fastest guaranteed option
  const freeOption = rates.find(r => r.rateCents === 0);
  const cheapestPaid = rates.filter(r => r.rateCents > 0).sort((a, b) => a.rateCents - b.rateCents)[0];
  const fastest = rates.filter(r => r.estimatedDays <= 2).sort((a, b) => a.estimatedDays - b.estimatedDays)[0];

  return [freeOption, cheapestPaid, fastest]
    .filter(Boolean)
    .filter((r, i, arr) => arr.findIndex(x => x?.service === r?.service) === i) // deduplicate
    .map(r => ({ label: r!.service, rateCents: r!.rateCents, estimatedDays: r!.estimatedDays }));
}
```

### Step 3: Configure dimensional weight calculation

Carriers charge based on the greater of actual weight vs. dimensional weight. Always configure thi