DOCS / HOW-TO

Shipping quotes and policy rules

Price a shipment against your own versioned rate card, decide whether it may ship at all, and keep the exact version every decision used.

Docs for Packvium 1.11.x · contract stable since 1.0

01What the commerce layer does#

Packing decides which boxes a load needs; the commerce layer prices them and checks whether they may ship. It is three functions - quote, evaluatePolicy and catalogVersionInfo - exported by all four packages under one contract: commerce.quote in @packvium/engine, packvium.commerce.quote in Python, Packvium\Commerce\quote in PHP and commerce::quote_json in Rust. Plain data goes in and plain data comes out, nothing reads the clock, and every amount is an exact integer: grams, minor currency units, and permille for rates, with every inexact division rounded up.

02Publish your rates as one document#

Tariffs, policy rules and catalogs each keep a history of versions in one document you store yourself. A version's number is its position in the list, starting at 1, and a change is a new version with its own effective_at, never an edit of an old one - so an old quote can always be replayed against the rates it used.

import { commerce } from '@packvium/engine';

const document = {
  tariffs: [{
    carrier_id: 'parcel-co', service_id: 'standard',
    versions: [
      { effective_at: 0, dimensional_weight_divisor: 5000,
        cost_per_dimensional_kg_minor: { domestic: 420, remote: 610 },
        minimum_charge_minor: 650, fuel_surcharge_permille: 90,
        accessorials: [{ accessorial_id: 'signature', flat_charge_minor: 150 }] },
      // A rate change is a new version, never an edit: version 2 applies from instant 1000.
      { effective_at: 1000, dimensional_weight_divisor: 5000,
        cost_per_dimensional_kg_minor: { domestic: 450, remote: 640 },
        minimum_charge_minor: 700, fuel_surcharge_permille: 110, accessorials: [] },
    ],
  }],
  policy_rules: [{
    rule_id: 'no-lithium-remote',
    versions: [{ scope: 'hazmat', action: 'reject', priority: 10, effective_at: 0,
      reason: 'loose lithium cells do not ship to remote zones',
      predicates: [{ scope: 'hazmat', field: 'zone', operator: 'equals', value: 'remote' }] }],
  }],
  catalogs: [],
};

03Quote a shipment#

Pin tariff_version to replay one exact version, or pass as_of to use whichever version was in force at that instant. The billed weight is the greater of the actual weight and the dimensional weight (volume over dimensional_weight_divisor), so a light, bulky parcel is billed on its size: here 6,000 g for a 3,150 g parcel, 2,897 in all with fuel and a signature. Feed it the outside size and gross weight of each box pack() opened, as a carrier measures them.

const shipment = { carrier_id: 'parcel-co', service_id: 'standard', zone: 'domestic',
  actual_weight_g: 3150, volume_mm3: 30000000, requested_accessorials: ['signature'] };

const pinned = commerce.quote(document, { ...shipment, tariff_version: 1 });  // replay exactly v1
const current = commerce.quote(document, { ...shipment, as_of: 1500 });       // whatever applied then
console.log(pinned.quote.billed_weight_g, pinned.quote.total_minor, current.status, current.error?.code);

04A rejection is an answer, a malformed request is a bug#

A shipment the rates cannot price comes back with status rejected and one of ten codes, each with the fields that explain it: tariff_not_found, no_effective_tariff, unavailable_zone, unavailable_accessorial, policy_rule_not_found, policy_version_not_found, catalog_not_found, catalog_version_not_found, no_effective_catalog_version and ambiguous_catalog_reference. Above, version 2 dropped the signature service, so the same parcel quoted as of instant 1500 is rejected as unavailable_accessorial rather than priced without it. A request that is malformed - a negative weight, an unknown policy scope - throws CommerceInputError instead, because that is the caller's bug, not a business outcome.

05May it ship at all? Policy rules#

evaluatePolicy answers whether a shipment is allowed under the rules in force, and cites the rule version that decided it: rule id, version, action, priority and the reason you wrote. Rules apply to one of seven scopes - facility, customer, carrier, material, hazmat, temperature and service - and compare context fields with equals, not_equals, in, not_in, exists or absent. Store the result with canonicalJson, the bytes every package produces alike, rather than JSON.stringify.

const decision = commerce.evaluatePolicy(document, { scope: 'hazmat', context: { zone: 'remote' }, as_of: 0 });
console.log(decision.decision.allowed, decision.decision.citation.rule_id);
console.log(commerce.canonicalJson(pinned).slice(0, 40));

06Which master data was used? Catalog versions#

catalogVersionInfo reports which version of a catalog of item and carton master data a decision was made against. A rollback is a new, higher version that points back at an older one, so the history of what was in force, and when, is never rewritten.

07Next steps#

The checkout integration puts this together with pack(): it packs the cart into real boxes, quotes each box on its outside size and gross weight, and adds the boxes' own cost. Run examples/commerce.mjs from the installed package for every function in one file.