@tokenoftrust/storefront-runner 3.7.2 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.7.2",
+  "version": "3.9.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/declared-config.mjs

@@ -197,20 +197,38 @@ export function seoDeclarationProblems(seo) {
 }
 
 /** Every `shipping` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
-export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+export const SHIPPING_KEYS = Object.freeze(["tiers"]);
+
+/** Every key of one `shipping.tiers` entry. */
+export const SHIPPING_TIER_KEYS = Object.freeze(["atOrAbove", "rate", "label"]);
 
 /** Largest shipping amount a declaration may state, in the cart's currency. */
 export const MAX_SHIPPING_AMOUNT = 100000;
 
+/** Most tiers one policy may declare. */
+export const MAX_SHIPPING_TIERS = 10;
+
+/** Longest shipping-line label, in characters. */
+export const MAX_SHIPPING_LABEL_LENGTH = 100;
+
 /** @param {unknown} value */
 const isShippingAmount = (value) =>
   typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
   && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
 
+/** @param {unknown} value */
+const isShippingLabel = (value) =>
+  typeof value === "string" && value.trim() === value && value.length > 0
+  && [...value].length <= MAX_SHIPPING_LABEL_LENGTH && !/[\u0000-\u001f\u007f]/.test(value);
+
 /**
  * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
  * valid. A policy with any problem is refused whole, so checkout never charges half of one.
  *
+ * Tiers are ordered by the item subtotal they start at. The first starts at 0 and states no
+ * `atOrAbove`; each later tier's `atOrAbove` is above the one before it and is inclusive, so an
+ * order whose subtotal equals it pays that tier's `rate`.
+ *
  * @param {unknown} shipping
  * @returns {string[]}
  */
@@ -221,12 +239,38 @@ export function shippingDeclarationProblems(shipping) {
   for (const key of Object.keys(source)) {
     if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
   }
-  if (!isShippingAmount(source.flatRate)) {
-    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
-  }
-  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
-    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  const tiers = source.tiers;
+  if (!Array.isArray(tiers) || tiers.length === 0 || tiers.length > MAX_SHIPPING_TIERS) {
+    problems.push(`\`shipping.tiers\` must be a list of 1 to ${MAX_SHIPPING_TIERS} tiers`);
+    return problems;
   }
+  let previous = 0;
+  tiers.forEach((tier, index) => {
+    const at = `shipping.tiers[${index}]`;
+    if (!isPlainObject(tier)) {
+      problems.push(`\`${at}\` must be an object`);
+      return;
+    }
+    const entry = /** @type {Record<string, unknown>} */ (tier);
+    for (const key of Object.keys(entry)) {
+      if (!SHIPPING_TIER_KEYS.includes(key)) problems.push(`\`${at}.${key}\` is not a tier key (${SHIPPING_TIER_KEYS.join(", ")})`);
+    }
+    if (!isShippingAmount(entry.rate)) {
+      problems.push(`\`${at}.rate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+    }
+    if (entry.label !== undefined && !isShippingLabel(entry.label)) {
+      problems.push(`\`${at}.label\` must be text of 1 to ${MAX_SHIPPING_LABEL_LENGTH} characters with no surrounding spaces or line breaks`);
+    }
+    if (index === 0) {
+      if (entry.atOrAbove !== undefined) problems.push(`\`${at}\` starts at 0, so it states no \`atOrAbove\``);
+      return;
+    }
+    if (!(isShippingAmount(entry.atOrAbove) && /** @type {number} */ (entry.atOrAbove) > previous)) {
+      problems.push(`\`${at}.atOrAbove\` must be an amount above ${previous}, where the tier before it starts, and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+      return;
+    }
+    previous = /** @type {number} */ (entry.atOrAbove);
+  });
   return problems;
 }
 
@@ -702,7 +746,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     const problems = shippingDeclarationProblems(config.shipping);
     if (problems.length > 0) {
       out.push(mk(ERROR, "config-shipping", `${file} shipping`, shippingProblemMessage(problems),
-        'declare e.g. `"shipping": { "flatRate": 5.99, "freeAtOrAbove": 100 }`, or remove `shipping` to charge none'));
+        'declare e.g. `"shipping": { "tiers": [ { "rate": 5.99 }, { "atOrAbove": 100, "rate": 0, "label": "Free shipping" } ] }`, or remove `shipping` to charge none'));
     }
   }
   return out;

package/packages/public-runtime/src/checkout.ts

@@ -224,12 +224,19 @@ export class ShippingPolicyUnavailableError extends Error {
   }
 }
 
-/** A shipping policy in the minor units of one currency. */
+/** One shipping tier in the minor units of one currency. */
+export interface ShippingTierMinor {
+  /** Item subtotal the tier starts at, inclusive; 0 for the first tier. */
+  fromMinor: number;
+  rateMinor: number;
+  label: string | null;
+}
+
+/** A shipping policy in the minor units of one currency, tiers ascending by `fromMinor`. */
 export interface ShippingPolicyMinor {
   currency: string;
   digits: number;
-  flatMinor: number;
-  freeAtOrAboveMinor: number | null;
+  tiers: ShippingTierMinor[];
 }
 
 function minorUnits(amount: number, digits: number): number {
@@ -255,27 +262,51 @@ export function shippingPolicyMinor(policy: ShippingPolicy, currency: string): S
     throw new ShippingPolicyUnavailableError();
   }
   if (digits === undefined) throw new ShippingPolicyUnavailableError();
-  const freeAtOrAboveMinor = policy.freeAtOrAbove === undefined ? null : minorUnits(policy.freeAtOrAbove, digits);
-  if (freeAtOrAboveMinor === 0) throw new ShippingPolicyUnavailableError();
-  return { currency, digits, flatMinor: minorUnits(policy.flatRate, digits), freeAtOrAboveMinor };
+  const declared = Array.isArray(policy?.tiers) ? policy.tiers : [];
+  if (declared.length === 0) throw new ShippingPolicyUnavailableError();
+  const tiers = declared.map((tier, index): ShippingTierMinor => {
+    if ((index === 0) !== (tier.atOrAbove === undefined)) throw new ShippingPolicyUnavailableError();
+    return {
+      fromMinor: index === 0 ? 0 : minorUnits(tier.atOrAbove!, digits),
+      rateMinor: minorUnits(tier.rate, digits),
+      label: tier.label ?? null,
+    };
+  });
+  // Tiers that collapse onto one minor-unit start (or run backwards) cannot say which applies.
+  if (tiers.some((tier, index) => index > 0 && tier.fromMinor <= tiers[index - 1]!.fromMinor)) {
+    throw new ShippingPolicyUnavailableError();
+  }
+  return { currency, digits, tiers };
 }
 
-/** Shipping owed on an order whose item subtotal is `subtotalMinor`: the flat rate, or 0 at or above the free threshold. */
+/**
+ * The tier an order whose item subtotal is `subtotalMinor` pays: the last one whose start it
+ * reaches. A subtotal exactly at a tier's `atOrAbove` pays that tier.
+ */
+export function shippingTierFor(policy: ShippingPolicy, currency: string, subtotalMinor: number): ShippingTierMinor {
+  const { tiers } = shippingPolicyMinor(policy, currency);
+  return tiers.reduce((paid, tier) => (subtotalMinor >= tier.fromMinor ? tier : paid), tiers[0]!);
+}
+
+/** Shipping owed, in minor units, on an order whose item subtotal is `subtotalMinor`. */
 export function shippingMinorFor(policy: ShippingPolicy, currency: string, subtotalMinor: number): number {
-  const minor = shippingPolicyMinor(policy, currency);
-  return minor.freeAtOrAboveMinor !== null && subtotalMinor >= minor.freeAtOrAboveMinor ? 0 : minor.flatMinor;
+  return shippingTierFor(policy, currency, subtotalMinor).rateMinor;
 }
 
 /**
- * The `shipping_policy` option value, e.g. `currency=USD;flat=5.99;free_at=100.00` (`free_at`
- * only when declared). Amounts carry exactly the currency's minor-unit digits; the checkout
- * store's shipping code parses this shape and refuses any other.
+ * The `shipping_policy` option value: `currency=<code>` then one `tier=<from>,<rate>[,<label>]`
+ * per tier, ascending, e.g.
+ * `currency=USD;tier=0.00,14.99,Flat%20rate%20shipping;tier=100.00,7.00,FREE%20shipping`.
+ * Amounts carry exactly the currency's minor-unit digits; a label is `encodeURIComponent`-encoded
+ * so it cannot contain `,` or `;`. The checkout store's shipping code parses this shape and
+ * refuses any other.
  */
 export function shippingPolicyOptionValue(policy: ShippingPolicy, currency: string): string {
   const minor = shippingPolicyMinor(policy, currency);
   const amount = (value: number) => (value / 10 ** minor.digits).toFixed(minor.digits);
-  return [`currency=${currency}`, `flat=${amount(minor.flatMinor)}`,
-    ...(minor.freeAtOrAboveMinor === null ? [] : [`free_at=${amount(minor.freeAtOrAboveMinor)}`])].join(";");
+  return [`currency=${currency}`, ...minor.tiers.map((tier) =>
+    `tier=${[amount(tier.fromMinor), amount(tier.rateMinor), ...(tier.label === null ? [] : [encodeURIComponent(tier.label)])].join(",")}`)]
+    .join(";");
 }
 
 /** A verification correlation handle as a cart may carry it (the commerce adapter's shape). */
@@ -298,16 +329,46 @@ export const VISIBLE_CART_FIELDS = ["Purchase option"] as const;
 
 export type CartFieldVisibility = "native" | "internal" | "visible" | "variant-option" | "undeclared";
 
+/**
+ * Characters the checkout store does not keep in a field name, each mapped to a look-alike it
+ * keeps. The store validates the name as it rewrites it, not as it was signed: ASCII space, `.`
+ * and `[` become `_` (a `[…]` pair turns the field into an array), `||` ends the name, and a name
+ * holding `&` or `"` is dropped from validation. Measured 2026-10-23 against tot-preview.foxycart.com
+ * by submitting each name with a non-matching hash and reading the name back from its
+ * "Cart Validation Error: <name>" refusal. Every other character (NBSP, `/`, `'`, `+`, `-`,
+ * non-ASCII) came back unchanged.
+ */
+const CHECKOUT_NAME_LOOKALIKES: Readonly<Record<string, string>> = {
+  " ": " ",
+  ".": "․",
+  "[": "(",
+  "]": ")",
+  "&": "＆",
+  '"': "”",
+  "|": "¦",
+};
+const CHECKOUT_NAME_REWRITTEN = /[ .[\]&"|]/g;
+
+/**
+ * The name a cart field is emitted AND signed under. The checkout store validates this exact
+ * string, and the shopper's cart line shows it, so "Nic Strength" stays readable as
+ * "Nic Strength" (with a no-break space) instead of failing as `Nic_Strength`.
+ */
+export function checkoutFieldName(name: string): string {
+  return name.trim().replace(CHECKOUT_NAME_REWRITTEN, (ch) => CHECKOUT_NAME_LOOKALIKES[ch] ?? ch);
+}
+
 /**
  * How a field emitted by `cartFieldsForVariant` reaches the shopper. A field
  * that is none of native, internal, declared-visible, or one of the variant's
  * own options is `undeclared`: it would render on the cart line unreviewed.
+ * `name` is the emitted name (`checkoutFieldName`).
  */
 export function cartFieldVisibility(name: string, variant: Pick<CatalogVariant, "option_values">): CartFieldVisibility {
   if ((NATIVE_CART_FIELDS as readonly string[]).includes(name)) return "native";
   if ((INTERNAL_CART_FIELDS as readonly string[]).includes(name)) return "internal";
-  if ((VISIBLE_CART_FIELDS as readonly string[]).includes(name)) return "visible";
-  if (Object.prototype.hasOwnProperty.call(variant.option_values, name)) return "variant-option";
+  if (VISIBLE_CART_FIELDS.some((visible) => checkoutFieldName(visible) === name)) return "visible";
+  if (Object.keys(variant.option_values).some((option) => checkoutFieldName(option) === name)) return "variant-option";
   return "undeclared";
 }
 
@@ -445,7 +506,9 @@ export function cartFieldsForVariant(
   // Variant options (Flavor, Nicotine strength, …) travel as product options so
   // the cart line reflects the exact variant the shopper picked.
   for (const [optName, optVal] of Object.entries(variant.option_values)) {
-    if (optName && optVal) fields.push({ name: optName, value: optVal });
+    const name = checkoutFieldName(optName);
+    const value = optVal.trim();
+    if (name && value) fields.push({ name, value });
   }
   // Bind the SELECTED purchase option into the signed payload so a shopper can't
   // switch one-time↔subscription (or between plans) after the form is signed —
@@ -455,7 +518,7 @@ export function cartFieldsForVariant(
   // on every non-subscription cart. Any authored option (a real one-time plan or
   // a subscription) is emitted and signed → modifying it fails validation.
   if (purchaseOption && !isDefaultOneTimeOption(purchaseOption)) {
-    fields.push({ name: "Purchase option", value: purchaseOption.label });
+    fields.push({ name: checkoutFieldName("Purchase option"), value: purchaseOption.label });
   }
   if (purchaseOption?.kind === "subscription") {
     fields.push(...subscriptionCartFields(purchaseOption));
@@ -586,8 +649,14 @@ function constantTimeHexEqual(expected: string, presented: string): boolean {
   return acc === 0;
 }
 
+/** A field as the checkout receives it unsigned: under its `checkoutFieldName`. */
+function unsignedField(field: CartField): RenderedCartField {
+  return { name: checkoutFieldName(field.name), value: field.value };
+}
+
 /**
- * Sign one field for product `code`. Editable fields hash the sentinel
+ * Sign one field for product `code`. The hashed name and the emitted name are the
+ * same `checkoutFieldName`, so they cannot diverge. Editable fields hash the sentinel
  * `--OPEN--` and gain the `||open` suffix so checkout accepts a user-entered value.
  */
 async function signField(
@@ -595,11 +664,12 @@ async function signField(
   code: string,
   field: CartField,
 ): Promise<RenderedCartField> {
+  const fieldName = checkoutFieldName(field.name);
   const valueToHash = field.open ? "--OPEN--" : field.value;
-  const hash = await hmacHex(secret, code + field.name + valueToHash);
+  const hash = await hmacHex(secret, code + fieldName + valueToHash);
   const name = field.open
-    ? `${field.name}||${hash}||open`
-    : `${field.name}||${hash}`;
+    ? `${fieldName}||${hash}||open`
+    : `${fieldName}||${hash}`;
   return { name, value: field.value };
 }
 
@@ -642,7 +712,7 @@ export async function buildVariantCartPayload(
 
   const rendered: RenderedCartField[] = signed
     ? await Promise.all(fields.map((f) => signField(opts.secret!, code, f)))
-    : fields.map((f) => ({ name: f.name, value: f.value }));
+    : fields.map(unsignedField);
 
   // Split the quantity field out: the island puts it on the visible stepper.
   const qtyIdx = fields.findIndex((f) => f.name === "quantity");
@@ -830,7 +900,7 @@ export async function withVerificationRef(
   const code = fields.find((field) => field.name.split("||")[0] === "code")?.value;
   if (!code) return [...fields];
   const field: CartField = { name: "verification", value: opts.ref };
-  if (opts.mode !== "signed") return [...fields, field];
+  if (opts.mode !== "signed") return [...fields, unsignedField(field)];
   if (!opts.secret) throw new CartSigningUnavailableError();
   return [...fields, await signField(opts.secret, code, field)];
 }
@@ -852,7 +922,7 @@ export async function withShippingPolicy(
   const currency = kept.find((field) => field.name.split("||")[0] === "currency")?.value;
   if (!code || !currency) throw new ShippingPolicyUnavailableError();
   const field: CartField = { name: SHIPPING_POLICY_CART_FIELD, value: shippingPolicyOptionValue(opts.policy, currency) };
-  if (opts.mode !== "signed") return [...kept, field];
+  if (opts.mode !== "signed") return [...kept, unsignedField(field)];
   if (!opts.secret) throw new CartSigningUnavailableError();
   return [...kept, await signField(opts.secret, code, field)];
 }

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -21,7 +21,10 @@ export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
 export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
 export function seoDeclarationProblems(seo: unknown): string[];
 export const SHIPPING_KEYS: readonly string[];
+export const SHIPPING_TIER_KEYS: readonly string[];
 export const MAX_SHIPPING_AMOUNT: number;
+export const MAX_SHIPPING_TIERS: number;
+export const MAX_SHIPPING_LABEL_LENGTH: number;
 export function shippingDeclarationProblems(shipping: unknown): string[];
 export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
 export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -243,20 +243,38 @@ export function seoDeclarationProblems(seo) {
 }
 
 /** Every `shipping` key (ShippingPolicy, tenant.ts). */
-export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+export const SHIPPING_KEYS = Object.freeze(["tiers"]);
+
+/** Every key of one `shipping.tiers` entry (ShippingTier, tenant.ts). */
+export const SHIPPING_TIER_KEYS = Object.freeze(["atOrAbove", "rate", "label"]);
 
 /** Largest shipping amount a declaration may state, in the cart's currency. */
 export const MAX_SHIPPING_AMOUNT = 100000;
 
+/** Most tiers one policy may declare. */
+export const MAX_SHIPPING_TIERS = 10;
+
+/** Longest shipping-line label, in characters. */
+export const MAX_SHIPPING_LABEL_LENGTH = 100;
+
 /** @param {unknown} value */
 const isShippingAmount = (value) =>
   typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
   && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
 
+/** @param {unknown} value */
+const isShippingLabel = (value) =>
+  typeof value === "string" && value.trim() === value && value.length > 0
+  && [...value].length <= MAX_SHIPPING_LABEL_LENGTH && !/[\u0000-\u001f\u007f]/.test(value);
+
 /**
  * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
  * valid. A policy with any problem is refused whole, so checkout never charges half of one.
  *
+ * Tiers are ordered by the item subtotal they start at. The first starts at 0 and states no
+ * `atOrAbove`; each later tier's `atOrAbove` is above the one before it and is inclusive, so an
+ * order whose subtotal equals it pays that tier's `rate`.
+ *
  * @param {unknown} shipping
  * @returns {string[]}
  */
@@ -267,15 +285,54 @@ export function shippingDeclarationProblems(shipping) {
   for (const key of Object.keys(source)) {
     if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
   }
-  if (!isShippingAmount(source.flatRate)) {
-    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
-  }
-  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
-    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  const tiers = source.tiers;
+  if (!Array.isArray(tiers) || tiers.length === 0 || tiers.length > MAX_SHIPPING_TIERS) {
+    problems.push(`\`shipping.tiers\` must be a list of 1 to ${MAX_SHIPPING_TIERS} tiers`);
+    return problems;
   }
+  let previous = 0;
+  tiers.forEach((tier, index) => {
+    const at = `shipping.tiers[${index}]`;
+    if (!isPlainObject(tier)) {
+      problems.push(`\`${at}\` must be an object`);
+      return;
+    }
+    const entry = /** @type {Record<string, unknown>} */ (tier);
+    for (const key of Object.keys(entry)) {
+      if (!SHIPPING_TIER_KEYS.includes(key)) problems.push(`\`${at}.${key}\` is not a tier key (${SHIPPING_TIER_KEYS.join(", ")})`);
+    }
+    if (!isShippingAmount(entry.rate)) {
+      problems.push(`\`${at}.rate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+    }
+    if (entry.label !== undefined && !isShippingLabel(entry.label)) {
+      problems.push(`\`${at}.label\` must be text of 1 to ${MAX_SHIPPING_LABEL_LENGTH} characters with no surrounding spaces or line breaks`);
+    }
+    if (index === 0) {
+      if (entry.atOrAbove !== undefined) problems.push(`\`${at}\` starts at 0, so it states no \`atOrAbove\``);
+      return;
+    }
+    if (!(isShippingAmount(entry.atOrAbove) && /** @type {number} */ (entry.atOrAbove) > previous)) {
+      problems.push(`\`${at}.atOrAbove\` must be an amount above ${previous}, where the tier before it starts, and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+      return;
+    }
+    previous = /** @type {number} */ (entry.atOrAbove);
+  });
   return problems;
 }
 
+/**
+ * A valid declaration copied to exactly its declared keys.
+ *
+ * @param {{ tiers: Array<Record<string, unknown>> }} policy
+ */
+const shippingPolicyOf = (policy) => ({
+  tiers: policy.tiers.map((tier) => ({
+    ...(tier.atOrAbove === undefined ? {} : { atOrAbove: tier.atOrAbove }),
+    rate: tier.rate,
+    ...(tier.label === undefined ? {} : { label: tier.label }),
+  })),
+});
+
 /**
  * The declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
  * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
@@ -302,8 +359,7 @@ export function declaredTenantConfig(config) {
   // The shipping charge: refused whole when any part is malformed (`tot validate` and the
   // reconcile report it), so checkout keeps charging no shipping rather than a guess.
   if (shipping !== undefined && shippingDeclarationProblems(shipping).length === 0) {
-    const policy = /** @type {Record<string, number>} */ (shipping);
-    out.shipping = { flatRate: policy.flatRate, ...(policy.freeAtOrAbove === undefined ? {} : { freeAtOrAbove: policy.freeAtOrAbove }) };
+    out.shipping = shippingPolicyOf(/** @type {{ tiers: Array<Record<string, unknown>> }} */ (shipping));
   }
   return out;
 }

package/packages/public-runtime/src/tenant.ts

@@ -773,16 +773,27 @@ export interface TenantConfig {
 }
 
 /**
- * A store's shipping charge: one flat rate per order, waived when the order's item subtotal
- * is at or above `freeAtOrAbove`. The cart carries it as the signed `shipping_policy` option;
- * the checkout store charges it and the final-cart authority re-derives it from this
- * declaration (checkout.ts `shippingMinorFor`).
+ * A store's shipping charge: one rate per order, chosen by the order's item subtotal from
+ * `tiers`. The cart carries it as the signed `shipping_policy` option; the checkout store
+ * charges it under the tier's label, and the final-cart authority re-derives the amount from
+ * this declaration (checkout.ts `shippingMinorFor`).
  */
 export interface ShippingPolicy {
-  /** Charged once per order, in the cart's currency. `0` ships every order free. */
-  flatRate: number;
-  /** Item subtotal at or above which shipping is free, in the cart's currency. */
-  freeAtOrAbove?: number;
+  /**
+   * Ascending by `atOrAbove`. The first tier starts at 0 and states no `atOrAbove`; an order
+   * pays the last tier whose start its item subtotal reaches.
+   */
+  tiers: ShippingTier[];
+}
+
+/** One band of item subtotals and what an order in it pays for shipping. */
+export interface ShippingTier {
+  /** Item subtotal this tier starts at, inclusive, in the cart's currency. Absent on the first tier. */
+  atOrAbove?: number;
+  /** Charged once per order, in the cart's currency. `0` ships free. */
+  rate: number;
+  /** The shipping line the shopper reads at checkout. Absent ⇒ "Free shipping" or "Shipping". */
+  label?: string;
 }
 
 /** Page types a structured-data profile declares a graph for (STRUCTURED_DATA_PAGE_TYPES). */