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.