Quartz 4

TOTM Shipping Backend

2 min read

Temple of the Moon Books - Shipping Backend

Overview

Dynamic shipping rate calculator with local delivery, USPS rate approximations, handling fees, and shipping markup for larger orders.

Location: src/lib/shipping.ts

Pricing Structure

ComponentRuleAmount
Handling FeeItems over 1 lb$2.00 per order
Shipping MarkupOrders over $5020% markup on shipping
Local DeliveryKC Metro ZIP codesFree

Shipping Methods

USPS First Class (up to 13 oz)

  • 3-5 business days
  • Rates: 4.50 based on weight

USPS Priority Mail (any weight)

  • 2-3 business days
  • Rates: 45.00+ based on weight

USPS Ground Advantage (up to 70 lbs)

  • 5-7 business days
  • Rates: 28.00+ based on weight

Local Delivery (KC Metro)

  • 1-3 business days
  • Free for all KC Metro ZIP codes

KC Metro Free Delivery Zone

Includes all ZIP codes for:

  • Kansas City, MO (64xxx)
  • Independence, Blue Springs, Lee’s Summit
  • Raytown, Grandview
  • Liberty, Gladstone, North KC
  • Kansas City, KS (66xxx)
  • Overland Park, Olathe, Shawnee, Lenexa

~150+ ZIP codes covered.

Rate Calculation Logic

calculateShipping(
  totalWeightLbs: number,
  destinationZip: string,
  orderSubtotal?: number,
  hasHeavyItem?: boolean
): ShippingEstimate
  1. Check if local delivery eligible → free shipping
  2. Check for heavy items (>1 lb) → add $2 handling
  3. Check order subtotal (>$50) → apply 20% markup
  4. Calculate base USPS rates by weight
  5. Apply markup + handling to final price
  6. Sort by price, return all options

Checkout Integration

  • Shipping calculated in real-time as ZIP is entered
  • Auto-selects local delivery if eligible, otherwise cheapest option
  • Tax calculated at 8.6% (Missouri)

Files involved:

  • src/lib/shipping.ts - Rate calculation
  • src/app/checkout/page.tsx - Checkout UI

Recent Changes (2026-01-31)

  • Added $2 handling fee for items over 1 lb
  • Added 20% shipping markup for orders over $50
  • Handling fee noted in shipping method descriptions
  • Fixed price scraper to grab retail price (strikethrough) not sale price
  • Created scripts/fix-pricing.ts for bulk price corrections

Testing

# Test shipping calculation
cd /home/shdwdev/projects/templeofthemoonbooks.com
npx ts-node -e "
import { calculateShipping, hasHeavyItem } from './src/lib/shipping';
console.log(calculateShipping(0.5, '64112', 75, false)); // KC, over $50
console.log(calculateShipping(2.0, '90210', 30, true));  // LA, heavy item
"

Graph View