Shipping rate estimate
Prices a domestic package across USPS and UPS for a ZIP-to-ZIP move, weight and optional dimensions, and returns normalized quotes cheapest first —…
Prices a domestic package across USPS and UPS for a ZIP-to-ZIP move, weight and optional dimensions, and returns normalized quotes cheapest first — service name, price and transit days where the carrier states one. Direct JSON, no browser. USPS needs no key and always quotes; UPS is BYOK, and a caller without a UPS developer key gets the USPS quotes plus a warnings line naming what was dropped rather than a silent skip.
Also known as: shipping rate, shipping rates, shipping cost, postage rate, postage cost, usps rate, ups rate, shipping rates usps ups, package shipping cost, how much to ship a package
Call it
bowmark.shipping.estimate(query: ShippingQuery, options?: CallOptions): Promise<ShippingEstimateResult>Functions
| Function | What it does |
|---|---|
estimate | Prices a domestic package — { fromZip: "20024", toZip: "10001", weightOz: 16 } — across every USPS and UPS service that quotes it, and returns rates cheapest first. |
Types
type ShippingQuery = {
fromZip: string // 5-digit US ZIP the package ships FROM
toZip: string
weightOz: number // package weight in ounces
length?: number // inches — all three or none
width?: number
height?: number
}
// One normalized shipping-rate quote. Same shape no matter which carrier
// quoted it.
type ShippingRate = {
source: string // "usps" | "ups"
serviceCode: string // the carrier's own code, verbatim
serviceName: string // the carrier's own name, e.g. "UPS Ground"
price: { amount: number; currency: string } // integer minor units (cents)
transitDays: number | null // null when the carrier didn't state one
}
type ShippingEstimateResult = {
rates: ShippingRate[] // cheapest first
warnings: string[] // always present; names a dropped/timed-out carrier
}
type CallOptions = {
timeoutMs?: number // per-provider budget in ms, default 30000, clamped to 1000-55000.
// A provider slower than this is DROPPED from the results and
// NAMED in warnings — never silently absent
}Examples
// Cheapest way to ship a 3lb box cross-country, whichever carrier wins.
const { rates, warnings } = await bowmark.shipping.estimate({
fromZip: "94103", toZip: "10001", weightOz: 48, length: 12, width: 9, height: 6,
});
for (const w of warnings) log(w);
const best = rates[0];
log(best ? `${best.source} ${best.serviceName}: $${(best.price.amount / 100).toFixed(2)}` : "no carrier quoted this shipment");
return rates.map(r => ({ carrier: r.source, service: r.serviceName, price: r.price.amount / 100, days: r.transitDays }));