@wtree/payload-ecommerce-coupon 3.77.0 → 3.77.3

package/README.md

@@ -27,6 +27,8 @@ Production-ready coupon and referral system plugin for **Payload CMS** with seam
 - ✅ **Commission Rules** – **Required.** At least one rule per program. Each rule supports:
   - **Direct Basis**: Separate Reward (Partner) and Referee Reward (Customer).
   - **Shared Basis**: Define a total "pot" (e.g., 20% of order) and split it (e.g., 50/50) between partner and customer.
+- ✅ **Rule-level Minimum Order** – Optional `minOrderAmount` per commission rule, validated on apply/validate/recalculate
+- ✅ **Fixed-only Mode** – Restrict `totalCommission.type` to fixed only via `referralConfig.allowedTotalCommissionTypes: ['fixed']`
 - ✅ **Referrer/Referee inside each rule** – Partner gets commission, customer gets discount; type (percentage/fixed), value, and optional max cap per rule.
 - ✅ **Partner Tracking** – Commission earnings and referral performance (credited when order is placed)
 - ✅ **Auto-Generated Codes** – Unique referral codes for each partner
@@ -85,6 +87,8 @@ export default buildConfig({
         singleCodePerCart: true, // Only one code per order
         defaultPartnerSplit: 70, // 70% to partner
         defaultCustomerSplit: 30, // 30% discount to customer
+        // Set fixed-only mode for production partner programs
+        allowedTotalCommissionTypes: ["fixed"], // Default: ["fixed", "percentage"]
       },
 
       // Custom admin panel groups
@@ -110,6 +114,13 @@ export default buildConfig({
         isPartner: ({ req }) => req.user?.role === "partner",
       },
 
+      // Optional: role resolver for custom user schemas
+      // roleConfig: {
+      //   roleFieldPaths: ["role", "roles", "account.roles"],
+      //   adminRoleValues: ["admin"],
+      //   partnerRoleValues: ["partner", "affiliate"],
+      // },
+
       // Optional: for per-customer coupon limit (defaults shown)
       // orderIntegration: {
       //   ordersSlug: 'orders',
@@ -138,7 +149,7 @@ This will create collections for:
 
 ### 3. Setting Up Partner Role
 
-To enable the partner dashboard and role-based access, add a `role` field to your Users collection:
+To enable the partner dashboard and role-based access, add a `role` or `roles` field to your Users collection (or configure custom paths with `roleConfig`):
 
 ```typescript
 // collections/Users.ts
@@ -175,6 +186,16 @@ export const Users: CollectionConfig = {
 };
 ```
 
+If your user schema stores roles in a custom structure, configure:
+
+```typescript
+roleConfig: {
+  roleFieldPaths: ["role", "roles", "profile.accountRoles"],
+  adminRoleValues: ["admin"],
+  partnerRoleValues: ["partner", "affiliate"],
+}
+```
+
 ### 4. Record Usage When Order Is Placed
 
 Coupon and referral **usage is not counted when a code is applied** to the cart. It is counted only when an **order is placed successfully** (e.g. paid). You must call the plugin when converting cart to order:

package/dist/collections/createReferralCodesCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createReferralCodesCollection.d.ts","sourceRoot":"","sources":["../../src/collections/createReferralCodesCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAE5D,eAAO,MAAM,6BAA6B,GACxC,cAAc,4BAA4B,KACzC,gBA+LF,CAAA"}
+{"version":3,"file":"createReferralCodesCollection.d.ts","sourceRoot":"","sources":["../../src/collections/createReferralCodesCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAG5D,eAAO,MAAM,6BAA6B,GACxC,cAAc,4BAA4B,KACzC,gBA0LF,CAAA"}

package/dist/collections/createReferralProgramsCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createReferralProgramsCollection.d.ts","sourceRoot":"","sources":["../../src/collections/createReferralProgramsCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAwB5D,eAAO,MAAM,gCAAgC,GAC3C,cAAc,4BAA4B,KACzC,gBA6PF,CAAA"}
+{"version":3,"file":"createReferralProgramsCollection.d.ts","sourceRoot":"","sources":["../../src/collections/createReferralProgramsCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAyB5D,eAAO,MAAM,gCAAgC,GAC3C,cAAc,4BAA4B,KACzC,gBAiRF,CAAA"}

package/dist/endpoints/applyCoupon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applyCoupon.d.ts","sourceRoot":"","sources":["../../src/endpoints/applyCoupon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAO5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAcD,eAAO,MAAM,kBAAkB,GAC5B,kBAAkB,IAAI,KAAG,cAyFzB,CAAA;AA4SH,eAAO,MAAM,mBAAmB,GAAI,kBAAkB,IAAI,KAAG,QAI3D,CAAA"}
+{"version":3,"file":"applyCoupon.d.ts","sourceRoot":"","sources":["../../src/endpoints/applyCoupon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAQ5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAcD,eAAO,MAAM,kBAAkB,GAC5B,kBAAkB,IAAI,KAAG,cAyFzB,CAAA;AA4TH,eAAO,MAAM,mBAAmB,GAAI,kBAAkB,IAAI,KAAG,QAI3D,CAAA"}

package/dist/endpoints/partnerStats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"partnerStats.d.ts","sourceRoot":"","sources":["../../src/endpoints/partnerStats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,KAAK,EAAsC,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAEhG,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,mBAAmB,GAC7B,kBAAkB,IAAI,KAAG,cA8KzB,CAAA;AAEH,eAAO,MAAM,oBAAoB,GAAI,kBAAkB,IAAI,KAAG,QAI5D,CAAA"}
+{"version":3,"file":"partnerStats.d.ts","sourceRoot":"","sources":["../../src/endpoints/partnerStats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,KAAK,EAAsC,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAGhG,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,mBAAmB,GAC7B,kBAAkB,IAAI,KAAG,cA6KzB,CAAA;AAEH,eAAO,MAAM,oBAAoB,GAAI,kBAAkB,IAAI,KAAG,QAI5D,CAAA"}

package/dist/endpoints/validateCoupon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateCoupon.d.ts","sourceRoot":"","sources":["../../src/endpoints/validateCoupon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAI5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAC/B,kBAAkB,IAAI,KAAG,cAkCzB,CAAA;AA2QH,eAAO,MAAM,sBAAsB,GAAI,kBAAkB,IAAI,KAAG,QAI9D,CAAA"}
+{"version":3,"file":"validateCoupon.d.ts","sourceRoot":"","sources":["../../src/endpoints/validateCoupon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAO5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAC/B,kBAAkB,IAAI,KAAG,cAkCzB,CAAA;AA4RH,eAAO,MAAM,sBAAsB,GAAI,kBAAkB,IAAI,KAAG,QAI9D,CAAA"}

package/dist/hooks/recalculateCart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recalculateCart.d.ts","sourceRoot":"","sources":["../../src/hooks/recalculateCart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAQ5D,eAAO,MAAM,mBAAmB,GAC7B,cAAc,4BAA4B,KAAG,0BAiO7C,CAAA"}
+{"version":3,"file":"recalculateCart.d.ts","sourceRoot":"","sources":["../../src/hooks/recalculateCart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAS5D,eAAO,MAAM,mBAAmB,GAC7B,cAAc,4BAA4B,KAAG,0BA2N7C,CAAA"}

package/dist/index.d.ts

@@ -3,10 +3,10 @@ import { createReferralCodesCollection } from './collections/createReferralCodes
 import { createReferralProgramsCollection } from './collections/createReferralProgramsCollection';
 import { payloadEcommerceCouponPlugin } from './plugin';
 export { useCouponCode, usePartnerStats, validateCouponCode } from './client/hooks';
-export { calculateCommissionAndDiscount } from './utilities/calculateValues';
+export { calculateCommissionAndDiscount, getProgramMinimumOrderAmount, } from './utilities/calculateValues';
 export { getCartTotalWithDiscounts } from './utilities/getCartTotalWithDiscounts';
 export { recordCouponUsageForOrder } from './utilities/recordCouponUsageForOrder';
 export { createCouponsCollection, createReferralCodesCollection, createReferralProgramsCollection, payloadEcommerceCouponPlugin as payloadEcommerceCoupon, };
-export type { AdminGroupConfig, ApplyCouponHook, ApplyCouponResponse, CouponPluginAccess, CouponPluginCollections, CouponPluginOptions, OrderIntegrationConfig, PartnerDashboardConfig, PartnerDashboardData, PartnerStats, ReferralProgramConfig, } from './types';
+export type { AdminGroupConfig, ApplyCouponHook, ApplyCouponResponse, CouponPluginAccess, CouponPluginCollections, CouponPluginOptions, OrderIntegrationConfig, PartnerDashboardConfig, PartnerDashboardData, PartnerStats, ReferralProgramConfig, RoleConfig, } from './types';
 export type { CartLike } from './utilities/getCartTotalWithDiscounts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAA;AAC/E,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAA;AAC3F,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAA;AACjG,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,gCAAgC,EAChC,4BAA4B,IAAI,sBAAsB,GACvD,CAAA;AAED,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,GACtB,MAAM,SAAS,CAAA;AAChB,YAAY,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAA;AAC/E,OAAO,EAAE,6BAA6B,EAAE,MAAM,6CAA6C,CAAA;AAC3F,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAA;AACjG,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACnF,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,gCAAgC,EAChC,4BAA4B,IAAI,sBAAsB,GACvD,CAAA;AAED,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,EACrB,UAAU,GACX,MAAM,SAAS,CAAA;AAChB,YAAY,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAA"}

package/dist/index.js

@@ -120,10 +120,59 @@ const createCouponsCollection = (pluginConfig) => {
 	};
 };
 
+//#endregion
+//#region src/utilities/userRoles.ts
+function readByPath(input, path) {
+	if (!input || typeof input !== "object" || !path) return void 0;
+	return path.split(".").reduce((acc, key) => {
+		if (!acc || typeof acc !== "object") return void 0;
+		return acc[key];
+	}, input);
+}
+function toRoleArray(value) {
+	if (typeof value === "string" && value.trim().length > 0) return [value];
+	if (Array.isArray(value)) return value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+	return [];
+}
+const normalizeRoleValue = (value) => value.trim().toLowerCase();
+const resolveUserRoles = ({ user, roleConfig }) => {
+	if (!user) return [];
+	if (typeof roleConfig.customRoleResolver === "function") {
+		const custom = roleConfig.customRoleResolver(user);
+		return Array.isArray(custom) ? custom.map(normalizeRoleValue).filter(Boolean) : [];
+	}
+	const roles = roleConfig.roleFieldPaths.flatMap((path) => toRoleArray(readByPath(user, path)));
+	return [...new Set(roles.map(normalizeRoleValue).filter(Boolean))];
+};
+const userHasAnyRole = ({ user, roleConfig, targetRoles }) => {
+	const userRoles = new Set(resolveUserRoles({
+		user,
+		roleConfig
+	}));
+	for (const target of targetRoles) if (userRoles.has(normalizeRoleValue(target))) return true;
+	return false;
+};
+const isPartnerUser = ({ user, roleConfig }) => userHasAnyRole({
+	user,
+	roleConfig,
+	targetRoles: roleConfig.partnerRoleValues
+});
+const isAdminUser = ({ user, roleConfig }) => userHasAnyRole({
+	user,
+	roleConfig,
+	targetRoles: roleConfig.adminRoleValues
+});
+const buildPartnerUserFilterWhere = ({ roleConfig }) => {
+	if (!roleConfig.roleFieldPaths.length || !roleConfig.partnerRoleValues.length) return true;
+	const conditions = roleConfig.roleFieldPaths.map((fieldPath) => ({ [fieldPath]: { in: roleConfig.partnerRoleValues } }));
+	if (conditions.length === 1) return conditions[0];
+	return { or: conditions };
+};
+
 //#endregion
 //#region src/collections/createReferralCodesCollection.ts
 const createReferralCodesCollection = (pluginConfig) => {
-	const { collections, access, adminGroups, defaultCurrency } = pluginConfig;
+	const { collections, access, adminGroups, defaultCurrency, roleConfig } = pluginConfig;
 	return {
 		slug: collections.referralCodesSlug,
 		admin: {
@@ -141,15 +190,27 @@ const createReferralCodesCollection = (pluginConfig) => {
 			read: ({ req }) => {
 				const user = req?.user;
 				if (!user) return false;
-				if (user.role === "admin" || Array.isArray(user.roles) && user.roles.includes("admin")) return true;
-				if (user.role === "partner" || Array.isArray(user.roles) && user.roles.includes("partner")) return { partner: { equals: user.id } };
+				if (isAdminUser({
+					user,
+					roleConfig
+				}) || access.isAdmin?.({ req })) return true;
+				if (isPartnerUser({
+					user,
+					roleConfig
+				}) || access.isPartner?.({ req })) return { partner: { equals: user.id } };
 				return access.canUseReferrals ? access.canUseReferrals({ req }) : false;
 			},
 			create: ({ req }) => {
 				const user = req?.user;
 				if (!user) return false;
-				if (user.role === "admin" || Array.isArray(user.roles) && user.roles.includes("admin")) return true;
-				if (user.role === "partner" || Array.isArray(user.roles) && user.roles.includes("partner")) return true;
+				if (isAdminUser({
+					user,
+					roleConfig
+				}) || access.isAdmin?.({ req })) return true;
+				if (isPartnerUser({
+					user,
+					roleConfig
+				}) || access.isPartner?.({ req })) return true;
 				return access.isAdmin ? access.isAdmin({ req }) : false;
 			},
 			update: access.isAdmin || (() => false),
@@ -175,7 +236,13 @@ const createReferralCodesCollection = (pluginConfig) => {
 				type: "relationship",
 				relationTo: "users",
 				required: true,
-				filterOptions: { roles: { contains: "partner" } },
+				filterOptions: ({ req, user }) => {
+					if (isAdminUser({
+						user: user || req?.user,
+						roleConfig
+					}) || access.isAdmin?.({ req })) return true;
+					return buildPartnerUserFilterWhere({ roleConfig });
+				},
 				admin: { description: "The partner who owns this referral code" }
 			},
 			{
@@ -252,7 +319,10 @@ const createReferralCodesCollection = (pluginConfig) => {
 			if (operation === "create" && !data.code && data.partner) data.code = `REF-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`.toUpperCase();
 			if (operation === "create" && req.user) {
 				const user = req.user;
-				if (user.role === "partner" || Array.isArray(user.roles) && user.roles.includes("partner")) data.partner = user.id;
+				if (isPartnerUser({
+					user,
+					roleConfig
+				})) data.partner = user.id;
 			}
 			return data;
 		}] },
@@ -274,6 +344,7 @@ const deriveCustomerSplit = (partnerSplit) => {
 };
 const createReferralProgramsCollection = (pluginConfig) => {
 	const { collections, access, defaultCurrency, adminGroups, referralConfig } = pluginConfig;
+	const allowedTotalCommissionTypes = referralConfig.allowedTotalCommissionTypes;
 	return {
 		slug: collections.referralProgramsSlug,
 		admin: {
@@ -296,7 +367,7 @@ const createReferralProgramsCollection = (pluginConfig) => {
 			data.commissionRules = data.commissionRules.map((rule, index) => {
 				const r = rule;
 				if (!r.totalCommission) throw new Error(`Commission rule ${index + 1}: Total Commission is required`);
-				if (!r.totalCommission.type || !["fixed", "percentage"].includes(r.totalCommission.type)) throw new Error(`Commission rule ${index + 1}: Total Commission type must be fixed or percentage`);
+				if (!r.totalCommission.type || !allowedTotalCommissionTypes.includes(r.totalCommission.type)) throw new Error(`Commission rule ${index + 1}: Total Commission type must be one of ${allowedTotalCommissionTypes.join(", ")}`);
 				const totalValue = toNumber(r.totalCommission.value);
 				if (totalValue == null || totalValue < 0) throw new Error(`Commission rule ${index + 1}: Total Commission value must be a non-negative number`);
 				if (r.totalCommission.type === "percentage" && totalValue > 100) throw new Error(`Commission rule ${index + 1}: Percentage Total Commission cannot exceed 100`);
@@ -308,6 +379,8 @@ const createReferralProgramsCollection = (pluginConfig) => {
 				const partnerSplit = toNumber(r.partnerSplit);
 				if (partnerSplit == null || partnerSplit < 0 || partnerSplit > 100) throw new Error(`Commission rule ${index + 1}: Partner Split must be between 0 and 100`);
 				const customerSplit = 100 - partnerSplit;
+				const minOrderAmount = toNumber(r.minOrderAmount);
+				if (minOrderAmount != null && minOrderAmount < 0) throw new Error(`Commission rule ${index + 1}: Minimum Order Amount must be a non-negative number`);
 				return {
 					...rule,
 					appliesTo: appliesTo === "categories" ? "segments" : appliesTo,
@@ -317,7 +390,8 @@ const createReferralProgramsCollection = (pluginConfig) => {
 						maxAmount: maxAmount ?? null
 					},
 					partnerSplit,
-					customerSplit
+					customerSplit,
+					minOrderAmount: minOrderAmount ?? null
 				};
 			});
 			return data;
@@ -407,14 +481,11 @@ const createReferralProgramsCollection = (pluginConfig) => {
 								name: "type",
 								type: "select",
 								required: true,
-								options: [{
-									label: "Fixed Amount",
-									value: "fixed"
-								}, {
-									label: "Percentage of Order",
-									value: "percentage"
-								}],
-								defaultValue: "percentage"
+								options: allowedTotalCommissionTypes.map((value) => ({
+									label: value === "fixed" ? "Fixed Amount" : "Percentage of Order",
+									value
+								})),
+								defaultValue: allowedTotalCommissionTypes.includes("fixed") ? "fixed" : "percentage"
 							},
 							{
 								name: "value",
@@ -440,6 +511,12 @@ const createReferralProgramsCollection = (pluginConfig) => {
 						defaultValue: referralConfig.defaultPartnerSplit,
 						admin: { description: "Percentage of total commission given to Partner (0-100)" }
 					},
+					{
+						name: "minOrderAmount",
+						type: "number",
+						min: 0,
+						admin: { description: `Minimum cart subtotal required for this rule in ${defaultCurrency}. Leave empty for no minimum.` }
+					},
 					{
 						name: "customerSplit",
 						type: "number",
@@ -526,6 +603,7 @@ function relationId(value) {
 	if (typeof value === "object" && (typeof value.id === "string" || typeof value.id === "number")) return value.id;
 	return null;
 }
+const allowedCommissionTypesSet = (allowed) => new Set((allowed && allowed.length ? allowed : ["fixed", "percentage"]).map((v) => v));
 function normalizeIds(values) {
 	if (!Array.isArray(values)) return [];
 	return values.map(relationId).filter((v) => v != null);
@@ -538,8 +616,10 @@ function getRuleSplits(rule) {
 		customerSplit: typeof rule.customerSplit === "number" ? rule.customerSplit : typeof rule.refereeSplit === "number" ? rule.refereeSplit : 100 - partnerRaw
 	};
 }
-function calculateItemRewardByRule({ rule, itemTotal, quantity }) {
+function calculateItemRewardByRule({ rule, itemTotal, quantity, allowedTotalCommissionTypes }) {
+	const allowedTypes = allowedCommissionTypesSet(allowedTotalCommissionTypes);
 	if (rule.totalCommission) {
+		if (!allowedTypes.has(rule.totalCommission.type)) return null;
 		const splits = getRuleSplits(rule);
 		if (!splits) return null;
 		let totalPot = 0;
@@ -578,21 +658,27 @@ function getItemCategoryIds(item) {
 function getItemTagIds(item) {
 	return Array.isArray(item?.product?.tags) ? normalizeIds(item.product.tags) : [];
 }
-function selectBestRuleForItem({ rules, item, itemTotal, quantity }) {
+function selectBestRuleForItem({ rules, item, itemTotal, quantity, cartTotal, allowedTotalCommissionTypes }) {
+	const allowedTypes = allowedCommissionTypesSet(allowedTotalCommissionTypes);
+	const eligibleRules = rules.filter((rule) => {
+		if (!(rule?.totalCommission?.type ? allowedTypes.has(rule.totalCommission.type) : true)) return false;
+		if (typeof rule?.minOrderAmount === "number" && Number.isFinite(rule.minOrderAmount)) return cartTotal >= rule.minOrderAmount;
+		return true;
+	});
 	const productId = relationId(item.product);
 	const itemCategoryIds = new Set(getItemCategoryIds(item));
 	const itemTagIds = new Set(getItemTagIds(item));
 	const candidates = [
-		rules.filter((r) => r.appliesTo === "products" && normalizeIds(r.products).some((id) => productId != null && id === productId)),
-		rules.filter((r) => {
+		eligibleRules.filter((r) => r.appliesTo === "products" && normalizeIds(r.products).some((id) => productId != null && id === productId)),
+		eligibleRules.filter((r) => {
 			if (!(r.appliesTo === "segments" || r.appliesTo === "categories")) return false;
 			return normalizeIds(r.categories).some((id) => itemCategoryIds.has(id));
 		}),
-		rules.filter((r) => {
+		eligibleRules.filter((r) => {
 			if (r.appliesTo !== "segments") return false;
 			return normalizeIds(r.tags).some((id) => itemTagIds.has(id));
 		}),
-		rules.filter((r) => r.appliesTo === "all")
+		eligibleRules.filter((r) => r.appliesTo === "all")
 	].find((level) => level.length > 0) ?? [];
 	if (!candidates.length) return null;
 	let best = null;
@@ -600,7 +686,8 @@ function selectBestRuleForItem({ rules, item, itemTotal, quantity }) {
 		const reward = calculateItemRewardByRule({
 			rule,
 			itemTotal,
-			quantity
+			quantity,
+			allowedTotalCommissionTypes
 		});
 		if (!reward) continue;
 		if (!best) {
@@ -624,7 +711,18 @@ function selectBestRuleForItem({ rules, item, itemTotal, quantity }) {
 	}
 	return best;
 }
-function calculateCommissionAndDiscount({ cartItems, program, currencyCode = "AED" }) {
+function getProgramMinimumOrderAmount({ program, allowedTotalCommissionTypes }) {
+	const rules = Array.isArray(program?.commissionRules) ? program.commissionRules : [];
+	if (!rules.length) return null;
+	const allowedTypes = allowedCommissionTypesSet(allowedTotalCommissionTypes);
+	const minValues = rules.filter((rule) => {
+		if (rule?.totalCommission?.type) return allowedTypes.has(rule.totalCommission.type);
+		return true;
+	}).map((rule) => rule?.minOrderAmount).filter((value) => typeof value === "number" && Number.isFinite(value));
+	if (!minValues.length) return null;
+	return Math.min(...minValues);
+}
+function calculateCommissionAndDiscount({ cartItems, program, currencyCode = "AED", cartTotal = 0, allowedTotalCommissionTypes }) {
 	const rules = Array.isArray(program?.commissionRules) ? program.commissionRules : [];
 	if (!rules.length) return {
 		partnerCommission: 0,
@@ -649,7 +747,9 @@ function calculateCommissionAndDiscount({ cartItems, program, currencyCode = "AE
 				product
 			},
 			itemTotal,
-			quantity
+			quantity,
+			cartTotal,
+			allowedTotalCommissionTypes
 		});
 		if (!bestMatch) continue;
 		totalPartnerCommission += bestMatch.reward.partner;
@@ -877,10 +977,20 @@ async function handleReferralCode({ payload, code, cartID, cart, customerEmail:
 		error: "Referral code already applied to this cart"
 	}, { status: 400 });
 	const cartTotal = cart.subtotal || cart.total || 0;
+	const minOrderAmount = getProgramMinimumOrderAmount({
+		program,
+		allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
+	});
+	if (typeof minOrderAmount === "number" && cartTotal < minOrderAmount) return Response.json({
+		success: false,
+		error: `Minimum order value of ${minOrderAmount} ${pluginConfig.defaultCurrency} required for this referral program`
+	}, { status: 400 });
 	const { partnerCommission, customerDiscount } = calculateCommissionAndDiscount({
 		cartItems: cart.items || [],
 		program,
-		currencyCode: pluginConfig.defaultCurrency
+		currencyCode: pluginConfig.defaultCurrency,
+		cartTotal,
+		allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
 	});
 	const roundedPartnerCommission = roundTo2(partnerCommission);
 	const roundedCustomerDiscount = roundTo2(customerDiscount);
@@ -920,8 +1030,14 @@ const partnerStatsHandler = ({ pluginConfig }) => async (req) => {
 		error: "Authentication required"
 	}, { status: 401 });
 	const typedUser = user;
-	const isPartner = typedUser.role === "partner" || Array.isArray(typedUser.roles) && typedUser.roles.includes("partner");
-	const isAdmin = typedUser.role === "admin" || Array.isArray(typedUser.roles) && typedUser.roles.includes("admin");
+	const isPartner = isPartnerUser({
+		user: typedUser,
+		roleConfig: pluginConfig.roleConfig
+	}) || pluginConfig.access.isPartner?.({ req });
+	const isAdmin = isAdminUser({
+		user: typedUser,
+		roleConfig: pluginConfig.roleConfig
+	}) || pluginConfig.access.isAdmin?.({ req });
 	if (!isPartner && !isAdmin) return Response.json({
 		success: false,
 		error: "Partner access required"
@@ -1201,12 +1317,22 @@ async function validateReferralCode({ payload, code, cartID, pluginConfig }) {
 		id: cartID,
 		depth: 2
 	}) : null;
+	const cartTotal = cart ? cart.subtotal || cart.total || 0 : 0;
+	const minOrderAmount = getProgramMinimumOrderAmount({
+		program,
+		allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
+	});
+	if (typeof minOrderAmount === "number" && cartTotal < minOrderAmount) return Response.json({
+		success: false,
+		error: `Minimum order value of ${minOrderAmount} ${pluginConfig.defaultCurrency} required for this referral program`
+	}, { status: 400 });
 	const { partnerCommission, customerDiscount } = calculateCommissionAndDiscount({
 		cartItems: cart?.items || [],
 		program,
-		currencyCode: pluginConfig.defaultCurrency
+		currencyCode: pluginConfig.defaultCurrency,
+		cartTotal,
+		allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
 	});
-	const cartTotal = cart ? cart.subtotal || cart.total || 0 : 0;
 	const cappedCustomerDiscount = cartTotal > 0 ? Math.min(customerDiscount, cartTotal) : customerDiscount;
 	const roundedPartnerCommission = roundTo2(partnerCommission);
 	const roundedCustomerDiscount = roundTo2(cappedCustomerDiscount);
@@ -1232,12 +1358,6 @@ const validateCouponEndpoint = ({ pluginConfig }) => ({
 const recalculateCartHook = (pluginConfig) => async ({ data, req, originalDoc }) => {
 	if (!req.payload) return data;
 	const effectiveItems = data.items || originalDoc?.items || [];
-	console.log("[RecalculateCart] Hook triggered", {
-		hasDataItems: !!data.items,
-		dataItemsCount: data.items?.length,
-		originalItemsCount: originalDoc?.items?.length,
-		effectiveItemsCount: effectiveItems.length
-	});
 	if (!effectiveItems.length) return {
 		...data,
 		partnerCommission: 0,
@@ -1284,12 +1404,6 @@ const recalculateCartHook = (pluginConfig) => async ({ data, req, originalDoc })
 			currencyCode: pluginConfig.defaultCurrency
 		});
 		calculatedSubtotal += itemPrice * (item.quantity ?? 1);
-		console.log("[RecalculateCart] Item processed", {
-			productId,
-			quantity: item.quantity,
-			priceUsed: itemPrice,
-			currentSubtotal: calculatedSubtotal
-		});
 		return {
 			...item,
 			product,
@@ -1318,16 +1432,30 @@ const recalculateCartHook = (pluginConfig) => async ({ data, req, originalDoc })
 				id: programId
 			}) : null;
 			if (program) {
+				const minOrderAmount = getProgramMinimumOrderAmount({
+					program,
+					allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
+				});
+				if (typeof minOrderAmount === "number" && calculatedSubtotal < minOrderAmount) {
+					data.appliedReferralCode = null;
+					data.partnerCommission = 0;
+					data.customerDiscount = 0;
+					data.total = calculatedSubtotal;
+					return data;
+				}
 				const { partnerCommission, customerDiscount } = calculateCommissionAndDiscount({
 					cartItems: enrichedItems,
 					program,
-					currencyCode: pluginConfig.defaultCurrency
+					currencyCode: pluginConfig.defaultCurrency,
+					cartTotal: calculatedSubtotal,
+					allowedTotalCommissionTypes: pluginConfig.referralConfig.allowedTotalCommissionTypes
 				});
 				const roundedCustomerDiscount = roundTo2(customerDiscount);
 				data.partnerCommission = roundTo2(partnerCommission);
 				data.customerDiscount = roundedCustomerDiscount;
 				data.total = Math.max(0, calculatedSubtotal - roundedCustomerDiscount);
 			} else {
+				data.appliedReferralCode = null;
 				data.partnerCommission = 0;
 				data.customerDiscount = 0;
 				data.total = calculatedSubtotal;
@@ -1348,12 +1476,6 @@ const recalculateCartHook = (pluginConfig) => async ({ data, req, originalDoc })
 				coupon,
 				cartTotal: calculatedSubtotal
 			});
-			console.log("[RecalculateCart] Coupon Logic", {
-				appliedCoupon,
-				couponId: coupon.id,
-				cartTotal: calculatedSubtotal,
-				discountAmount
-			});
 			data.discountAmount = discountAmount;
 			const currentDiscount = data.customerDiscount || 0;
 			data.total = Math.max(0, calculatedSubtotal - currentDiscount - discountAmount);
@@ -1365,6 +1487,13 @@ const recalculateCartHook = (pluginConfig) => async ({ data, req, originalDoc })
 //#endregion
 //#region src/utilities/sanitizePluginConfig.ts
 const sanitizePluginConfig = ({ pluginConfig }) => {
+	const roleConfig = {
+		roleFieldPaths: Array.isArray(pluginConfig?.roleConfig?.roleFieldPaths) && pluginConfig.roleConfig.roleFieldPaths.length > 0 ? pluginConfig.roleConfig.roleFieldPaths.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean) : ["role", "roles"],
+		adminRoleValues: Array.isArray(pluginConfig?.roleConfig?.adminRoleValues) && pluginConfig.roleConfig.adminRoleValues.length > 0 ? pluginConfig.roleConfig.adminRoleValues.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean) : ["admin"],
+		partnerRoleValues: Array.isArray(pluginConfig?.roleConfig?.partnerRoleValues) && pluginConfig.roleConfig.partnerRoleValues.length > 0 ? pluginConfig.roleConfig.partnerRoleValues.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean) : ["partner"],
+		customRoleResolver: typeof pluginConfig?.roleConfig?.customRoleResolver === "function" ? pluginConfig.roleConfig.customRoleResolver : void 0
+	};
+	const normalizedAllowedTotalCommissionTypes = Array.isArray(pluginConfig?.referralConfig?.allowedTotalCommissionTypes) ? [...new Set(pluginConfig.referralConfig.allowedTotalCommissionTypes.filter((value) => value === "fixed" || value === "percentage"))] : [];
 	return {
 		enabled: !(pluginConfig?.enabled === false || typeof pluginConfig?.enabled === "string" && pluginConfig.enabled === "false"),
 		enableReferrals: !!pluginConfig?.enableReferrals && (typeof pluginConfig?.enableReferrals !== "string" || pluginConfig.enableReferrals !== "false"),
@@ -1386,20 +1515,21 @@ const sanitizePluginConfig = ({ pluginConfig }) => {
 		access: {
 			canUseCoupons: typeof pluginConfig?.access?.canUseCoupons === "function" ? pluginConfig.access.canUseCoupons : () => true,
 			canUseReferrals: typeof pluginConfig?.access?.canUseReferrals === "function" ? pluginConfig.access.canUseReferrals : () => false,
-			isAdmin: typeof pluginConfig?.access?.isAdmin === "function" ? pluginConfig.access.isAdmin : () => false,
-			isPartner: typeof pluginConfig?.access?.isPartner === "function" ? pluginConfig.access.isPartner : ({ req }) => {
-				const user = req?.user;
-				if (!user) return false;
-				if (user.role === "partner") return true;
-				if (Array.isArray(user.roles) && user.roles.includes("partner")) return true;
-				return false;
-			}
+			isAdmin: typeof pluginConfig?.access?.isAdmin === "function" ? pluginConfig.access.isAdmin : ({ req }) => isAdminUser({
+				user: req?.user,
+				roleConfig
+			}),
+			isPartner: typeof pluginConfig?.access?.isPartner === "function" ? pluginConfig.access.isPartner : ({ req }) => isPartnerUser({
+				user: req?.user,
+				roleConfig
+			})
 		},
 		referralConfig: {
 			allowBothSystems: pluginConfig?.referralConfig?.allowBothSystems ?? false,
 			singleCodePerCart: pluginConfig?.referralConfig?.singleCodePerCart ?? true,
 			defaultPartnerSplit: pluginConfig?.referralConfig?.defaultPartnerSplit ?? 70,
-			defaultCustomerSplit: pluginConfig?.referralConfig?.defaultCustomerSplit ?? 30
+			defaultCustomerSplit: pluginConfig?.referralConfig?.defaultCustomerSplit ?? 30,
+			allowedTotalCommissionTypes: normalizedAllowedTotalCommissionTypes.length > 0 ? normalizedAllowedTotalCommissionTypes : ["fixed", "percentage"]
 		},
 		adminGroups: {
 			couponsGroup: pluginConfig?.adminGroups?.couponsGroup ?? "Coupons",
@@ -1417,7 +1547,8 @@ const sanitizePluginConfig = ({ pluginConfig }) => {
 			orderCustomerEmailField: typeof pluginConfig?.orderIntegration?.orderCustomerEmailField === "string" && pluginConfig.orderIntegration.orderCustomerEmailField.trim().length > 0 ? pluginConfig.orderIntegration.orderCustomerEmailField : "customerEmail",
 			orderPaymentStatusField: typeof pluginConfig?.orderIntegration?.orderPaymentStatusField === "string" && pluginConfig.orderIntegration.orderPaymentStatusField.trim().length > 0 ? pluginConfig.orderIntegration.orderPaymentStatusField : "paymentStatus",
 			orderPaidStatusValue: typeof pluginConfig?.orderIntegration?.orderPaidStatusValue === "string" ? pluginConfig.orderIntegration.orderPaidStatusValue : "paid"
-		}
+		},
+		roleConfig
 	};
 };
 
@@ -1809,6 +1940,7 @@ exports.createCouponsCollection = createCouponsCollection;
 exports.createReferralCodesCollection = createReferralCodesCollection;
 exports.createReferralProgramsCollection = createReferralProgramsCollection;
 exports.getCartTotalWithDiscounts = getCartTotalWithDiscounts;
+exports.getProgramMinimumOrderAmount = getProgramMinimumOrderAmount;
 exports.payloadEcommerceCoupon = payloadEcommerceCouponPlugin;
 exports.recordCouponUsageForOrder = recordCouponUsageForOrder;
 exports.useCouponCode = useCouponCode;