@wtree/payload-ecommerce-coupon 3.70.7 → 3.72.0

package/README.md

@@ -14,14 +14,15 @@ 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; per-product/category commission rates
-- ✅ **Referrer/Referee Split** – **Partner (referrer)** receives **commission**; **customer (referee)** receives **discount**; configurable share ratios
+- ✅ **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).
+- ✅ **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
 - ✅ **Partner Dashboard** – Ready-to-use React components for partner stats
@@ -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) {
@@ -297,30 +335,13 @@ Best when you need both traditional coupons AND partner referrals, but want to e
 ### **Setting Up Referral Mode**
 
 1. **Navigate to Admin Panel** → Go to "Referral Programs" (under "Referrals" group)
-2. **Create Referral Program**:
-   - **Name**: "Partner Affiliate Program"
-   - **Description**: "Earn commissions by referring customers"
-   - **Is Active**: Enable/disable program
-   - **Commission Rules**: **Required** – at least one rule per program (product/category-specific or "all products"). Each rule defines total commission and split between partner and customer.
-
-3. **Configure Commission Rules** (required – at least one):
-   ```json
-   {
-     "name": "Electronics Category",
-     "appliesTo": "categories",
-     "categories": ["electronics"],
-     "totalCommission": {
-       "type": "percentage",
-       "value": 15
-     },
-     "split": {
-       "partnerPercentage": 70,
-       "customerPercentage": 30
-     }
-   }
-   ```
-   - **Referrer (partner)** receives the **commission** share (`partnerPercentage`).
-   - **Referee (customer)** receives the **discount** share (`customerPercentage`).
+2. **Create Referral Program** with **Commission Rules** (required – at least one). Each rule has:
+   - **Name**: e.g. "Default" or "Electronics"
+   - **Applies To**: All Products, Specific Categories, or Specific Products
+   - **Referrer Reward** (inside the rule): Commission for the partner. Type: Percentage of Order or Fixed Amount. Value: e.g. 65 = 65% of order value. Optional Max Reward.
+   - **Referee Reward** (inside the rule): Discount for the customer. Type: Percentage Discount or Fixed Amount. Value: e.g. 30 = 30% off. Optional Max Reward.
+
+   There are no outer Referrer Reward / Referee Reward fields – only **Commission Rules**, and each rule contains its own Referrer Reward and Referee Reward.
 
 ### **Commission and Discount (Referrer / Referee)**
 
@@ -345,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
@@ -471,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'
+  }
 }
 ```
 
@@ -634,10 +669,8 @@ This occurs when `singleCodePerCart: true` and a code is already applied.
 - Usage is **not** incremented when a code is applied to the cart. Call **record-order-usage** (or `recordCouponUsageForOrder`) when an order is placed/paid. See [Record usage when order is placed](#4-record-usage-when-order-is-placed).
 
 #### **Commission not calculating correctly**
-- At least **one commission rule is required** per referral program
-- Verify commission rules (product/category/all) are configured
-- Check that products have correct category assignments
-- Ensure cart has valid `subtotal` or `total` field
+- Ensure at least one **Commission Rule** exists and each rule has **Referrer Reward** and **Referee Reward** set
+- Verify cart has valid `subtotal` or `total` and items match rule’s appliesTo (all / categories / products)
 
 ## 📋 Future Features (Roadmap)
 

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,gBAoTF,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,gBA4PF,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;AAyXH,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;AA6XH,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,cAoKzB,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;AAEhG,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,mBAAmB,GAC7B,kBAAkB,IAAI,KAAG,cAqKzB,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;AAE5D,KAAK,IAAI,GAAG;IACV,YAAY,EAAE,4BAA4B,CAAA;CAC3C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAC/B,kBAAkB,IAAI,KAAG,cA2BzB,CAAA;AA0OH,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"}