Stock SKU policy

API contracts for inventory SKU policy defaults, group overrides, and evaluation.

Last updated:

All routes below require session auth via requireAuth("json") and are tenant-scoped by customer_id.

Inventory default policy

GET /api/inventory/stock/sku-policy

Returns current customer policy configuration and effective default policy.

POST /api/inventory/stock/sku-policy

Saves customer default policy.

Request body:

  • mode: off | warn | block
  • pattern: string | null (required when mode is warn or block)
  • normalise_to_uppercase: boolean

POST /api/inventory/stock/sku-policy/preview

Dry-run test of an unsaved inventory default policy against existing stock.

Request body:

  • mode: off | warn | block
  • pattern: string | null (required when mode is warn or block)
  • normalise_to_uppercase: boolean
  • exception_limit: number (optional, default 250, max 20000)

Response includes:

  • policy_under_test
  • summary counts:
    • scanned_rows
    • policy_active_rows
    • matching_rows
    • exception_rows
    • blocked_rows
    • warned_rows
    • configuration_error_rows
    • source_counts (customer, stock_group, default)
    • mode_counts (off, warn, block)
  • exceptions[] report rows (SKU, stock item, policy source/mode/pattern, level, message)
  • hidden_exception_count and truncated when exceptions exceed exception_limit

Stock-group override policy

GET /api/inventory/stock/groups/:id/sku-policy

Returns group override (if present) and effective policy for that group.

POST /api/inventory/stock/groups/:id/sku-policy

Saves or removes group override.

Request body:

  • inherit_default: true to remove override, or
  • mode, pattern, normalise_to_uppercase to save override.

Evaluate a SKU against effective policy

POST /api/inventory/stock/sku-policy/evaluate

Request body:

  • sku: string (optional)
  • stock_group_id: uuid (optional)

Response includes:

  • effective policy
  • evaluated sku object:
    • input
    • normalised
    • matches
    • blocked
    • message

Enforcement behaviour

SKU policy is applied server-side on:

  • stock create
  • stock item update when stock_group_id changes
  • stock import validation/commit

For stock item update, SKU remains immutable; when group changes, the existing SKU is re-evaluated against the target effective policy.

warn mode allows save/import and surfaces warnings.
block mode rejects non-matching SKUs with 400.