C

Cart rules

Name: Cart rules
Author: Xross-dev

Medusa v2 plugin: cart & per-product quantity rules scoped by customer group, sales channel, product, variant, collection or category.

Featured on Medusa

npm install @xross-dev/medusa-cart-rules

@xross-dev/medusa-cart-rules

Medusa v2 plugin. Blocks add-to-cart, quantity increase and checkout when a quantity rule is violated.

Rules

	Meaning
	Total items ≤ limit. Scope = whole cart; other scopes = combined items matching the scope (e.g. "max 4 items from collection X").
	Per product ≤ limit (per variant when scope = ). Scope = every product; // = matching products.

Audience: everyone (+ optional guests), or one customer group. Also: sales channel, active window (/), priority, custom message ().

Resolution

Per-product: variant > product > collection/category > global (first tier with a matching rule wins).
Same scope target: a customer-group rule overrides the "everyone" rule (VIP 50 beats global 20).
Several matching group rules: (lowest, default) or (highest).
Cart-level and product-level rules are checked independently; all must pass.
Decreasing a quantity is always allowed. Add/update only block for products they touch; checks the whole cart.

Install

1# in the plugin
2yarn && yarn build        # migration for cart_rule + cart_rule_violation is already included
3                          # (after changing models: yarn db:generate, needs a local Postgres + DB_USERNAME/DB_PASSWORD)
4npx medusa plugin:publish                  # or: yalc / npm publish

1// medusa-config.ts
2plugins: [
3  { resolve: "@xross-dev/medusa-cart-rules", options: { conflict_strategy: "restrictive" } },
4],

npx medusa db:migrate   # in the app

Dev loop: in the plugin, in the app.

API

Admin (auth required): , , , .

Store (publishable key): or

1{ "limits": [{ "rule_id": "crule_…", "rule_type": "max_cart_quantity", "scope_type": "global", "limit": 20, "current": 12, "remaining": 8 }],
2  "lines": { "item_…": { "remaining": 2, "max_quantity": 5 } },
3  "variant": { "variant_id": "variant_…", "remaining": 3 } }

Use to cap the quantity stepper.

Blocked requests return HTTP 400 .

Custom rule types

1import { registerRuleType } from "@xross-dev/medusa-cart-rules/modules/cart-rules/engine"
2registerRuleType("max_cart_total", { label: "...", defaultMessage: "...", measure: (cart, rules, ctx) => [/* Measurement[] */] })

Call it from a loader or any file loaded at boot. The engine () is pure (no I/O) and unit-tested: .

Notes

Workflow hooks used: , , → .
Scope/group/channel IDs are plain strings (no module links), validated on create/update.
Admin page: Cart Rules in the sidebar (rules CRUD + blocked-attempts log), built with .