Shipping Configuration

The shipping system in Jose Madrid Salsa uses a multi-tier strategy: real carrier API rates with fallback to estimate-based rates, ensuring checkout is never blocked.

How Shipping Calculation Works

The calculateShipping function in lib/shipping-calculator.ts follows this strategy:

const origin = await getShippingOrigin()

if (!origin.ok) {
  console.error(describeMissingOrigin(origin.missing))
  return calculateEstimateRates(input, true)
}

const parcel = calculateParcelDimensions(items)
const shipmentRequest: ShipmentRequest = {
  fromAddress: DEFAULT_ORIGIN_ADDRESS,
  toAddress: { ... },
  parcel,
}
const ratesResponse = await getShippingRates(shipmentRequest)

if (isPoBox) {
  filteredRates = ratesResponse.rates.filter((rate) =>
    rate.carrier.toUpperCase().includes('USPS')
  )
}
const sortedRates = [...filteredRates].sort((a, b) => a.rate - b.rate)

catch (error) {
  console.error('[Shipping Calculator] Error:', error)
  return calculateEstimateRates(input, true)
}

Shipping Rate Configuration

Rates come from the ShippingSettings singleton where a store has set them, and fall back field-by-field to the built-in defaults in lib/shipping/rate-config.ts:

export const DEFAULT_RATE_CONFIG: ShippingRateConfig = {
  flatRateCents: 699,
  weightSurchargeBaseCents: 499,
  weightSurchargePerLbCents: 50,
  weightSurchargeThresholdLb: 5,
  internationalRateCents: 2499,
  stateSurcharges: { AK: 1.5, HI: 1.5, PR: 2.0 },
}

These are carriage only. A flat $4.00 packaging-and-materials fee (lib/shipping/handling-fee.ts) is added once per order to every customer-facing quote — live carrier rates included — so what the customer actually sees is:

The fee is not scaled by the state surcharge or the weight surcharge, which price carriage rather than packaging. The admin label routes call getShippingRates directly and do not include it — buying postage is a cost, not a quote.

Origin Address Configuration

Set the shipping origin via environment variables:

SHIPPING_ORIGIN_ADDRESS="123 Main St"
SHIPPING_ORIGIN_CITY="San Francisco"
SHIPPING_ORIGIN_STATE="CA"
SHIPPING_ORIGIN_ZIP="94111"
SHIPPING_API_KEY="..."  # Carrier API key

PO Box Detection

The system automatically detects PO Box addresses and restricts shipping options to USPS-only:

function isPOBox(address: string | undefined): boolean {
  const patterns = [
    /\bP\s*O\s+BOX\b/,
    /\bPOST\s+OFFICE\s+BOX\b/,
    /^\s*BOX\s+\d+/,
  ]
  return patterns.some(p => p.test(address.toUpperCase()))
}

Address Validation

Use the built-in validation before submitting shipping requests:

import { validateShippingAddress } from '@/lib/shipping-calculator'

const result = validateShippingAddress({
  address1: '123 Main St',
  city: 'San Francisco',
  state: 'CA',
  postalCode: '94111',
  country: 'US',
})

if (!result.valid) {
  console.error(result.errors)
  // ["State must be a 2-letter code (e.g., CA, NY)"]
}

Frontend Shipping Estimates

For real-time shipping previews, use the lightweight estimate function:

import { getShippingEstimate } from '@/lib/shipping-calculator'

const estimate = await getShippingEstimate({
  subtotal: 35.00,
  state: 'CA',
  country: 'US',
})
// Returns: 10.99 — the $6.99 carriage plus the $4.00 packaging fee.
// Shipping is charged on every order, and the preview matches what checkout will charge.

Parcel Dimensions

The system calculates parcel dimensions from order items:

• Weight: Sum of all item weights (defaults to 1 lb per item), converted to ounces
• Length/Width: Maximum dimensions across items
• Height: Sum of heights, capped at 24 inches

Key Files