@wtree/payload-ecommerce-coupon 3.71.1 → 3.72.1

package/README.md

@@ -14,10 +14,11 @@ Production-ready coupon and referral system plugin for **Payload CMS** with seam
 - **Hybrid Mode** (`enableReferrals: true` + `referralConfig.allowBothSystems: true`) – Both systems active
 
 ### **Coupon Mode Features**
-- ✅ **Flexible Discounts** – Percentage or fixed amount discounts
-- ✅ **Usage Controls** – Usage limits; usage is counted when an **order is placed** (not on apply)
+- ✅ **Flexible Discounts** – Percentage or fixed amount discounts (all amounts rounded to 2 decimals)
+- ✅ **Usage Controls** – Global usage limit; usage is counted when an **order is placed** (not on apply)
+- ✅ **Per-customer limit** – Optional limit per customer (requires `customerEmail` when applying)
 - ✅ **Conditions** – Minimum/maximum order values (top-level fields), product restrictions
-- ✅ **Auto-Application** – Seamless cart integration
+- ✅ **Auto-Application** – Seamless cart integration; cart total is reduced when a code is applied
 
 ### **Referral Mode Features**
 - ✅ **Commission Rules** – **Required.** At least one rule per program. Each rule has **Referrer Reward** (partner commission) and **Referee Reward** (customer discount) inside it, plus appliesTo (all products / categories / products).
@@ -32,6 +33,7 @@ Production-ready coupon and referral system plugin for **Payload CMS** with seam
 - ✅ **Frontend Hooks** – `useCouponCode()`, `usePartnerStats()`, `validateCouponCode()` for React/Next.js
 - ✅ **Auto-Integration** – Extends carts/orders automatically
 - ✅ **Usage on Order** – Coupon/referral usage and partner earnings are recorded when an order is placed (not when code is applied)
+- ✅ **Cart total helper** – `getCartTotalWithDiscounts(cart)` for host app cart hooks so totals respect discounts
 - ✅ **Type-Safe** – Full TypeScript support
 - ✅ **Access Control** – Role-based permissions with partner role support
 - ✅ **Custom Admin Groups** – Separate "Coupons" and "Referrals" categories
@@ -100,6 +102,14 @@ export default buildConfig({
         isAdmin: ({ req }) => req.user?.role === 'admin',
         isPartner: ({ req }) => req.user?.role === 'partner',
       },
+
+      // Optional: for per-customer coupon limit (defaults shown)
+      // orderIntegration: {
+      //   ordersSlug: 'orders',
+      //   orderCustomerEmailField: 'customerEmail',
+      //   orderPaymentStatusField: 'paymentStatus',
+      //   orderPaidStatusValue: 'paid',
+      // },
     }),
   ],
 })
@@ -183,6 +193,32 @@ if (doc.paymentStatus === 'paid' && (doc.appliedCoupon || doc.appliedReferralCod
 - **Coupon:** increments the coupon’s `usageCount`.
 - **Referral:** increments the referral code’s `usageCount` and `successfulReferralsCount`, and adds `order.partnerCommission` to the referral code’s `totalEarnings` and `pendingEarnings` (referrer gets commission; referee discount is already on the order).
 
+### 4.5 Coupon usage rules and cart total
+
+**Usage rule**
+- A customer can use a coupon until the coupon’s **global usage limit** or **expiry date** (usage is counted when the order is placed, not when the code is applied).
+- **Optional per-customer limit:** If you set **Per customer limit** on a coupon, the customer must provide their email when applying (e.g. `customerEmail` in the apply request). The coupon is rejected once they have that many **paid** orders with that coupon. You can pass `customerEmail` when validating so the UI can show “limit reached” before apply.
+
+**Monetary values**
+- All discount, commission, and total values are rounded to **2 decimal places**.
+
+**Cart total in your app**
+- The plugin writes the reduced `total` when a code is applied. If your host app recalculates the cart total (e.g. in a `beforeChange` hook when items change), use the formula **total = subtotal − discountAmount − customerDiscount** so the discount is not overwritten. Use the provided helper in your Carts collection:
+
+```typescript
+import { getCartTotalWithDiscounts } from '@wtree/payload-ecommerce-coupon'
+
+// In your Carts collection beforeChange hook, after setting items/subtotal:
+data.total = getCartTotalWithDiscounts(data)
+```
+
+- **Optional config** for per-customer limit: `orderIntegration` with `ordersSlug`, `orderCustomerEmailField`, `orderPaymentStatusField`, `orderPaidStatusValue` (defaults: `'orders'`, `'customerEmail'`, `'paymentStatus'`, `'paid'`).
+
+**Server utilities (for host app)**
+
+- `getCartTotalWithDiscounts(cart)` – Returns `roundTo2(subtotal - discountAmount - customerDiscount)`. Use in your Carts `beforeChange` (or wherever you compute total) so the displayed total always reflects coupon/referral discounts.
+- `recordCouponUsageForOrder(payload, order, pluginConfig)` – Call when an order is paid to increment coupon/referral usage and credit partner earnings (see step 4 above).
+
 ### 5. Frontend Integration
 
 #### Apply Coupon/Referral Code
@@ -198,6 +234,8 @@ function CheckoutComponent() {
     const result = await useCouponCode({
       code,
       cartID: cartId,
+      // When a coupon has per-customer limit, pass customerEmail so the limit can be enforced
+      // customerEmail: customerEmailFromAuthOrForm,
     })
 
     if (result.success) {
@@ -328,21 +366,27 @@ Best when you need both traditional coupons AND partner referrals, but want to e
 ### **Coupon/Referral Endpoints**
 
 #### POST /api/coupons/validate
-Validate a code without applying it.
+Validate a code without applying it. Optionally pass `customerEmail` to check per-customer limit for coupons that have one.
 
 ```bash
 curl -X POST http://localhost:3000/api/coupons/validate \
   -H "Content-Type: application/json" \
   -d '{"code": "WELCOME10", "cartValue": 5000}'
+
+# With per-customer limit check:
+# -d '{"code": "WELCOME10", "cartValue": 5000, "customerEmail": "user@example.com"}'
 ```
 
 #### POST /api/coupons/apply
-Apply a code to a cart. **Does not** increment usage; usage is recorded when you call the record-order-usage endpoint for a placed order.
+Apply a code to a cart. **Does not** increment usage; usage is recorded when you call the record-order-usage endpoint for a placed order. For coupons with **per-customer limit**, include `customerEmail` so the limit can be enforced.
 
 ```bash
 curl -X POST http://localhost:3000/api/coupons/apply \
   -H "Content-Type: application/json" \
   -d '{"code": "WELCOME10", "cartID": "cart-123"}'
+
+# With per-customer limit (required when coupon has per-customer limit):
+# -d '{"code": "WELCOME10", "cartID": "cart-123", "customerEmail": "user@example.com"}'
 ```
 
 #### POST /api/coupons/record-order-usage
@@ -454,6 +498,14 @@ export type CouponPluginOptions = {
     showRecentReferrals?: boolean      // Show recent referrals (default: true)
     showCommissionBreakdown?: boolean  // Show breakdown (default: true)
   }
+
+  /** Optional: for per-customer coupon limit (query paid orders by customer) */
+  orderIntegration?: {
+    ordersSlug?: string                // Default: 'orders'
+    orderCustomerEmailField?: string   // Default: 'customerEmail'
+    orderPaymentStatusField?: string  // Default: 'paymentStatus'
+    orderPaidStatusValue?: string     // Default: 'paid'
+  }
 }
 ```
 

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;AAE5D,eAAO,MAAM,gCAAgC,GAC3C,cAAc,4BAA4B,KACzC,gBA4PF,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;AAE5D,eAAO,MAAM,gCAAgC,GAC3C,cAAc,4BAA4B,KACzC,gBAyWF,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;AAEvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAE5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC5B,kBAAkB,IAAI,KAAG,cAsFzB,CAAA;AAsVH,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;AAEvD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAA;AAG5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC5B,kBAAkB,IAAI,KAAG,cAsFzB,CAAA;AAsZH,eAAO,MAAM,mBAAmB,GAAI,kBAAkB,IAAI,KAAG,QAI3D,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;AAE5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAC/B,kBAAkB,IAAI,KAAG,cA2BzB,CAAA;AA8OH,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;AAG5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAC/B,kBAAkB,IAAI,KAAG,cAiCzB,CAAA;AAkRH,eAAO,MAAM,sBAAsB,GAAI,kBAAkB,IAAI,KAAG,QAI9D,CAAA"}

package/dist/index.d.ts

@@ -4,5 +4,8 @@ import { createReferralProgramsCollection } from './collections/createReferralPr
 import { payloadEcommerceCouponPlugin } from './plugin';
 export { useCouponCode, usePartnerStats, validateCouponCode } from './client/hooks';
 export { createCouponsCollection, createReferralCodesCollection, createReferralProgramsCollection, payloadEcommerceCouponPlugin as payloadEcommerceCoupon, };
-export type { AdminGroupConfig, ApplyCouponHook, ApplyCouponResponse, CouponPluginAccess, CouponPluginCollections, CouponPluginOptions, PartnerDashboardConfig, PartnerDashboardData, PartnerStats, ReferralProgramConfig, } from './types';
+export { getCartTotalWithDiscounts } from './utilities/getCartTotalWithDiscounts';
+export { recordCouponUsageForOrder } from './utilities/recordCouponUsageForOrder';
+export type { AdminGroupConfig, ApplyCouponHook, ApplyCouponResponse, CouponPluginAccess, CouponPluginCollections, CouponPluginOptions, OrderIntegrationConfig, PartnerDashboardConfig, PartnerDashboardData, PartnerStats, ReferralProgramConfig, } 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,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,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,GACtB,MAAM,SAAS,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,uBAAuB,EACvB,6BAA6B,EAC7B,gCAAgC,EAChC,4BAA4B,IAAI,sBAAsB,GACvD,CAAA;AACD,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AAEjF,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"}

package/dist/index.js

@@ -283,10 +283,17 @@ const createReferralProgramsCollection = (pluginConfig) => {
 			if (!data.commissionRules || !Array.isArray(data.commissionRules) || data.commissionRules.length === 0) throw new Error("At least one commission rule is required");
 			data.commissionRules.forEach((rule, index) => {
 				const r = rule;
-				if (!r.referrerReward || r.referrerReward.value == null) throw new Error(`Commission rule ${index + 1}: Referrer Reward is required`);
-				if (!r.refereeReward || r.refereeReward.value == null) throw new Error(`Commission rule ${index + 1}: Referee Reward is required`);
-				if (r.referrerReward?.type === "percentage" && r.refereeReward?.type === "percentage") {
-					if ((r.referrerReward.value || 0) + (r.refereeReward.value || 0) > 100) throw new Error(`Commission rule ${index + 1}: Referrer + Referee percentage cannot exceed 100%`);
+				if (r.basis === "shared") {
+					if (!r.totalCommission || r.totalCommission.value == null) throw new Error(`Commission rule ${index + 1}: Total Commission is required for Shared Basis`);
+					if (r.referrerSplit == null) throw new Error(`Commission rule ${index + 1}: Referrer Split is required for Shared Basis`);
+					if (r.refereeSplit == null) throw new Error(`Commission rule ${index + 1}: Referee Split is required for Shared Basis`);
+					if ((r.referrerSplit || 0) + (r.refereeSplit || 0) > 100) throw new Error(`Commission rule ${index + 1}: Referrer + Referee split cannot exceed 100%`);
+				} else {
+					if (!r.referrerReward || r.referrerReward.value == null) throw new Error(`Commission rule ${index + 1}: Referrer Reward is required`);
+					if (!r.refereeReward || r.refereeReward.value == null) throw new Error(`Commission rule ${index + 1}: Referee Reward is required`);
+					if (r.referrerReward?.type === "percentage" && r.refereeReward?.type === "percentage") {
+						if ((r.referrerReward.value || 0) + (r.refereeReward.value || 0) > 100) throw new Error(`Commission rule ${index + 1}: Referrer + Referee percentage cannot exceed 100%`);
+					}
 				}
 			});
 			return data;
@@ -362,11 +369,81 @@ const createReferralProgramsCollection = (pluginConfig) => {
 							description: "Products this rule applies to"
 						}
 					},
+					{
+						name: "basis",
+						type: "select",
+						required: true,
+						defaultValue: "direct",
+						options: [{
+							label: "Direct Values",
+							value: "direct"
+						}, {
+							label: "Shared Commission",
+							value: "shared"
+						}],
+						admin: { description: "Direct: Set specific reward/discount for each. Shared: Set a total commission and split it." }
+					},
+					{
+						name: "totalCommission",
+						type: "group",
+						admin: {
+							condition: (_, siblingData) => siblingData?.basis === "shared",
+							description: "Total commission available to be split between partner and customer"
+						},
+						fields: [
+							{
+								name: "type",
+								type: "select",
+								required: true,
+								options: [{
+									label: "Fixed Amount",
+									value: "fixed"
+								}, {
+									label: "Percentage of Order",
+									value: "percentage"
+								}],
+								defaultValue: "percentage"
+							},
+							{
+								name: "value",
+								type: "number",
+								required: true,
+								admin: { description: `Total commission value` }
+							},
+							{
+								name: "maxAmount",
+								type: "number",
+								admin: { description: `Max commission cap per item in ${defaultCurrency}` }
+							}
+						]
+					},
+					{
+						name: "referrerSplit",
+						type: "number",
+						min: 0,
+						max: 100,
+						admin: {
+							condition: (_, siblingData) => siblingData?.basis === "shared",
+							description: "Percentage of total commission given to the Partner (0-100)"
+						}
+					},
+					{
+						name: "refereeSplit",
+						type: "number",
+						min: 0,
+						max: 100,
+						admin: {
+							condition: (_, siblingData) => siblingData?.basis === "shared",
+							description: "Percentage of total commission given as Discount to Customer (0-100)"
+						}
+					},
 					{
 						name: "referrerReward",
 						type: "group",
-						required: true,
-						admin: { description: "Reward given to the partner who refers others" },
+						admin: {
+							condition: (_, siblingData) => siblingData?.basis !== "shared",
+							description: "Reward given to the partner who refers others"
+						},
 						fields: [
 							{
 								name: "type",
@@ -398,8 +475,10 @@ const createReferralProgramsCollection = (pluginConfig) => {
 					{
 						name: "refereeReward",
 						type: "group",
-						required: true,
-						admin: { description: "Discount given to the customer who was referred" },
+						admin: {
+							condition: (_, siblingData) => siblingData?.basis !== "shared",
+							description: "Discount given to the customer who was referred"
+						},
 						fields: [
 							{
 								name: "type",
@@ -478,6 +557,15 @@ const createReferralProgramsCollection = (pluginConfig) => {
 	};
 };
 
+//#endregion
+//#region src/utilities/roundTo2.ts
+/**
+* Rounds a number to 2 decimal places (standard for monetary values).
+*/
+function roundTo2(value) {
+	return Math.round(value * 100) / 100;
+}
+
 //#endregion
 //#region src/endpoints/applyCoupon.ts
 const applyCouponHandler = ({ pluginConfig }) => async (req) => {
@@ -538,7 +626,7 @@ const applyCouponHandler = ({ pluginConfig }) => async (req) => {
 		}, { status: 500 });
 	}
 };
-async function handleCouponCode({ payload, code, cartID, cart, customerEmail: _customerEmail, pluginConfig }) {
+async function handleCouponCode({ payload, code, cartID, cart, customerEmail, pluginConfig }) {
 	const couponQuery = await payload.find({
 		collection: pluginConfig.collections.couponsSlug,
 		where: { code: { equals: code } },
@@ -564,6 +652,26 @@ async function handleCouponCode({ payload, code, cartID, cart, customerEmail: _c
 		success: false,
 		error: "Coupon usage limit exceeded"
 	}, { status: 400 });
+	if (coupon.perCustomerLimit != null && coupon.perCustomerLimit > 0) {
+		const email = typeof customerEmail === "string" ? customerEmail.trim() : "";
+		if (!email) return Response.json({
+			success: false,
+			error: "Customer email is required for this coupon."
+		}, { status: 400 });
+		const { ordersSlug, orderCustomerEmailField, orderPaymentStatusField, orderPaidStatusValue } = pluginConfig.orderIntegration;
+		if ((await payload.find({
+			collection: ordersSlug,
+			where: { and: [
+				{ appliedCoupon: { equals: coupon.id } },
+				{ [orderCustomerEmailField]: { equals: email } },
+				{ [orderPaymentStatusField]: { equals: orderPaidStatusValue } }
+			] },
+			limit: 0
+		})).totalDocs >= coupon.perCustomerLimit) return Response.json({
+			success: false,
+			error: "You have reached the maximum uses for this coupon."
+		}, { status: 400 });
+	}
 	if (cart.appliedCoupon === coupon.id) return Response.json({
 		success: false,
 		error: "Coupon already applied to this cart"
@@ -579,18 +687,21 @@ async function handleCouponCode({ payload, code, cartID, cart, customerEmail: _c
 	}, { status: 400 });
 	let discount = 0;
 	if (coupon.type === "percentage") {
-		discount = Math.round(cartTotal * coupon.value / 100);
-		if (coupon.maxDiscountAmount && discount > coupon.maxDiscountAmount) discount = coupon.maxDiscountAmount;
+		discount = roundTo2(cartTotal * coupon.value / 100);
+		if (coupon.maxDiscountAmount != null && discount > coupon.maxDiscountAmount) discount = roundTo2(coupon.maxDiscountAmount);
 	} else if (coupon.type === "fixed") {
-		discount = coupon.value;
-		if (discount > cartTotal) discount = cartTotal;
+		discount = roundTo2(coupon.value);
+		if (discount > cartTotal) discount = roundTo2(cartTotal);
 	}
+	const discountAmount = roundTo2(discount);
+	const total = roundTo2(Math.max(0, cartTotal - discountAmount));
 	await payload.update({
 		collection: "carts",
 		id: cartID,
 		data: {
 			appliedCoupon: coupon.id,
-			discountAmount: discount
+			discountAmount,
+			total
 		}
 	});
 	return Response.json({
@@ -601,7 +712,7 @@ async function handleCouponCode({ payload, code, cartID, cart, customerEmail: _c
 			type: coupon.type,
 			value: coupon.value
 		},
-		discount,
+		discount: discountAmount,
 		currency: pluginConfig.defaultCurrency
 	});
 }
@@ -662,21 +773,25 @@ async function handleReferralCode({ payload, code, cartID, cart, customerEmail:
 		pluginConfig,
 		payload
 	});
+	const roundedPartnerCommission = roundTo2(partnerCommission);
+	const roundedCustomerDiscount = roundTo2(customerDiscount);
+	const total = roundTo2(Math.max(0, cartTotal - roundedCustomerDiscount));
 	await payload.update({
 		collection: "carts",
 		id: cartID,
 		data: {
 			appliedReferralCode: referralCode.id,
-			partnerCommission: Math.round(partnerCommission * 100) / 100,
-			customerDiscount: Math.round(customerDiscount * 100) / 100
+			partnerCommission: roundedPartnerCommission,
+			customerDiscount: roundedCustomerDiscount,
+			total
 		}
 	});
 	return Response.json({
 		success: true,
 		message: "Referral code applied successfully",
 		referralCode: { code: referralCode.code },
-		partnerCommission: Math.round(partnerCommission * 100) / 100,
-		customerDiscount: Math.round(customerDiscount * 100) / 100,
+		partnerCommission: roundedPartnerCommission,
+		customerDiscount: roundedCustomerDiscount,
 		currency: pluginConfig.defaultCurrency
 	});
 }
@@ -692,19 +807,30 @@ function calculateCommissionAndDiscount({ cart, program, pluginConfig: _pluginCo
 	let totalCustomerDiscount = 0;
 	for (const item of cartItems) {
 		const rule = findApplicableCommissionRule(rules, item);
-		if (!rule?.referrerReward || !rule?.refereeReward) continue;
+		if (!rule) continue;
 		const itemPrice = item.price ?? item.unitPrice ?? 0;
 		const quantity = item.quantity ?? 1;
 		const itemTotal = itemPrice * quantity;
 		let itemPartner = 0;
-		if (rule.referrerReward.type === "percentage") itemPartner = itemTotal * rule.referrerReward.value / 100;
-		else itemPartner = rule.referrerReward.value * quantity;
-		if (rule.referrerReward.maxReward != null && itemPartner > rule.referrerReward.maxReward) itemPartner = rule.referrerReward.maxReward;
-		totalPartnerCommission += itemPartner;
 		let itemCustomer = 0;
-		if (rule.refereeReward.type === "percentage") itemCustomer = itemTotal * rule.refereeReward.value / 100;
-		else itemCustomer = rule.refereeReward.value * quantity;
-		if (rule.refereeReward.maxReward != null && itemCustomer > rule.refereeReward.maxReward) itemCustomer = rule.refereeReward.maxReward;
+		if (rule.basis === "shared") {
+			if (!rule.totalCommission || rule.referrerSplit == null || rule.refereeSplit == null) continue;
+			let totalPot = 0;
+			if (rule.totalCommission.type === "percentage") totalPot = itemTotal * rule.totalCommission.value / 100;
+			else totalPot = rule.totalCommission.value * quantity;
+			if (rule.totalCommission.maxAmount != null && totalPot > rule.totalCommission.maxAmount) totalPot = rule.totalCommission.maxAmount;
+			itemPartner = totalPot * rule.referrerSplit / 100;
+			itemCustomer = totalPot * rule.refereeSplit / 100;
+		} else {
+			if (!rule.referrerReward || !rule.refereeReward) continue;
+			if (rule.referrerReward.type === "percentage") itemPartner = itemTotal * rule.referrerReward.value / 100;
+			else itemPartner = rule.referrerReward.value * quantity;
+			if (rule.referrerReward.maxReward != null && itemPartner > rule.referrerReward.maxReward) itemPartner = rule.referrerReward.maxReward;
+			if (rule.refereeReward.type === "percentage") itemCustomer = itemTotal * rule.refereeReward.value / 100;
+			else itemCustomer = rule.refereeReward.value * quantity;
+			if (rule.refereeReward.maxReward != null && itemCustomer > rule.refereeReward.maxReward) itemCustomer = rule.refereeReward.maxReward;
+		}
+		totalPartnerCommission += itemPartner;
 		totalCustomerDiscount += itemCustomer;
 	}
 	if (totalCustomerDiscount > cartTotal) totalCustomerDiscount = cartTotal;
@@ -858,7 +984,7 @@ const partnerStatsEndpoint = ({ pluginConfig }) => ({
 //#region src/endpoints/validateCoupon.ts
 const validateCouponHandler = ({ pluginConfig }) => async (req) => {
 	const { payload } = req;
-	const { code, cartValue, cartID } = req.data || {};
+	const { code, cartValue, cartID, customerEmail } = req.data || {};
 	if (!code) return Response.json({
 		success: false,
 		error: "Code is required"
@@ -874,6 +1000,7 @@ const validateCouponHandler = ({ pluginConfig }) => async (req) => {
 			payload,
 			code,
 			cartValue,
+			customerEmail,
 			pluginConfig
 		});
 	} catch (error) {
@@ -884,7 +1011,7 @@ const validateCouponHandler = ({ pluginConfig }) => async (req) => {
 		}, { status: 500 });
 	}
 };
-async function validateCouponCode$1({ payload, code, cartValue, pluginConfig }) {
+async function validateCouponCode$1({ payload, code, cartValue, customerEmail, pluginConfig }) {
 	const coupon = await payload.find({
 		collection: pluginConfig.collections.couponsSlug,
 		where: { code: { equals: code } },
@@ -910,23 +1037,43 @@ async function validateCouponCode$1({ payload, code, cartValue, pluginConfig })
 		success: false,
 		error: "Coupon usage limit exceeded"
 	}, { status: 400 });
-	if (cartValue !== void 0 && couponData.conditions) {
-		const { minOrderValue, maxOrderValue } = couponData.conditions;
+	if (couponData.perCustomerLimit != null && couponData.perCustomerLimit > 0 && typeof customerEmail === "string" && customerEmail.trim().length > 0) {
+		const email = customerEmail.trim();
+		const { ordersSlug, orderCustomerEmailField, orderPaymentStatusField, orderPaidStatusValue } = pluginConfig.orderIntegration;
+		if ((await payload.find({
+			collection: ordersSlug,
+			where: { and: [
+				{ appliedCoupon: { equals: couponData.id } },
+				{ [orderCustomerEmailField]: { equals: email } },
+				{ [orderPaymentStatusField]: { equals: orderPaidStatusValue } }
+			] },
+			limit: 0
+		})).totalDocs >= couponData.perCustomerLimit) return Response.json({
+			success: false,
+			error: "You have reached the maximum uses for this coupon."
+		}, { status: 400 });
+	}
+	if (cartValue !== void 0) {
+		const minOrderValue = couponData.minOrderValue;
+		const maxOrderValue = couponData.maxOrderValue;
 		if (minOrderValue && cartValue < minOrderValue) return Response.json({
 			success: false,
-			error: `Minimum order value of ${minOrderValue} required`
+			error: `Minimum order value of ${minOrderValue} ${pluginConfig.defaultCurrency} required`
 		}, { status: 400 });
 		if (maxOrderValue && cartValue > maxOrderValue) return Response.json({
 			success: false,
-			error: `Maximum order value of ${maxOrderValue} exceeded`
+			error: `Maximum order value of ${maxOrderValue} ${pluginConfig.defaultCurrency} exceeded`
 		}, { status: 400 });
 	}
 	let discount = 0;
 	if (cartValue !== void 0) {
 		if (couponData.type === "percentage") {
-			discount = Math.round(cartValue * couponData.value / 100);
-			if (couponData.maxDiscountAmount && discount > couponData.maxDiscountAmount) discount = couponData.maxDiscountAmount;
-		} else if (couponData.type === "fixed") discount = couponData.value;
+			discount = roundTo2(cartValue * couponData.value / 100);
+			if (couponData.maxDiscountAmount != null && discount > couponData.maxDiscountAmount) discount = roundTo2(couponData.maxDiscountAmount);
+		} else if (couponData.type === "fixed") {
+			discount = roundTo2(couponData.value);
+			if (discount > cartValue) discount = roundTo2(cartValue);
+		}
 	}
 	return Response.json({
 		success: true,
@@ -1000,14 +1147,16 @@ async function validateReferralCode({ payload, code, cartID, pluginConfig }) {
 		}
 		if (totalCustomerDiscount > cartTotal) totalCustomerDiscount = cartTotal;
 	}
+	const roundedPartnerCommission = roundTo2(totalPartnerCommission);
+	const roundedCustomerDiscount = roundTo2(totalCustomerDiscount);
 	return Response.json({
 		success: true,
 		referralCode: {
 			code: referralData.code,
-			description: `Get ${totalCustomerDiscount.toFixed(2)} discount with this referral code`
+			description: `Get ${roundedCustomerDiscount.toFixed(2)} discount with this referral code`
 		},
-		partnerCommission: totalPartnerCommission,
-		customerDiscount: totalCustomerDiscount,
+		partnerCommission: roundedPartnerCommission,
+		customerDiscount: roundedCustomerDiscount,
 		currency: pluginConfig.defaultCurrency
 	});
 }
@@ -1077,6 +1226,12 @@ const sanitizePluginConfig = ({ pluginConfig }) => {
 			showReferralPerformance: pluginConfig?.partnerDashboard?.showReferralPerformance ?? true,
 			showRecentReferrals: pluginConfig?.partnerDashboard?.showRecentReferrals ?? true,
 			showCommissionBreakdown: pluginConfig?.partnerDashboard?.showCommissionBreakdown ?? true
+		},
+		orderIntegration: {
+			ordersSlug: typeof pluginConfig?.orderIntegration?.ordersSlug === "string" && pluginConfig.orderIntegration.ordersSlug.trim().length > 0 ? pluginConfig.orderIntegration.ordersSlug : "orders",
+			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"
 		}
 	};
 };
@@ -1379,11 +1534,88 @@ async function usePartnerStats(apiEndpoint = "/api/referrals/partner-stats") {
 	}
 }
 
+//#endregion
+//#region src/utilities/getCartTotalWithDiscounts.ts
+/**
+* Computes the cart total after applying plugin discounts.
+* Use this in your host app's cart beforeChange (or wherever you compute total)
+* so the amount always reflects coupon/referral discounts and is not overwritten incorrectly.
+*
+* Formula: subtotal - discountAmount - customerDiscount (each defaulting to 0).
+*/
+function getCartTotalWithDiscounts(cart) {
+	const subtotal = cart.subtotal ?? cart.total ?? 0;
+	const discountAmount = cart.discountAmount ?? 0;
+	const customerDiscount = cart.customerDiscount ?? 0;
+	return roundTo2(Math.max(0, subtotal - discountAmount - customerDiscount));
+}
+
+//#endregion
+//#region src/utilities/recordCouponUsageForOrder.ts
+/**
+* Record coupon and referral usage when an order is placed successfully.
+* Call this once when the order is created/paid (e.g. from Orders collection afterChange hook).
+*
+* - Coupon: increments the coupon's usageCount.
+* - Referral: increments the referral code's usageCount and successfulReferralsCount,
+*   and adds order.partnerCommission to totalEarnings and pendingEarnings (referrer gets commission;
+*   referee discount is already on the order).
+*/
+async function recordCouponUsageForOrder(payload, order, pluginConfig) {
+	const result = {
+		recordedCoupon: false,
+		recordedReferral: false
+	};
+	const couponId = order.appliedCoupon == null ? null : typeof order.appliedCoupon === "string" ? order.appliedCoupon : order.appliedCoupon?.id;
+	const referralCodeId = order.appliedReferralCode == null ? null : typeof order.appliedReferralCode === "string" ? order.appliedReferralCode : order.appliedReferralCode?.id;
+	if (couponId) {
+		const coupon = await payload.findByID({
+			collection: pluginConfig.collections.couponsSlug,
+			id: couponId
+		});
+		if (coupon) {
+			await payload.update({
+				collection: pluginConfig.collections.couponsSlug,
+				id: couponId,
+				data: { usageCount: (coupon.usageCount ?? 0) + 1 }
+			});
+			result.recordedCoupon = true;
+		}
+	}
+	if (referralCodeId) {
+		const referralCode = await payload.findByID({
+			collection: pluginConfig.collections.referralCodesSlug,
+			id: referralCodeId
+		});
+		if (referralCode) {
+			const commission = Number(order.partnerCommission) || 0;
+			const currentTotal = Number(referralCode.totalEarnings) || 0;
+			const currentPending = Number(referralCode.pendingEarnings) || 0;
+			const currentUsageCount = Number(referralCode.usageCount) || 0;
+			const currentSuccessful = Number(referralCode.successfulReferralsCount) || 0;
+			await payload.update({
+				collection: pluginConfig.collections.referralCodesSlug,
+				id: referralCodeId,
+				data: {
+					usageCount: currentUsageCount + 1,
+					successfulReferralsCount: currentSuccessful + 1,
+					totalEarnings: currentTotal + commission,
+					pendingEarnings: currentPending + commission
+				}
+			});
+			result.recordedReferral = true;
+		}
+	}
+	return result;
+}
+
 //#endregion
 exports.createCouponsCollection = createCouponsCollection;
 exports.createReferralCodesCollection = createReferralCodesCollection;
 exports.createReferralProgramsCollection = createReferralProgramsCollection;
+exports.getCartTotalWithDiscounts = getCartTotalWithDiscounts;
 exports.payloadEcommerceCoupon = payloadEcommerceCouponPlugin;
+exports.recordCouponUsageForOrder = recordCouponUsageForOrder;
 exports.useCouponCode = useCouponCode;
 exports.usePartnerStats = usePartnerStats;
 exports.validateCouponCode = validateCouponCode;