INTEGRATION / CHECKOUT-SHIPPING-QUOTE

Shipping rates at checkout from real boxes

Quote a shipping rate from the cartons a cart actually packs into, priced on their outside size and gross weight against your own rate card.

WHERE IT SITS

Between the cart and the rate a shopper sees: an e-commerce checkout, a quoting endpoint or an order-management system that needs a shipping price before the order exists.

HOW THE DATA FLOWS
  1. 01

    The checkout sends the cart lines and the box sizes your packing station stocks.

  2. 02

    pack() opens the cheapest set of boxes that legally hold the cart, or names the line that cannot ship.

  3. 03

    commerce.quote() prices each opened box from its outside dimensions and gross weight, so dimensional weight is billed the way a carrier bills it.

  4. 04

    The rate is the carrier charges plus the boxes themselves; the same request always gives the same rate.

THE WHOLE PROGRAM, IN Node / JavaScript
import { commerce, pack } from '@packvium/engine';

// Your published rate card: one carrier service, priced per billed kilogram.
const rates = {
  tariffs: [{
    carrier_id: 'parcel-co', service_id: 'standard',
    versions: [{
      effective_at: 0,
      dimensional_weight_divisor: 5000,          // mm³ per gram of DIM weight
      cost_per_dimensional_kg_minor: { domestic: 420 },
      minimum_charge_minor: 650,
      fuel_surcharge_permille: 90,
      accessorials: [],
    }],
  }],
  policy_rules: [],
  catalogs: [],
};

// The cart, and the boxes your packing station stocks.
const cart = [
  { id: 'kettle', quantity: 1, weight: '1.4 kg', dimensions: { length: '240', width: '180', height: '230' } },
  { id: 'mug', quantity: 4, weight: '350 g', dimensions: { length: '120', width: '90', height: '100' } },
];
const boxes = [
  { id: 'box-s', cost_minor: 60, tare_weight: '150 g', inner_dimensions: { length: '300', width: '200', height: '150' } },
  { id: 'box-m', cost_minor: 85, tare_weight: '250 g', inner_dimensions: { length: '400', width: '300', height: '250' } },
  { id: 'box-l', cost_minor: 120, tare_weight: '400 g', inner_dimensions: { length: '600', width: '400', height: '400' } },
];

// 1. Pack the cart for real: which boxes, how many.
const packed = pack({ items: cart, containers: boxes, configuration: { objective: 'lowest_cost' } });
if (packed.unpacked_items.length > 0) {
  // Never quote a cart you cannot ship: show the reason instead of a price.
  throw new Error(`cannot ship ${packed.unpacked_items[0].item_id}: ${packed.unpacked_items[0].reason}`);
}

// 2. Price every opened box on its outside size and gross weight, as a carrier bills it.
const boxCost = Object.fromEntries(boxes.map((box) => [box.id, box.cost_minor]));
let total = 0;
for (const box of packed.containers) {
  const { length, width, height } = box.outer_dimensions;
  const answer = commerce.quote(rates, {
    carrier_id: 'parcel-co', service_id: 'standard', tariff_version: 1, zone: 'domestic',
    actual_weight_g: Math.ceil(Number(box.gross_weight.value)),
    volume_mm3: Number(length.value) * Number(width.value) * Number(height.value),
  });
  if (answer.status !== 'ok') throw new Error(answer.error.code); // e.g. unavailable_zone
  total += answer.quote.total_minor + boxCost[box.container_type];
  console.log(box.container_type, answer.quote.billed_weight_g, 'g billed,', answer.quote.total_minor, 'to ship');
}
console.log('checkout rate:', total);
WHAT IT DOES

The cart opens one 400 x 300 x 250 mm box: the kettle does not fit the small box in any orientation. That box bills 6,000 g of dimensional weight rather than its 3 kg actual weight, so it costs 2,747 to ship and 2,832 with the box itself - the dimensional-weight charge a flat per-order rate would have missed.

Every program on these pages is run exactly as printed by this site's test suite, against the published package, on every change.

WHAT TO KEEP

Keep the tariff version the quote used with the order (tariff_version is in every quote). A dispute months later replays against exactly that version instead of today's rates; commerce.canonicalJson gives the bytes to store and compare.

WHEN THE ENGINE SAYS NO

Two kinds of failure, kept apart. A cart line that fits no box comes back in unpacked_items with a reason: show it and offer no rate, rather than a price for a parcel that cannot be packed. A zone or service your rate card does not price is a result with status rejected and a code such as unavailable_zone, not an exception; a malformed quote request does throw, and that is a bug on your side.

INSTALL
npm install @packvium/engine