ifixkart-admin/docs/billing/store-credits-and-cashback.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- Backend: FastAPI app with all models, services, schemas, routes
- Admin Panel: Next.js dashboard with all modules
  (CRM, POS, repairs, warranties, billing, notifications, etc.)
- Ecommerce: storefront (submodule) + product catalog
- AI Agents: .agents/ skill library for Antigravity IDE
- Docs: architecture, billing, notification gateway markdown
- Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
2026-10-13 12:59:47 +05:30

118 lines
6.5 KiB
Markdown

# Store Credits & Cashback Rewards Engine
## 1. Overview
The Store Credit & Cashback Engine automates reward generation for customer purchases across both E-Commerce Sales Orders and Repair Service Jobs.
To protect business margins against returns and chargebacks, credits are not awarded immediately. Instead, they are generated in a **PENDING** state with a dynamic maturity date governed by the configurable **Return Window**.
---
## 2. Configuration & Admin Settings
The engine settings are stored dynamically in the `settings` table (`group = "credits"`) and editable through the Admin Console under **Settings > Credits & Return Windows**:
| Key | Default | Description |
| :--- | :--- | :--- |
| `credits_enabled` | `true` | Master switch for store credit generation |
| `credits_sales_percentage` | `5.0` | Percentage credited on final e-commerce order amount (e.g. 5.0 = 5%) |
| `credits_sales_return_window_days` | `7` | Duration in days after order delivery before credit matures |
| `credits_service_percentage` | `5.0` | Percentage credited on captured repair service amount |
| `credits_service_claim_window_days` | `3` | Duration in days after repair completion before credit matures |
| `credits_minimum_order_value` | `0.0` | Minimum invoice value eligible for credit |
| `credits_expiry_days` | `365` | Expiry period for spendable credits in days |
---
## 3. Data Models
### `CustomerWallet` (`customer_wallets`)
* `wallet_id`: Unique identifier (ULID)
* `customer_id`: FK to `ecom_customers.customer_id`
* `active_balance`: Spendable, matured wallet balance
* `pending_balance`: Credits awaiting return window expiration
* `lifetime_earned`: Total historical credits earned
* `lifetime_redeemed`: Total credits spent on checkout
* `is_locked`: Fraud prevention lock
### `WalletTransaction` (`wallet_transactions`)
* `transaction_id`: Unique identifier (ULID)
* `wallet_id`: FK to `customer_wallets.wallet_id`
* `transaction_type`: `EARN`, `REDEEM`, `VOID_RETURN`, `ADJUSTMENT`
* `reference_type`: `ORDER`, `SERVICE_JOB`, `MANUAL_ADMIN`, `PURCHASE_REDEMPTION`
* `reference_id`: Originating Order ID or Service Job ID
* `reference_no`: User-friendly Order No or Job No
* `base_amount`: Invoice base amount
* `percentage_applied`: Percentage calculated (e.g. 5.0%)
* `credit_amount`: Reward credit amount
* `status`: `PENDING`, `MATURED`, `VOIDED`, `EXPIRED`
* `matures_at`: Timestamp when the return window expires (`delivered_at + window_days`)
* `matured_at`: Actual maturity timestamp
---
## 4. Lifecycle & Workflows
1. **Order Delivery Hook**:
* Transitioning an order to `DELIVERED` triggers `CreditService.create_pending_credit_for_order(db, order_id)`.
* Pending balance increases on customer wallet.
2. **Service Completion Hook**:
* Transitioning a service job to `DELIVERED` or `COMPLETED` triggers `CreditService.create_pending_credit_for_service(db, job_id)`.
* Pending balance increases on customer wallet.
3. **Cancellation & Return Voiding**:
* If an order is marked `RETURNED` or `CANCELLED`, `CreditService.void_pending_credit(db, "ORDER", order_id)` immediately cancels the pending transaction and reduces `pending_balance`.
4. **Maturity Sweep Worker**:
* Endpoint: `POST /api/v1/cron/process-credit-maturity`
* Scans all `PENDING` transactions where `matures_at <= NOW`.
* Verifies reference order/service was not returned or refunded.
* Promotes transaction to `MATURED`, increments `active_balance`, and decrements `pending_balance`.
---
## 5. API Endpoints
* `GET /api/v1/credits/settings`: Retrieve active credit percentages and return window durations.
* `PUT /api/v1/credits/settings`: Update credit percentages and return window durations (Admin only).
* `GET /api/v1/credits/wallets/{customer_id}`: Admin view of customer wallet and transaction ledger.
* `POST /api/v1/credits/wallets/{customer_id}/adjust`: Admin manual credit/debit adjustment with audit reason.
* `GET /api/v1/credits/my-wallet`: Storefront customer wallet summary.
* `POST /api/v1/cron/process-credit-maturity`: Scheduled maturity sweep worker.
---
## 6. Checkout Redemption & Cancellation Restitution
### Redemption Flow
1. During checkout (`POST /api/v1/checkout/create`), the client can pass `use_wallet_credits: true`.
2. The server acquires a row lock (`with_for_update()`) on `CustomerWallet` to prevent race conditions or double-spending.
3. The spendable amount is calculated as `min(wallet.active_balance, eligible_total)` where `eligible_total = subtotal + shipping_fee`.
4. The order's `discount_amount` is updated with `credits_applied`, and `final_amount` is reduced accordingly.
5. If `final_amount == 0`, payment gateway initiation is bypassed (`zero_amount: true`), and the order is marked confirmed immediately.
6. A `REDEEM` transaction entry is written to `wallet_transactions` with status `MATURED`, and `wallet.active_balance` is atomically debited while `wallet.lifetime_redeemed` is incremented.
### Cancellation & Return Restitution
* When an admin marks an order `CANCELLED` or `RETURNED` via `AdminOrderRouter`, two actions occur:
1. `CreditService.void_pending_credit()`: Voids any pending future cashback earned on the order.
2. `CreditService.refund_redeemed_credits()`: Automatically refunds any store credits previously spent/redeemed on that order back to the customer's `active_balance`, logging an `ADJUSTMENT` refund entry in the audit ledger.
---
## 7. Storefront UI Integrations
1. **Customer Account Portal (`/account?tab=wallet`)**:
* **Dashboard Widget**: High-level quick card showing current spendable credit balance.
* **My Wallet & Credits Tab**:
* Three primary metric cards: Spendable Balance, Pending Balance, Lifetime Earned.
* "How Store Credits Work" visual educational guide explaining pending duration, return window security, and checkout usage.
* Itemized transaction ledger table listing Transaction ID, Date, Reference (Order/Service ID), Amount, and Status pills (`✓ Active`, `⏳ Pending`, `✕ Voided`).
2. **Checkout Order Summary (`/checkout`)**:
* Interactive "Redeem Store Credits" card showing spendable credits available.
* Toggle to apply credits, dynamically updating order breakdown rows:
* Subtotal, Shipping, **Store Credits Applied (-₹X.XX)**, Final Payable Total.
* Live Estimated Cashback badge calculating rewards to be received after delivery return window.
3. **Product Details Page (`ProductInteractiveGrid.tsx`)**:
* Dynamic cashback badge under the product price:
* *"🎁 Earn 5% Store Credit (≈ ₹XX) after 7-day return window"*.