Minimum and maximum quantity per product

api_version = "2026-10"

[[extensions]]
name = "Minimum and maximum quantity per product"
handle = "min-max-quantity-per-product"
type = "function"

  [[extensions.targeting]]
  target = "cart.validations.generate.run"
  input_query = "src/cart_validations_generate_run.graphql"
  export = "cart-validations-generate-run"

  [extensions.build]
  command = ""
  path = "dist/function.wasm"

query CartValidationsGenerateRunInput {
  buyerJourney {
    step
  }
  cart {
    lines {
      quantity
      merchandise {
        __typename
        ... on ProductVariant {
          product {
            id
            title
            minQuantity: metafield(namespace: "custom", key: "min_quantity") {
              value
            }
            maxQuantity: metafield(namespace: "custom", key: "max_quantity") {
              value
            }
          }
        }
      }
    }
  }
}

// @ts-check

/**
 * @typedef {import("../generated/api").CartValidationsGenerateRunInput} CartValidationsGenerateRunInput
 * @typedef {import("../generated/api").CartValidationsGenerateRunResult} CartValidationsGenerateRunResult
 */

/** Errors about the cart as a whole show at the top of checkout and on the cart. */
const CART_TARGET = "$.cart";

/** @param {{value: string} | null | undefined} metafield */
function readLimit(metafield) {
  const limit = Number.parseInt(metafield?.value ?? "", 10);
  return Number.isInteger(limit) && limit > 0 ? limit : null;
}

/**
 * @param {CartValidationsGenerateRunInput} input
 * @returns {CartValidationsGenerateRunResult}
 */
export function cartValidationsGenerateRun(input) {
  // While the cart is being built, a shopper adding one unit at a time would be
  // stopped by the minimum before reaching it; enforce it from checkout on.
  const checkMinimum = input.buyerJourney?.step !== "CART_INTERACTION";
  // Limits are per product, so add up all variants (sizes, colors) of it.
  /** @type {Map<string, {title: string, quantity: number, min: number | null, max: number | null}>} */
  const products = new Map();
  for (const line of input.cart.lines) {
    if (line.merchandise.__typename !== "ProductVariant") continue;
    const { product } = line.merchandise;
    const entry = products.get(product.id) ?? {
      title: product.title,
      quantity: 0,
      min: readLimit(product.minQuantity),
      max: readLimit(product.maxQuantity),
    };
    entry.quantity += line.quantity;
    products.set(product.id, entry);
  }

  const errors = [];
  for (const { title, quantity, min, max } of products.values()) {
    if (checkMinimum && min !== null && quantity < min) {
      errors.push({ message: `${title}: the minimum order quantity is ${min}.`, target: CART_TARGET });
    } else if (max !== null && quantity > max) {
      errors.push({ message: `${title}: you can buy at most ${max}.`, target: CART_TARGET });
    }
  }

  return { operations: errors.length > 0 ? [{ validationAdd: { errors } }] : [] };
}