WesternBid Shipping Calculator Widget

Shipping widgets with two integration modes:

• dist/calculator.es.js + dist/index.css for React apps.
• dist/calculator.iife.js for plain HTML sites via <script> (styles included in JS).

Local development

npm install
npm run dev

Build

npm run build

npm run build creates:

• dist/calculator.es.js
• dist/index.css
• dist/calculator.iife.js

Embed shipping calculator on any website (no React)

Use the standalone bundle and mount widget from window.WbShippingCalculatorWidget.

<div id="wb-shipping-calculator"></div>

<script src="https://cdn.jsdelivr.net/npm/westernbid-shipping-calculator-widget@latest/dist/calculator.iife.js"></script>
<script>
  const widget = window.WbShippingCalculatorWidget.mount({
    target: "#wb-shipping-calculator",
    proxyBaseUrl: "https://your-domain.com/api/wb",
    routes: {
      originCountries: "/origin-countries",
      destinationCountries: "/destination-countries",
      calculateRates: "/calculate-shipping",
      hsCodes: "/hs-codes"
    },
    language: "uk",
    onCalculationChange(result) {
      console.log(result.chargeableWeightKg, result.shippingRates);
    },
    onError(error) {
      console.error("Shipping widget error:", error);
    }
  });

  // Optional:
  // widget.update({ language: "en" });
  // widget.destroy();
</script>

Notes:

• Add scripts after the container element (or run mount on DOMContentLoaded).
• Global API aliases are available:
  • window.WbShippingCalculatorWidget.mount(...)
  • window.WbShippingCalculatorWidget.mountShippingCalculatorWidget(...)
  • window.WbShippingCalculatorWidget.mountFulfillmentCalculatorWidget(...)
  • window.WbShippingCalculatorWidget.mountFulfillmentCenterCalculatorWidget(...)
  • window.WbShippingCalculatorWidget.mountShippingRatesTableWidget(...)

Embed shipping rates table page

Use this widget on the separate shipping prices page, then link to that page from the main shipping page. The proxy endpoint recalculates the table from the WesternBid calculator roughly every 30 days and returns matching ShippingService JSON-LD schema markup.

<div id="wb-shipping-rates-table"></div>

<script src="https://cdn.jsdelivr.net/npm/westernbid-shipping-calculator-widget@latest/dist/calculator.iife.js"></script>
<script>
  window.WbShippingCalculatorWidget.mountShippingRatesTableWidget({
    target: "#wb-shipping-rates-table",
    proxyBaseUrl: "https://your-domain.com/api/wb",
    routes: {
      rateTable: "/shipping-rate-table"
    },
    language: "uk",
    styleMode: "light",
    maxServices: 12,
    injectSchema: true
  });
</script>

The default table covers 0.3, 0.5, 1, 2, 3, 5, and 10 kg for the United States, Canada, Germany, France, and Great Britain. Each cell shows up to twelve available delivery options in WesternBid service order, with price used as a secondary sort. The table renders immediately and fills cells progressively as each calculation finishes. US calculations use a benchmark customs item because the WesternBid US calculator requires item data.

Embed fulfillment calculator on any website (no React)

<div id="wb-fulfillment-calculator"></div>

<script src="https://cdn.jsdelivr.net/npm/westernbid-shipping-calculator-widget@latest/dist/calculator.iife.js"></script>
<script>
  const widget = window.WbShippingCalculatorWidget.mountFulfillmentCalculatorWidget({
    target: "#wb-fulfillment-calculator",
    proxyBaseUrl: "https://your-domain.com/api/wb",
    routes: {
      warehouses: "/warehouses",
      destinationCountries: "/destination-countries",
      destinationStates: "/destination-countries/states",
      packages: "/packages",
      calculateRates: "/calculate-shipping/FulfillmentCenter"
    },
    language: "uk",
    onCalculationChange(result) {
      console.log(result.chargeableWeightKg, result.warnings, result.shippingRates);
    }
  });

  // Optional:
  // widget.update({ language: "en" });
  // widget.destroy();
</script>

React usage

import { ShippingCalculatorWidget } from "westernbid-shipping-calculator-widget";
import "westernbid-shipping-calculator-widget/dist/index.css";

export function ShippingBlock() {
  return (
    <ShippingCalculatorWidget
      proxyBaseUrl="https://your-domain.com/api/wb"
      routes={{
        originCountries: "/origin-countries",
        destinationCountries: "/destination-countries",
        calculateRates: "/calculate-shipping",
        hsCodes: "/hs-codes"
      }}
      language="uk"
      onCalculationChange={(result) => {
        console.log(result.chargeableWeightKg, result.shippingRates);
      }}
    />
  );
}

React fulfillment usage

import { FulfillmentCalculatorWidget } from "westernbid-shipping-calculator-widget";
import "westernbid-shipping-calculator-widget/dist/index.css";

export function FulfillmentBlock() {
  return (
    <FulfillmentCalculatorWidget
      proxyBaseUrl="https://your-domain.com/api/wb"
      routes={{
        warehouses: "/warehouses",
        destinationCountries: "/destination-countries",
        destinationStates: "/destination-countries/states",
        packages: "/packages",
        calculateRates: "/calculate-shipping/FulfillmentCenter"
      }}
      language="uk"
      onCalculationChange={(result) => {
        console.log(result.chargeableWeightKg, result.warnings, result.shippingRates);
      }}
    />
  );
}

React shipping rates table usage

import { ShippingRatesTableWidget } from "westernbid-shipping-calculator-widget";
import "westernbid-shipping-calculator-widget/dist/index.css";

export function ShippingRatesPage() {
  return (
    <ShippingRatesTableWidget
      proxyBaseUrl="https://your-domain.com/api/wb"
      routes={{ rateTable: "/shipping-rate-table" }}
      language="uk"
      styleMode="light"
      maxServices={12}
      injectSchema
    />
  );
}

Widget options

• target: string | HTMLElement only for standalone mount API.
• proxyBaseUrl: string proxy base URL.
• routes?: { originCountries; destinationCountries; calculateRates?; calculateWeight?; hsCodes? } proxy routes.
• routes?: { warehouses; destinationCountries; destinationStates; packages; calculateRates } for the fulfillment widget.
• routes?: { rateTable; rateTableMetadata?; rateTableCell? } for the shipping rates table widget.
• language?: string adds lang query param to requests.
• styleMode?: "shadow" | "light" renders calculator widgets in Shadow DOM by default; the shipping rates table defaults to light DOM so the page contains a crawlable HTML table.
• styleInjections?: Array<{ cssText?: string; href?: string }> injects additional stylesheets directly into the widget shadow root.
• defaultUseImperialSystem?: boolean default input mode.
• requestHeaders?: Record<string, string> extra request headers.
• rateItems?: Record<string, unknown>[] forwarded to Items in rates request body.
• onError?: (error: Error) => void callback for API errors.
• onSubmit?: (payload) => void callback before API call.
• onCalculationChange?: (result) => void callback with calculated result and normalized rates/warnings.
• maxServices?: number limits the shipping rates table to 1-12 delivery options per destination/weight cell.
• injectSchema?: boolean injects the returned shipping JSON-LD into document.head for the rates table page.
• schemaElementId?: string custom element id for the injected JSON-LD script.
• onDataChange?: (result) => void callback with the generated rates table response.

Styling

• Default mode is styleMode: "shadow", so host-page CSS does not bleed into the widget.
• You can theme the widget from outside via CSS custom properties on the mount target, for example --wb-widget-accent, --wb-widget-text, --wb-widget-border, --wb-widget-shadow.
• For deeper customization in shadow mode, pass styleInjections with inline CSS text or external stylesheet URLs.
• If you need legacy light DOM styling, set styleMode: "light" and keep using dist/index.css.

Required proxy routes

• originCountries endpoint returning countries list.
• destinationCountries endpoint returning countries list.
• calculateRates endpoint proxying POST /api/v1/rate/CalculateShipping.
• calculateWeight is still supported as fallback (deprecated).
• hsCodes endpoint returning HS/HTS suggestions for US shipments from the public USITC HTS API.
• rateTable endpoint returning the cached shipping rates table and schema markup.
• rateTableMetadata and rateTableCell endpoints for progressive shipping rates table rendering.
• warehouses endpoint returning Fulfillment Center warehouses.
• destinationStates endpoint returning states by destination country.
• packages endpoint returning package types for selected warehouse.
• calculateRates: "/calculate-shipping/FulfillmentCenter" proxying POST /api/v1/rate/CalculateFulfillmentShipping.