From d43f29c1531d62f4a43f645ff0d1bf2f045c8f1b Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Tue, 18 Aug 2026 14:06:24 +0300
Subject: [PATCH 1/8] Add Magento registry, boot-gated Vue adapters, and desk
 JS yield on develop.

Keep origin/develop baseline offers; GWP/auth Python stay in posnext_promotions. Free-bundle SI merge is no longer in the POS Next invoice class.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 POS/src/App.vue                               |   2 +
 .../components/common/AuthorizationDialog.vue | 185 ++++++++++
 POS/src/components/sale/CouponDialog.vue      |   5 +-
 POS/src/components/sale/CouponManagement.vue  |  13 +-
 .../components/sale/CreateCustomerDialog.vue  | 233 ++++++++++---
 POS/src/components/sale/EditItemDialog.vue    | 209 +++++++++++-
 POS/src/components/sale/InvoiceCart.vue       | 319 ++++++++++++++----
 POS/src/components/sale/PaymentDialog.vue     |  56 +++
 .../components/sale/PromotionManagement.vue   |  17 +-
 .../components/sale/ReturnInvoiceDialog.vue   |  44 ++-
 POS/src/composables/useAuthorization.js       | 111 ++++++
 POS/src/composables/useInvoice.js             |   3 +-
 POS/src/stores/__tests__/posOffers.spec.js    |  70 ++++
 POS/src/stores/bootstrap.js                   |  16 +
 POS/src/stores/posOffers.js                   |   5 +-
 POS/src/stores/posSettings.js                 |   8 +
 POS/src/utils/offerSchedule.js                | 104 ++++++
 POS/src/utils/promoApi.js                     | 122 +++++++
 pos_next/api/bootstrap.py                     |   6 +
 pos_next/api/constants.py                     |  12 +
 pos_next/api/customers.py                     |  35 +-
 pos_next/api/pos_profile.py                   |   4 +
 pos_next/api/sales_invoice_hooks.py           |  34 +-
 pos_next/api/wallet.py                        |  84 ++++-
 pos_next/hooks.py                             |   9 +
 pos_next/integrations/__init__.py             |   1 +
 pos_next/integrations/registry.py             |  67 ++++
 pos_next/overrides/sales_invoice.py           | 272 +++++++--------
 .../doctype/pos_settings/pos_settings.py      |   4 +
 pos_next/public/js/pricing_rule.js            |  58 ++--
 pos_next/public/js/promotional_scheme.js      |  73 ++--
 pos_next/test_no_promotions_import.py         |  60 ++++
 pos_next/test_split_smoke.py                  |  85 +++++
 scripts/run_split_smoke_tests.py              |  90 +++++
 34 files changed, 2080 insertions(+), 336 deletions(-)
 create mode 100644 POS/src/components/common/AuthorizationDialog.vue
 create mode 100644 POS/src/composables/useAuthorization.js
 create mode 100644 POS/src/stores/__tests__/posOffers.spec.js
 create mode 100644 POS/src/utils/offerSchedule.js
 create mode 100644 POS/src/utils/promoApi.js
 create mode 100644 pos_next/integrations/__init__.py
 create mode 100644 pos_next/integrations/registry.py
 create mode 100644 pos_next/test_no_promotions_import.py
 create mode 100644 pos_next/test_split_smoke.py
 create mode 100644 scripts/run_split_smoke_tests.py

diff --git a/POS/src/App.vue b/POS/src/App.vue
index 73c5f397b..f108f0cf6 100644
--- a/POS/src/App.vue
+++ b/POS/src/App.vue
@@ -2,10 +2,12 @@
 	<div>
 		<router-view :key="translationVersion" />
 		<Toast />
+		<AuthorizationDialog />
 	</div>
 </template>
 
 <script setup>
+import AuthorizationDialog from "@/components/common/AuthorizationDialog.vue";
 import Toast from "@/components/common/Toast.vue";
 import { translationVersion } from "@/utils/translation";
 </script>
diff --git a/POS/src/components/common/AuthorizationDialog.vue b/POS/src/components/common/AuthorizationDialog.vue
new file mode 100644
index 000000000..b57032a69
--- /dev/null
+++ b/POS/src/components/common/AuthorizationDialog.vue
@@ -0,0 +1,185 @@
+<template>
+	<div
+		v-if="state.open"
+		class="pointer-events-auto fixed inset-0 z-[var(--z-authorization)] flex items-center justify-center bg-black/50 p-4"
+		@click.self="onCancel"
+		@pointerdown.stop
+	>
+		<FocusScope trapped as-child>
+			<div class="w-full max-w-sm rounded-xl bg-white shadow-xl dark:bg-gray-800">
+				<div class="border-b border-gray-200 px-5 py-4 dark:border-gray-700">
+					<h3 class="text-lg font-semibold text-gray-900 dark:text-gray-100">
+						{{ __("Authorization Required") }}
+					</h3>
+					<p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
+						{{ __("A manager must approve this action.") }}
+					</p>
+				</div>
+
+				<div class="space-y-4 px-5 py-4">
+					<div v-if="loading" class="py-6 text-center text-sm text-gray-500">
+						{{ __("Loading approvers…") }}
+					</div>
+
+					<div
+						v-else-if="!authorizers.length"
+						class="rounded-lg bg-amber-50 p-3 text-sm text-amber-800 dark:bg-amber-900/30 dark:text-amber-200"
+					>
+						{{
+							__(
+								"No approver is available. Ask a System Manager to set an authorization PIN for a manager."
+							)
+						}}
+					</div>
+
+					<template v-else>
+						<div>
+							<label
+								class="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300"
+							>
+								{{ __("Approver") }}
+							</label>
+							<select
+								v-model="approver"
+								class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm dark:border-gray-600 dark:bg-gray-700 dark:text-gray-100"
+							>
+								<option
+									v-for="person in authorizers"
+									:key="person.user"
+									:value="person.user"
+								>
+									{{ person.full_name || person.user }}
+								</option>
+							</select>
+						</div>
+
+						<div>
+							<label
+								class="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300"
+							>
+								{{ __("PIN") }}
+							</label>
+							<input
+								ref="pinInput"
+								v-model="pin"
+								type="password"
+								inputmode="numeric"
+								autocomplete="off"
+								:maxlength="pinLength"
+								:placeholder="__('{0}-digit PIN', [pinLength])"
+								class="w-full rounded-lg border px-3 py-2 text-center text-2xl tracking-[0.5em] dark:bg-gray-700 dark:text-gray-100"
+								:class="
+									errorMessage
+										? 'border-red-500'
+										: 'border-gray-300 dark:border-gray-600'
+								"
+								@keyup.enter="onApprove"
+							/>
+							<p v-if="errorMessage" class="mt-1.5 text-sm text-red-600">
+								{{ errorMessage }}
+							</p>
+						</div>
+					</template>
+				</div>
+
+				<div
+					class="flex justify-end gap-2 border-t border-gray-200 px-5 py-3 dark:border-gray-700"
+				>
+					<button
+						type="button"
+						class="rounded-lg px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700"
+						@click="onCancel"
+					>
+						{{ __("Cancel") }}
+					</button>
+					<button
+						type="button"
+						:disabled="!canApprove"
+						class="rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:opacity-50"
+						@click="onApprove"
+					>
+						{{ verifying ? __("Verifying…") : __("Approve") }}
+					</button>
+				</div>
+			</div>
+		</FocusScope>
+	</div>
+</template>
+
+<script setup>
+import { useAuthorizationDialog } from "@/composables/useAuthorization";
+import { computed, nextTick, ref, watch } from "vue";
+import { FocusScope } from "reka-ui";
+
+const {
+	state,
+	loadAuthorizers,
+	requestGrant,
+	pinLength: getPinLength,
+	approve,
+	cancel,
+} = useAuthorizationDialog();
+
+const authorizers = ref([]);
+const approver = ref("");
+const pin = ref("");
+const errorMessage = ref("");
+const loading = ref(false);
+const verifying = ref(false);
+const pinInput = ref(null);
+const pinLength = ref(getPinLength());
+
+const canApprove = computed(
+	() => Boolean(approver.value) && pin.value.length === pinLength.value && !verifying.value
+);
+
+watch(
+	() => state.open,
+	async (open) => {
+		if (!open) return;
+
+		authorizers.value = [];
+		approver.value = "";
+		pin.value = "";
+		pinLength.value = getPinLength();
+		errorMessage.value = "";
+		loading.value = true;
+
+		authorizers.value = await loadAuthorizers();
+		if (authorizers.value.length) {
+			approver.value = authorizers.value[0].user;
+		}
+		loading.value = false;
+
+		await nextTick();
+		pinInput.value?.focus();
+	}
+);
+
+async function onApprove() {
+	if (!canApprove.value) return;
+
+	verifying.value = true;
+	errorMessage.value = "";
+
+	try {
+		const result = await requestGrant(approver.value, pin.value);
+		if (result?.authorized) {
+			approve(result);
+			return;
+		}
+		errorMessage.value = result?.message || __("Authorization failed");
+	} catch (error) {
+		errorMessage.value = error?.message || __("Authorization failed");
+	} finally {
+		verifying.value = false;
+		pin.value = "";
+		await nextTick();
+		pinInput.value?.focus();
+	}
+}
+
+function onCancel() {
+	cancel();
+}
+</script>
diff --git a/POS/src/components/sale/CouponDialog.vue b/POS/src/components/sale/CouponDialog.vue
index 65ab34de4..5f82b3592 100644
--- a/POS/src/components/sale/CouponDialog.vue
+++ b/POS/src/components/sale/CouponDialog.vue
@@ -231,6 +231,7 @@
 </template>
 
 <script setup>
+import { promoApi } from "@/utils/promoApi";
 import { DEFAULT_CURRENCY, formatCurrency as formatCurrencyUtil } from "@/utils/currency";
 import { Button, Dialog, Input, createResource } from "frappe-ui";
 import { ref, watch } from "vue";
@@ -281,7 +282,7 @@ const errorMessage = ref("");
 
 // Resource to load gift cards
 const giftCardsResource = createResource({
-	url: "pos_next.api.offers.get_active_coupons",
+	url: promoApi.getActiveCoupons(),
 	makeParams() {
 		return {
 			customer: props.customer,
@@ -296,7 +297,7 @@ const giftCardsResource = createResource({
 
 // Resource to validate coupon
 const couponResource = createResource({
-	url: "pos_next.api.offers.validate_coupon",
+	url: promoApi.validateCoupon(),
 	makeParams() {
 		return {
 			coupon_code: couponCode.value,
diff --git a/POS/src/components/sale/CouponManagement.vue b/POS/src/components/sale/CouponManagement.vue
index f94c112c5..c139e7c5a 100644
--- a/POS/src/components/sale/CouponManagement.vue
+++ b/POS/src/components/sale/CouponManagement.vue
@@ -694,6 +694,7 @@
 </template>
 
 <script setup>
+import { promoApi } from "@/utils/promoApi";
 import AutocompleteSelect from "@/components/common/AutocompleteSelect.vue";
 import { useToast } from "@/composables/useToast";
 import { useCustomerSearchStore } from "@/stores/customerSearch";
@@ -811,7 +812,7 @@ const customerOptions = computed(() => {
 
 // Resources
 const couponsResource = createResource({
-	url: "pos_next.api.promotions.get_coupons",
+	url: promoApi.getCoupons(),
 	makeParams() {
 		return {
 			company: props.company,
@@ -830,7 +831,7 @@ const couponsResource = createResource({
 });
 
 const couponDetailsResource = createResource({
-	url: "pos_next.api.promotions.get_coupon_details",
+	url: promoApi.getCouponDetails(),
 	makeParams() {
 		return { coupon_name: selectedCoupon.value?.name };
 	},
@@ -863,7 +864,7 @@ const campaignsResource = createResource({
 });
 
 const createCouponResource = createResource({
-	url: "pos_next.api.promotions.create_coupon",
+	url: promoApi.createCoupon(),
 	makeParams() {
 		return { data: JSON.stringify(form.value) };
 	},
@@ -883,7 +884,7 @@ const createCouponResource = createResource({
 });
 
 const updateCouponResource = createResource({
-	url: "pos_next.api.promotions.update_coupon",
+	url: promoApi.updateCoupon(),
 	makeParams() {
 		return {
 			coupon_name: selectedCoupon.value?.name,
@@ -917,7 +918,7 @@ const updateCouponResource = createResource({
 });
 
 const toggleCouponResource = createResource({
-	url: "pos_next.api.promotions.toggle_coupon",
+	url: promoApi.toggleCoupon(),
 	makeParams() {
 		return { coupon_name: selectedCoupon.value?.name };
 	},
@@ -939,7 +940,7 @@ const toggleCouponResource = createResource({
 });
 
 const deleteCouponResource = createResource({
-	url: "pos_next.api.promotions.delete_coupon",
+	url: promoApi.deleteCoupon(),
 	makeParams() {
 		return { coupon_name: selectedCoupon.value?.name };
 	},
diff --git a/POS/src/components/sale/CreateCustomerDialog.vue b/POS/src/components/sale/CreateCustomerDialog.vue
index 10e83d50a..cd929f1d3 100644
--- a/POS/src/components/sale/CreateCustomerDialog.vue
+++ b/POS/src/components/sale/CreateCustomerDialog.vue
@@ -9,7 +9,7 @@
 		<template #body-content>
 			<div class="flex flex-col gap-6">
 				<!-- Customer Name (Required) -->
-				<div>
+				<div v-if="!miraayaCustomerSync">
 					<label class="block text-start text-sm font-medium text-gray-700 mb-2">
 						{{ __("Customer Name") }} <span class="text-red-500">*</span>
 					</label>
@@ -21,6 +21,44 @@
 					/>
 				</div>
 
+				<template v-else>
+					<div class="grid grid-cols-2 gap-4">
+						<div>
+							<label class="block text-start text-sm font-medium text-gray-700 mb-2">
+								{{ __("First Name") }} <span class="text-red-500">*</span>
+							</label>
+							<Input
+								v-model="customerData.custom_first_name"
+								type="text"
+								:placeholder="__('First name')"
+								required
+							/>
+						</div>
+						<div>
+							<label class="block text-start text-sm font-medium text-gray-700 mb-2">
+								{{ __("Last Name") }} <span class="text-red-500">*</span>
+							</label>
+							<Input
+								v-model="customerData.custom_last_name"
+								type="text"
+								:placeholder="__('Last name')"
+								required
+							/>
+						</div>
+					</div>
+					<div>
+						<label class="block text-start text-sm font-medium text-gray-700 mb-2">
+							{{ __("Customer Name") }}
+						</label>
+						<Input
+							:model-value="computedCustomerName"
+							type="text"
+							disabled
+							:placeholder="__('Auto-generated from first and last name')"
+						/>
+					</div>
+				</template>
+
 				<!-- Mobile Number with Country Code Selector -->
 				<div>
 					<label class="block text-start text-sm font-medium text-gray-700 mb-2">
@@ -35,13 +73,26 @@
 								class="flex items-center gap-1 w-24 ps-2 pe-1 py-2 border border-gray-300 rounded-lg text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 bg-white hover:bg-gray-50"
 							>
 								<img
+									v-if="currentCountryCode"
 									:src="`https://flagcdn.com/h24/${currentCountryCode}.png`"
 									:alt="currentCountryCode"
 									class="w-6 h-auto rounded-sm"
 									@error="handleFlagError"
 								/>
+								<svg
+									v-else
+									class="w-4 h-4 text-gray-400"
+									fill="currentColor"
+									viewBox="0 0 20 20"
+								>
+									<path
+										fill-rule="evenodd"
+										d="M10 18a8 8 0 100-16 8 8 0 000 16zM4.332 8.027a6.012 6.012 0 011.912-2.706C6.512 5.73 6.974 6 7.5 6A1.5 1.5 0 019 7.5V8a2 2 0 004 0 2 2 0 011.523-1.943A5.977 5.977 0 0116 10c0 .34-.028.675-.083 1H15a2 2 0 00-2 2v2.197A5.973 5.973 0 0110 16v-2a2 2 0 00-2-2 2 2 0 01-2-2 2 2 0 00-1.668-1.973z"
+										clip-rule="evenodd"
+									/>
+								</svg>
 								<span class="flex-1 text-start">{{
-									selectedCountryCode || "+20"
+									selectedCountryCode || "+"
 								}}</span>
 								<svg
 									class="w-4 h-4 text-gray-400"
@@ -119,7 +170,7 @@
 					</div>
 				</div>
 
-				<!-- Email -->
+				<!-- Email (optional; Magento sync uses a default if blank) -->
 				<div>
 					<label class="block text-start text-sm font-medium text-gray-700 mb-2">
 						{{ __("Email") }}
@@ -127,7 +178,7 @@
 					<Input
 						v-model="customerData.email_id"
 						type="email"
-						:placeholder="__('Enter email address')"
+						:placeholder="__('Enter email address (optional)')"
 					/>
 				</div>
 
@@ -255,7 +306,7 @@
 							updateCustomerResource.loading ||
 							checkingPermission
 						"
-						:disabled="!customerData.customer_name || !phoneNumber || !hasPermission"
+						:disabled="!canSubmitCustomer"
 					>
 						{{ isEditMode ? __("Save Changes") : __("Create Customer") }}
 					</Button>
@@ -274,6 +325,7 @@
  *
  * Features:
  * - Country code selector with flag icons and search
+ * - Default mobile ISD from POS Profile country (Company.country)
  * - Auto-sets territory based on selected country
  * - Permission checking before allowing creation
  * - Lazy loads countries data when dialog opens (not on app startup)
@@ -281,7 +333,10 @@
 
 import { usePOSPermissions } from "@/composables/usePermissions";
 import { useToast } from "@/composables/useToast";
+import { useBootstrapStore } from "@/stores/bootstrap";
 import { useCountriesStore } from "@/stores/countries";
+import { usePOSSettingsStore } from "@/stores/posSettings";
+import { usePOSShiftStore } from "@/stores/posShift";
 import { logger } from "@/utils/logger";
 import { Button, Dialog, Input, createResource } from "frappe-ui";
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
@@ -293,6 +348,9 @@ const log = logger.create("CreateCustomerDialog");
 // =============================================================================
 
 const countriesStore = useCountriesStore();
+const posSettingsStore = usePOSSettingsStore();
+const shiftStore = usePOSShiftStore();
+const bootstrapStore = useBootstrapStore();
 const { canCreateCustomer } = usePOSPermissions();
 const { showSuccess, showError } = useToast();
 
@@ -321,6 +379,8 @@ const showCountryDropdown = ref(false);
 const countrySearchQuery = ref("");
 const dropdownRef = ref(null);
 const countrySearchRef = ref(null);
+/** Ensures POS Profile default ISD is applied only once per dialog open */
+const defaultCountryApplied = ref(false);
 
 const customerGroups = ref([]);
 const territories = ref([]);
@@ -335,6 +395,8 @@ const customerData = ref({
 	territory: "",
 	custom_governorate: "",
 	custom_district: "",
+	custom_first_name: "",
+	custom_last_name: "",
 });
 
 // =============================================================================
@@ -348,9 +410,28 @@ const show = computed({
 
 const isEditMode = computed(() => !!props.customer?.name);
 
+const miraayaCustomerSync = computed(() => posSettingsStore.miraayaInstalled);
+
+const computedCustomerName = computed(() => {
+	const first = (customerData.value.custom_first_name || "").trim();
+	const last = (customerData.value.custom_last_name || "").trim();
+	return [first, last].filter(Boolean).join(" ");
+});
+
+const hasValidCustomerName = computed(() => {
+	if (miraayaCustomerSync.value) {
+		return Boolean(computedCustomerName.value);
+	}
+	return Boolean((customerData.value.customer_name || "").trim());
+});
+
+const canSubmitCustomer = computed(
+	() => hasValidCustomerName.value && Boolean(phoneNumber.value) && hasPermission.value
+);
+
 const currentCountryCode = computed(() => {
 	const country = countriesStore.countries.find((c) => c.isd === selectedCountryCode.value);
-	return country?.code.toLowerCase() || "eg";
+	return country?.code.toLowerCase() || "";
 });
 
 const filteredCountries = computed(() => {
@@ -376,6 +457,8 @@ const selectCountry = (country) => {
 	showCountryDropdown.value = false;
 	countrySearchQuery.value = "";
 	updateMobileNumber();
+	// Manual pick only — do not auto-change territory on open/default
+	updateTerritoryFromCountry();
 };
 
 const updateMobileNumber = () => {
@@ -391,20 +474,83 @@ const handleClickOutside = (event) => {
 	}
 };
 
-const setCountryFromName = (countryName) => {
-	if (!countryName) {
-		selectedCountryCode.value = "+20";
+/** Resolve ISD from country name, ISO code, or ISD itself. */
+const resolveCountryIsd = (value) => {
+	if (!value) return null;
+
+	const byName = countriesStore.countryNameToISDMap[value];
+	if (byName) return byName;
+
+	const byCode = countriesStore.findCountryByCode(value);
+	if (byCode?.isd) return byCode.isd;
+
+	const byIsd = countriesStore.findCountryByISD(value);
+	if (byIsd?.isd) return byIsd.isd;
+
+	// Value may already be an ISD like "+20"
+	if (String(value).startsWith("+")) return value;
+
+	return null;
+};
+
+/** Set selectedCountryCode from POS Profile country / country code (once). */
+const setCountryFromProfileValue = (profileCountry) => {
+	const isd = resolveCountryIsd(profileCountry);
+	if (!isd) {
+		log.warn(`Country "${profileCountry}" not found in countries list`);
+		return false;
+	}
+	selectedCountryCode.value = isd;
+	log.info(`Set country code to ${isd} for ${profileCountry}`);
+	return true;
+};
+
+/** POS Profile country (Company → country), from shift/bootstrap or API. */
+const resolvePosProfileCountry = async () => {
+	const fromShift = shiftStore.currentProfile?.country;
+	if (fromShift) return fromShift;
+
+	const fromBootstrap = bootstrapStore.getPreloadedPOSProfile()?.country;
+	if (fromBootstrap) return fromBootstrap;
+
+	if (!props.posProfile) return null;
+
+	try {
+		const data = await posProfileResource.reload();
+		return data?.country || null;
+	} catch (err) {
+		log.error("Error loading POS Profile country", err);
+		return null;
+	}
+};
+
+/**
+ * Apply default mobile ISD once when opening Create Customer.
+ * Does nothing in edit mode, and never re-applies after open / user pick.
+ */
+const applyDefaultCountryCode = async () => {
+	if (isEditMode.value || defaultCountryApplied.value || selectedCountryCode.value) {
+		defaultCountryApplied.value = true;
 		return;
 	}
 
-	const isd = countriesStore.countryNameToISDMap[countryName];
-	if (isd) {
-		selectedCountryCode.value = isd;
-		log.info(`Set country code to ${isd} for ${countryName}`);
-	} else {
-		log.warn(`Country "${countryName}" not found`);
-		selectedCountryCode.value = "+20";
+	await countriesStore.loadCountries();
+
+	// Bail if cashier already picked a code while countries were loading
+	if (selectedCountryCode.value) {
+		defaultCountryApplied.value = true;
+		return;
 	}
+
+	const profileCountry = await resolvePosProfileCountry();
+
+	if (selectedCountryCode.value) {
+		defaultCountryApplied.value = true;
+		return;
+	}
+
+	setCountryFromProfileValue(profileCountry);
+	defaultCountryApplied.value = true;
 };
 
 /** Auto-set territory based on selected country (exact or fuzzy match) */
@@ -441,13 +587,18 @@ const updateTerritoryFromCountry = () => {
 const createCustomerResource = createResource({
 	url: "pos_next.api.customers.create_customer",
 	makeParams: () => ({
-		customer_name: customerData.value.customer_name,
+		customer_name: miraayaCustomerSync.value
+			? computedCustomerName.value
+			: customerData.value.customer_name,
 		mobile_no: customerData.value.mobile_no || "",
 		email_id: customerData.value.email_id || "",
 		customer_group: customerData.value.customer_group || "",
 		territory: customerData.value.territory || "",
 		custom_governorate: customerData.value.custom_governorate || "",
 		custom_district: customerData.value.custom_district || "",
+		custom_first_name: customerData.value.custom_first_name || "",
+		custom_last_name: customerData.value.custom_last_name || "",
+		custom_is_publish: 1,
 		pos_profile: props.posProfile,
 	}),
 	onSuccess: (data) => {
@@ -586,11 +737,7 @@ const posProfileResource = createResource({
 		fieldname: ["country"],
 	}),
 	auto: false,
-	onSuccess: (data) => setCountryFromName(data?.country || "Egypt"),
-	onError: (err) => {
-		log.error("Error loading POS Profile", err);
-		selectedCountryCode.value = "+20";
-	},
+	onError: (err) => log.error("Error loading POS Profile", err),
 });
 
 // =============================================================================
@@ -598,9 +745,6 @@ const posProfileResource = createResource({
 // =============================================================================
 
 const loadDialogData = async () => {
-	// Lazy load countries (non-blocking)
-	countriesStore.loadCountries();
-
 	await sellingSettingsResource.reload();
 
 	if (!isEditMode.value) {
@@ -608,8 +752,9 @@ const loadDialogData = async () => {
 		customerData.value.territory = "";
 	}
 
-	// Load form options
+	// Load form options + countries (awaited so ISD map is ready before default)
 	await Promise.all([
+		countriesStore.loadCountries(),
 		territoriesResource.reload(),
 		customerGroupsResource.reload(),
 		governoratesResource.reload(),
@@ -622,12 +767,8 @@ const loadDialogData = async () => {
 	}
 	checkPermissions();
 
-	// Set country from POS Profile
-	if (props.posProfile) {
-		await posProfileResource.reload();
-	} else {
-		selectedCountryCode.value = "+20";
-	}
+	// Default mobile country code from POS Profile → Company country
+	await applyDefaultCountryCode();
 };
 
 const checkPermissions = async () => {
@@ -643,7 +784,14 @@ const checkPermissions = async () => {
 };
 
 const handleCreate = async () => {
-	if (!customerData.value.customer_name) {
+	if (miraayaCustomerSync.value) {
+		if (!customerData.value.custom_first_name?.trim()) {
+			return showError(__("First Name is required"));
+		}
+		if (!customerData.value.custom_last_name?.trim()) {
+			return showError(__("Last Name is required"));
+		}
+	} else if (!customerData.value.customer_name) {
 		return showError(__("Customer Name is required"));
 	}
 	if (!phoneNumber.value) {
@@ -668,10 +816,13 @@ const resetForm = () => {
 		),
 		custom_governorate: "",
 		custom_district: "",
+		custom_first_name: "",
+		custom_last_name: "",
 	});
 	districts.value = [];
 	selectedCountryCode.value = "";
 	phoneNumber.value = "";
+	defaultCountryApplied.value = false;
 };
 
 // =============================================================================
@@ -719,20 +870,14 @@ watch(
 watch(
 	() => customerData.value.mobile_no,
 	(value) => {
-		if (value?.includes("-")) {
-			const [code, ...rest] = value.split("-");
-			selectedCountryCode.value = code;
-			phoneNumber.value = rest.join("-");
-		}
+		// Only sync from stored mobile when editing; never overwrite create-mode default
+		if (!isEditMode.value || !value?.includes("-")) return;
+		const [code, ...rest] = value.split("-");
+		selectedCountryCode.value = code;
+		phoneNumber.value = rest.join("-");
 	}
 );
 
-watch(selectedCountryCode, async (newVal, oldVal) => {
-	if (!oldVal) return;
-	await nextTick();
-	updateTerritoryFromCountry();
-});
-
 watch(
 	() => customerData.value.custom_governorate,
 	(governorate) => {
diff --git a/POS/src/components/sale/EditItemDialog.vue b/POS/src/components/sale/EditItemDialog.vue
index afd762ce8..424f0c20c 100644
--- a/POS/src/components/sale/EditItemDialog.vue
+++ b/POS/src/components/sale/EditItemDialog.vue
@@ -213,7 +213,7 @@
 																name="lock"
 																class="w-3 h-3"
 															/>
-															{{ __("Locked (offer applied)") }}
+															{{ __("Locked (promotional offer)") }}
 														</p>
 													</div>
 												</div>
@@ -340,7 +340,7 @@
 
 											<!-- Item Discount Section (only if allowed by POS Profile) -->
 											<div
-												v-if="settingsStore.allowItemDiscount"
+												v-if="canEditItemDiscount"
 												class="border-t border-gray-200 pt-4"
 											>
 												<label
@@ -357,6 +357,7 @@
 														<SelectInput
 															v-model="discountType"
 															:options="discountTypeOptions"
+															:disabled="!canEditDiscount"
 															@change="handleDiscountTypeChange"
 														/>
 													</div>
@@ -381,7 +382,15 @@
 																		: undefined
 																"
 																step="0.01"
-																class="w-full h-7 border border-gray-300 rounded-lg px-3 pe-8 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+																:readonly="!canEditDiscount"
+																:disabled="!canEditDiscount"
+																:title="discountEditDisabledReason"
+																:class="
+																	canEditDiscount
+																		? 'bg-white focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent'
+																		: 'bg-gray-50 cursor-not-allowed'
+																"
+																class="w-full h-7 border border-gray-300 rounded-lg px-3 pe-8 text-sm"
 																@input="calculateDiscount"
 															/>
 															<span
@@ -396,6 +405,24 @@
 														</div>
 													</div>
 												</div>
+												<!-- Compact warning when discount editing disabled due to pricing rules -->
+												<p
+													v-if="hasPricingRules"
+													class="mt-2 text-xs text-amber-600 flex items-center gap-1"
+												>
+													<FeatherIcon
+														name="lock"
+														class="w-3 h-3"
+													/>
+													{{ __("Locked (promotional offer)") }}
+												</p>
+											</div>
+
+											<div
+												v-else-if="isItemLevelPromotion"
+												class="border-t border-gray-200 pt-4 text-xs text-amber-700"
+											>
+												{{ __("SKU promotion applied — discount is locked") }}
 											</div>
 
 											<!-- Totals -->
@@ -473,8 +500,11 @@
 </template>
 
 <script setup>
+import { promoApi } from "@/utils/promoApi";
 import { useToast } from "@/composables/useToast";
 import { usePOSSettingsStore } from "@/stores/posSettings";
+import { usePOSOffersStore } from "@/stores/posOffers";
+import { usePOSShiftStore } from "@/stores/posShift";
 import { useSerialNumberStore } from "@/stores/serialNumber";
 import { getItemStock } from "@/utils/stockValidator";
 import {
@@ -482,14 +512,58 @@ import {
 	getCurrencySymbol,
 	roundCurrency,
 } from "@/utils/currency";
+import { call } from "@/utils/apiWrapper";
 import { Button, FeatherIcon, createResource } from "frappe-ui";
 import { computed, ref, watch } from "vue";
 import SelectInput from "@/components/common/SelectInput.vue";
 
 const { showSuccess, showError, showWarning } = useToast();
 const settingsStore = usePOSSettingsStore();
+const offersStore = usePOSOffersStore();
+const shiftStore = usePOSShiftStore();
 const serialStore = useSerialNumberStore();
 
+/**
+ * True if this item currently qualifies for an active offer based on qty
+ * (min_qty / max_qty). Outside that range, manual discount stays allowed.
+ */
+function isItemCoveredByOffer(item, offers, qty) {
+	if (!item?.item_code || !Array.isArray(offers) || offers.length === 0) {
+		return false;
+	}
+
+	const q = Number(qty);
+	if (!Number.isFinite(q) || q <= 0) return false;
+
+	for (const offer of offers) {
+		if (!offer || offer.coupon_based) continue;
+
+		const minQty = Number(offer.min_qty) || 0;
+		const maxQty = Number(offer.max_qty) || 0;
+		if (minQty > 0 && q < minQty) continue;
+		if (maxQty > 0 && q > maxQty) continue;
+
+		if (offer.apply_on === "Item Code") {
+			const eligibleItems = offer.eligible_items || [];
+			if (eligibleItems.includes(item.item_code)) return true;
+		} else if (offer.apply_on === "Item Group") {
+			const eligibleGroups = offer.eligible_item_groups || [];
+			if (
+				eligibleGroups.includes("All Item Groups") ||
+				(item.item_group && eligibleGroups.includes(item.item_group))
+			) {
+				return true;
+			}
+		} else if (offer.apply_on === "Brand") {
+			const eligibleBrands = offer.eligible_brands || [];
+			if (item.brand && eligibleBrands.includes(item.brand)) return true;
+		}
+		// Transaction-level offers intentionally skipped
+	}
+
+	return false;
+}
+
 const props = defineProps({
 	modelValue: Boolean,
 	item: Object,
@@ -524,6 +598,34 @@ const localSerials = ref([]); // List of serial numbers for this item
 const removedSerials = ref([]); // Track serials removed during this edit session
 const originalSerials = ref([]); // Original serials when dialog opened
 const originalPriceListRate = ref(0); // Original price_list_rate when dialog opened (for rate edit validation)
+// True when server confirms current qty qualifies for an active promotion
+const itemHasActivePromotion = ref(false);
+let promotionCheckRequestId = 0;
+
+async function checkItemPromotion(itemCode, qty) {
+	const requestId = ++promotionCheckRequestId;
+	itemHasActivePromotion.value = false;
+	if (!itemCode) return;
+
+	const quantity = Number(qty);
+	if (!Number.isFinite(quantity) || quantity <= 0) return;
+
+	try {
+		const company = shiftStore.currentProfile?.company || shiftStore.profileCompany;
+		const resp = await call(promoApi.itemHasActivePromotion(), {
+			item_code: itemCode,
+			company: company || undefined,
+			qty: quantity,
+		});
+		if (requestId !== promotionCheckRequestId) return;
+		const result = resp?.message ?? resp;
+		itemHasActivePromotion.value = Boolean(result?.has_promotion);
+	} catch (error) {
+		if (requestId !== promotionCheckRequestId) return;
+		console.error("Failed to check item promotion:", error);
+		itemHasActivePromotion.value = false;
+	}
+}
 
 const getItemDetailsResource = createResource({
 	url: "pos_next.api.items.get_item_details",
@@ -542,26 +644,53 @@ const availableUoms = computed(() => {
 
 const currencySymbol = computed(() => getCurrencySymbol(props.currency));
 
-// Check if item has pricing rules applied (promotional offers)
+// Lock rate/discount only when the current qty qualifies for a promo
+// (e.g. qty 2–5 for Buy 2–5 Get 1). Qty 1 or 6+ stays editable.
 const hasPricingRules = computed(() => {
 	if (!localItem.value) return false;
-	return Boolean(localItem.value.pricing_rules) && localItem.value.pricing_rules.length > 0;
+	if (localItem.value.is_free_item) return true;
+	if (itemHasActivePromotion.value) return true;
+	return isItemCoveredByOffer(
+		localItem.value,
+		offersStore.availableOffers,
+		localQuantity.value
+	);
+});
+
+const isItemLevelPromotion = computed(() => {
+	return localItem.value?.discount_source === "item_level_promotion";
+});
+
+const canEditItemDiscount = computed(() => {
+	return settingsStore.allowItemDiscount && !isItemLevelPromotion.value;
 });
 
 // Rate editing is allowed only if:
 // 1. POS Settings allows rate editing AND
-// 2. Item does NOT have pricing rules (promotional offers) applied
+// 2. Item does NOT have pricing rules (promotional offers) applied / configured
 const canEditRate = computed(() => {
 	return settingsStore.allowUserToEditRate && !hasPricingRules.value;
 });
 
+// Item discount editing is allowed only if no promotional offer covers this item
+const canEditDiscount = computed(() => {
+	return settingsStore.allowItemDiscount && !hasPricingRules.value;
+});
+
 // Tooltip message for why rate editing is disabled
 const rateEditDisabledReason = computed(() => {
 	if (!settingsStore.allowUserToEditRate) {
 		return __("Rate editing is disabled");
 	}
 	if (hasPricingRules.value) {
-		return __("Locked (offer applied)");
+		return __("Locked (promotional offer)");
+	}
+	return "";
+});
+
+const discountEditDisabledReason = computed(() => {
+	if (hasPricingRules.value) {
+		return __("Cannot add item discount while a promotional offer applies to this item");
 	}
 	return "";
 });
@@ -622,7 +751,14 @@ watch(
 			}
 
 			// Initialize discount
-			if (newItem.discount_percentage && newItem.discount_percentage > 0) {
+			const usesExactPromoDiscount =
+				(newItem.discount_source === "free_item" ||
+					newItem.discount_source === "gwp") &&
+				Number(newItem.discount_amount) > 0;
+			if (usesExactPromoDiscount) {
+				discountType.value = "amount";
+				discountValue.value = newItem.discount_amount;
+			} else if (newItem.discount_percentage && newItem.discount_percentage > 0) {
 				discountType.value = "percentage";
 				discountValue.value = newItem.discount_percentage;
 			} else if (newItem.discount_amount && newItem.discount_amount > 0) {
@@ -633,12 +769,18 @@ watch(
 				discountValue.value = 0;
 			}
 
+			// Lock discount only when current qty qualifies for the promo
+			checkItemPromotion(newItem.item_code, localQuantity.value);
+
 			// Reset stock check state
 			hasStock.value = true;
 			isCheckingStock.value = false;
 
 			calculateTotals();
 			isInitializingItem.value = false;
+		} else {
+			localItem.value = null;
+			itemHasActivePromotion.value = false;
 		}
 	},
 	{ immediate: true }
@@ -649,6 +791,12 @@ watch(localUom, (newUom, oldUom) => {
 	handleUomChange(newUom);
 });
 
+// Re-evaluate promo lock when qty changes (e.g. 1 → editable, 2–5 → locked)
+watch(localQuantity, (newQty) => {
+	if (isInitializingItem.value || !localItem.value?.item_code) return;
+	checkItemPromotion(localItem.value.item_code, newQty);
+});
+
 /**
  * Intelligently determine the step size based on current quantity
  * - Whole numbers (1, 2, 3): step by 1
@@ -915,6 +1063,39 @@ function updateItem() {
 		}
 	}
 
+	// ========================================================================
+	// ITEM DISCOUNT VALIDATION — block manual discount when offer is applied
+	// ========================================================================
+	let discountPercentage =
+		discountType.value === "percentage" ? discountValue.value : 0;
+	let discountAmount = discountType.value === "amount" ? discountValue.value : 0;
+
+	if (hasPricingRules.value) {
+		// Keep promotional discount values; do not allow manual override
+		discountPercentage = Number(localItem.value.discount_percentage) || 0;
+		discountAmount = Number(localItem.value.discount_amount) || 0;
+
+		const attemptedPct =
+			discountType.value === "percentage" ? Number(discountValue.value) || 0 : 0;
+		const attemptedAmt =
+			discountType.value === "amount" ? Number(discountValue.value) || 0 : 0;
+		const initPct =
+			discountType.value === "percentage"
+				? Number(localItem.value.discount_percentage) || 0
+				: 0;
+		const initAmt =
+			discountType.value === "amount"
+				? Number(localItem.value.discount_amount) || 0
+				: 0;
+
+		if (attemptedPct !== initPct || attemptedAmt !== initAmt) {
+			showError(
+				__("Cannot add item discount while a promotional offer applies to this item")
+			);
+			return;
+		}
+	}
+
 	const updatedItem = {
 		...localItem.value,
 		quantity: localQuantity.value,
@@ -923,8 +1104,16 @@ function updateItem() {
 		// Preserve price_list_rate for reference (original price before any manual edits)
 		price_list_rate: originalPriceListRate.value,
 		warehouse: localWarehouse.value,
-		discount_percentage: discountType.value === "percentage" ? discountValue.value : 0,
-		discount_amount: discountType.value === "amount" ? discountValue.value : 0,
+		discount_percentage: discountPercentage,
+		discount_amount: discountAmount,
+		discount_source:
+			(discountPercentage > 0 || discountAmount > 0) && !isItemLevelPromotion.value
+				? "manual_discount"
+				: localItem.value.discount_source || "",
+		is_already_discounted:
+			(discountPercentage > 0 || discountAmount > 0) && !isItemLevelPromotion.value
+				? 1
+				: localItem.value.is_already_discounted || 0,
 		// Track manual rate edits for audit logging
 		is_rate_manually_edited: isRateManuallyEdited ? 1 : 0,
 		original_rate: isRateManuallyEdited ? originalPriceListRate.value : null,
diff --git a/POS/src/components/sale/InvoiceCart.vue b/POS/src/components/sale/InvoiceCart.vue
index aeefa004d..b8168eff4 100644
--- a/POS/src/components/sale/InvoiceCart.vue
+++ b/POS/src/components/sale/InvoiceCart.vue
@@ -105,6 +105,16 @@
 									>
 										{{ customer.mobile_no }}
 									</p>
+									<p
+										v-if="customerLpInfo.wallet_enabled"
+										class="text-[10px] text-amber-600 font-medium truncate leading-tight"
+									>
+										{{ __("LP") }}:
+										{{ formatCurrency(customerLpInfo.balance_iqd) }}
+										<span v-if="customerLpInfo.balance_points">
+											({{ customerLpInfo.balance_points }} {{ __("pts") }})
+										</span>
+									</p>
 								</div>
 							</div>
 
@@ -911,18 +921,18 @@
 
 			<div v-else class="flex flex-col gap-0.5 sm:gap-1">
 				<div
-					v-for="(item, index) in sortedItems"
+					v-for="(item, index) in displayCartItems"
 					:key="
 						item.item_code +
 						'-' +
 						(item.uom || '') +
 						(item.is_free_item ? '-free' : '')
 					"
-					@click="item.is_free_item ? null : openEditDialog(item)"
+					@click="openEditDialog(item)"
 					:class="[
 						'border rounded-md p-1.5 sm:p-2 transition-all duration-200',
-						item.is_free_item
-							? 'bg-green-50 border-green-300 cursor-default'
+						item.is_free_item || item._isStandaloneFreeRow
+							? 'bg-green-50 border-green-200 hover:border-green-300'
 							: 'bg-white border-gray-200 hover:border-blue-300 hover:shadow-md active:scale-[0.99] cursor-pointer group',
 					]"
 				>
@@ -967,15 +977,11 @@
 									>
 										{{ item.item_name }}
 									</h4>
-									<!-- Free Item Badge -->
+									<!-- GWP / Free Item Badge -->
 									<span
-										v-if="item.free_qty && item.free_qty > 0"
+										v-if="getDisplayFreeQty(item) > 0"
 										class="inline-flex items-center px-1.5 py-0.5 bg-green-600 text-white rounded-full text-[9px] font-bold flex-shrink-0"
-										:title="
-											item.is_free_item
-												? __('Free item')
-												: __('{0} free item(s) included', [item.free_qty])
-										"
+										:title="formatFreeItemBadgeText(getDisplayFreeQty(item))"
 									>
 										<svg
 											class="w-2.5 h-2.5 me-0.5"
@@ -988,15 +994,16 @@
 												clip-rule="evenodd"
 											/>
 										</svg>
-										{{
-											item.is_free_item
-												? __("FREE")
-												: __("+{0} FREE", [item.free_qty])
-										}}
+										{{ formatFreeItemBadgeText(getDisplayFreeQty(item)) }}
 									</span>
-									<!-- Discount Badge -->
+									<!-- Discount Badge (hide when same-item free gift is bundled on this line) -->
 									<div
-										v-if="item.discount_amount && item.discount_amount > 0"
+										v-if="
+											!isGwpItem(item) &&
+											!hasBundledSameItemFree(item) &&
+											item.discount_amount &&
+											item.discount_amount > 0
+										"
 										class="inline-flex items-center px-1.5 py-0.5 bg-gradient-to-r from-red-50 to-orange-50 text-red-700 rounded-full text-[9px] font-bold border border-red-200 flex-shrink-0"
 									>
 										<svg
@@ -1012,13 +1019,12 @@
 										</svg>
 										{{
 											__("{0}%", [
-												Number(item.discount_percentage).toFixed(0),
+												Number(getItemDiscountPercent(item)).toFixed(0),
 											])
 										}}
 									</div>
 								</div>
 								<button
-									v-if="!item.is_free_item"
 									type="button"
 									@click.stop="$emit('remove-item', item.item_code, item.uom)"
 									class="text-gray-400 hover:text-red-600 active:text-red-700 transition-colors flex-shrink-0 p-0.5 -m-0.5 touch-manipulation active:scale-90"
@@ -1045,19 +1051,9 @@
 							<div class="flex items-center justify-between gap-1.5">
 								<div class="flex items-center gap-1.5">
 									<!-- Quantity Counter -->
-									<!-- For free items, show static quantity badge -->
-									<div
-										v-if="item.is_free_item"
-										class="flex items-center bg-green-100 border border-green-300 rounded px-2 h-6 sm:h-7"
-									>
-										<span
-											class="text-xs sm:text-sm font-bold text-green-700"
-											>{{ item.quantity }}</span
-										>
-									</div>
 									<!-- For serial items, show serial badge with edit button -->
 									<div
-										v-else-if="item.has_serial_no && item.serial_no"
+										v-if="item.has_serial_no && item.serial_no"
 										class="flex items-center gap-1"
 										@click.stop
 									>
@@ -1126,7 +1122,7 @@
 											</svg>
 										</button>
 										<input
-											:value="formatQuantity(item.quantity)"
+											:value="formatQuantity(getDisplayQuantity(item))"
 											@click.stop
 											@input="updateQuantity(item, $event.target.value)"
 											@blur="handleQuantityBlur(item)"
@@ -1274,9 +1270,20 @@
 									</div>
 
 									<!-- Price -->
-									<span class="text-[10px] sm:text-xs font-bold text-gray-700">
-										{{ formatCurrency(item.rate) }}
-									</span>
+									<div class="flex flex-col items-end">
+										<span
+											v-if="
+												item.is_already_discounted &&
+												item.price_list_rate > item.rate
+											"
+											class="text-[9px] text-gray-400 line-through leading-none"
+										>
+											{{ formatCurrency(item.price_list_rate) }}
+										</span>
+										<span class="text-[10px] sm:text-xs font-bold text-gray-700">
+											{{ formatCurrency(item.rate) }}
+										</span>
+									</div>
 								</div>
 
 								<!-- Item Total -->
@@ -1320,7 +1327,7 @@
 			<div v-if="items.length > 0" class="mb-1.5">
 				<!-- Discount Display - Highlighted -->
 				<div
-					v-if="discountAmount > 0"
+					v-if="displayDiscountAmount > 0"
 					class="flex items-center justify-between mb-0.5 bg-red-50 rounded px-1.5 py-1 -mx-0.5"
 				>
 					<div class="flex items-center gap-1">
@@ -1338,7 +1345,7 @@
 						<span class="text-xs font-bold text-red-700">{{ __("Discount") }}</span>
 					</div>
 					<span class="text-sm font-extrabold text-red-600 text-center min-w-[60px]">{{
-						formatCurrency(discountAmount)
+						formatCurrency(displayDiscountAmount)
 					}}</span>
 				</div>
 
@@ -1453,6 +1460,7 @@
  * IMPORTS
  * ============================================================================
  */
+import { isMagentoAppInstalled, promoApi } from "@/utils/promoApi";
 import { usePOSCartStore } from "@/stores/posCart";
 import { usePOSSettingsStore } from "@/stores/posSettings";
 import { usePOSOffersStore } from "@/stores/posOffers";
@@ -1523,6 +1531,7 @@ const props = defineProps({
 		default: 0,
 	},
 	posProfile: String,
+	company: String,
 	currency: {
 		type: String,
 		default: DEFAULT_CURRENCY,
@@ -1581,8 +1590,53 @@ const {
 } = useCartSort(() => props.items);
 
 /**
- * ============================================================================
- * REACTIVE STATE
+ * Display-only merge: hide matching same-item free rows and show one combined line.
+ * Cart data stays unchanged for offers and invoicing.
+ */
+function cartLineKey(item) {
+	return `${item.item_code}\0${item.uom || item.stock_uom || ""}`;
+}
+
+const displayCartItems = computed(() => {
+	const items = sortedItems.value;
+	const freeQtyByKey = new Map();
+	const paidKeys = new Set();
+
+	for (const item of items) {
+		if (!item.is_free_item) {
+			paidKeys.add(cartLineKey(item));
+			continue;
+		}
+		const key = cartLineKey(item);
+		freeQtyByKey.set(
+			key,
+			(freeQtyByKey.get(key) || 0) + (Number.parseFloat(item.quantity) || 0)
+		);
+	}
+
+	const merged = [];
+	for (const item of items) {
+		if (item.is_free_item) continue;
+		const bundledFreeQty = freeQtyByKey.get(cartLineKey(item)) || 0;
+		merged.push(
+			bundledFreeQty > 0 ? { ...item, _bundledFreeQty: bundledFreeQty } : item
+		);
+	}
+
+	// Different-item product discounts add dedicated is_free_item rows (e.g. buy A get B).
+	// Those rows are not bundled onto a paid line — show them as their own cart lines.
+	for (const item of items) {
+		if (!item.is_free_item) continue;
+		const key = cartLineKey(item);
+		if (paidKeys.has(key)) continue;
+		merged.push({ ...item, _isStandaloneFreeRow: true });
+	}
+
+	return merged;
+});
+
+/**
+ * Reactive State
  * ============================================================================
  */
 // Customer search state
@@ -1643,11 +1697,12 @@ if (props.posProfile) {
  * @endpoint pos_next.api.offers.get_active_coupons
  */
 const giftCardsResource = createResource({
-	url: "pos_next.api.offers.get_active_coupons",
+	url: promoApi.getActiveCoupons(),
 	makeParams() {
+		const customerName = props.customer?.name || props.customer;
 		return {
-			customer: props.customer?.name || props.customer,
-			company: props.posProfile, // Will get company from profile
+			customer: customerName,
+			company: props.company,
 		};
 	},
 	auto: false,
@@ -1656,6 +1711,38 @@ const giftCardsResource = createResource({
 	},
 });
 
+const customerLpInfo = ref({
+	wallet_enabled: false,
+	balance_points: 0,
+	balance_iqd: 0,
+});
+
+const customerLpResource = createResource({
+	url: "magento_integration.api.magento_loyalty.get_lp_balance_for_customer",
+	makeParams() {
+		const customerName = props.customer?.name || props.customer;
+		return {
+			customer: customerName,
+			pos_profile: props.posProfile,
+		};
+	},
+	auto: false,
+	onSuccess(data) {
+		customerLpInfo.value = data || {
+			wallet_enabled: false,
+			balance_points: 0,
+			balance_iqd: 0,
+		};
+	},
+	onError() {
+		customerLpInfo.value = {
+			wallet_enabled: false,
+			balance_points: 0,
+			balance_iqd: 0,
+		};
+	},
+});
+
 /**
  * Watch for customer changes to load their gift cards.
  * Reloads gift cards resource when customer is selected (and online).
@@ -1664,11 +1751,36 @@ const giftCardsResource = createResource({
 watch(
 	() => props.customer,
 	(newCustomer) => {
-		if (newCustomer && props.posProfile && !isOffline()) {
+		const customerName = newCustomer?.name || newCustomer;
+		if (customerName && props.company && !isOffline()) {
 			giftCardsResource.reload();
 		} else {
 			availableGiftCards.value = [];
 		}
+
+		if (isMagentoAppInstalled() && customerName && props.posProfile && !isOffline()) {
+			customerLpResource.reload();
+		} else {
+			customerLpInfo.value = {
+				wallet_enabled: false,
+				balance_points: 0,
+				balance_iqd: 0,
+			};
+		}
+	}
+);
+
+// Refresh Magento LP balance after a completed sale when the cart is cleared
+// but the same customer stays selected (watch on customer alone won't re-fire).
+watch(
+	() => props.items?.length ?? 0,
+	(newLen, oldLen) => {
+		if (oldLen > 0 && newLen === 0) {
+			const customerName = props.customer?.name || props.customer;
+			if (isMagentoAppInstalled() && customerName && props.posProfile && !isOffline()) {
+				customerLpResource.reload();
+			}
+		}
 	}
 );
 
@@ -1798,9 +1910,20 @@ const displaySubtotal = computed(() => {
  * @returns {Number} Grand total amount to display
  */
 const displayGrandTotal = computed(() => {
-	// Always: displaySubtotal + tax - discount
-	// This makes the display consistent and intuitive
-	return displaySubtotal.value + props.taxAmount - props.discountAmount;
+	return displaySubtotal.value + props.taxAmount - displayDiscountAmount.value;
+});
+
+/**
+ * Sum line discounts directly from cart items for instant, exact footer display.
+ * Avoids waiting on incremental cache updates after offer application.
+ */
+const displayDiscountAmount = computed(() => {
+	const lineDiscounts = props.items.reduce(
+		(sum, item) => sum + (Number.parseFloat(item.discount_amount) || 0),
+		0
+	);
+	// Fall back to store total when items haven't been stamped yet (e.g. header coupon)
+	return lineDiscounts > 0 ? lineDiscounts : props.discountAmount;
 });
 
 /**
@@ -1953,6 +2076,84 @@ function getInitials(name) {
 	return Array.from(parts[0]).slice(0, 2).join("").toUpperCase();
 }
 
+/**
+ * Effective discount % for badges. Coupon max_amount caps are stored as
+ * absolute amounts (discount_percentage=0), so derive % from amount/base.
+ */
+function isGwpItem(item) {
+	return item?.discount_source === "gwp" || Number.parseFloat(item?.gwp_free_qty) > 0;
+}
+
+function getGwpFreeQty(item) {
+	const gwpQty = Number.parseFloat(item?.gwp_free_qty) || 0;
+	if (gwpQty > 0) return gwpQty;
+	return Number.parseFloat(item?.free_qty) || 0;
+}
+
+function hasBundledSameItemFree(item) {
+	if (item?.is_free_item || item?._isStandaloneFreeRow) {
+		return false;
+	}
+	const bundled = Number.parseFloat(item?._bundledFreeQty) || 0;
+	if (bundled > 0) return true;
+	if ((Number.parseFloat(item?.free_qty) || 0) > 0) return true;
+	return item?.discount_source === "free_item";
+}
+
+function getDisplayFreeQty(item) {
+	if (item?.is_free_item || item?._isStandaloneFreeRow) {
+		return Number.parseFloat(item.quantity) || 0;
+	}
+	const freeQty = Number.parseFloat(item?.free_qty) || 0;
+	if (freeQty > 0) return freeQty;
+	const bundled = Number.parseFloat(item?._bundledFreeQty) || 0;
+	if (bundled > 0) return bundled;
+	return getGwpFreeQty(item);
+}
+
+function getDisplayQuantity(item) {
+	if (item?.discount_source === "free_item" && (Number.parseFloat(item?.free_qty) || 0) > 0) {
+		return item.quantity || 0;
+	}
+	const bundled = Number.parseFloat(item?._bundledFreeQty) || 0;
+	if (bundled > 0) {
+		return (Number.parseFloat(item.quantity) || 0) + bundled;
+	}
+	return item.quantity || 0;
+}
+
+function formatFreeItemBadgeText(freeQty) {
+	const count = Number.parseFloat(freeQty) || 0;
+	if (count === 1) return __("1 free item");
+	return __("{0} free items", [count]);
+}
+
+function resolvePaidQuantityFromDisplay(item, displayQty) {
+	if (item?.discount_source === "free_item") {
+		const freeQty = Number.parseFloat(item?.free_qty) || 0;
+		if (freeQty > 0) {
+			return Math.max(0, displayQty - freeQty);
+		}
+	}
+	const bundled = Number.parseFloat(item?._bundledFreeQty) || 0;
+	if (bundled > 0) {
+		return Math.max(0, displayQty - bundled);
+	}
+	return displayQty;
+}
+
+function getItemDiscountPercent(item) {
+	const pct = Number.parseFloat(item?.discount_percentage) || 0;
+	if (pct > 0) return pct;
+	const discountAmount = Number.parseFloat(item?.discount_amount) || 0;
+	if (discountAmount <= 0) return 0;
+	const qty = Number.parseFloat(item?.quantity || item?.qty) || 0;
+	const rate = Number.parseFloat(item?.price_list_rate || item?.rate) || 0;
+	const base = qty * rate;
+	if (base <= 0) return 0;
+	return (discountAmount / base) * 100;
+}
+
 /**
  * Format a numeric amount as currency string.
  * Uses the component's currency prop for formatting.
@@ -2014,9 +2215,9 @@ function incrementQuantity(item) {
 	// Prevent editing resolved barcode items
 	if (item.is_resolved_barcode) return;
 
-	const step = getSmartStep(item.quantity);
-	const newQty = Math.round((item.quantity + step) * 10000) / 10000;
-	emit("update-quantity", item.item_code, newQty, item.uom);
+	const step = getSmartStep(getDisplayQuantity(item));
+	const newPaidQty = Math.round((item.quantity + step) * 10000) / 10000;
+	emit("update-quantity", item.item_code, newPaidQty, item.uom);
 }
 
 /**
@@ -2029,14 +2230,14 @@ function decrementQuantity(item) {
 	// Prevent editing resolved barcode items
 	if (item.is_resolved_barcode) return;
 
-	const step = getSmartStep(item.quantity);
-	const newQty = Math.round((item.quantity - step) * 10000) / 10000;
+	const step = getSmartStep(getDisplayQuantity(item));
+	const newPaidQty = Math.round((item.quantity - step) * 10000) / 10000;
 
-	if (newQty <= 0) {
+	if (newPaidQty <= 0) {
 		// If quantity would be 0 or negative, remove the item
 		emit("remove-item", item.item_code, item.uom);
 	} else {
-		emit("update-quantity", item.item_code, newQty, item.uom);
+		emit("update-quantity", item.item_code, newPaidQty, item.uom);
 	}
 }
 
@@ -2052,16 +2253,18 @@ function updateQuantity(item, value) {
 	// Prevent editing resolved barcode items
 	if (item.is_resolved_barcode) return;
 
-	const qty = Number.parseFloat(value);
+	const displayQty = Number.parseFloat(value);
 
 	// If the input isn't a valid number (e.g., user cleared the field), do nothing
-	if (isNaN(qty)) return;
+	if (isNaN(displayQty)) return;
+
+	const paidQty = resolvePaidQuantityFromDisplay(item, displayQty);
 
 	// If quantity is zero or negative, remove the item from the cart
-	if (qty <= 0) return emit("remove-item", item.item_code, item.uom);
+	if (paidQty <= 0) return emit("remove-item", item.item_code, item.uom);
 
-	// For positive numbers, update quantity immediately (no rounding here while typing)
-	emit("update-quantity", item.item_code, qty, item.uom);
+	// For positive numbers, update paid quantity (free row stays separate in data)
+	emit("update-quantity", item.item_code, paidQty, item.uom);
 }
 
 /**
diff --git a/POS/src/components/sale/PaymentDialog.vue b/POS/src/components/sale/PaymentDialog.vue
index ee71d01cc..f507cf52a 100644
--- a/POS/src/components/sale/PaymentDialog.vue
+++ b/POS/src/components/sale/PaymentDialog.vue
@@ -511,6 +511,12 @@
 							<div v-if="customer" class="text-gray-600 text-xs mt-0.5 text-start">
 								{{ customer?.customer_name || customer?.name || customer }}
 							</div>
+							<div
+								v-else-if="requiresCustomerForPayment"
+								class="text-amber-700 text-xs mt-0.5 text-start font-medium"
+							>
+								{{ __("Customer required for this payment method") }}
+							</div>
 						</div>
 
 						<!-- Promotional offers & coupons (same entry points as cart — usable while paying) -->
@@ -1173,6 +1179,12 @@
 									]"
 								>
 									{{ formatCurrency(availableWalletBalance) }}
+									<span
+										v-if="walletInfo.balance_points"
+										class="ms-0.5"
+									>
+										({{ walletInfo.balance_points }} {{ __("pts") }})
+									</span>
 								</span>
 								<!-- Payment Amount Badge -->
 								<span
@@ -2136,6 +2148,8 @@ const walletInfo = ref({
 	wallet_exists: false,
 	wallet_balance: 0,
 	wallet_name: null,
+	balance_points: 0,
+	magento_loyalty: false,
 });
 const loadingWallet = ref(false);
 const walletPaymentMethods = ref(new Set()); // Set of mode_of_payment names that are wallet payments
@@ -2339,6 +2353,8 @@ const walletInfoResource = createResource({
 			wallet_exists: false,
 			wallet_balance: 0,
 			wallet_name: null,
+			balance_points: 0,
+			magento_loyalty: false,
 		};
 		loadingWallet.value = false;
 	},
@@ -2399,6 +2415,30 @@ function isCashPaymentMethod(method) {
 	return name.includes("cash") || name.includes("نقد") || name.includes("نقدي");
 }
 
+// Check if a payment method posts to a Receivable account (requires customer)
+function isReceivablePaymentMethod(method) {
+	if (!method) return false;
+	return (method.account_type || "").toLowerCase() === "receivable";
+}
+
+function getCustomerName() {
+	if (!props.customer) return "";
+	if (typeof props.customer === "string") return props.customer;
+	return props.customer?.name || props.customer?.customer_name || "";
+}
+
+const requiresCustomerForPayment = computed(() => {
+	if (selectedReceivableAccount.value) return true;
+	return paymentEntries.value.some((entry) => {
+		const method = paymentMethods.value.find(
+			(m) => m.mode_of_payment === entry.mode_of_payment,
+		);
+		return isReceivablePaymentMethod(method);
+	});
+});
+
+const hasCustomerForPayment = computed(() => !!getCustomerName());
+
 // Get available wallet balance for payment (considering already added wallet payments)
 const availableWalletBalance = computed(() => {
 	const totalWalletPayments = paymentEntries.value
@@ -2855,6 +2895,11 @@ const canComplete = computed(() => {
 		return false;
 	}
 
+	// Receivable payment modes require a customer on the invoice
+	if (requiresCustomerForPayment.value && !hasCustomerForPayment.value) {
+		return false;
+	}
+
 	// Check exact amount validation
 	if (!isExactAmountValid.value) {
 		return false;
@@ -3030,6 +3075,10 @@ function selectPaymentMethod(method) {
 // invoice's debit_to). It's a destination, not a tendered amount — the outstanding is
 // grand_total minus the cash tendered. Tapping again clears it (back to default Debtors).
 function toggleReceivableAccount(acc) {
+	if (!hasCustomerForPayment.value) {
+		showWarning(__("Please select a customer before paying on account"));
+		return;
+	}
 	selectedReceivableAccount.value = selectedReceivableAccount.value === acc.name ? "" : acc.name;
 	// Drop the active payment-method highlight so only one option looks active at a time.
 	if (selectedReceivableAccount.value) {
@@ -3082,6 +3131,13 @@ function switchToNextPaymentMethod(partialAmount) {
 // Consolidate payment entries: if a row with the same mode already exists,
 // add to it instead of creating a duplicate row.
 function _upsertPaymentEntry(method, amt) {
+	if (isReceivablePaymentMethod(method) && !hasCustomerForPayment.value) {
+		showWarning(
+			__("Please select a customer before paying with {0}", [method.mode_of_payment]),
+		);
+		return;
+	}
+
 	const existing = paymentEntries.value.find(
 		(e) => e.mode_of_payment === method.mode_of_payment && !e.is_customer_credit
 	);
diff --git a/POS/src/components/sale/PromotionManagement.vue b/POS/src/components/sale/PromotionManagement.vue
index b89eb68e2..501937abe 100644
--- a/POS/src/components/sale/PromotionManagement.vue
+++ b/POS/src/components/sale/PromotionManagement.vue
@@ -1020,6 +1020,7 @@
 </template>
 
 <script setup>
+import { promoApi } from "@/utils/promoApi";
 import { usePOSPermissions } from "@/composables/usePermissions";
 import { useToast } from "@/composables/useToast";
 import { useItemSearchStore } from "@/stores/itemSearch";
@@ -1215,7 +1216,7 @@ const itemCodeOptions = computed(() => {
 
 // Resources
 const promotionsResource = createResource({
-	url: "pos_next.api.promotions.get_promotions",
+	url: promoApi.getPromotions(),
 	makeParams() {
 		return {
 			pos_profile: props.posProfile,
@@ -1231,7 +1232,7 @@ const promotionsResource = createResource({
 });
 
 const itemGroupsResource = createResource({
-	url: "pos_next.api.promotions.get_item_groups",
+	url: promoApi.getItemGroups(),
 	makeParams() {
 		return { company: props.company };
 	},
@@ -1246,7 +1247,7 @@ const itemGroupsResource = createResource({
 });
 
 const brandsResource = createResource({
-	url: "pos_next.api.promotions.get_brands",
+	url: promoApi.getBrands(),
 	auto: false,
 	onSuccess(data) {
 		brands.value = data || [];
@@ -1258,7 +1259,7 @@ const brandsResource = createResource({
 });
 
 const savePromotionResource = createResource({
-	url: "pos_next.api.promotions.create_promotion",
+	url: promoApi.createPromotion(),
 	makeParams() {
 		return { data: JSON.stringify(form.value) };
 	},
@@ -1280,7 +1281,7 @@ const savePromotionResource = createResource({
 });
 
 const updatePromotionResource = createResource({
-	url: "pos_next.api.promotions.update_promotion",
+	url: promoApi.updatePromotion(),
 	makeParams() {
 		return {
 			scheme_name: form.value.name,
@@ -1314,7 +1315,7 @@ const updatePromotionResource = createResource({
 });
 
 const toggleResource = createResource({
-	url: "pos_next.api.promotions.toggle_promotion",
+	url: promoApi.togglePromotion(),
 	auto: false,
 	onSuccess() {
 		showSuccess(__("Promotion status updated successfully"));
@@ -1326,7 +1327,7 @@ const toggleResource = createResource({
 });
 
 const deleteResource = createResource({
-	url: "pos_next.api.promotions.delete_promotion",
+	url: promoApi.deletePromotion(),
 	auto: false,
 	onSuccess(data) {
 		const responseData = data?.message || data;
@@ -1351,7 +1352,7 @@ const deleteResource = createResource({
 });
 
 const promotionDetailsResource = createResource({
-	url: "pos_next.api.promotions.get_promotion_details",
+	url: promoApi.getPromotionDetails(),
 	makeParams() {
 		return {
 			scheme_name: selectedPromotion.value?.name,
diff --git a/POS/src/components/sale/ReturnInvoiceDialog.vue b/POS/src/components/sale/ReturnInvoiceDialog.vue
index 49e3c2293..003920924 100644
--- a/POS/src/components/sale/ReturnInvoiceDialog.vue
+++ b/POS/src/components/sale/ReturnInvoiceDialog.vue
@@ -1179,6 +1179,7 @@
 </template>
 
 <script setup>
+import { useAuthorization } from "@/composables/useAuthorization";
 import { useOfflineStatus } from "@/composables/useOfflineStatus";
 import { useToast } from "@/composables/useToast";
 import { getPaymentIcon } from "@/utils/payment";
@@ -1194,6 +1195,9 @@ import { computed, onMounted, onUnmounted, reactive, ref, watch } from "vue";
 
 const { showSuccess, showError, showWarning } = useToast();
 const { isOffline } = useOfflineStatus();
+const { requireAuthorization } = useAuthorization();
+const authorizationToken = ref(null);
+const awaitingAuthorization = ref(false);
 
 // ============================================
 // Constants (hoisted for performance)
@@ -1444,10 +1448,10 @@ const createReturnResource = createResource({
 			doctype: "Sales Invoice",
 			pos_profile: props.posProfile,
 			posa_pos_opening_shift: props.posOpeningShift,
-			customer: baseDoc.customer || originalInvoice.value.customer,
-			company: baseDoc.company || originalInvoice.value.company,
+			customer: baseDoc.customer || originalInvoice.value?.customer,
+			company: baseDoc.company || originalInvoice.value?.company,
 			is_return: 1,
-			return_against: baseDoc.return_against || originalInvoice.value.name,
+			return_against: baseDoc.return_against || originalInvoice.value?.name,
 			// Setting to 0 ensures GL entries point to original invoice,
 			// which reduces its outstanding amount and updates its status
 			update_outstanding_for_self: 0,
@@ -1483,7 +1487,8 @@ const createReturnResource = createResource({
 						mode_of_payment: payment.mode_of_payment,
 						amount: -Math.abs(payment.amount),
 				  })),
-			remarks: returnReason.value || __("Return against {0}", [originalInvoice.value.name]),
+			remarks: returnReason.value || __("Return against {0}", [originalInvoice.value?.name]),
+			authorization_token: authorizationToken.value,
 		};
 
 		// Return in the correct format: invoice as JSON string
@@ -1980,7 +1985,7 @@ function handleKeyboardShortcuts(event) {
 		event.preventDefault();
 		handleCreateReturn();
 	}
-	if (event.key === "Escape") closeReturnModal();
+	if (event.key === "Escape" && !awaitingAuthorization.value) closeReturnModal();
 }
 
 function incrementReturnQuantity(item) {
@@ -2009,6 +2014,34 @@ async function handleCreateReturn() {
 	}
 
 	submitError.value = "";
+
+	const returnAgainst = preparedReturnDoc.value?.return_against || originalInvoice.value?.name;
+	const action = returnAgainst ? "Sales Invoice Return" : "Sales Return Without Invoice";
+
+	authorizationToken.value = null;
+	awaitingAuthorization.value = true;
+	let grant;
+	try {
+		grant = await requireAuthorization(action, {
+			pos_profile: props.posProfile,
+			return_against: returnAgainst,
+			customer: preparedReturnDoc.value?.customer || originalInvoice.value?.customer,
+			amount: returnTotal.value,
+		});
+	} finally {
+		awaitingAuthorization.value = false;
+	}
+
+	if (!grant) return;
+
+	if (!originalInvoice.value) {
+		openErrorDialog(
+			__("This return was closed before authorization completed. Please start again.")
+		);
+		return;
+	}
+
+	authorizationToken.value = grant.grant_token || null;
 	isSubmitting.value = true;
 
 	try {
@@ -2027,6 +2060,7 @@ async function handleCreateReturn() {
 		}
 	} finally {
 		isSubmitting.value = false;
+		authorizationToken.value = null;
 	}
 }
 
diff --git a/POS/src/composables/useAuthorization.js b/POS/src/composables/useAuthorization.js
new file mode 100644
index 000000000..439abe52a
--- /dev/null
+++ b/POS/src/composables/useAuthorization.js
@@ -0,0 +1,111 @@
+import { promoApi } from "@/utils/promoApi";
+import { call } from "@/utils/apiWrapper";
+import { useBootstrapStore } from "@/stores/bootstrap";
+import { logger } from "@/utils/logger";
+import { reactive } from "vue";
+
+const log = logger.create("Authorization");
+
+const state = reactive({
+	open: false,
+	action: null,
+	actionLabel: "",
+	context: null,
+	resolve: null,
+});
+
+function settle(grant) {
+	const resolve = state.resolve;
+	state.open = false;
+	state.action = null;
+	state.actionLabel = "";
+	state.context = null;
+	state.resolve = null;
+	if (resolve) resolve(grant);
+}
+
+export function useAuthorization() {
+	/**
+	 * Whether an action is gated on this POS Profile, per the bootstrap payload.
+	 * @param {string} action
+	 * @returns {boolean}
+	 */
+	function isAuthorizationRequired(action) {
+		const bootstrap = useBootstrapStore();
+		const policy = bootstrap.data?.authorization_policy || {};
+		return Boolean(policy[action]);
+	}
+
+	/**
+	 * Ask for approval, if this action needs it.
+	 *
+	 * @param {string} action Registered action name, e.g. "Sales Invoice Return" — this
+	 *   is both the registry key and its display text (see pos_next.authorization.registry),
+	 *   so it must be the human-readable string, not a snake_case code.
+	 * @param {object} context Passed to the server to bind the grant. Include every value
+	 *   the action's binding uses — for returns that is pos_profile, return_against or
+	 *   customer, and amount.
+	 * @returns {Promise<object|null>} The grant, or null when the user cancelled.
+	 *   Returns a stub grant with no token when the action is not gated, so callers can
+	 *   treat "not required" and "approved" the same way.
+	 */
+	async function requireAuthorization(action, context = {}) {
+		if (!isAuthorizationRequired(action)) {
+			return { grant_token: null, required: false };
+		}
+
+		return new Promise((resolve) => {
+			state.action = action;
+			state.actionLabel = context.actionLabel || "";
+			state.context = context;
+			state.resolve = resolve;
+			state.open = true;
+		});
+	}
+
+	return { requireAuthorization, isAuthorizationRequired };
+}
+
+/**
+ * Internal wiring for <AuthorizationDialog />. Not for general use.
+ */
+export function useAuthorizationDialog() {
+	async function loadAuthorizers() {
+		try {
+			return await call(promoApi.getAuthorizers(), {
+				action: state.action,
+				pos_profile: state.context?.pos_profile,
+				context: JSON.stringify(state.context || {}),
+			});
+		} catch (error) {
+			log.error("Failed to load authorizers", error);
+			return [];
+		}
+	}
+
+	async function requestGrant(approver, pin) {
+		return await call(promoApi.requestGrant(), {
+			action: state.action,
+			approver,
+			pin,
+			context: JSON.stringify(state.context || {}),
+		});
+	}
+
+	/**
+	 * Digits the PIN input should accept, set server-side by POS Authorization
+	 */
+	function pinLength() {
+		const bootstrap = useBootstrapStore();
+		return Number(bootstrap.data?.authorization_pin_length) || 4;
+	}
+
+	return {
+		state,
+		loadAuthorizers,
+		requestGrant,
+		pinLength,
+		approve: (grant) => settle(grant),
+		cancel: () => settle(null),
+	};
+}
diff --git a/POS/src/composables/useInvoice.js b/POS/src/composables/useInvoice.js
index 34b22585c..2a2cb05f8 100644
--- a/POS/src/composables/useInvoice.js
+++ b/POS/src/composables/useInvoice.js
@@ -1,3 +1,4 @@
+import { promoApi } from "@/utils/promoApi";
 import { createResource } from "frappe-ui";
 import { computed, ref, toRaw } from "vue";
 import { isOffline, getCachedItem } from "@/utils/offline";
@@ -82,7 +83,7 @@ export function useInvoice() {
 	});
 
 	const applyOffersResource = createResource({
-		url: "pos_next.api.invoices.apply_offers",
+		url: promoApi.applyOffers(),
 		makeParams({ invoice_data, selected_offers }) {
 			const params = {
 				invoice_data: JSON.stringify(invoice_data),
diff --git a/POS/src/stores/__tests__/posOffers.spec.js b/POS/src/stores/__tests__/posOffers.spec.js
new file mode 100644
index 000000000..eab206052
--- /dev/null
+++ b/POS/src/stores/__tests__/posOffers.spec.js
@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { setActivePinia, createPinia } from "pinia";
+
+vi.mock("@/utils/apiWrapper", () => ({ call: vi.fn() }));
+vi.mock("@/utils/offline", () => ({ isOffline: () => false }));
+vi.mock("@/utils/offline/workerClient", () => ({ offlineWorker: {} }));
+vi.mock("@/utils/offline/db", () => ({
+	getOneTimeRedemptions: vi.fn(), setOneTimeRedemptions: vi.fn(), addOneTimeRedemptions: vi.fn(),
+}));
+vi.mock("@/stores/posShift", () => ({ usePOSShiftStore: () => ({}) }));
+globalThis.__ = (s, args = []) => String(s).replace(/\{(\d+)\}/g, (_, i) => args[i]);
+
+import { usePOSOffersStore } from "@/stores/posOffers";
+
+// Invoice ACC-SINV-2026-00165 / 00167: SKU009 x1 @150 (50% off), 9505 x2 @90.
+// gross = 330, net = 255.
+const SNAPSHOT = {
+	subtotal: 330, netSubtotal: 255, itemCount: 3,
+	itemCodes: ["SKU009", "9505"], itemGroups: ["Demo Item Group"], brands: [],
+	itemQuantities: { SKU009: 1, "9505": 2 },
+	itemGroupQuantities: { "Demo Item Group": 3 },
+	brandQuantities: {},
+	itemAmounts: { SKU009: 150, "9505": 180 },
+	itemGroupAmounts: { "Demo Item Group": 330 },
+	brandAmounts: {},
+};
+
+describe("offer amount gate mirrors the server basis", () => {
+	let store;
+	beforeEach(() => {
+		setActivePinia(createPinia());
+		store = usePOSOffersStore();
+		store.updateCartSnapshot(SNAPSHOT);
+	});
+
+	it("PRLE-0013: Transaction max_amt=260 gates on net 255, not gross 330", () => {
+		const offer = { name: "PRLE-0013", apply_on: "Transaction", max_amt: 260 };
+		expect(store.getEligibleItemAmount(offer)).toBe(255);
+		expect(store.checkOfferEligibility(offer).eligible).toBe(true);
+	});
+
+	it("Transaction rule is still rejected when the net total really exceeds max_amt", () => {
+		const offer = { name: "X", apply_on: "Transaction", max_amt: 200 };
+		expect(store.checkOfferEligibility(offer).eligible).toBe(false);
+	});
+
+	it("Item Code rule gates on that item's gross line amount, not the cart", () => {
+		// SKU009 alone is 150 gross; cart is 330.
+		const offer = { name: "Y", apply_on: "Item Code", eligible_items: ["SKU009"], min_amt: 200 };
+		expect(store.getEligibleItemAmount(offer)).toBe(150);
+		expect(store.checkOfferEligibility(offer).eligible).toBe(false);
+		expect(store.getUnlockAmount(offer)).toBe(50);
+
+		const ok = { ...offer, min_amt: 120 };
+		expect(store.checkOfferEligibility(ok).eligible).toBe(true);
+	});
+
+	it("Item Group rule sums only the matching lines", () => {
+		const offer = {
+			name: "Z", apply_on: "Item Group",
+			eligible_item_groups: ["Demo Item Group"], min_amt: 300,
+		};
+		expect(store.getEligibleItemAmount(offer)).toBe(330);
+		expect(store.checkOfferEligibility(offer).eligible).toBe(true);
+	});
+
+	it("offers with no scope metadata fall back to the gross subtotal", () => {
+		expect(store.getEligibleItemAmount({ name: "W" })).toBe(330);
+	});
+});
diff --git a/POS/src/stores/bootstrap.js b/POS/src/stores/bootstrap.js
index aaa7a273f..69e1ed98e 100644
--- a/POS/src/stores/bootstrap.js
+++ b/POS/src/stores/bootstrap.js
@@ -12,6 +12,7 @@
  */
 
 import { call } from "@/utils/apiWrapper";
+import { isAuthGateInstalled, promoApi } from "@/utils/promoApi";
 import { logger } from "@/utils/logger";
 import { defineStore } from "pinia";
 import { ref } from "vue";
@@ -57,6 +58,21 @@ export const useBootstrapStore = defineStore("bootstrap", () => {
 			const result = await call("pos_next.api.bootstrap.get_initial_data", {});
 
 			if (result?.success) {
+				if (isAuthGateInstalled()) {
+					const profileName = result.pos_profile?.name || result.pos_profile;
+					try {
+						if (profileName) {
+							result.authorization_policy = await call(promoApi.getAuthorizationPolicy(), {
+								pos_profile: profileName,
+							});
+						}
+						const pinInfo = await call(promoApi.hasAuthorizationPin(), {});
+						result.authorization_pin_length =
+							pinInfo?.pin_length || result.authorization_pin_length || 4;
+					} catch (authErr) {
+						log.warn("Promotions auth overlay failed", authErr);
+					}
+				}
 				data.value = result;
 				loaded.value = true;
 				log.success("Bootstrap data loaded", {
diff --git a/POS/src/stores/posOffers.js b/POS/src/stores/posOffers.js
index b11eb3163..0ba2540cd 100644
--- a/POS/src/stores/posOffers.js
+++ b/POS/src/stores/posOffers.js
@@ -1,3 +1,4 @@
+import { promoApi } from "@/utils/promoApi";
 import { defineStore } from "pinia";
 import { computed, ref } from "vue";
 import { call } from "@/utils/apiWrapper";
@@ -77,7 +78,7 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 
 		if (!isOffline()) {
 			try {
-				const resp = await call("pos_next.api.offers.get_customer_one_time_redemptions", {
+				const resp = await call(promoApi.getCustomerOneTimeRedemptions(), {
 					customer: customerName,
 				});
 				const serverRules = resp?.message || resp || [];
@@ -416,7 +417,7 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 				}
 
 				// Online: fetch from API
-				const response = await call("pos_next.api.offers.get_offers", {
+				const response = await call(promoApi.getOffers(), {
 					pos_profile: posProfile,
 				});
 
diff --git a/POS/src/stores/posSettings.js b/POS/src/stores/posSettings.js
index 49f4dcb43..ec9933d7f 100644
--- a/POS/src/stores/posSettings.js
+++ b/POS/src/stores/posSettings.js
@@ -14,6 +14,8 @@ export const usePOSSettingsStore = defineStore("posSettings", () => {
 		wallet_account: "",
 		auto_create_wallet: 1,
 		loyalty_to_wallet: 1,
+		magento_loyalty_available: 0,
+		miraaya_installed: 0,
 		// General Settings
 		max_discount_allowed: 0,
 		use_percentage_discount: 0,
@@ -79,6 +81,8 @@ export const usePOSSettingsStore = defineStore("posSettings", () => {
 	const walletAccount = computed(() => settings.value.wallet_account || "");
 	const autoCreateWallet = computed(() => Boolean(settings.value.auto_create_wallet));
 	const loyaltyToWallet = computed(() => Boolean(settings.value.loyalty_to_wallet));
+	const magentoLoyaltyAvailable = computed(() => Boolean(settings.value.magento_loyalty_available));
+	const miraayaInstalled = computed(() => Boolean(settings.value.miraaya_installed));
 
 	// Computed - General Settings
 	const isEnabled = computed(() => Boolean(settings.value.enabled));
@@ -238,6 +242,8 @@ export const usePOSSettingsStore = defineStore("posSettings", () => {
 			wallet_account: "",
 			auto_create_wallet: 1,
 			loyalty_to_wallet: 1,
+			magento_loyalty_available: 0,
+			miraaya_installed: 0,
 			// General Settings
 			max_discount_allowed: 0,
 			use_percentage_discount: 0,
@@ -349,6 +355,8 @@ export const usePOSSettingsStore = defineStore("posSettings", () => {
 		walletAccount,
 		autoCreateWallet,
 		loyaltyToWallet,
+		magentoLoyaltyAvailable,
+		miraayaInstalled,
 
 		// Computed - General Settings
 		isEnabled,
diff --git a/POS/src/utils/offerSchedule.js b/POS/src/utils/offerSchedule.js
new file mode 100644
index 000000000..a57fa4e30
--- /dev/null
+++ b/POS/src/utils/offerSchedule.js
@@ -0,0 +1,104 @@
+/**
+ * Hour-of-day windows for offers — the client half of `pos_next/promotions/schedule.py`.
+ *
+ * The server ships each offer's window as `{from_time, to_time}` (absent when the
+ * offer runs at any hour) and evaluates it in the **system timezone**. This module
+ * reads the clock in that same zone so an offer switches on and off at the same
+ * instant on the counter as it does on the server, whatever the device is set to.
+ *
+ * Semantics mirror the Python side exactly:
+ *   - no window            -> always active
+ *   - from === to          -> all day
+ *   - from  <  to          -> inside the range
+ *   - from  >  to          -> wraps past midnight (22:00 -> 02:00)
+ */
+
+const SECONDS_PER_DAY = 24 * 60 * 60;
+
+/** Seconds since midnight for "HH:MM:SS", or null if unusable. */
+function toSeconds(value) {
+	if (!value) return null;
+	const parts = String(value).split(":");
+	if (parts.length < 2) return null;
+	const [h, m, s] = parts;
+	const hours = Number.parseInt(h, 10);
+	const minutes = Number.parseInt(m, 10);
+	const seconds = Number.parseInt(s ?? "0", 10);
+	if (Number.isNaN(hours) || Number.isNaN(minutes)) return null;
+	return hours * 3600 + minutes * 60 + (Number.isNaN(seconds) ? 0 : seconds);
+}
+
+/**
+ * Seconds since midnight *in the given timezone*.
+ * @param {string|null} timezone - IANA zone; the device's own zone when null
+ * @param {Date} [now]
+ */
+export function secondsSinceMidnight(timezone, now = new Date()) {
+	try {
+		const parts = new Intl.DateTimeFormat("en-GB", {
+			timeZone: timezone || undefined,
+			hour12: false,
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+		}).formatToParts(now);
+		const get = (type) => Number.parseInt(parts.find((p) => p.type === type)?.value ?? "0", 10);
+		let hour = get("hour");
+		if (hour === 24) hour = 0; // some engines render midnight as 24
+		return hour * 3600 + get("minute") * 60 + get("second");
+	} catch {
+		return now.getHours() * 3600 + now.getMinutes() * 60 + now.getSeconds();
+	}
+}
+
+/** The `{from_time, to_time}` an offer carries, or null when unrestricted. */
+export function getOfferWindow(offer) {
+	const schedule = offer?.schedule;
+	if (!schedule) return null;
+
+	const from = toSeconds(schedule.from_time);
+	const to = toSeconds(schedule.to_time);
+	if (from === null || to === null || from === to) return null;
+
+	return { from, to };
+}
+
+/**
+ * Whether an offer's hour window is open.
+ * @param {Object} offer
+ * @param {string|null} timezone - the site's system timezone
+ */
+export function isOfferInSchedule(offer, timezone, now = new Date()) {
+	const window = getOfferWindow(offer);
+	if (!window) return true;
+
+	const current = secondsSinceMidnight(timezone, now);
+	return window.from < window.to
+		? current >= window.from && current <= window.to
+		: current >= window.from || current <= window.to;
+}
+
+/**
+ * Milliseconds until the next moment any of these offers opens or closes.
+ *
+ * Lets the cart schedule a single timer that fires exactly on the boundary,
+ * rather than polling. Returns null when no offer has a window.
+ */
+export function msUntilNextScheduleBoundary(offers, timezone, now = new Date()) {
+	const current = secondsSinceMidnight(timezone, now);
+	let smallest = null;
+
+	for (const offer of offers || []) {
+		const window = getOfferWindow(offer);
+		if (!window) continue;
+
+		for (const edge of [window.from, window.to]) {
+			// +1s so the timer lands just *after* the boundary, never a hair before.
+			let delta = edge - current + 1;
+			if (delta <= 0) delta += SECONDS_PER_DAY;
+			if (smallest === null || delta < smallest) smallest = delta;
+		}
+	}
+
+	return smallest === null ? null : smallest * 1000;
+}
diff --git a/POS/src/utils/promoApi.js b/POS/src/utils/promoApi.js
new file mode 100644
index 000000000..8779541d9
--- /dev/null
+++ b/POS/src/utils/promoApi.js
@@ -0,0 +1,122 @@
+/**
+ * Runtime API paths for optional POSNext Promotions.
+ *
+ * pos_next never imports the promotions Python package. Vue may call
+ * posnext_promotions.api.* only when that app's extend_bootinfo flag is present.
+ */
+
+export function isPromotionsAppInstalled() {
+	return Boolean(window.frappe?.boot?.posnext_promotions);
+}
+
+export function isAuthGateInstalled() {
+	return Boolean(
+		window.frappe?.boot?.posnext_promotions_auth || window.frappe?.boot?.posnext_promotions,
+	);
+}
+
+export function isMagentoAppInstalled() {
+	return Boolean(window.frappe?.boot?.magento_integration);
+}
+
+function promoOrPos(promoPath, posPath) {
+	return isPromotionsAppInstalled() ? promoPath : posPath;
+}
+
+function authOrPos(promoPath, posPath) {
+	return isAuthGateInstalled() ? promoPath : posPath;
+}
+
+export const promoApi = {
+	applyOffers: () =>
+		promoOrPos("posnext_promotions.api.offers.apply_offers", "pos_next.api.invoices.apply_offers"),
+	getOffers: () => promoOrPos("posnext_promotions.api.offers.get_offers", "pos_next.api.offers.get_offers"),
+	validateCoupon: () =>
+		promoOrPos("posnext_promotions.api.offers.validate_coupon", "pos_next.api.offers.validate_coupon"),
+	getActiveCoupons: () =>
+		promoOrPos(
+			"posnext_promotions.api.offers.get_active_coupons",
+			"pos_next.api.offers.get_active_coupons",
+		),
+	calculateCouponDiscount: () =>
+		promoOrPos(
+			"posnext_promotions.api.offers.calculate_coupon_discount",
+			"pos_next.api.offers.calculate_coupon_discount",
+		),
+	itemHasActivePromotion: () =>
+		promoOrPos(
+			"posnext_promotions.api.offers.item_has_active_promotion",
+			"pos_next.api.offers.item_has_active_promotion",
+		),
+	getCustomerOneTimeRedemptions: () =>
+		promoOrPos(
+			"posnext_promotions.api.offers.get_customer_one_time_redemptions",
+			"pos_next.api.offers.get_customer_one_time_redemptions",
+		),
+	getPromotions: () =>
+		promoOrPos("posnext_promotions.api.promotions.get_promotions", "pos_next.api.promotions.get_promotions"),
+	getPromotionDetails: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.get_promotion_details",
+			"pos_next.api.promotions.get_promotion_details",
+		),
+	createPromotion: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.create_promotion",
+			"pos_next.api.promotions.create_promotion",
+		),
+	updatePromotion: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.update_promotion",
+			"pos_next.api.promotions.update_promotion",
+		),
+	togglePromotion: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.toggle_promotion",
+			"pos_next.api.promotions.toggle_promotion",
+		),
+	deletePromotion: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.delete_promotion",
+			"pos_next.api.promotions.delete_promotion",
+		),
+	getItemGroups: () =>
+		promoOrPos("posnext_promotions.api.promotions.get_item_groups", "pos_next.api.promotions.get_item_groups"),
+	getBrands: () =>
+		promoOrPos("posnext_promotions.api.promotions.get_brands", "pos_next.api.promotions.get_brands"),
+	getCoupons: () =>
+		promoOrPos("posnext_promotions.api.promotions.get_coupons", "pos_next.api.promotions.get_coupons"),
+	getCouponDetails: () =>
+		promoOrPos(
+			"posnext_promotions.api.promotions.get_coupon_details",
+			"pos_next.api.promotions.get_coupon_details",
+		),
+	createCoupon: () =>
+		promoOrPos("posnext_promotions.api.promotions.create_coupon", "pos_next.api.promotions.create_coupon"),
+	updateCoupon: () =>
+		promoOrPos("posnext_promotions.api.promotions.update_coupon", "pos_next.api.promotions.update_coupon"),
+	toggleCoupon: () =>
+		promoOrPos("posnext_promotions.api.promotions.toggle_coupon", "pos_next.api.promotions.toggle_coupon"),
+	deleteCoupon: () =>
+		promoOrPos("posnext_promotions.api.promotions.delete_coupon", "pos_next.api.promotions.delete_coupon"),
+	getAuthorizers: () =>
+		authOrPos(
+			"posnext_promotions.api.authorization.get_authorizers",
+			"pos_next.api.authorization.get_authorizers",
+		),
+	requestGrant: () =>
+		authOrPos(
+			"posnext_promotions.api.authorization.request_grant",
+			"pos_next.api.authorization.request_grant",
+		),
+	getAuthorizationPolicy: () =>
+		authOrPos(
+			"posnext_promotions.api.authorization.get_authorization_policy",
+			"pos_next.api.authorization.get_authorization_policy",
+		),
+	hasAuthorizationPin: () =>
+		authOrPos(
+			"posnext_promotions.api.authorization.has_authorization_pin",
+			"pos_next.api.authorization.has_authorization_pin",
+		),
+};
diff --git a/pos_next/api/bootstrap.py b/pos_next/api/bootstrap.py
index 86fbc28e9..926cf057a 100644
--- a/pos_next/api/bootstrap.py
+++ b/pos_next/api/bootstrap.py
@@ -28,6 +28,7 @@
 from frappe import _
 from frappe.query_builder import DocType
 from frappe.query_builder.functions import Coalesce
+from frappe.utils import get_system_timezone
 
 from pos_next.api.constants import DEFAULT_POS_SETTINGS, POS_SETTINGS_FIELDS
 
@@ -64,6 +65,7 @@ def get_initial_data():
 		"site_name": frappe.local.site,
 		"locale": _get_user_language(),
 		"precision": _get_precision_settings(),
+		"system_timezone": get_system_timezone(),
 		"can_switch_to_desk": "Nexus POS Manager" in frappe.get_roles(),
 		"shift": None,
 		"pos_profile": None,
@@ -223,6 +225,10 @@ def _get_pos_settings(pos_profile_doc):
 		)
 		settings["disable_rounded_total"] = pos_profile_doc.disable_rounded_total or 0
 
+		from pos_next.integrations.registry import extend_bootstrap_settings
+
+		extend_bootstrap_settings(settings, pos_profile_doc.name)
+
 		return settings
 	except Exception:
 		frappe.log_error(frappe.get_traceback(), "Get POS Settings Error")
diff --git a/pos_next/api/constants.py b/pos_next/api/constants.py
index 67ec4319f..ede15a9cc 100644
--- a/pos_next/api/constants.py
+++ b/pos_next/api/constants.py
@@ -39,6 +39,11 @@
 	"enable_session_lock",
 	"session_lock_timeout",
 	"show_variants_as_items",
+	"enable_loyalty_program",
+	"default_loyalty_program",
+	"wallet_account",
+	"auto_create_wallet",
+	"loyalty_to_wallet",
 ]
 
 # Default POS Settings values
@@ -69,4 +74,11 @@
 	"enable_session_lock": 0,
 	"session_lock_timeout": 5,
 	"show_variants_as_items": 0,
+	"enable_loyalty_program": 0,
+	"default_loyalty_program": "",
+	"wallet_account": "",
+	"auto_create_wallet": 1,
+	"loyalty_to_wallet": 1,
+	"magento_loyalty_available": 0,
+	"miraaya_installed": 0,
 }
diff --git a/pos_next/api/customers.py b/pos_next/api/customers.py
index fa396fbd9..b24f80a5b 100644
--- a/pos_next/api/customers.py
+++ b/pos_next/api/customers.py
@@ -6,7 +6,11 @@
 import frappe
 from frappe import _
 
-
+from pos_next.integrations.registry import (
+	after_customer_insert,
+	prepare_customer_doc,
+	validate_customer_create,
+)
 @frappe.whitelist()
 def get_customers(search_term="", pos_profile=None, limit=20, modified_since=None):
 	"""
@@ -83,6 +87,9 @@ def create_customer(
 	pos_profile=None,
 	custom_governorate=None,
 	custom_district=None,
+	custom_first_name=None,
+	custom_last_name=None,
+	custom_is_publish=1,
 ):
 	"""
 	Create a new customer from POS.
@@ -97,6 +104,9 @@ def create_customer(
 	    pos_profile (str): POS Profile (optional, preferred for context-aware loyalty assignment)
 	    custom_governorate (str): Governorate (optional)
 	    custom_district (str): District (optional, must belong to the governorate)
+	    custom_first_name (str): First name for Magento sync (required when masar_miraaya installed)
+	    custom_last_name (str): Last name for Magento sync (required when masar_miraaya installed)
+	    custom_is_publish (int): Publish customer to Magento (default 1)
 
 	Returns:
 	    dict: Created customer document
@@ -108,6 +118,13 @@ def create_customer(
 	if not customer_name:
 		frappe.throw(_("Customer name is required"))
 
+	validate_customer_create(
+		customer_name=customer_name,
+		email_id=email_id,
+		custom_first_name=custom_first_name,
+		custom_last_name=custom_last_name,
+	)
+
 	loyalty_program = get_default_loyalty_program_from_settings(
 		company=company,
 		pos_profile=pos_profile,
@@ -145,10 +162,26 @@ def create_customer(
 		}
 	)
 
+	publish_to_magento = prepare_customer_doc(
+		customer,
+		custom_first_name=custom_first_name,
+		custom_last_name=custom_last_name,
+		custom_is_publish=custom_is_publish,
+	)
+
 	frappe.flags.pos_next_customer_company = company
 	frappe.flags.pos_next_customer_pos_profile = pos_profile
 	try:
 		customer.insert()
+		if publish_to_magento:
+			after_customer_insert(
+				customer,
+				email_id=email_id,
+				mobile_no=mobile_no,
+				custom_first_name=custom_first_name,
+				custom_last_name=custom_last_name,
+				custom_is_publish=custom_is_publish,
+			)
 	finally:
 		frappe.flags.pos_next_customer_company = None
 		frappe.flags.pos_next_customer_pos_profile = None
diff --git a/pos_next/api/pos_profile.py b/pos_next/api/pos_profile.py
index 3ac2f2cb4..db9150bd6 100644
--- a/pos_next/api/pos_profile.py
+++ b/pos_next/api/pos_profile.py
@@ -4,6 +4,7 @@
 
 import frappe
 from frappe import _
+from frappe.utils import cint
 
 from pos_next.api.utilities import _parse_list_parameter, check_user_company
 
@@ -81,6 +82,9 @@ def get_pos_settings(pos_profile):
 		if not pos_settings:
 			return DEFAULT_POS_SETTINGS.copy()
 
+		from pos_next.integrations.registry import extend_bootstrap_settings
+
+		extend_bootstrap_settings(pos_settings, pos_profile)
 		return pos_settings
 	except Exception:
 		frappe.log_error(frappe.get_traceback(), "Get POS Settings Error")
diff --git a/pos_next/api/sales_invoice_hooks.py b/pos_next/api/sales_invoice_hooks.py
index 85537c7c1..3963ae7f2 100644
--- a/pos_next/api/sales_invoice_hooks.py
+++ b/pos_next/api/sales_invoice_hooks.py
@@ -16,6 +16,7 @@ def validate(doc, method=None):
 	Validate hook for Sales Invoice.
 	Apply tax inclusive settings based on POS Profile configuration.
 	Auto-assign loyalty program to customer if enabled.
+	Keep return invoices aligned with the original invoice's loyalty program.
 
 	Args:
 		doc: Sales Invoice document
@@ -23,6 +24,7 @@ def validate(doc, method=None):
 	"""
 	apply_tax_inclusive(doc)
 	auto_assign_loyalty_program_on_invoice(doc)
+	sync_return_loyalty_program(doc)
 
 
 def apply_tax_inclusive(doc):
@@ -75,16 +77,28 @@ def auto_assign_loyalty_program_on_invoice(doc):
 	but customer doesn't have a loyalty program yet.
 
 	This ensures customers created before loyalty was enabled can still earn points.
+	The invoice itself must also carry loyalty_program — ERPNext's on_submit
+	checks the invoice field, not the customer.
 
 	Args:
 		doc: Sales Invoice document
 	"""
+	if doc.get("is_return"):
+		return
+
 	if not doc.is_pos or not doc.pos_profile or not doc.customer:
 		return
 
+	from pos_next.integrations.registry import is_external_loyalty_mode
+
+	if is_external_loyalty_mode(doc.pos_profile):
+		return
+
 	# Check if customer already has a loyalty program
 	customer_loyalty = frappe.db.get_value("Customer", doc.customer, "loyalty_program")
 	if customer_loyalty:
+		if not doc.loyalty_program:
+			doc.loyalty_program = customer_loyalty
 		return
 
 	# Get POS Settings
@@ -105,8 +119,26 @@ def auto_assign_loyalty_program_on_invoice(doc):
 	if not loyalty_program:
 		return
 
-	# Assign loyalty program to customer
+	# Assign loyalty program to customer and this invoice
 	frappe.db.set_value("Customer", doc.customer, "loyalty_program", loyalty_program, update_modified=False)
+	if not doc.loyalty_program:
+		doc.loyalty_program = loyalty_program
+
+
+def sync_return_loyalty_program(doc):
+	"""Keep credit notes on the original invoice's loyalty program.
+
+	Sales Invoice.loyalty_program is no_copy and fetch_from customer.loyalty_program.
+	If the customer was enrolled after the original invoice was submitted, the
+	credit note would pick up that program and ERPNext would recalculate loyalty
+	on an original invoice whose loyalty_program is empty — raising
+	DoesNotExistError: Loyalty Program None not found.
+	"""
+	if not doc.get("is_return") or not doc.get("return_against"):
+		return
+
+	original_program = frappe.db.get_value("Sales Invoice", doc.return_against, "loyalty_program")
+	doc.loyalty_program = original_program or None
 
 
 def record_one_time_offer_usage(doc, method=None):
diff --git a/pos_next/api/wallet.py b/pos_next/api/wallet.py
index 59bb8084b..8c43fca71 100644
--- a/pos_next/api/wallet.py
+++ b/pos_next/api/wallet.py
@@ -10,6 +10,11 @@
 from frappe import _
 from frappe.utils import cint, flt
 
+from pos_next.integrations.registry import (
+	get_external_loyalty_balance,
+	is_external_loyalty_mode,
+)
+
 
 def validate_wallet_payment(doc, method=None):
 	"""
@@ -26,7 +31,9 @@ def validate_wallet_payment(doc, method=None):
 		return
 
 	# Get customer wallet balance
-	wallet_balance = get_customer_wallet_balance(doc.customer, doc.company, exclude_invoice=doc.name)
+	wallet_balance = get_customer_wallet_balance(
+		doc.customer, doc.company, exclude_invoice=doc.name, pos_profile=doc.pos_profile
+	)
 
 	if wallet_amount > wallet_balance:
 		frappe.throw(
@@ -43,6 +50,9 @@ def process_loyalty_to_wallet(doc, method=None):
 	Convert earned loyalty points to wallet balance after invoice submission.
 	Called during on_submit hook.
 	"""
+	if is_external_loyalty_mode(doc.pos_profile):
+		return
+
 	if not doc.is_pos or doc.is_return:
 		return
 
@@ -142,21 +152,47 @@ def get_wallet_amount_from_payments(payments):
 	Calculate total wallet payment amount from invoice payments.
 	"""
 	wallet_amount = 0.0
+	if not payments:
+		return wallet_amount
 
+	wallet_modes = _get_wallet_payment_modes()
 	for payment in payments:
-		if not payment.mode_of_payment:
+		mode_of_payment = payment.get("mode_of_payment") if isinstance(payment, dict) else payment.mode_of_payment
+		if not mode_of_payment:
 			continue
 
-		is_wallet = frappe.db.get_value("Mode of Payment", payment.mode_of_payment, "is_wallet_payment")
-
-		if is_wallet:
-			wallet_amount += flt(payment.amount)
+		if wallet_modes.get(mode_of_payment):
+			amount = payment.get("amount") if isinstance(payment, dict) else payment.amount
+			wallet_amount += flt(amount)
 
 	return wallet_amount
 
 
+def get_wallet_amount_for_sales_invoice(invoice_name, payments=None):
+	"""Return wallet/LP payment total for a submitted Sales Invoice."""
+	if payments is None:
+		payments = frappe.get_all(
+			"Sales Invoice Payment",
+			filters={"parent": invoice_name},
+			fields=["mode_of_payment", "amount"],
+		)
+	return get_wallet_amount_from_payments(payments)
+
+
+def _get_wallet_payment_modes():
+	"""Return a cached map of wallet-enabled Mode of Payment names."""
+	modes = frappe.cache().get_value("pos_next_wallet_payment_modes")
+	if modes is None:
+		modes = {
+			row.name: 1
+			for row in frappe.get_all("Mode of Payment", filters={"is_wallet_payment": 1}, fields=["name"])
+		}
+		frappe.cache().set_value("pos_next_wallet_payment_modes", modes)
+	return modes
+
+
 @frappe.whitelist()
-def get_customer_wallet_balance(customer, company=None, exclude_invoice=None):
+def get_customer_wallet_balance(customer, company=None, exclude_invoice=None, pos_profile=None):
 	"""
 	Get customer's available wallet balance.
 
@@ -164,14 +200,25 @@ def get_customer_wallet_balance(customer, company=None, exclude_invoice=None):
 	- Negative GL balance = customer has credit (we owe them) = positive wallet balance
 	- Positive GL balance = customer owes us = no wallet balance
 
+	When masar_miraaya is active, returns Magento LP balance (balance_iqd).
+
 	Args:
 		customer: Customer ID
 		company: Company (optional)
 		exclude_invoice: Invoice name to exclude from pending calculations
+		pos_profile: POS Profile (optional, used for Magento loyalty mode)
 
 	Returns:
 		float: Available wallet balance
 	"""
+	if is_external_loyalty_mode(pos_profile):
+		try:
+			balance = get_external_loyalty_balance(customer)
+			return flt(balance.get("balance_iqd")) if balance else 0.0
+		except Exception:
+			frappe.log_error(frappe.get_traceback(), "Magento LP Balance Error")
+			return 0.0
+
 	try:
 		from erpnext.accounts.utils import get_balance_on
 
@@ -261,6 +308,9 @@ def create_wallet_on_customer_insert(doc, method=None):
 	if not pos_profile:
 		return
 
+	if is_external_loyalty_mode(pos_profile):
+		return
+
 	pos_settings = get_pos_settings(pos_profile)
 	if not pos_settings or not cint(pos_settings.get("auto_create_wallet")):
 		return
@@ -394,6 +444,8 @@ def get_wallet_info(customer, company, pos_profile=None):
 		"auto_create": False,
 		"loyalty_program": None,
 		"loyalty_to_wallet": False,
+		"balance_points": 0.0,
+		"magento_loyalty": False,
 	}
 
 	# Check if loyalty program is enabled in POS Settings
@@ -409,6 +461,20 @@ def get_wallet_info(customer, company, pos_profile=None):
 	if not result["wallet_enabled"]:
 		return result
 
+	if is_external_loyalty_mode(pos_profile):
+		result["magento_loyalty"] = True
+		result["wallet_exists"] = True
+		try:
+			balance = get_external_loyalty_balance(customer)
+			result["wallet_balance"] = flt(balance.get("balance_iqd"))
+			result["balance_points"] = flt(balance.get("balance_points"))
+		except Exception as exc:
+			frappe.log_error(
+				title="Magento LP Balance Error",
+				message=f"Customer: {customer}, Error: {exc!s}\n{frappe.get_traceback()}",
+			)
+		return result
+
 	# Get wallet details (support both pos_next and wallete status values)
 	wallet = frappe.db.get_value(
 		"Wallet",
@@ -420,7 +486,9 @@ def get_wallet_info(customer, company, pos_profile=None):
 	if wallet:
 		result["wallet_exists"] = True
 		result["wallet_name"] = wallet.name
-		result["wallet_balance"] = get_customer_wallet_balance(customer, company)
+		result["wallet_balance"] = get_customer_wallet_balance(
+			customer, company, pos_profile=pos_profile
+		)
 	elif result["auto_create"]:
 		# Auto-create wallet for customer if enabled
 		try:
diff --git a/pos_next/hooks.py b/pos_next/hooks.py
index 534680d70..dc72f00d6 100644
--- a/pos_next/hooks.py
+++ b/pos_next/hooks.py
@@ -274,6 +274,15 @@
 # }
 
 
+
+# Extension points consumed by POS Next, implemented by optional apps
+pos_next_loyalty_provider = []
+pos_next_bootstrap_settings = []
+pos_next_customer_validators = []
+pos_next_customer_prepare = []
+pos_next_customer_after_insert = []
+
+
 website_route_rules = [
 	{"from_route": "/pos/<path:app_path>", "to_route": "pos"},
 ]
diff --git a/pos_next/integrations/__init__.py b/pos_next/integrations/__init__.py
new file mode 100644
index 000000000..39ea298d8
--- /dev/null
+++ b/pos_next/integrations/__init__.py
@@ -0,0 +1 @@
+"""Optional integration hooks for POS Next extension apps."""
diff --git a/pos_next/integrations/registry.py b/pos_next/integrations/registry.py
new file mode 100644
index 000000000..6c4856419
--- /dev/null
+++ b/pos_next/integrations/registry.py
@@ -0,0 +1,67 @@
+"""Integration registry for optional POS Next extension apps."""
+
+from __future__ import annotations
+
+import frappe
+
+
+def get_loyalty_provider():
+	for method_path in frappe.get_hooks("pos_next_loyalty_provider") or []:
+		try:
+			provider = frappe.get_attr(method_path)()
+			if provider:
+				return provider
+		except Exception:
+			frappe.log_error(frappe.get_traceback(), f"Loyalty provider hook failed: {method_path}")
+	return None
+
+
+def is_external_loyalty_available():
+	provider = get_loyalty_provider()
+	if not provider:
+		return False
+	is_available = provider.get("is_available")
+	return bool(is_available()) if is_available else False
+
+
+def is_external_loyalty_mode(pos_profile):
+	provider = get_loyalty_provider()
+	if not provider:
+		return False
+	is_loyalty_mode = provider.get("is_loyalty_mode")
+	return bool(is_loyalty_mode(pos_profile)) if is_loyalty_mode else False
+
+
+def get_external_loyalty_balance(customer):
+	provider = get_loyalty_provider()
+	if not provider:
+		return None
+	get_balance = provider.get("get_balance")
+	return get_balance(customer) if get_balance else None
+
+
+def extend_bootstrap_settings(settings, pos_profile=None):
+	for method_path in frappe.get_hooks("pos_next_bootstrap_settings") or []:
+		try:
+			frappe.get_attr(method_path)(settings, pos_profile)
+		except Exception:
+			frappe.log_error(frappe.get_traceback(), f"Bootstrap settings hook failed: {method_path}")
+
+
+def validate_customer_create(**kwargs):
+	for method_path in frappe.get_hooks("pos_next_customer_validators") or []:
+		frappe.get_attr(method_path)(**kwargs)
+
+
+def prepare_customer_doc(customer, **kwargs):
+	publish_to_magento = False
+	for method_path in frappe.get_hooks("pos_next_customer_prepare") or []:
+		result = frappe.get_attr(method_path)(customer, **kwargs)
+		if result:
+			publish_to_magento = True
+	return publish_to_magento
+
+
+def after_customer_insert(customer, **kwargs):
+	for method_path in frappe.get_hooks("pos_next_customer_after_insert") or []:
+		frappe.get_attr(method_path)(customer, **kwargs)
diff --git a/pos_next/overrides/sales_invoice.py b/pos_next/overrides/sales_invoice.py
index 144b9c731..dc14f5aa6 100644
--- a/pos_next/overrides/sales_invoice.py
+++ b/pos_next/overrides/sales_invoice.py
@@ -8,49 +8,12 @@
 """
 
 import frappe
+from frappe import _
 from erpnext.accounts.doctype.sales_invoice.sales_invoice import SalesInvoice
 from erpnext.accounts.utils import get_account_currency
 from frappe.utils import cint, flt
 
 
-def _find_paid_bundle_row_for_free(si_doc, free_row):
-	"""Pick the paid SI item row whose bundle qty should absorb this free bundle's packed items."""
-	candidates = []
-	for row in si_doc.get("items"):
-		if row.name == free_row.name or cint(row.is_free_item):
-			continue
-		if row.item_code != free_row.item_code:
-			continue
-		if (row.warehouse or "") != (free_row.warehouse or ""):
-			continue
-		candidates.append(row)
-	if not candidates:
-		return None
-	free_idx = free_row.idx or 0
-	before = [r for r in candidates if (r.idx or 0) < free_idx]
-	if before:
-		return max(before, key=lambda r: r.idx or 0)
-	return candidates[0]
-
-
-def _find_matching_packed_item_for_merge(si_doc, paid_row, component_item_code, warehouse):
-	"""Match a packed item on the paid bundle line; prefer same warehouse."""
-	w = warehouse or ""
-	matches = []
-	for pi in si_doc.get("packed_items"):
-		if pi.parent_detail_docname != paid_row.name:
-			continue
-		if pi.parent_item != paid_row.item_code:
-			continue
-		if pi.item_code != component_item_code:
-			continue
-		matches.append(pi)
-	if not matches:
-		return None
-	for pi in matches:
-		if (pi.warehouse or "") == w:
-			return pi
-	return matches[0]
 
 
 def _get_post_change_gl_entries_setting():
@@ -86,6 +49,21 @@ def _get_post_change_gl_entries_setting():
 	return cint(result[0][0]) if result else 0
 
 
+def _resolve_pos_customer(invoice_doc):
+	"""Return a valid Customer name for POS invoices, or None."""
+	customer = (invoice_doc.get("customer") or "").strip()
+	if customer and frappe.db.exists("Customer", customer):
+		return customer
+
+	pos_profile = invoice_doc.get("pos_profile")
+	if pos_profile:
+		default_customer = frappe.db.get_value("POS Profile", pos_profile, "customer")
+		if default_customer and frappe.db.exists("Customer", default_customer):
+			return default_customer
+
+	return None
+
+
 class CustomSalesInvoice(SalesInvoice):
 	"""
 	Custom Sales Invoice class that handles wallet payments correctly.
@@ -95,9 +73,38 @@ class CustomSalesInvoice(SalesInvoice):
 	for wallet payment methods marked with is_wallet_payment.
 	"""
 
+	def validate(self):
+		if cint(self.is_pos):
+			self._ensure_pos_customer()
+			self._validate_pos_payment_accounts()
+		super().validate()
+
+	def on_submit(self):
+		# Re-align after fetch_from so ERPNext's loyalty branch does not run on a
+		# credit note whose original invoice has no loyalty_program.
+		from pos_next.api.sales_invoice_hooks import sync_return_loyalty_program
+
+		sync_return_loyalty_program(self)
+		super().on_submit()
+
+	def _ensure_pos_customer(self):
+		"""POS invoices always need a customer for Receivable GL entries (debit_to)."""
+		customer = _resolve_pos_customer(self)
+		if not customer:
+			frappe.throw(
+				_(
+					"Customer is required. Please select a customer or configure a default customer in POS Profile."
+				),
+				title=_("Customer Required"),
+			)
+
+		self.customer = customer
+		if not self.customer_name:
+			self.customer_name = frappe.db.get_value("Customer", customer, "customer_name")
+
 	def make_pos_gl_entries(self, gl_entries):
 		"""
-		Override to add party information for wallet payment accounts.
+		Override to add party information for wallet / receivable payment accounts.
 
 		The standard ERPNext implementation doesn't set party_type/party for
 		payment mode accounts, which causes validation errors for Receivable
@@ -110,67 +117,82 @@ def make_pos_gl_entries(self, gl_entries):
 				if skip_change_gl_entries and payment_mode.account == self.account_for_change_amount:
 					payment_mode.base_amount -= flt(self.change_amount)
 
-				if payment_mode.amount:
-					# POS, make payment entries
-					# Credit entry to debit_to (customer receivable)
-					gl_entries.append(
-						self.get_gl_dict(
-							{
-								"account": self.debit_to,
-								"party_type": "Customer",
-								"party": self.customer,
-								"against": payment_mode.account,
-								"credit": payment_mode.base_amount,
-								"credit_in_account_currency": payment_mode.base_amount
-								if self.party_account_currency == self.company_currency
-								else payment_mode.amount,
-								"against_voucher": self.return_against
-								if cint(self.is_return) and self.return_against
-								else self.name,
-								"against_voucher_type": self.doctype,
-								"cost_center": self.cost_center,
-							},
-							self.party_account_currency,
-							item=self,
-						)
-					)
+				against_voucher = self.name
+				if self.is_return and self.return_against and not self.update_outstanding_for_self:
+					against_voucher = self.return_against
 
-					# Debit entry to payment mode account
-					payment_mode_account_currency = get_account_currency(payment_mode.account)
+				payment_amount = flt(payment_mode.base_amount) or flt(payment_mode.amount)
+				if not payment_amount:
+					continue
 
-					# Get party info for wallet payments
-					party_type, party = self.get_party_and_party_type_for_pos_gl_entry(
-						payment_mode.mode_of_payment, payment_mode.account
+				# Credit customer receivable (payment received against the invoice)
+				gl_entries.append(
+					self.get_gl_dict(
+						{
+							"account": self.debit_to,
+							"party_type": "Customer",
+							"party": self.customer,
+							"against": payment_mode.account,
+							"credit": payment_amount,
+							"credit_in_account_currency": payment_amount
+							if self.party_account_currency == self.company_currency
+							else payment_mode.amount,
+							"against_voucher": against_voucher,
+							"against_voucher_type": self.doctype,
+							"cost_center": self.cost_center,
+						},
+						self.party_account_currency,
+						item=self,
 					)
-
-					gl_entries.append(
-						self.get_gl_dict(
-							{
-								"account": payment_mode.account,
-								"party_type": party_type,
-								"party": party,
-								"against": self.customer,
-								"debit": payment_mode.base_amount,
-								"debit_in_account_currency": payment_mode.base_amount
-								if payment_mode_account_currency == self.company_currency
-								else payment_mode.amount,
-								"cost_center": self.cost_center,
-							},
-							payment_mode_account_currency,
-							item=self,
-						)
+				)
+
+				# Debit the payment-mode account (Cash/Bank/another Receivable, etc.)
+				payment_mode_account_currency = get_account_currency(payment_mode.account)
+				party_type, party = self.get_party_and_party_type_for_pos_gl_entry(
+					payment_mode.mode_of_payment, payment_mode.account
+				)
+
+				gl_entries.append(
+					self.get_gl_dict(
+						{
+							"account": payment_mode.account,
+							"party_type": party_type,
+							"party": party,
+							"against": self.customer,
+							"debit": payment_amount,
+							"debit_in_account_currency": payment_amount
+							if payment_mode_account_currency == self.company_currency
+							else payment_mode.amount,
+							"cost_center": self.cost_center,
+						},
+						payment_mode_account_currency,
+						item=self,
 					)
+				)
 
 			if not skip_change_gl_entries:
 				if hasattr(self, "get_gle_for_change_amount"):
-					# ERPNext v16+: Method renamed and returns a list of GL entries
-					# that needs to be extended to the main gl_entries list
 					gl_entries.extend(self.get_gle_for_change_amount())
 				else:
-					# ERPNext v15: Method takes gl_entries as parameter
-					# and appends change amount entries directly to it
 					self.make_gle_for_change_amount(gl_entries)
 
+	def _validate_pos_payment_accounts(self):
+		"""Payment modes must not post to the same account as debit_to."""
+		if not self.payments or not self.debit_to:
+			return
+
+		for payment in self.payments:
+			if not payment.account or not flt(payment.amount):
+				continue
+			if payment.account == self.debit_to:
+				frappe.throw(
+					_(
+						"Mode of Payment {0} uses account {1}, which is the same as the invoice receivable account. "
+						"Please set a Cash or Bank account on the Mode of Payment."
+					).format(payment.mode_of_payment, self.debit_to),
+					title=_("Invalid Payment Account"),
+				)
+
 	def validate_pos_paid_amount(self):
 		"""
 		Allow POS sales to submit without a payment row in two cases:
@@ -195,25 +217,46 @@ def validate_pos_paid_amount(self):
 
 	def get_party_and_party_type_for_pos_gl_entry(self, mode_of_payment, account):
 		"""
-		Get party type and party for wallet payment GL entries.
+		Get party type and party for POS payment GL entries.
 
-		For wallet payments (Mode of Payment with is_wallet_payment=1),
-		returns Customer as party_type and the invoice customer as party.
-		For regular payments, returns empty strings.
+		ERPNext requires party on GL entries against Receivable/Payable accounts.
+		Wallet modes and any payment mode linked to a Receivable account need the
+		invoice customer as party.
 		"""
+		party_type, party = "", ""
+
+		if not account or not self.customer:
+			return party_type, party
+
 		is_wallet_mode_of_payment = frappe.db.get_value(
 			"Mode of Payment", mode_of_payment, "is_wallet_payment"
 		)
+		account_type = frappe.get_cached_value("Account", account, "account_type")
 
-		party_type, party = "", ""
-		if is_wallet_mode_of_payment:
+		if is_wallet_mode_of_payment or account_type == "Receivable":
 			party_type, party = "Customer", self.customer
 
 		return party_type, party
 
+	def make_loyalty_point_entry(self):
+		"""Skip ERPNext loyalty ledger when this invoice has no program.
+
+		Return invoices copy-map with no_copy on loyalty_program, then fetch the
+		customer's current program. ERPNext then recalculates points on the
+		original invoice. If that original has loyalty_program=None,
+		get_loyalty_program_details_with_points does get_doc("Loyalty Program", None).
+		"""
+		if not self.loyalty_program:
+			return
+		return super().make_loyalty_point_entry()
+
+	def set_loyalty_program_tier(self):
+		if not self.loyalty_program:
+			return
+		return super().set_loyalty_program_tier()
+
 	def update_packing_list(self):
 		super().update_packing_list()
-		self._combine_packed_qty_for_free_product_bundles()
 		self._set_use_serial_batch_fields_on_packed_items()
 
 	def _set_use_serial_batch_fields_on_packed_items(self):
@@ -242,40 +285,3 @@ def _set_use_serial_batch_fields_on_packed_items(self):
 			if tracking.has_batch_no or tracking.has_serial_no:
 				pi.use_serial_batch_fields = 1
 
-	def _combine_packed_qty_for_free_product_bundles(self):
-		"""
-		Merge packed_items from free bundle lines into the matching paid bundle line.
-
-		ERPNext builds packed rows per Sales Invoice Item row. For BOGO / pricing-rule
-		free rows, the same product bundle often appears twice (paid + is_free_item).
-		That duplicates component rows. Stock and picking should follow total bundle
-		qty on one set of packed lines tied to the paid row.
-		"""
-		if self.is_return or not self.get("packed_items"):
-			return
-
-		free_bundle_rows = [
-			row
-			for row in self.get("items")
-			if row.item_code and cint(row.is_free_item) and self.has_product_bundle(row.item_code)
-		]
-		if not free_bundle_rows:
-			return
-
-		for free_row in free_bundle_rows:
-			paid_row = _find_paid_bundle_row_for_free(self, free_row)
-			if not paid_row:
-				continue
-
-			to_remove = []
-			for pi in list(self.get("packed_items")):
-				if pi.parent_detail_docname != free_row.name or pi.parent_item != free_row.item_code:
-					continue
-				tgt = _find_matching_packed_item_for_merge(self, paid_row, pi.item_code, pi.warehouse)
-				if tgt:
-					prec = tgt.precision("qty")
-					tgt.qty = flt(flt(tgt.qty) + flt(pi.qty), prec)
-					to_remove.append(pi)
-
-			for pi in to_remove:
-				self.remove(pi)
diff --git a/pos_next/pos_next/doctype/pos_settings/pos_settings.py b/pos_next/pos_next/doctype/pos_settings/pos_settings.py
index f7dc2babd..d9244a0e1 100644
--- a/pos_next/pos_next/doctype/pos_settings/pos_settings.py
+++ b/pos_next/pos_next/doctype/pos_settings/pos_settings.py
@@ -116,6 +116,10 @@ def get_pos_settings(pos_profile):
 		frappe.db.get_single_value("Stock Settings", "allow_negative_stock") or 0
 	)
 
+	from pos_next.integrations.registry import extend_bootstrap_settings
+
+	extend_bootstrap_settings(settings, pos_profile)
+
 	return settings
 
 
diff --git a/pos_next/public/js/pricing_rule.js b/pos_next/public/js/pricing_rule.js
index 45c2fab92..04d3df6a8 100644
--- a/pos_next/public/js/pricing_rule.js
+++ b/pos_next/public/js/pricing_rule.js
@@ -1,31 +1,39 @@
 // Copyright (c) 2026, BrainWise and contributors
 // For license information, please see license.txt
 
+// Frappe concatenates every app's doctype_js into one Function. Yield to
+// posnext_promotions when it is installed so the two copies do not redeclare
+// const or double-bind handlers.
+(function () {
+	if (frappe.boot && frappe.boot.posnext_promotions) {
+		return;
+	}
 
-frappe.ui.form.on("Pricing Rule", {
-	refresh(frm) {
-		pn_toggle_min_max(frm);
-	},
-	apply_discount_on_price(frm) {
-		pn_toggle_min_max(frm);
-	},
-});
+	frappe.ui.form.on("Pricing Rule", {
+		refresh(frm) {
+			pn_toggle_min_max(frm);
+		},
+		apply_discount_on_price(frm) {
+			pn_toggle_min_max(frm);
+		},
+	});
 
-function pn_toggle_min_max(frm) {
-	const is_min_max = ["Min", "Max"].includes(frm.doc.apply_discount_on_price);
-	if (is_min_max && !frm.doc.mixed_conditions) {
-		frm.set_value("mixed_conditions", 1);
+	function pn_toggle_min_max(frm) {
+		const is_min_max = ["Min", "Max"].includes(frm.doc.apply_discount_on_price);
+		if (is_min_max && !frm.doc.mixed_conditions) {
+			frm.set_value("mixed_conditions", 1);
+		}
+		frm.set_df_property("mixed_conditions", "read_only", is_min_max ? 1 : 0);
+		frm.set_df_property(
+			"mixed_conditions",
+			"description",
+			is_min_max
+				? __(
+						"Automatically enabled and locked because <b>Apply Discount On</b> is set to Min/Max. " +
+							"A cheapest/most-expensive-item discount must evaluate all document items together " +
+							"(not line by line), which requires Mixed Conditions. Clear <b>Apply Discount On</b> to edit this."
+					)
+				: ""
+		);
 	}
-	frm.set_df_property("mixed_conditions", "read_only", is_min_max ? 1 : 0);
-	frm.set_df_property(
-		"mixed_conditions",
-		"description",
-		is_min_max
-			? __(
-					"Automatically enabled and locked because <b>Apply Discount On</b> is set to Min/Max. " +
-						"A cheapest/most-expensive-item discount must evaluate all document items together " +
-						"(not line by line), which requires Mixed Conditions. Clear <b>Apply Discount On</b> to edit this."
-				)
-			: ""
-	);
-}
+})();
diff --git a/pos_next/public/js/promotional_scheme.js b/pos_next/public/js/promotional_scheme.js
index fcf60b514..4aad45aa5 100644
--- a/pos_next/public/js/promotional_scheme.js
+++ b/pos_next/public/js/promotional_scheme.js
@@ -1,38 +1,47 @@
 // Copyright (c) 2026, BrainWise and contributors
 // For license information, please see license.txt
 
-frappe.ui.form.on("Promotional Scheme", {
-	refresh(frm) {
-		pn_sync_min_max(frm);
-	},
-	price_discount_slabs_remove(frm) {
-		pn_sync_min_max(frm);
-	},
-});
+// Frappe concatenates every app's doctype_js into one Function. Yield to
+// posnext_promotions when it is installed so the two copies do not redeclare
+// const or double-bind handlers.
+(function () {
+	if (frappe.boot && frappe.boot.posnext_promotions) {
+		return;
+	}
+
+	frappe.ui.form.on("Promotional Scheme", {
+		refresh(frm) {
+			pn_sync_min_max(frm);
+		},
+		price_discount_slabs_remove(frm) {
+			pn_sync_min_max(frm);
+		},
+	});
 
-frappe.ui.form.on("Promotional Scheme Price Discount", {
-	apply_discount_on_price(frm) {
-		pn_sync_min_max(frm);
-	},
-});
+	frappe.ui.form.on("Promotional Scheme Price Discount", {
+		apply_discount_on_price(frm) {
+			pn_sync_min_max(frm);
+		},
+	});
 
-function pn_sync_min_max(frm) {
-	const has_min_max = (frm.doc.price_discount_slabs || []).some((row) =>
-		["Min", "Max"].includes(row.apply_discount_on_price)
-	);
-	if (has_min_max && !frm.doc.mixed_conditions) {
-		frm.set_value("mixed_conditions", 1);
+	function pn_sync_min_max(frm) {
+		const has_min_max = (frm.doc.price_discount_slabs || []).some((row) =>
+			["Min", "Max"].includes(row.apply_discount_on_price)
+		);
+		if (has_min_max && !frm.doc.mixed_conditions) {
+			frm.set_value("mixed_conditions", 1);
+		}
+		frm.set_df_property("mixed_conditions", "read_only", has_min_max ? 1 : 0);
+		frm.set_df_property(
+			"mixed_conditions",
+			"description",
+			has_min_max
+				? __(
+						"Automatically enabled and locked because a price discount row uses a Min/Max discount. " +
+							"A cheapest/most-expensive-item discount must evaluate all document items together " +
+							"which requires Mixed Conditions. Remove the Min/Max rows to edit this."
+					)
+				: ""
+		);
 	}
-	frm.set_df_property("mixed_conditions", "read_only", has_min_max ? 1 : 0);
-	frm.set_df_property(
-		"mixed_conditions",
-		"description",
-		has_min_max
-			? __(
-					"Automatically enabled and locked because a price discount row uses a Min/Max discount. " +
-						"A cheapest/most-expensive-item discount must evaluate all document items together " +
-						"which requires Mixed Conditions. Remove the Min/Max rows to edit this."
-				)
-			: ""
-	);
-}
+})();
diff --git a/pos_next/test_no_promotions_import.py b/pos_next/test_no_promotions_import.py
new file mode 100644
index 000000000..915285a2f
--- /dev/null
+++ b/pos_next/test_no_promotions_import.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2026, BrainWise and contributors
+"""pos_next must not import posnext_promotions (compose only via Frappe hooks / Vue boot)."""
+
+from __future__ import annotations
+
+import ast
+import unittest
+from pathlib import Path
+
+POS_NEXT_PKG = Path(__file__).resolve().parent
+
+
+def _python_files():
+	for path in POS_NEXT_PKG.rglob("*.py"):
+		if "__pycache__" in path.parts:
+			continue
+		yield path
+
+
+class TestNoPromotionsImport(unittest.TestCase):
+	def test_hooks_do_not_require_posnext_promotions(self):
+		hooks = (POS_NEXT_PKG / "hooks.py").read_text()
+		self.assertNotIn("posnext_promotions", hooks)
+		self.assertNotIn("pos_next_promotions_provider", hooks)
+		self.assertNotIn("pos_next_auth_provider", hooks)
+
+	def test_no_python_import_of_posnext_promotions(self):
+		violations = []
+		for path in _python_files():
+			if path.name == "test_no_promotions_import.py":
+				continue
+			try:
+				tree = ast.parse(path.read_text(), filename=str(path))
+			except SyntaxError:
+				continue
+			for node in ast.walk(tree):
+				if isinstance(node, ast.Import):
+					for alias in node.names:
+						if alias.name == "posnext_promotions" or alias.name.startswith("posnext_promotions."):
+							violations.append(f"{path}:{node.lineno} import {alias.name}")
+				elif isinstance(node, ast.ImportFrom):
+					mod = node.module or ""
+					if mod == "posnext_promotions" or mod.startswith("posnext_promotions."):
+						violations.append(f"{path}:{node.lineno} from {mod}")
+		self.assertEqual(violations, [], "posnext_promotions imports are forbidden:\n" + "\n".join(violations))
+
+	def test_magento_registry_hook_lists_exist(self):
+		hooks = (POS_NEXT_PKG / "hooks.py").read_text()
+		for name in (
+			"pos_next_loyalty_provider",
+			"pos_next_bootstrap_settings",
+			"pos_next_customer_validators",
+			"pos_next_customer_prepare",
+			"pos_next_customer_after_insert",
+		):
+			self.assertIn(f"{name} = []", hooks)
+
+
+if __name__ == "__main__":
+	unittest.main()
diff --git a/pos_next/test_split_smoke.py b/pos_next/test_split_smoke.py
new file mode 100644
index 000000000..56d641e82
--- /dev/null
+++ b/pos_next/test_split_smoke.py
@@ -0,0 +1,85 @@
+# Copyright (c) 2026, BrainWise and contributors
+"""Smoke tests for Magento integration split."""
+
+import unittest
+from unittest.mock import Mock, patch
+
+import frappe
+
+from pos_next.integrations.registry import (
+	extend_bootstrap_settings,
+	get_loyalty_provider,
+	is_external_loyalty_available,
+	is_external_loyalty_mode,
+)
+
+
+class TestMagentoSplitSmoke(unittest.TestCase):
+	def test_loyalty_provider_hook_registered(self):
+		provider = get_loyalty_provider()
+		self.assertIsNotNone(provider)
+		self.assertTrue(callable(provider.get("is_available")))
+		self.assertTrue(callable(provider.get("is_loyalty_mode")))
+		self.assertTrue(callable(provider.get("get_balance")))
+
+	def test_bootstrap_settings_hook_extends_flags(self):
+		settings = {"magento_loyalty_available": 0, "miraaya_installed": 0}
+		extend_bootstrap_settings(settings)
+		self.assertIn("miraaya_installed", settings)
+		self.assertIn("magento_loyalty_available", settings)
+
+	def test_magento_doc_events_registered(self):
+		hooks = frappe.get_hooks("doc_events", {}).get("Sales Invoice", {}).get("on_submit", [])
+		self.assertIn(
+			"magento_integration.api.magento_loyalty.redeem_magento_lp_on_submit",
+			hooks,
+		)
+		self.assertIn(
+			"magento_integration.api.magento_loyalty.add_magento_lp_on_submit",
+			hooks,
+		)
+		self.assertNotIn(
+			"pos_next.api.magento_loyalty.redeem_magento_lp_on_submit",
+			hooks,
+		)
+
+	def test_pos_next_has_no_magento_module(self):
+		with self.assertRaises((ImportError, ModuleNotFoundError)):
+			import pos_next.api.magento_loyalty  # noqa: F401
+
+	@patch("pos_next.api.wallet.is_external_loyalty_mode", return_value=False)
+	def test_wallet_balance_without_magento_mode(self, _mock_mode):
+		from pos_next.api.wallet import get_customer_wallet_balance
+
+		with patch("pos_next.api.wallet.frappe.db.get_value", return_value=None):
+			balance = get_customer_wallet_balance("CUST-TEST", "Test Company")
+			self.assertEqual(balance, 0.0)
+
+	def test_magento_lp_balance_api_callable(self):
+		from magento_integration.api.magento_loyalty import get_lp_balance_for_customer
+
+		result = get_lp_balance_for_customer("NONEXISTENT-CUSTOMER", pos_profile=None)
+		self.assertIn("wallet_enabled", result)
+		self.assertIn("balance_iqd", result)
+		self.assertIn("balance_points", result)
+
+	def test_bootstrap_includes_integration_flags(self):
+		from pos_next.api.bootstrap import get_initial_data
+
+		profiles = frappe.get_all("POS Profile", filters={"disabled": 0}, pluck="name", limit=1)
+		if not profiles:
+			self.skipTest("No active POS Profile on site")
+
+		frappe.local.form_dict = frappe._dict(pos_profile=profiles[0])
+		data = get_initial_data()
+		settings = data.get("pos_settings") or {}
+		self.assertIn("miraaya_installed", settings)
+		self.assertIn("magento_loyalty_available", settings)
+		self.assertTrue(data.get("success"))
+
+
+def run_smoke_tests():
+	loader = unittest.TestLoader()
+	suite = loader.loadTestsFromTestCase(TestMagentoSplitSmoke)
+	result = unittest.TextTestRunner(verbosity=2).run(suite)
+	return 0 if result.wasSuccessful() else 1
diff --git a/scripts/run_split_smoke_tests.py b/scripts/run_split_smoke_tests.py
new file mode 100644
index 000000000..422322fed
--- /dev/null
+++ b/scripts/run_split_smoke_tests.py
@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Run POS Next split smoke tests outside bench test runner."""
+
+import os
+import sys
+import unittest
+from unittest.mock import patch
+
+import frappe
+
+BENCH_PATH = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../.."))
+sys.path.insert(0, os.path.join(BENCH_PATH, "apps"))
+
+
+def bootstrap(site: str):
+	os.chdir(BENCH_PATH)
+	frappe.init(site=site, sites_path=os.path.join(BENCH_PATH, "sites"))
+	frappe.connect()
+	frappe.set_user("Administrator")
+
+
+class TestMagentoSplitSmoke(unittest.TestCase):
+	def test_loyalty_provider_hook_registered(self):
+		from pos_next.integrations.registry import get_loyalty_provider
+
+		provider = get_loyalty_provider()
+		self.assertIsNotNone(provider)
+		self.assertTrue(callable(provider.get("is_available")))
+		self.assertTrue(callable(provider.get("is_loyalty_mode")))
+		self.assertTrue(callable(provider.get("get_balance")))
+
+	def test_bootstrap_settings_hook_extends_flags(self):
+		from pos_next.integrations.registry import extend_bootstrap_settings
+
+		settings = {"magento_loyalty_available": 0, "miraaya_installed": 0}
+		extend_bootstrap_settings(settings)
+		self.assertIn("miraaya_installed", settings)
+		self.assertIn("magento_loyalty_available", settings)
+
+	def test_magento_doc_events_registered(self):
+		hooks = frappe.get_hooks("doc_events", {}).get("Sales Invoice", {}).get("on_submit", [])
+		self.assertIn(
+			"magento_integration.api.magento_loyalty.redeem_magento_lp_on_submit",
+			hooks,
+		)
+		self.assertIn(
+			"magento_integration.api.magento_loyalty.add_magento_lp_on_submit",
+			hooks,
+		)
+		self.assertNotIn(
+			"pos_next.api.magento_loyalty.redeem_magento_lp_on_submit",
+			hooks,
+		)
+
+	def test_pos_next_has_no_magento_module(self):
+		with self.assertRaises((ImportError, ModuleNotFoundError)):
+			import pos_next.api.magento_loyalty  # noqa: F401
+
+	@patch("pos_next.api.wallet.is_external_loyalty_mode", return_value=False)
+	def test_wallet_balance_without_magento_mode(self, _mock_mode):
+		from pos_next.api.wallet import get_customer_wallet_balance
+
+		with patch("pos_next.api.wallet.frappe.db.get_value", return_value=None):
+			balance = get_customer_wallet_balance("CUST-TEST", "Test Company")
+			self.assertEqual(balance, 0.0)
+
+	def test_magento_lp_balance_api_callable(self):
+		from magento_integration.api.magento_loyalty import get_lp_balance_for_customer
+
+		result = get_lp_balance_for_customer("NONEXISTENT-CUSTOMER", pos_profile=None)
+		self.assertIn("wallet_enabled", result)
+		self.assertIn("balance_iqd", result)
+		self.assertIn("balance_points", result)
+
+	def test_bootstrap_api_importable(self):
+		from pos_next.api import bootstrap
+
+		self.assertTrue(hasattr(bootstrap, "get_bootstrap_data"))
+
+
+def main():
+	bootstrap("brainwise.dev")
+	suite = unittest.defaultTestLoader.loadTestsFromTestCase(TestMagentoSplitSmoke)
+	result = unittest.TextTestRunner(verbosity=2).run(suite)
+	frappe.destroy()
+	return 0 if result.wasSuccessful() else 1
+
+
+if __name__ == "__main__":
+	sys.exit(main())

From 0b932f9753d640527b8213b34691da5627580571 Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Tue, 18 Aug 2026 14:10:41 +0300
Subject: [PATCH 2/8] Register AuthorizationDialog in generated Vue component
 types.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 POS/components.d.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/POS/components.d.ts b/POS/components.d.ts
index 1f2e8b35f..6b5b0b148 100644
--- a/POS/components.d.ts
+++ b/POS/components.d.ts
@@ -9,6 +9,7 @@ export {}
 declare module 'vue' {
   export interface GlobalComponents {
     ActionButton: typeof import('./src/components/common/ActionButton.vue')['default']
+    AuthorizationDialog: typeof import('./src/components/common/AuthorizationDialog.vue')['default']
     AutocompleteSelect: typeof import('./src/components/common/AutocompleteSelect.vue')['default']
     BatchSerialDialog: typeof import('./src/components/sale/BatchSerialDialog.vue')['default']
     CheckboxField: typeof import('./src/components/settings/CheckboxField.vue')['default']

From c4412097932382e42334a4c94781f8a605371712 Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Mon, 24 Aug 2026 14:31:08 +0300
Subject: [PATCH 3/8] Enhance POS components with conditional rendering and new
 features

- Updated App.vue to conditionally render AuthorizationDialog based on authGateInstalled.
- Modified SelectInput.vue to support multiple selections and improved UI for selected options.
- Refactored CreateCustomerDialog.vue to use requiresSplitCustomerName for customer name handling.
- Adjusted InvoiceCart.vue to utilize the new wallet API and removed Magento dependencies.
- Enhanced PromotionManagement.vue to include Gift Pool promotion type and related UI elements.
- Introduced applyOfflineGiftPool function in posCart.js for handling gift pool discounts.
- Updated various API endpoints to ensure compatibility with new promotional features.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 POS/src/App.vue                               |   5 +-
 POS/src/components/common/SelectInput.vue     |  76 +++-
 .../components/sale/CreateCustomerDialog.vue  |  10 +-
 POS/src/components/sale/InvoiceCart.vue       |  20 +-
 .../components/sale/PromotionManagement.vue   | 381 +++++++++++++++++-
 POS/src/stores/posCart.js                     | 111 +++++
 pos_next/__init__.py                          |  71 ++--
 pos_next/api/customers.py                     |   4 +-
 pos_next/api/sales_invoice_hooks.py           |  10 +
 pos_next/api/wallet.py                        |   5 +-
 pos_next/integrations/registry.py             |   6 +-
 pos_next/optional_apps.py                     |  19 +
 pos_next/overrides/pricing_rule.py            |  10 +
 pos_next/test_no_promotions_import.py         |  76 +++-
 pos_next/test_split_smoke.py                  |  53 ++-
 scripts/run_split_smoke_tests.py              |  72 +---
 16 files changed, 777 insertions(+), 152 deletions(-)
 create mode 100644 pos_next/optional_apps.py

diff --git a/POS/src/App.vue b/POS/src/App.vue
index f108f0cf6..93d31357f 100644
--- a/POS/src/App.vue
+++ b/POS/src/App.vue
@@ -2,12 +2,15 @@
 	<div>
 		<router-view :key="translationVersion" />
 		<Toast />
-		<AuthorizationDialog />
+		<AuthorizationDialog v-if="authGateInstalled" />
 	</div>
 </template>
 
 <script setup>
 import AuthorizationDialog from "@/components/common/AuthorizationDialog.vue";
 import Toast from "@/components/common/Toast.vue";
+import { isAuthGateInstalled } from "@/utils/promoApi";
 import { translationVersion } from "@/utils/translation";
+
+const authGateInstalled = isAuthGateInstalled();
 </script>
diff --git a/POS/src/components/common/SelectInput.vue b/POS/src/components/common/SelectInput.vue
index 39f52e6e0..a4f170f4c 100644
--- a/POS/src/components/common/SelectInput.vue
+++ b/POS/src/components/common/SelectInput.vue
@@ -84,19 +84,45 @@
 							:ref="(el) => (optionRefs[index] = el)"
 							tabindex="0"
 							role="option"
-							:aria-selected="option.value === modelValue"
+							:aria-selected="isSelected(option.value)"
 							class="px-2 py-1.5 text-base cursor-pointer text-start transition-colors focus:outline-none"
 							:class="
-								option.value === modelValue
+								isSelected(option.value)
 									? 'bg-blue-50 text-blue-700'
 									: 'text-gray-800 hover:bg-gray-100 focus:bg-gray-100'
 							"
 						>
-							<div v-if="option.subtitle" class="flex flex-col">
-								<span class="text-sm font-medium">{{ option.label }}</span>
-								<span class="text-xs text-gray-500">{{ option.subtitle }}</span>
+							<div class="flex items-center gap-2">
+								<span
+									v-if="multiple"
+									class="flex-shrink-0 w-4 h-4 border rounded flex items-center justify-center"
+									:class="
+										isSelected(option.value)
+											? 'bg-blue-600 border-blue-600 text-white'
+											: 'border-gray-300 bg-white'
+									"
+								>
+									<svg
+										v-if="isSelected(option.value)"
+										class="w-3 h-3"
+										fill="none"
+										stroke="currentColor"
+										viewBox="0 0 24 24"
+									>
+										<path
+											stroke-linecap="round"
+											stroke-linejoin="round"
+											stroke-width="3"
+											d="M5 13l4 4L19 7"
+										/>
+									</svg>
+								</span>
+								<div v-if="option.subtitle" class="flex flex-col min-w-0">
+									<span class="text-sm font-medium">{{ option.label }}</span>
+									<span class="text-xs text-gray-500">{{ option.subtitle }}</span>
+								</div>
+								<span v-else class="min-w-0 truncate">{{ option.label }}</span>
 							</div>
-							<span v-else>{{ option.label }}</span>
 						</div>
 					</div>
 				</div>
@@ -115,7 +141,7 @@ defineOptions({
 
 const props = defineProps({
 	modelValue: {
-		type: [String, Number],
+		type: [String, Number, Array],
 		default: "",
 	},
 	options: {
@@ -150,6 +176,10 @@ const props = defineProps({
 		type: Number,
 		default: 50, // Limit displayed options for performance
 	},
+	multiple: {
+		type: Boolean,
+		default: false,
+	},
 });
 
 const emit = defineEmits(["update:modelValue", "change"]);
@@ -163,11 +193,31 @@ const optionRefs = ref([]);
 const dropdownPosition = ref({ top: 0, left: 0, width: 0 });
 const searchQuery = ref("");
 
+const selectedValues = computed(() => {
+	if (props.multiple) {
+		return Array.isArray(props.modelValue) ? props.modelValue : [];
+	}
+	return props.modelValue === 0 || props.modelValue ? [props.modelValue] : [];
+});
+
 const selectedLabel = computed(() => {
+	if (props.multiple) {
+		const count = selectedValues.value.length;
+		if (!count) return "";
+		if (count === 1) {
+			const selected = props.options.find((opt) => opt.value === selectedValues.value[0]);
+			return selected?.label || String(selectedValues.value[0]);
+		}
+		return `${count} selected`;
+	}
 	const selected = props.options.find((opt) => opt.value === props.modelValue);
 	return selected?.label || "";
 });
 
+function isSelected(value) {
+	return selectedValues.value.includes(value);
+}
+
 const filteredOptions = computed(() => {
 	let result = props.options;
 
@@ -237,6 +287,18 @@ function openAndFocusFirst() {
 }
 
 function selectOption(option) {
+	if (props.multiple) {
+		const current = [...selectedValues.value];
+		const idx = current.indexOf(option.value);
+		if (idx >= 0) {
+			current.splice(idx, 1);
+		} else {
+			current.push(option.value);
+		}
+		emit("update:modelValue", current);
+		emit("change", current);
+		return;
+	}
 	emit("update:modelValue", option.value);
 	emit("change", option.value);
 	close();
diff --git a/POS/src/components/sale/CreateCustomerDialog.vue b/POS/src/components/sale/CreateCustomerDialog.vue
index cd929f1d3..ee3831765 100644
--- a/POS/src/components/sale/CreateCustomerDialog.vue
+++ b/POS/src/components/sale/CreateCustomerDialog.vue
@@ -9,7 +9,7 @@
 		<template #body-content>
 			<div class="flex flex-col gap-6">
 				<!-- Customer Name (Required) -->
-				<div v-if="!miraayaCustomerSync">
+				<div v-if="!requiresSplitCustomerName">
 					<label class="block text-start text-sm font-medium text-gray-700 mb-2">
 						{{ __("Customer Name") }} <span class="text-red-500">*</span>
 					</label>
@@ -410,7 +410,7 @@ const show = computed({
 
 const isEditMode = computed(() => !!props.customer?.name);
 
-const miraayaCustomerSync = computed(() => posSettingsStore.miraayaInstalled);
+const requiresSplitCustomerName = computed(() => Boolean(posSettingsStore.miraayaInstalled));
 
 const computedCustomerName = computed(() => {
 	const first = (customerData.value.custom_first_name || "").trim();
@@ -419,7 +419,7 @@ const computedCustomerName = computed(() => {
 });
 
 const hasValidCustomerName = computed(() => {
-	if (miraayaCustomerSync.value) {
+	if (requiresSplitCustomerName.value) {
 		return Boolean(computedCustomerName.value);
 	}
 	return Boolean((customerData.value.customer_name || "").trim());
@@ -587,7 +587,7 @@ const updateTerritoryFromCountry = () => {
 const createCustomerResource = createResource({
 	url: "pos_next.api.customers.create_customer",
 	makeParams: () => ({
-		customer_name: miraayaCustomerSync.value
+		customer_name: requiresSplitCustomerName.value
 			? computedCustomerName.value
 			: customerData.value.customer_name,
 		mobile_no: customerData.value.mobile_no || "",
@@ -784,7 +784,7 @@ const checkPermissions = async () => {
 };
 
 const handleCreate = async () => {
-	if (miraayaCustomerSync.value) {
+	if (requiresSplitCustomerName.value) {
 		if (!customerData.value.custom_first_name?.trim()) {
 			return showError(__("First Name is required"));
 		}
diff --git a/POS/src/components/sale/InvoiceCart.vue b/POS/src/components/sale/InvoiceCart.vue
index b8168eff4..5315e5fcb 100644
--- a/POS/src/components/sale/InvoiceCart.vue
+++ b/POS/src/components/sale/InvoiceCart.vue
@@ -1460,7 +1460,7 @@
  * IMPORTS
  * ============================================================================
  */
-import { isMagentoAppInstalled, promoApi } from "@/utils/promoApi";
+import { promoApi } from "@/utils/promoApi";
 import { usePOSCartStore } from "@/stores/posCart";
 import { usePOSSettingsStore } from "@/stores/posSettings";
 import { usePOSOffersStore } from "@/stores/posOffers";
@@ -1718,20 +1718,22 @@ const customerLpInfo = ref({
 });
 
 const customerLpResource = createResource({
-	url: "magento_integration.api.magento_loyalty.get_lp_balance_for_customer",
+	url: "pos_next.api.wallet.get_wallet_info",
 	makeParams() {
 		const customerName = props.customer?.name || props.customer;
 		return {
 			customer: customerName,
+			company: props.company,
 			pos_profile: props.posProfile,
 		};
 	},
 	auto: false,
 	onSuccess(data) {
-		customerLpInfo.value = data || {
-			wallet_enabled: false,
-			balance_points: 0,
-			balance_iqd: 0,
+		const payload = data?.message || data || {};
+		customerLpInfo.value = {
+			wallet_enabled: Boolean(payload.wallet_enabled),
+			balance_points: Number(payload.balance_points) || 0,
+			balance_iqd: Number(payload.balance_iqd ?? payload.wallet_balance) || 0,
 		};
 	},
 	onError() {
@@ -1758,7 +1760,7 @@ watch(
 			availableGiftCards.value = [];
 		}
 
-		if (isMagentoAppInstalled() && customerName && props.posProfile && !isOffline()) {
+		if (customerName && props.company && props.posProfile && !isOffline()) {
 			customerLpResource.reload();
 		} else {
 			customerLpInfo.value = {
@@ -1770,14 +1772,14 @@ watch(
 	}
 );
 
-// Refresh Magento LP balance after a completed sale when the cart is cleared
+// Refresh wallet / LP balance after a completed sale when the cart is cleared
 // but the same customer stays selected (watch on customer alone won't re-fire).
 watch(
 	() => props.items?.length ?? 0,
 	(newLen, oldLen) => {
 		if (oldLen > 0 && newLen === 0) {
 			const customerName = props.customer?.name || props.customer;
-			if (isMagentoAppInstalled() && customerName && props.posProfile && !isOffline()) {
+			if (customerName && props.company && props.posProfile && !isOffline()) {
 				customerLpResource.reload();
 			}
 		}
diff --git a/POS/src/components/sale/PromotionManagement.vue b/POS/src/components/sale/PromotionManagement.vue
index 501937abe..56c49495b 100644
--- a/POS/src/components/sale/PromotionManagement.vue
+++ b/POS/src/components/sale/PromotionManagement.vue
@@ -499,6 +499,33 @@
 															/>
 														</div>
 
+														<div
+															v-if="promotionsInstalled"
+															class="col-span-3"
+														>
+															<label
+																class="block text-sm font-medium text-gray-700 mb-1.5 text-start"
+															>
+																{{ __("Promotion Type") }}
+															</label>
+															<SelectInput
+																v-model="form.promotion_type"
+																:disabled="!isCreating || isPricingRule"
+																:options="promotionTypeOptions"
+																:placeholder="__('Select promotion type')"
+															/>
+															<p
+																v-if="isGiftPoolPromotionType"
+																class="text-xs text-emerald-700 mt-1"
+															>
+																{{
+																	__(
+																		"Buy any item in a group (except pool items) and get Free Qty units spread across that group's pool items."
+																	)
+																}}
+															</p>
+														</div>
+
 														<FormControl
 															type="date"
 															:label="__('Valid From')"
@@ -523,7 +550,9 @@
 															<SelectInput
 																v-model="form.apply_on"
 																:disabled="
-																	!isCreating || isPricingRule
+																	!isCreating ||
+																	isPricingRule ||
+																	isGiftPoolPromotionType
 																"
 																:options="applyOnOptions"
 																:placeholder="__('Select option')"
@@ -534,7 +563,12 @@
 											</Card>
 
 											<!-- Item Selection Card -->
-											<Card v-if="form.apply_on !== 'Transaction'">
+											<Card
+												v-if="
+													form.apply_on !== 'Transaction' &&
+													!isGiftPoolPromotionType
+												"
+											>
 												<div class="p-5">
 													<div class="flex items-center gap-2 mb-4">
 														<FeatherIcon
@@ -704,8 +738,181 @@
 												</div>
 											</Card>
 
+											<!-- Gift Pool free items: one ordered list per selected item group -->
+											<Card v-if="isGiftPoolPromotionType">
+												<div class="p-5">
+													<div class="flex items-center gap-2 mb-2">
+														<FeatherIcon
+															name="gift"
+															class="w-4 h-4 text-emerald-600"
+														/>
+														<h4
+															class="text-sm font-semibold text-gray-900"
+														>
+															{{ __("Gift Pool Free Items") }}
+														</h4>
+														<Badge
+															variant="subtle"
+															theme="red"
+															size="sm"
+															>{{ __("Required") }}</Badge
+														>
+													</div>
+													<p class="text-xs text-gray-600 mb-4">
+														{{
+															__(
+																"For each item group, choose free items and set Free Qty as the total free units (default 1). They are given in list order across those item codes — not one per paid unit."
+															)
+														}}
+													</p>
+													<div class="flex flex-col gap-3 mb-4">
+														<SelectInput
+															v-model="selectedItemGroup"
+															:disabled="!isCreating"
+															@change="addItemGroup"
+															:options="itemGroupOptions"
+															:placeholder="__('Select Item Group')"
+														/>
+														<div
+															v-if="giftPoolGroups.length > 0"
+															class="flex flex-wrap gap-2 items-center"
+														>
+															<Badge
+																v-for="group in giftPoolGroups"
+																:key="group"
+																variant="subtle"
+																theme="green"
+															>
+																{{ group }}
+																<button
+																	v-if="isCreating"
+																	@click="
+																		removeGiftPoolGroup(group)
+																	"
+																	class="ms-1 hover:text-green-900"
+																	type="button"
+																>
+																	×
+																</button>
+															</Badge>
+														</div>
+													</div>
+													<div
+														v-if="!giftPoolGroups.length"
+														class="text-sm text-amber-700 bg-amber-50 border border-amber-200 rounded-lg px-3 py-2"
+													>
+														{{
+															__(
+																"Select at least one item group, then add free items."
+															)
+														}}
+													</div>
+													<div v-else class="flex flex-col gap-5">
+														<div
+															v-for="group in giftPoolGroups"
+															:key="group"
+															class="border border-gray-200 rounded-lg p-3 flex flex-col gap-3"
+														>
+															<div
+																class="flex items-center justify-between gap-3"
+															>
+																<p
+																	class="text-sm font-medium text-gray-900"
+																>
+																	{{ group }}
+																</p>
+																<FormControl
+																	type="number"
+																	:label="__('Free Qty')"
+																	:model-value="
+																		giftPoolFreeQty(group)
+																	"
+																	:disabled="!isCreating"
+																	min="1"
+																	class="w-28"
+																	@update:model-value="
+																		(qty) =>
+																			setGiftPoolFreeQty(
+																				group,
+																				qty
+																			)
+																	"
+																/>
+															</div>
+															<SelectInput
+																:model-value="
+																	giftPoolItemsForGroup(
+																		group
+																	).map((row) => row.item_code)
+																"
+																:disabled="!isCreating"
+																multiple
+																@update:model-value="
+																	(codes) =>
+																		setGiftPoolItemsForGroup(
+																			group,
+																			codes
+																		)
+																"
+																:options="
+																	giftPoolItemOptions(group)
+																"
+																:placeholder="
+																	__('Select free items')
+																"
+																:searchable="true"
+																:searchPlaceholder="
+																	__('Search items...')
+																"
+																:noResultsText="
+																	__('No items in this group')
+																"
+																:maxDisplayed="30"
+															/>
+															<div
+																v-if="
+																	giftPoolItemsForGroup(group)
+																		.length
+																"
+																class="flex flex-wrap gap-2 items-center"
+															>
+																<Badge
+																	v-for="(
+																		row, index
+																	) in giftPoolItemsForGroup(
+																		group
+																	)"
+																	:key="row.item_code"
+																	variant="subtle"
+																	theme="green"
+																>
+																	{{ index + 1 }}.
+																	{{
+																		row.item_name ||
+																		row.item_code
+																	}}
+																	<button
+																		v-if="isCreating"
+																		@click="
+																			removeGiftPoolItem(
+																				group,
+																				row.item_code
+																			)
+																		"
+																		class="ms-1 hover:text-green-900"
+																		type="button"
+																	>
+																		×
+																	</button>
+																</Badge>
+															</div>
+														</div>
+													</div>
+												</div>
+											</Card>
+
 											<!-- Discount Details Card -->
-											<Card>
+											<Card v-if="!isGiftPoolPromotionType">
 												<div class="p-5">
 													<div class="flex items-center gap-2 mb-4">
 														<FeatherIcon
@@ -1020,7 +1227,7 @@
 </template>
 
 <script setup>
-import { promoApi } from "@/utils/promoApi";
+import { isPromotionsAppInstalled, promoApi } from "@/utils/promoApi";
 import { usePOSPermissions } from "@/composables/usePermissions";
 import { useToast } from "@/composables/useToast";
 import { useItemSearchStore } from "@/stores/itemSearch";
@@ -1072,15 +1279,27 @@ const promotions = ref([]);
 const searchQuery = ref("");
 const filterStatus = ref("all");
 
+const promotionsInstalled = isPromotionsAppInstalled();
+const PROMOTION_TYPE_GIFT_POOL = "Gift Pool";
+
+const promotionTypeOptions = promotionsInstalled
+	? [
+			{ label: __("Standard"), value: "" },
+			{ label: __("Gift Pool"), value: PROMOTION_TYPE_GIFT_POOL },
+		]
+	: [];
+
 // Form state
 const form = ref({
 	name: "",
 	company: props.company,
+	promotion_type: "",
 	apply_on: "Item Group",
 	discount_type: "percentage",
 	discount_value: 0,
 	free_item: "",
 	free_qty: 1,
+	gift_pool_items: [],
 	items: [],
 	min_qty: 0,
 	max_qty: 0,
@@ -1097,6 +1316,7 @@ const itemSearch = ref("");
 const freeItemSearch = ref("");
 const selectedItemGroup = ref("");
 const selectedBrand = ref("");
+const giftPoolFreeQtyByGroup = ref({});
 
 // Discount types
 const discountTypes = [
@@ -1110,6 +1330,18 @@ const isPricingRule = computed(() => {
 	return !isCreating.value && selectedPromotion.value?.source === "Pricing Rule";
 });
 
+const isGiftPoolPromotionType = computed(
+	() => promotionsInstalled && form.value.promotion_type === PROMOTION_TYPE_GIFT_POOL
+);
+
+const giftPoolGroups = computed(() => {
+	const fromItems = (form.value.items || []).map((row) => row.item_group).filter(Boolean);
+	const fromPool = (form.value.gift_pool_items || [])
+		.map((row) => row.item_group)
+		.filter(Boolean);
+	return [...new Set([...fromItems, ...fromPool])];
+});
+
 const filteredPromotions = computed(() => {
 	let filtered = promotions.value;
 
@@ -1288,6 +1520,7 @@ const updatePromotionResource = createResource({
 			data: JSON.stringify({
 				valid_from: form.value.valid_from,
 				valid_upto: form.value.valid_upto,
+				promotion_type: form.value.promotion_type,
 				min_qty: form.value.min_qty,
 				max_qty: form.value.max_qty,
 				min_amt: form.value.min_amt,
@@ -1295,6 +1528,7 @@ const updatePromotionResource = createResource({
 				discount_value: form.value.discount_value,
 				free_item: form.value.free_item,
 				free_qty: form.value.free_qty,
+				gift_pool_items: form.value.gift_pool_items,
 			}),
 		};
 	},
@@ -1396,6 +1630,22 @@ watch(
 	(newVal, oldVal) => {
 		if (isCreating.value && oldVal && newVal !== oldVal) {
 			form.value.items = [];
+			form.value.gift_pool_items = [];
+			giftPoolFreeQtyByGroup.value = {};
+		}
+	}
+);
+
+watch(
+	() => form.value.promotion_type,
+	(type) => {
+		if (type === PROMOTION_TYPE_GIFT_POOL) {
+			form.value.apply_on = "Item Group";
+			form.value.discount_type = "free_item";
+			if (isCreating.value) {
+				form.value.gift_pool_items = [];
+				giftPoolFreeQtyByGroup.value = {};
+			}
 		}
 	}
 );
@@ -1535,7 +1785,16 @@ function handleSubmit() {
 		}
 	}
 
-	if (form.value.apply_on !== "Transaction" && form.value.items.length === 0) {
+	if (isGiftPoolPromotionType.value) {
+		if (!form.value.gift_pool_items.length) {
+			showWarning(__("Please choose at least one free item"));
+			return;
+		}
+		const groups = [
+			...new Set(form.value.gift_pool_items.map((row) => row.item_group).filter(Boolean)),
+		];
+		form.value.items = groups.map((item_group) => ({ item_group }));
+	} else if (form.value.apply_on !== "Transaction" && form.value.items.length === 0) {
 		showWarning(__("Please select at least one {0}", [translateApplyOn(form.value.apply_on)]));
 		return;
 	}
@@ -1577,6 +1836,12 @@ function addItemGroup() {
 		!form.value.items.some((i) => i.item_group === selectedItemGroup.value)
 	) {
 		form.value.items.push({ item_group: selectedItemGroup.value });
+		if (!giftPoolFreeQtyByGroup.value[selectedItemGroup.value]) {
+			giftPoolFreeQtyByGroup.value = {
+				...giftPoolFreeQtyByGroup.value,
+				[selectedItemGroup.value]: 1,
+			};
+		}
 	}
 	selectedItemGroup.value = "";
 }
@@ -1589,11 +1854,97 @@ function addBrand() {
 }
 
 function removeItem(index) {
+	const removed = form.value.items[index];
 	form.value.items.splice(index, 1);
+	if (removed?.item_group) {
+		form.value.gift_pool_items = form.value.gift_pool_items.filter(
+			(row) => row.item_group !== removed.item_group
+		);
+		const qtyNext = { ...giftPoolFreeQtyByGroup.value };
+		delete qtyNext[removed.item_group];
+		giftPoolFreeQtyByGroup.value = qtyNext;
+	}
 }
 
 function clearAllItems() {
 	form.value.items = [];
+	form.value.gift_pool_items = [];
+	giftPoolFreeQtyByGroup.value = {};
+}
+
+function giftPoolItemsForGroup(itemGroup) {
+	return (form.value.gift_pool_items || []).filter((row) => row.item_group === itemGroup);
+}
+
+function giftPoolFreeQty(itemGroup) {
+	const fromMap = Number(giftPoolFreeQtyByGroup.value[itemGroup]);
+	if (fromMap > 0) {
+		return fromMap;
+	}
+	const qty = Number(giftPoolItemsForGroup(itemGroup)[0]?.free_qty);
+	return qty > 0 ? qty : 1;
+}
+
+function setGiftPoolFreeQty(itemGroup, qty) {
+	const next = Math.max(1, Math.floor(Number(qty) || 1));
+	giftPoolFreeQtyByGroup.value = {
+		...giftPoolFreeQtyByGroup.value,
+		[itemGroup]: next,
+	};
+	form.value.gift_pool_items = (form.value.gift_pool_items || []).map((row) =>
+		row.item_group === itemGroup ? { ...row, free_qty: next } : row
+	);
+}
+
+function giftPoolItemOptions(itemGroup) {
+	const allItems = itemSearchStore.allItems || [];
+	return allItems
+		.filter((item) => item.item_group === itemGroup)
+		.map((item) => ({
+			label: item.item_name || item.item_code,
+			value: item.item_code,
+			subtitle: item.item_code,
+		}));
+}
+
+function setGiftPoolItemsForGroup(itemGroup, selectedCodes) {
+	const selected = Array.isArray(selectedCodes) ? selectedCodes.filter(Boolean) : [];
+	const selectedSet = new Set(selected);
+	const kept = (form.value.gift_pool_items || []).filter(
+		(row) => row.item_group !== itemGroup || selectedSet.has(row.item_code)
+	);
+	const alreadyInGroup = new Set(
+		kept.filter((row) => row.item_group === itemGroup).map((row) => row.item_code)
+	);
+	const allItems = itemSearchStore.allItems || [];
+	for (const itemCode of selected) {
+		if (alreadyInGroup.has(itemCode)) continue;
+		const item = allItems.find((row) => row.item_code === itemCode);
+		kept.push({
+			item_group: itemGroup,
+			item_code: itemCode,
+			item_name: item?.item_name || itemCode,
+			free_qty: giftPoolFreeQty(itemGroup),
+		});
+		alreadyInGroup.add(itemCode);
+	}
+	form.value.gift_pool_items = kept;
+}
+
+function removeGiftPoolItem(itemGroup, itemCode) {
+	form.value.gift_pool_items = form.value.gift_pool_items.filter(
+		(row) => !(row.item_group === itemGroup && row.item_code === itemCode)
+	);
+}
+
+function removeGiftPoolGroup(itemGroup) {
+	form.value.items = form.value.items.filter((row) => row.item_group !== itemGroup);
+	form.value.gift_pool_items = form.value.gift_pool_items.filter(
+		(row) => row.item_group !== itemGroup
+	);
+	const qtyNext = { ...giftPoolFreeQtyByGroup.value };
+	delete qtyNext[itemGroup];
+	giftPoolFreeQtyByGroup.value = qtyNext;
 }
 
 function selectFreeItem(item) {
@@ -1605,11 +1956,13 @@ function resetForm() {
 	form.value = {
 		name: "",
 		company: props.company,
+		promotion_type: "",
 		apply_on: "Item Group",
 		discount_type: "percentage",
 		discount_value: 0,
 		free_item: "",
 		free_qty: 1,
+		gift_pool_items: [],
 		items: [],
 		min_qty: 0,
 		max_qty: 0,
@@ -1622,6 +1975,7 @@ function resetForm() {
 	freeItemSearch.value = "";
 	selectedItemGroup.value = "";
 	selectedBrand.value = "";
+	giftPoolFreeQtyByGroup.value = {};
 }
 
 function populateFormFromPromotion(promotion) {
@@ -1631,6 +1985,7 @@ function populateFormFromPromotion(promotion) {
 	// Basic fields
 	form.value.name = promotion.name;
 	form.value.company = promotion.company;
+	form.value.promotion_type = promotionsInstalled ? promotion.promotion_type || "" : "";
 	form.value.apply_on = promotion.apply_on;
 	form.value.valid_from = promotion.valid_from || "";
 	form.value.valid_upto = promotion.valid_upto || "";
@@ -1653,6 +2008,22 @@ function populateFormFromPromotion(promotion) {
 		}));
 	}
 
+	if (promotionsInstalled && promotion.gift_pool_items?.length) {
+		form.value.gift_pool_items = promotion.gift_pool_items.map((row) => ({
+			item_group: row.item_group,
+			item_code: row.item_code,
+			item_name: row.item_name || row.item_code,
+			free_qty: Number(row.free_qty) > 0 ? Number(row.free_qty) : 1,
+		}));
+		const qtyByGroup = {};
+		for (const row of form.value.gift_pool_items) {
+			if (row.item_group && !qtyByGroup[row.item_group]) {
+				qtyByGroup[row.item_group] = row.free_qty;
+			}
+		}
+		giftPoolFreeQtyByGroup.value = qtyByGroup;
+	}
+
 	// Populate discount details from slabs
 	if (promotion.price_discount_slabs && promotion.price_discount_slabs.length > 0) {
 		const slab = promotion.price_discount_slabs[0];
diff --git a/POS/src/stores/posCart.js b/POS/src/stores/posCart.js
index 8d451c946..08a012713 100644
--- a/POS/src/stores/posCart.js
+++ b/POS/src/stores/posCart.js
@@ -1,3 +1,4 @@
+import { isPromotionsAppInstalled } from "@/utils/promoApi";
 import { useInvoice } from "@/composables/useInvoice";
 import { usePOSOffersStore } from "@/stores/posOffers";
 import { usePOSSettingsStore } from "@/stores/posSettings";
@@ -1050,6 +1051,113 @@ export const usePOSCartStore = defineStore("posCart", () => {
 		return applied;
 	}
 
+	/**
+	 * Apply Gift Pool product discount offline: paid items in a group grant
+	 * free_qty units spread across that group's pool SKUs.
+	 */
+	function applyOfflineGiftPool(offer, eligibleItems) {
+		const poolRows = Array.isArray(offer.gift_pool_items) ? offer.gift_pool_items : [];
+		if (!poolRows.length) return false;
+
+		const pools = {};
+		for (const row of poolRows) {
+			const group = row.item_group;
+			const code = row.item_code;
+			if (!group || !code) continue;
+			if (!pools[group]) pools[group] = [];
+			if (!pools[group].includes(code)) pools[group].push(code);
+		}
+
+		let applied = false;
+		const referenceItem = eligibleItems[0];
+		const uomKey = referenceItem?.uom || referenceItem?.stock_uom || "Nos";
+
+		for (const [itemGroup, poolCodes] of Object.entries(pools)) {
+			const poolSet = new Set(poolCodes);
+			const sample = poolRows.find((row) => row.item_group === itemGroup);
+			const groupSet = new Set(
+				sample?.matching_item_groups?.length ? sample.matching_item_groups : [itemGroup]
+			);
+			const paidItems = eligibleItems.filter(
+				(item) => groupSet.has(item.item_group) && !poolSet.has(item.item_code)
+			);
+			const paidQty = paidItems.reduce(
+				(sum, item) => sum + (Math.floor(item.quantity || item.qty || 0) || 0),
+				0
+			);
+			if (paidQty <= 0) continue;
+
+			const giftQty = Math.max(1, Number(sample?.free_qty) || 1);
+			const counts = {};
+			for (let i = 0; i < giftQty; i++) {
+				const giftCode = poolCodes[i % poolCodes.length];
+				counts[giftCode] = (counts[giftCode] || 0) + 1;
+			}
+
+			for (const item of paidItems) {
+				const pr = item.pricing_rules;
+				const prArr = Array.isArray(pr)
+					? [...pr]
+					: pr
+						? String(pr)
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean)
+						: [];
+				if (!prArr.includes(offer.name)) prArr.push(offer.name);
+				item.pricing_rules = prArr;
+			}
+
+			for (const [giftCode, freeItemsToGive] of Object.entries(counts)) {
+				const poolRow = poolRows.find((row) => row.item_code === giftCode);
+				const existingFreeRow = invoiceItems.value.find(
+					(r) =>
+						r.is_free_item &&
+						r.item_code === giftCode &&
+						(r.uom || r.stock_uom) === uomKey
+				);
+				if (existingFreeRow) {
+					existingFreeRow.quantity = freeItemsToGive;
+					existingFreeRow.free_qty = freeItemsToGive;
+					const pr = existingFreeRow.pricing_rules;
+					const prArr = Array.isArray(pr)
+						? [...pr]
+						: pr
+							? String(pr)
+									.split(",")
+									.map((s) => s.trim())
+									.filter(Boolean)
+							: [];
+					if (!prArr.includes(offer.name)) prArr.push(offer.name);
+					existingFreeRow.pricing_rules = prArr;
+				} else {
+					invoiceItems.value.push({
+						item_code: giftCode,
+						item_name: poolRow?.item_name || giftCode,
+						rate: 0,
+						price_list_rate: 0,
+						quantity: freeItemsToGive,
+						discount_amount: 0,
+						discount_percentage: 0,
+						tax_amount: 0,
+						amount: 0,
+						stock_qty: 0,
+						uom: uomKey,
+						stock_uom: uomKey,
+						conversion_factor: 1,
+						is_free_item: 1,
+						free_qty: freeItemsToGive,
+						pricing_rules: [offer.name],
+						warehouse: referenceItem?.warehouse,
+					});
+				}
+				applied = true;
+			}
+		}
+
+		return applied;
+	}
+
 	/**
 	 * Apply free item (product discount) offer offline
 	 * Handles: same_item (free item = purchased item) or specific free_item
@@ -1065,6 +1173,9 @@ export const usePOSCartStore = defineStore("posCart", () => {
 	 * @returns {boolean} True if free item was applied
 	 */
 	function applyOfflineFreeItem(offer, eligibleItems) {
+		if (isPromotionsAppInstalled() && offer.promotion_type === "Gift Pool") {
+			return applyOfflineGiftPool(offer, eligibleItems);
+		}
 		const freeQty = Number.parseFloat(offer.free_qty) || 0;
 		const sameItem = offer.same_item === 1;
 		const isRecursive = offer.is_recursive === 1;
diff --git a/pos_next/__init__.py b/pos_next/__init__.py
index 9130b6a1e..eb49f20b5 100644
--- a/pos_next/__init__.py
+++ b/pos_next/__init__.py
@@ -12,42 +12,49 @@ def console(*data):
 		frappe.publish_realtime("toconsole", data, user=frappe.session.user)
 
 
+def _promotions_installed():
+	try:
+		return bool(frappe) and "posnext_promotions" in frappe.get_installed_apps()
+	except Exception:
+		return False
+
+
 # Patch get_other_conditions to exclude pos_only pricing rules from non-POS documents.
 # No Frappe hook exists for non-whitelisted module-level functions (override_whitelisted_methods
 # only works for @frappe.whitelist() HTTP endpoints, override_doctype_class only for DocType
 # classes). This is the standard Python module init approach — runs once at import.
-try:
-	from erpnext.accounts.doctype.pricing_rule import utils as pr_utils
-
-	from pos_next.overrides.pricing_rule import patch_get_other_conditions
-
-	patch_get_other_conditions(pr_utils)
-except Exception:
-	pass
-
-
-try:
-	from erpnext.accounts.doctype.pricing_rule import pricing_rule as _erpnext_pricing_rule
-
-	from pos_next.overrides.pricing_rule import (
-		apply_price_discount_rule as _pos_next_apply_price_discount_rule,
-	)
-
-	_erpnext_pricing_rule.apply_price_discount_rule = _pos_next_apply_price_discount_rule
-except Exception:
-	if frappe:
-		frappe.log_error(frappe.get_traceback(), "Pricing Rule Override Error")
-
-
-try:
-	from erpnext.accounts.doctype.promotional_scheme import promotional_scheme as _promotional_scheme
-
-	for _min_max_field in ("apply_discount_on_price", "min_or_max_discount_qty_limit"):
-		if _min_max_field not in _promotional_scheme.price_discount_fields:
-			_promotional_scheme.price_discount_fields.append(_min_max_field)
-except Exception:
-	if frappe:
-		frappe.log_error(frappe.get_traceback(), "Promotional Scheme Field Patch Error")
+# Skip when posnext_promotions is installed so that app's patches are the single owner.
+if not _promotions_installed():
+	try:
+		from erpnext.accounts.doctype.pricing_rule import utils as pr_utils
+
+		from pos_next.overrides.pricing_rule import patch_get_other_conditions
+
+		patch_get_other_conditions(pr_utils)
+	except Exception:
+		pass
+
+	try:
+		from erpnext.accounts.doctype.pricing_rule import pricing_rule as _erpnext_pricing_rule
+
+		from pos_next.overrides.pricing_rule import (
+			apply_price_discount_rule as _pos_next_apply_price_discount_rule,
+		)
+
+		_erpnext_pricing_rule.apply_price_discount_rule = _pos_next_apply_price_discount_rule
+	except Exception:
+		if frappe:
+			frappe.log_error(frappe.get_traceback(), "Pricing Rule Override Error")
+
+	try:
+		from erpnext.accounts.doctype.promotional_scheme import promotional_scheme as _promotional_scheme
+
+		for _min_max_field in ("apply_discount_on_price", "min_or_max_discount_qty_limit"):
+			if _min_max_field not in _promotional_scheme.price_discount_fields:
+				_promotional_scheme.price_discount_fields.append(_min_max_field)
+	except Exception:
+		if frappe:
+			frappe.log_error(frappe.get_traceback(), "Promotional Scheme Field Patch Error")
 
 # Frappe/ERPNext compatibility shim:
 # ERPNext may pass do_not_round_fields to round_floats_in, but older Frappe
diff --git a/pos_next/api/customers.py b/pos_next/api/customers.py
index b24f80a5b..a12604a70 100644
--- a/pos_next/api/customers.py
+++ b/pos_next/api/customers.py
@@ -162,7 +162,7 @@ def create_customer(
 		}
 	)
 
-	publish_to_magento = prepare_customer_doc(
+	sync_external_customer = prepare_customer_doc(
 		customer,
 		custom_first_name=custom_first_name,
 		custom_last_name=custom_last_name,
@@ -173,7 +173,7 @@ def create_customer(
 	frappe.flags.pos_next_customer_pos_profile = pos_profile
 	try:
 		customer.insert()
-		if publish_to_magento:
+		if sync_external_customer:
 			after_customer_insert(
 				customer,
 				email_id=email_id,
diff --git a/pos_next/api/sales_invoice_hooks.py b/pos_next/api/sales_invoice_hooks.py
index 3963ae7f2..02377857b 100644
--- a/pos_next/api/sales_invoice_hooks.py
+++ b/pos_next/api/sales_invoice_hooks.py
@@ -151,6 +151,11 @@ def record_one_time_offer_usage(doc, method=None):
 	composite name ({customer}::{pricing_rule}) makes a duplicate insert raise
 	DuplicateEntryError, so it stays idempotent and race-safe.
 	"""
+	from pos_next.optional_apps import promotions_installed
+
+	if promotions_installed():
+		return
+
 	import json
 
 	if doc.get("is_return") or not doc.get("customer"):
@@ -186,6 +191,11 @@ def record_one_time_offer_usage(doc, method=None):
 
 def release_one_time_offer_usage(doc, method=None):
 	"""Release one-time redemptions on cancel so the customer can redeem again."""
+	from pos_next.optional_apps import promotions_installed
+
+	if promotions_installed():
+		return
+
 	frappe.db.delete("One Time Customer Offer Usage", {"sales_invoice": doc.name})
 
 
diff --git a/pos_next/api/wallet.py b/pos_next/api/wallet.py
index 8c43fca71..6f51a8117 100644
--- a/pos_next/api/wallet.py
+++ b/pos_next/api/wallet.py
@@ -445,6 +445,7 @@ def get_wallet_info(customer, company, pos_profile=None):
 		"loyalty_program": None,
 		"loyalty_to_wallet": False,
 		"balance_points": 0.0,
+		"balance_iqd": 0.0,
 		"magento_loyalty": False,
 	}
 
@@ -467,10 +468,11 @@ def get_wallet_info(customer, company, pos_profile=None):
 		try:
 			balance = get_external_loyalty_balance(customer)
 			result["wallet_balance"] = flt(balance.get("balance_iqd"))
+			result["balance_iqd"] = result["wallet_balance"]
 			result["balance_points"] = flt(balance.get("balance_points"))
 		except Exception as exc:
 			frappe.log_error(
-				title="Magento LP Balance Error",
+				title="External Loyalty Balance Error",
 				message=f"Customer: {customer}, Error: {exc!s}\n{frappe.get_traceback()}",
 			)
 		return result
@@ -505,6 +507,7 @@ def get_wallet_info(customer, company, pos_profile=None):
 				message=f"Customer: {customer}, Company: {company}, Error: {e!s}",
 			)
 
+	result["balance_iqd"] = flt(result.get("wallet_balance"))
 	return result
 
 
diff --git a/pos_next/integrations/registry.py b/pos_next/integrations/registry.py
index 6c4856419..833b871cd 100644
--- a/pos_next/integrations/registry.py
+++ b/pos_next/integrations/registry.py
@@ -54,12 +54,12 @@ def validate_customer_create(**kwargs):
 
 
 def prepare_customer_doc(customer, **kwargs):
-	publish_to_magento = False
+	sync_external_customer = False
 	for method_path in frappe.get_hooks("pos_next_customer_prepare") or []:
 		result = frappe.get_attr(method_path)(customer, **kwargs)
 		if result:
-			publish_to_magento = True
-	return publish_to_magento
+			sync_external_customer = True
+	return sync_external_customer
 
 
 def after_customer_insert(customer, **kwargs):
diff --git a/pos_next/optional_apps.py b/pos_next/optional_apps.py
new file mode 100644
index 000000000..154a0f84b
--- /dev/null
+++ b/pos_next/optional_apps.py
@@ -0,0 +1,19 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Runtime checks for optional apps.
+
+pos_next must not import those packages. Callers skip duplicate hooks and
+monkey-patches when the owning app is installed.
+"""
+
+from __future__ import annotations
+
+import frappe
+
+
+def promotions_installed() -> bool:
+	try:
+		return "posnext_promotions" in frappe.get_installed_apps()
+	except Exception:
+		return False
diff --git a/pos_next/overrides/pricing_rule.py b/pos_next/overrides/pricing_rule.py
index 928a24c05..2e4eb9f6c 100644
--- a/pos_next/overrides/pricing_rule.py
+++ b/pos_next/overrides/pricing_rule.py
@@ -32,6 +32,8 @@
 )
 from erpnext.accounts.doctype.pricing_rule.utils import get_applied_pricing_rules
 
+from pos_next.optional_apps import promotions_installed
+
 # Values of the ``apply_discount_on_price`` custom field that trigger ranking.
 MIN_MAX_OPTIONS = ("Min", "Max")
 
@@ -71,6 +73,8 @@ def sync_pos_only_to_pricing_rules(doc, method=None):
 	Propagates both ``pos_only`` and ``one_time_per_customer`` so a scheme acts as
 	the single source of truth for the rules it generates.
 	"""
+	if promotions_installed():
+		return
 	frappe.db.set_value(
 		"Pricing Rule",
 		{"promotional_scheme": doc.name},
@@ -131,6 +135,9 @@ def enforce_min_max_pricing_config(doc, method=None):
 	on the price-discount slabs and the generated rules inherit ``mixed_conditions``)
 	and **Pricing Rule** (standalone or scheme-generated).
 	"""
+	if promotions_installed():
+		return
+
 	if doc.doctype == "Promotional Scheme":
 		min_max_slabs = [
 			slab
@@ -221,6 +228,9 @@ def apply_min_max_price_discounts(doc, method=None, allowed_rules=None):
 		allowed_rules: Optional iterable of rule names; when given, only those rules
 			are applied (used by the POS UI to honour explicitly selected offers).
 	"""
+	if promotions_installed():
+		return
+
 	try:
 		rule_items, pricing_rules = _collect_min_max_rule_items(doc)
 		if not rule_items:
diff --git a/pos_next/test_no_promotions_import.py b/pos_next/test_no_promotions_import.py
index 915285a2f..e2ca54166 100644
--- a/pos_next/test_no_promotions_import.py
+++ b/pos_next/test_no_promotions_import.py
@@ -1,5 +1,5 @@
 # Copyright (c) 2026, BrainWise and contributors
-"""pos_next must not import posnext_promotions (compose only via Frappe hooks / Vue boot)."""
+"""pos_next must not import optional apps (compose only via Frappe hooks / Vue boot)."""
 
 from __future__ import annotations
 
@@ -8,6 +8,8 @@
 from pathlib import Path
 
 POS_NEXT_PKG = Path(__file__).resolve().parent
+POS_NEXT_APP = POS_NEXT_PKG.parent
+SKIP_IMPORT_FILES = {"test_no_promotions_import.py", "test_split_smoke.py"}
 
 
 def _python_files():
@@ -17,6 +19,27 @@ def _python_files():
 		yield path
 
 
+def _forbidden_imports(forbidden: str, skip_names=()):
+	violations = []
+	for path in _python_files():
+		if path.name in skip_names:
+			continue
+		try:
+			tree = ast.parse(path.read_text(), filename=str(path))
+		except SyntaxError:
+			continue
+		for node in ast.walk(tree):
+			if isinstance(node, ast.Import):
+				for alias in node.names:
+					if alias.name == forbidden or alias.name.startswith(forbidden + "."):
+						violations.append(f"{path}:{node.lineno} import {alias.name}")
+			elif isinstance(node, ast.ImportFrom):
+				mod = node.module or ""
+				if mod == forbidden or mod.startswith(forbidden + "."):
+					violations.append(f"{path}:{node.lineno} from {mod}")
+	return violations
+
+
 class TestNoPromotionsImport(unittest.TestCase):
 	def test_hooks_do_not_require_posnext_promotions(self):
 		hooks = (POS_NEXT_PKG / "hooks.py").read_text()
@@ -25,25 +48,14 @@ def test_hooks_do_not_require_posnext_promotions(self):
 		self.assertNotIn("pos_next_auth_provider", hooks)
 
 	def test_no_python_import_of_posnext_promotions(self):
-		violations = []
-		for path in _python_files():
-			if path.name == "test_no_promotions_import.py":
-				continue
-			try:
-				tree = ast.parse(path.read_text(), filename=str(path))
-			except SyntaxError:
-				continue
-			for node in ast.walk(tree):
-				if isinstance(node, ast.Import):
-					for alias in node.names:
-						if alias.name == "posnext_promotions" or alias.name.startswith("posnext_promotions."):
-							violations.append(f"{path}:{node.lineno} import {alias.name}")
-				elif isinstance(node, ast.ImportFrom):
-					mod = node.module or ""
-					if mod == "posnext_promotions" or mod.startswith("posnext_promotions."):
-						violations.append(f"{path}:{node.lineno} from {mod}")
+		violations = _forbidden_imports("posnext_promotions", skip_names=SKIP_IMPORT_FILES)
 		self.assertEqual(violations, [], "posnext_promotions imports are forbidden:\n" + "\n".join(violations))
 
+	def test_no_python_import_of_magento_or_miraaya(self):
+		for pkg in ("magento_integration", "masar_miraaya"):
+			violations = _forbidden_imports(pkg, skip_names=SKIP_IMPORT_FILES)
+			self.assertEqual(violations, [], f"{pkg} imports are forbidden:\n" + "\n".join(violations))
+
 	def test_magento_registry_hook_lists_exist(self):
 		hooks = (POS_NEXT_PKG / "hooks.py").read_text()
 		for name in (
@@ -55,6 +67,34 @@ def test_magento_registry_hook_lists_exist(self):
 		):
 			self.assertIn(f"{name} = []", hooks)
 
+	def test_no_gift_pool_backend_on_pos_next(self):
+		self.assertFalse((POS_NEXT_PKG / "api" / "gift_pool.py").exists())
+		self.assertFalse((POS_NEXT_PKG / "pos_next" / "doctype" / "pos_gift_pool_item").exists())
+
+	def test_no_miraaya_receipt_on_pos_next(self):
+		self.assertFalse((POS_NEXT_PKG / "pos_next" / "print_format" / "miraaya_receipt").exists())
+		uninstall = (POS_NEXT_PKG / "uninstall.py").read_text()
+		self.assertNotIn("Miraaya Receipt", uninstall)
+
+	def test_invoice_cart_uses_wallet_api(self):
+		invoice_cart = (POS_NEXT_APP / "POS" / "src" / "components" / "sale" / "InvoiceCart.vue").read_text()
+		self.assertIn("pos_next.api.wallet.get_wallet_info", invoice_cart)
+		self.assertNotIn("magento_integration", invoice_cart)
+
+	def test_gift_pool_vue_is_boot_gated(self):
+		promo_mgmt = (POS_NEXT_APP / "POS" / "src" / "components" / "sale" / "PromotionManagement.vue").read_text()
+		self.assertIn("isPromotionsAppInstalled", promo_mgmt)
+		self.assertIn("Gift Pool", promo_mgmt)
+		pos_cart = (POS_NEXT_APP / "POS" / "src" / "stores" / "posCart.js").read_text()
+		self.assertIn("isPromotionsAppInstalled", pos_cart)
+		self.assertIn("Gift Pool", pos_cart)
+
+	def test_customer_create_uses_bootstrap_flag(self):
+		dialog = (POS_NEXT_APP / "POS" / "src" / "components" / "sale" / "CreateCustomerDialog.vue").read_text()
+		self.assertIn("requiresSplitCustomerName", dialog)
+		self.assertNotIn("masar_miraaya", dialog)
+		self.assertNotIn("magento_integration", dialog)
+
 
 if __name__ == "__main__":
 	unittest.main()
diff --git a/pos_next/test_split_smoke.py b/pos_next/test_split_smoke.py
index 56d641e82..701bcca0c 100644
--- a/pos_next/test_split_smoke.py
+++ b/pos_next/test_split_smoke.py
@@ -1,8 +1,8 @@
 # Copyright (c) 2026, BrainWise and contributors
-"""Smoke tests for Magento integration split."""
+"""Smoke tests for optional-app split (Magento / promotions / Miraaya)."""
 
 import unittest
-from unittest.mock import Mock, patch
+from unittest.mock import patch
 
 import frappe
 
@@ -11,16 +11,26 @@
 	get_loyalty_provider,
 	is_external_loyalty_available,
 	is_external_loyalty_mode,
+	prepare_customer_doc,
 )
 
 
+def _app_installed(name: str) -> bool:
+	return name in frappe.get_installed_apps()
+
+
 class TestMagentoSplitSmoke(unittest.TestCase):
 	def test_loyalty_provider_hook_registered(self):
 		provider = get_loyalty_provider()
-		self.assertIsNotNone(provider)
-		self.assertTrue(callable(provider.get("is_available")))
-		self.assertTrue(callable(provider.get("is_loyalty_mode")))
-		self.assertTrue(callable(provider.get("get_balance")))
+		if _app_installed("magento_integration"):
+			self.assertIsNotNone(provider)
+			self.assertTrue(callable(provider.get("is_available")))
+			self.assertTrue(callable(provider.get("is_loyalty_mode")))
+			self.assertTrue(callable(provider.get("get_balance")))
+		else:
+			self.assertIsNone(provider)
+			self.assertFalse(is_external_loyalty_available())
+			self.assertFalse(is_external_loyalty_mode("POS-TEST"))
 
 	def test_bootstrap_settings_hook_extends_flags(self):
 		settings = {"magento_loyalty_available": 0, "miraaya_installed": 0}
@@ -29,6 +39,8 @@ def test_bootstrap_settings_hook_extends_flags(self):
 		self.assertIn("magento_loyalty_available", settings)
 
 	def test_magento_doc_events_registered(self):
+		if not _app_installed("magento_integration"):
+			self.skipTest("magento_integration is not installed")
 		hooks = frappe.get_hooks("doc_events", {}).get("Sales Invoice", {}).get("on_submit", [])
 		self.assertIn(
 			"magento_integration.api.magento_loyalty.redeem_magento_lp_on_submit",
@@ -55,7 +67,26 @@ def test_wallet_balance_without_magento_mode(self, _mock_mode):
 			balance = get_customer_wallet_balance("CUST-TEST", "Test Company")
 			self.assertEqual(balance, 0.0)
 
+	def test_wallet_info_includes_lp_aliases(self):
+		from pos_next.api.wallet import get_wallet_info
+
+		with (
+			patch("pos_next.api.wallet.get_pos_settings", return_value={"enable_loyalty_program": 0}),
+			patch("pos_next.api.wallet.is_external_loyalty_mode", return_value=False),
+		):
+			result = get_wallet_info("CUST-TEST", "Test Company", pos_profile="POS-TEST")
+		self.assertIn("wallet_enabled", result)
+		self.assertIn("balance_iqd", result)
+		self.assertIn("balance_points", result)
+		self.assertFalse(result["wallet_enabled"])
+
+	def test_prepare_customer_doc_is_generic(self):
+		result = prepare_customer_doc(frappe._dict(name="CUST-TEST"), custom_is_publish=0)
+		self.assertIsInstance(result, bool)
+
 	def test_magento_lp_balance_api_callable(self):
+		if not _app_installed("magento_integration"):
+			self.skipTest("magento_integration is not installed")
 		from magento_integration.api.magento_loyalty import get_lp_balance_for_customer
 
 		result = get_lp_balance_for_customer("NONEXISTENT-CUSTOMER", pos_profile=None)
@@ -77,6 +108,16 @@ def test_bootstrap_includes_integration_flags(self):
 		self.assertIn("magento_loyalty_available", settings)
 		self.assertTrue(data.get("success"))
 
+	def test_promotions_override_when_installed(self):
+		if not _app_installed("posnext_promotions"):
+			self.skipTest("posnext_promotions is not installed")
+		overrides = frappe.get_hooks("override_whitelisted_methods") or {}
+		mapped = overrides.get("pos_next.api.gift_pool.gift_pool_item_query")
+		if isinstance(mapped, (list, tuple)):
+			mapped = mapped[-1] if mapped else None
+		self.assertEqual(mapped, "posnext_promotions.api.gift_pool.gift_pool_item_query")
+		self.assertTrue(frappe.db.exists("DocType", "POS Gift Pool Item"))
+
 
 def run_smoke_tests():
 	loader = unittest.TestLoader()
diff --git a/scripts/run_split_smoke_tests.py b/scripts/run_split_smoke_tests.py
index 422322fed..7f0bb156c 100644
--- a/scripts/run_split_smoke_tests.py
+++ b/scripts/run_split_smoke_tests.py
@@ -4,7 +4,6 @@
 import os
 import sys
 import unittest
-from unittest.mock import patch
 
 import frappe
 
@@ -13,74 +12,21 @@
 
 
 def bootstrap(site: str):
-	os.chdir(BENCH_PATH)
-	frappe.init(site=site, sites_path=os.path.join(BENCH_PATH, "sites"))
+	os.chdir(os.path.join(BENCH_PATH, "sites"))
+	frappe.init(site=site)
 	frappe.connect()
 	frappe.set_user("Administrator")
 
 
-class TestMagentoSplitSmoke(unittest.TestCase):
-	def test_loyalty_provider_hook_registered(self):
-		from pos_next.integrations.registry import get_loyalty_provider
-
-		provider = get_loyalty_provider()
-		self.assertIsNotNone(provider)
-		self.assertTrue(callable(provider.get("is_available")))
-		self.assertTrue(callable(provider.get("is_loyalty_mode")))
-		self.assertTrue(callable(provider.get("get_balance")))
-
-	def test_bootstrap_settings_hook_extends_flags(self):
-		from pos_next.integrations.registry import extend_bootstrap_settings
-
-		settings = {"magento_loyalty_available": 0, "miraaya_installed": 0}
-		extend_bootstrap_settings(settings)
-		self.assertIn("miraaya_installed", settings)
-		self.assertIn("magento_loyalty_available", settings)
-
-	def test_magento_doc_events_registered(self):
-		hooks = frappe.get_hooks("doc_events", {}).get("Sales Invoice", {}).get("on_submit", [])
-		self.assertIn(
-			"magento_integration.api.magento_loyalty.redeem_magento_lp_on_submit",
-			hooks,
-		)
-		self.assertIn(
-			"magento_integration.api.magento_loyalty.add_magento_lp_on_submit",
-			hooks,
-		)
-		self.assertNotIn(
-			"pos_next.api.magento_loyalty.redeem_magento_lp_on_submit",
-			hooks,
-		)
-
-	def test_pos_next_has_no_magento_module(self):
-		with self.assertRaises((ImportError, ModuleNotFoundError)):
-			import pos_next.api.magento_loyalty  # noqa: F401
-
-	@patch("pos_next.api.wallet.is_external_loyalty_mode", return_value=False)
-	def test_wallet_balance_without_magento_mode(self, _mock_mode):
-		from pos_next.api.wallet import get_customer_wallet_balance
-
-		with patch("pos_next.api.wallet.frappe.db.get_value", return_value=None):
-			balance = get_customer_wallet_balance("CUST-TEST", "Test Company")
-			self.assertEqual(balance, 0.0)
-
-	def test_magento_lp_balance_api_callable(self):
-		from magento_integration.api.magento_loyalty import get_lp_balance_for_customer
-
-		result = get_lp_balance_for_customer("NONEXISTENT-CUSTOMER", pos_profile=None)
-		self.assertIn("wallet_enabled", result)
-		self.assertIn("balance_iqd", result)
-		self.assertIn("balance_points", result)
-
-	def test_bootstrap_api_importable(self):
-		from pos_next.api import bootstrap
-
-		self.assertTrue(hasattr(bootstrap, "get_bootstrap_data"))
-
-
 def main():
 	bootstrap("brainwise.dev")
-	suite = unittest.defaultTestLoader.loadTestsFromTestCase(TestMagentoSplitSmoke)
+	from pos_next.test_no_promotions_import import TestNoPromotionsImport
+	from pos_next.test_split_smoke import TestMagentoSplitSmoke
+
+	loader = unittest.defaultTestLoader
+	suite = unittest.TestSuite()
+	for cls in (TestNoPromotionsImport, TestMagentoSplitSmoke):
+		suite.addTests(loader.loadTestsFromTestCase(cls))
 	result = unittest.TextTestRunner(verbosity=2).run(suite)
 	frappe.destroy()
 	return 0 if result.wasSuccessful() else 1

From 7898316c659700af9b0db3def3532e15a9ec4945 Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Mon, 24 Aug 2026 15:44:25 +0300
Subject: [PATCH 4/8] Enhance stock validation and invoice handling in POS

- Updated useInvoice.js to prevent free items from inflating stock checks and adjusted actual_qty to prefer original_stock.
- Improved posCart.js to utilize new stock validation functions for accurate quantity checks, ensuring free items do not affect paid item stock validation.
- Added utility functions in stockValidator.js for calculating stock quantities and validating item availability based on combined paid and free rows.
- Modified _collect_stock_errors in invoices.py to sum quantities per item_code and warehouse, ensuring accurate stock error reporting.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 POS/src/composables/useInvoice.js             |  7 +-
 POS/src/stores/posCart.js                     | 29 ++++--
 .../utils/__tests__/stockValidator.spec.js    | 99 +++++++++++++++++++
 POS/src/utils/stockValidator.js               | 56 ++++++++++-
 pos_next/api/invoices.py                      | 29 ++++--
 5 files changed, 199 insertions(+), 21 deletions(-)
 create mode 100644 POS/src/utils/__tests__/stockValidator.spec.js

diff --git a/POS/src/composables/useInvoice.js b/POS/src/composables/useInvoice.js
index 2a2cb05f8..cc9f5bb23 100644
--- a/POS/src/composables/useInvoice.js
+++ b/POS/src/composables/useInvoice.js
@@ -219,7 +219,8 @@ export function useInvoice() {
 	function addItem(item, quantity = 1) {
 		const itemUom = item.uom || item.stock_uom;
 		const existingItem = invoiceItems.value.find(
-			(i) => i.item_code === item.item_code && i.uom === itemUom
+			(i) =>
+				!i.is_free_item && i.item_code === item.item_code && i.uom === itemUom
 		);
 
 		if (existingItem) {
@@ -285,7 +286,9 @@ export function useInvoice() {
 				// Resolved barcode flag - prevents editing qty/uom/rate for weighted/priced barcodes
 				is_resolved_barcode: item.is_resolved_barcode || false,
 				// Stock validation fields — needed for qty increase checks in cart
-				actual_qty: item.actual_qty ?? 0,
+				// Prefer Bin qty (original_stock). Grid actual_qty is remaining after cart reserve.
+				actual_qty: item.original_stock ?? item.actual_qty ?? 0,
+				original_stock: item.original_stock ?? item.actual_qty ?? 0,
 				is_stock_item: item.is_stock_item ?? 1,
 				is_bundle: item.is_bundle || false,
 				allow_negative_stock: item.allow_negative_stock || 0,
diff --git a/POS/src/stores/posCart.js b/POS/src/stores/posCart.js
index 08a012713..7742df180 100644
--- a/POS/src/stores/posCart.js
+++ b/POS/src/stores/posCart.js
@@ -4,7 +4,12 @@ import { usePOSOffersStore } from "@/stores/posOffers";
 import { usePOSSettingsStore } from "@/stores/posSettings";
 import { usePOSShiftStore } from "@/stores/posShift";
 import { parseError } from "@/utils/errorHandler";
-import { shouldValidateItemStock, checkStockAvailability } from "@/utils/stockValidator";
+import {
+	shouldValidateItemStock,
+	checkStockAvailability,
+	getCartStockQtyForItem,
+	rowStockQty,
+} from "@/utils/stockValidator";
 import { offlineState } from "@/utils/offline/offlineState";
 import { useToast } from "@/composables/useToast";
 import { defineStore } from "pinia";
@@ -182,12 +187,11 @@ export const usePOSCartStore = defineStore("posCart", () => {
 			settingsStore.shouldEnforceStockValidation() &&
 			shouldValidateItemStock(item)
 		) {
-			// Account for quantity already in the cart for this item
-			const itemUom = item.uom || item.stock_uom;
-			const existing = invoiceItems.value.find(
-				(i) => i.item_code === item.item_code && i.uom === itemUom
-			);
-			const totalQty = (existing ? existing.quantity : 0) + qty;
+			// Only this SKU (paid + free rows of the same item). A free gift of a
+			// different product must not inflate requested qty (Iphone 17 x6 +
+			// Aqua Water free x1 is 6 phones, not 7).
+			const totalQty =
+				getCartStockQtyForItem(invoiceItems.value, item.item_code) + rowStockQty(item, qty);
 			const warehouse = item.warehouse || currentProfile.warehouse;
 
 			const check = checkStockAvailability(item, totalQty, warehouse);
@@ -219,7 +223,10 @@ export const usePOSCartStore = defineStore("posCart", () => {
 			settingsStore.shouldEnforceStockValidation() &&
 			shouldValidateItemStock(item)
 		) {
-			const check = checkStockAvailability(item, newQty);
+			const otherLinesQty =
+				getCartStockQtyForItem(invoiceItems.value, item.item_code) - rowStockQty(item);
+			const totalQty = otherLinesQty + rowStockQty(item, newQty);
+			const check = checkStockAvailability(item, totalQty);
 			if (!check.available) {
 				showWarning(check.error);
 				return;
@@ -1492,7 +1499,11 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				settingsStore.shouldEnforceStockValidation() &&
 				shouldValidateItemStock(cartItem)
 			) {
-				const check = checkStockAvailability(cartItem, updates.quantity);
+				const otherLinesQty =
+					getCartStockQtyForItem(invoiceItems.value, cartItem.item_code) -
+					rowStockQty(cartItem);
+				const totalQty = otherLinesQty + rowStockQty(cartItem, updates.quantity);
+				const check = checkStockAvailability(cartItem, totalQty);
 				if (!check.available) {
 					throw new Error(check.error);
 				}
diff --git a/POS/src/utils/__tests__/stockValidator.spec.js b/POS/src/utils/__tests__/stockValidator.spec.js
new file mode 100644
index 000000000..b6def7963
--- /dev/null
+++ b/POS/src/utils/__tests__/stockValidator.spec.js
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("frappe-ui", () => ({ call: vi.fn() }));
+
+import {
+	checkStockAvailability,
+	getCartStockQtyForItem,
+	getWarehouseStockQty,
+	rowStockQty,
+} from "@/utils/stockValidator";
+
+/**
+ * Production case: Iphone 17 Bin qty = 6, cart has 6 phones + 1 free Aqua Water.
+ * Total cart qty is 7, but stock for the phone must only see the 6 phones.
+ */
+const IPHONE = {
+	item_code: "Iphone 17",
+	item_name: "Iphone 17",
+	warehouse: "Cairo - BPD",
+	actual_qty: 0, // grid remaining after reserving 6
+	stock_qty: 0,
+	original_stock: 6, // Bin qty
+	conversion_factor: 1,
+	is_stock_item: 1,
+};
+
+const CART = [
+	{
+		item_code: "Iphone 17",
+		item_name: "Iphone 17",
+		quantity: 6,
+		uom: "Nos",
+		conversion_factor: 1,
+		actual_qty: 6,
+		warehouse: "Cairo - BPD",
+	},
+	{
+		item_code: "Aqua Water",
+		item_name: "Aqua Water",
+		quantity: 1,
+		uom: "Nos",
+		conversion_factor: 1,
+		is_free_item: 1,
+		actual_qty: 9,
+		warehouse: "Cairo - BPD",
+	},
+];
+
+describe("getCartStockQtyForItem", () => {
+	it("counts only the SKU being sold, not free gift rows of other items", () => {
+		expect(getCartStockQtyForItem(CART, "Iphone 17")).toBe(6);
+		expect(getCartStockQtyForItem(CART, "Aqua Water")).toBe(1);
+	});
+
+	it("includes free rows of the same SKU (same-item BOGO still consumes stock)", () => {
+		const cart = [
+			{ item_code: "Iphone 17", quantity: 5, conversion_factor: 1 },
+			{ item_code: "Iphone 17", quantity: 1, conversion_factor: 1, is_free_item: 1 },
+		];
+		expect(getCartStockQtyForItem(cart, "Iphone 17")).toBe(6);
+	});
+});
+
+describe("getWarehouseStockQty", () => {
+	it("uses original_stock (Bin) instead of remaining display stock", () => {
+		expect(getWarehouseStockQty(IPHONE)).toBe(6);
+	});
+
+	it("falls back to actual_qty on cart lines that store Bin qty", () => {
+		expect(getWarehouseStockQty({ actual_qty: 6, stock_qty: 0 })).toBe(6);
+	});
+});
+
+describe("checkStockAvailability — Iphone 17 + free Aqua Water", () => {
+	it("allows keeping 6 phones in the cart when Bin qty is 6 (gift does not consume phone stock)", () => {
+		const requested = getCartStockQtyForItem(CART, "Iphone 17");
+		const check = checkStockAvailability(IPHONE, requested, "Cairo - BPD");
+		expect(check.available).toBe(true);
+		expect(check.actualQty).toBe(6);
+	});
+
+	it("blocks adding a 7th phone", () => {
+		const requested = getCartStockQtyForItem(CART, "Iphone 17") + rowStockQty(IPHONE, 1);
+		const check = checkStockAvailability(IPHONE, requested, "Cairo - BPD");
+		expect(check.available).toBe(false);
+		expect(check.error).toContain("You requested 7 units");
+		expect(check.error).toContain("only 6 units available");
+	});
+
+	it("does not double-count remaining grid stock against qty already in the cart", () => {
+		// Grid remaining is 1 after 5 phones reserved; Bin is 6. Adding the 6th must pass.
+		const gridItem = { ...IPHONE, actual_qty: 1, stock_qty: 1, original_stock: 6 };
+		const cart = [{ item_code: "Iphone 17", quantity: 5, conversion_factor: 1 }, CART[1]];
+		const requested = getCartStockQtyForItem(cart, "Iphone 17") + 1;
+		const check = checkStockAvailability(gridItem, requested, "Cairo - BPD");
+		expect(requested).toBe(6);
+		expect(check.available).toBe(true);
+	});
+});
diff --git a/POS/src/utils/stockValidator.js b/POS/src/utils/stockValidator.js
index 1d6fbe525..9ee38d23a 100644
--- a/POS/src/utils/stockValidator.js
+++ b/POS/src/utils/stockValidator.js
@@ -29,16 +29,66 @@ export function shouldValidateItemStock(item) {
 	return !!(item.is_stock_item || item.is_bundle || hasStockData);
 }
 
+/**
+ * Stock qty for a single cart/catalog row (qty × conversion_factor).
+ * @param {Object} row
+ * @returns {number}
+ */
+export function rowStockQty(row, qtyOverride = null) {
+	const qty =
+		qtyOverride !== null && qtyOverride !== undefined
+			? Number.parseFloat(qtyOverride)
+			: Number.parseFloat(row?.quantity ?? row?.qty ?? 0);
+	const factor = Number.parseFloat(row?.conversion_factor) || 1;
+	return (Number.isFinite(qty) ? qty : 0) * factor;
+}
+
+/**
+ * Sum stock qty already in the cart for one SKU only.
+ * Includes paid and free rows of that item_code; never other products
+ * (e.g. a free Aqua Water line must not count against iPhone 17).
+ *
+ * @param {Array} cartItems
+ * @param {string} itemCode
+ * @returns {number}
+ */
+export function getCartStockQtyForItem(cartItems, itemCode) {
+	if (!itemCode || !Array.isArray(cartItems)) return 0;
+	return cartItems.reduce((sum, row) => {
+		if (row?.item_code !== itemCode) return sum;
+		return sum + rowStockQty(row);
+	}, 0);
+}
+
+/**
+ * Warehouse (Bin) qty for the item.
+ *
+ * Grid items inject remaining stock into `actual_qty` (server − cart reserved)
+ * and keep Bin qty on `original_stock`. Cart lines store Bin qty on `actual_qty`.
+ * Always prefer `original_stock` so we never compare "qty already in cart + new"
+ * against remaining stock (that double-counts and inflates requested vs available).
+ *
+ * @param {Object} item
+ * @returns {number}
+ */
+export function getWarehouseStockQty(item) {
+	if (!item) return 0;
+	if (item.original_stock !== undefined && item.original_stock !== null) {
+		return Number.parseFloat(item.original_stock) || 0;
+	}
+	return Number.parseFloat(item.actual_qty ?? item.stock_qty ?? 0) || 0;
+}
+
 /**
  * Check if the requested quantity exceeds available stock.
  *
- * @param {Object}  item       - Item with actual_qty / stock_qty
- * @param {number}  requestedQty - Total quantity to validate against
+ * @param {Object}  item       - Item with actual_qty / stock_qty / original_stock
+ * @param {number}  requestedQty - Total quantity to validate against (this SKU only)
  * @param {string}  [warehouse]  - Warehouse name (for error message)
  * @returns {{ available: boolean, actualQty: number, error: string|null }}
  */
 export function checkStockAvailability(item, requestedQty, warehouse) {
-	const actualQty = item.actual_qty ?? item.stock_qty ?? 0;
+	const actualQty = getWarehouseStockQty(item);
 	const wh = warehouse || item.warehouse || "";
 
 	if (actualQty >= requestedQty) {
diff --git a/pos_next/api/invoices.py b/pos_next/api/invoices.py
index f927a6ebf..a5a318bac 100644
--- a/pos_next/api/invoices.py
+++ b/pos_next/api/invoices.py
@@ -444,24 +444,39 @@ def _get_available_stock(item):
 def _collect_stock_errors(items):
 	"""Return list of items exceeding available stock.
 
+	Sums qty per (item_code, warehouse) so paid + free rows of the same SKU are
+	checked together. Different products are never combined (a free gift of
+	another item must not count against the paid item's Bin qty).
+
 	Respects per-item allow_negative_stock if the field exists on Item.
 	"""
 	allowed_items = _get_item_negative_stock_allow_set(items)
-	errors = []
+	requested_by_key = {}
+	sample_by_key = {}
 	for d in items:
 		if flt(d.get("qty")) < 0:
 			continue
-
-		available = _get_available_stock(d)
+		item_code = d.get("item_code")
+		warehouse = d.get("warehouse")
+		if not item_code or not warehouse:
+			continue
 		requested = flt(d.get("stock_qty") or (flt(d.get("qty")) * flt(d.get("conversion_factor") or 1)))
+		key = (item_code, warehouse)
+		requested_by_key[key] = requested_by_key.get(key, 0) + requested
+		sample_by_key[key] = d
 
+	errors = []
+	for key, requested in requested_by_key.items():
+		item_code, warehouse = key
+		if item_code in allowed_items:
+			continue
+		sample = sample_by_key[key]
+		available = _get_available_stock(sample)
 		if requested > available:
-			if d.get("item_code") in allowed_items:
-				continue
 			errors.append(
 				{
-					"item_code": d.get("item_code"),
-					"warehouse": d.get("warehouse"),
+					"item_code": item_code,
+					"warehouse": warehouse,
 					"requested_qty": requested,
 					"available_qty": available,
 				}

From 3c3a7458b3f83f19f502eb0fcf0a7a7579770484 Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Tue, 25 Aug 2026 11:43:36 +0300
Subject: [PATCH 5/8] Enhance InvoiceCart and posCart for improved free item
 handling

- Added conditional rendering for buttons in InvoiceCart.vue to prevent actions on locked free rows.
- Updated quantity handling logic to ensure free items do not interfere with paid item interactions.
- Introduced isLockedFreeRow function to streamline checks for free item status.
- Enhanced posCart.js to manage free item quantities more effectively, ensuring accurate invoice processing for promotions like GWP.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 POS/src/components/sale/InvoiceCart.vue |  62 +++-------
 POS/src/stores/posCart.js               | 149 +++++++++++++++++++++---
 2 files changed, 155 insertions(+), 56 deletions(-)

diff --git a/POS/src/components/sale/InvoiceCart.vue b/POS/src/components/sale/InvoiceCart.vue
index 5315e5fcb..e4826bc49 100644
--- a/POS/src/components/sale/InvoiceCart.vue
+++ b/POS/src/components/sale/InvoiceCart.vue
@@ -1025,6 +1025,7 @@
 									</div>
 								</div>
 								<button
+									v-if="!isLockedFreeRow(item)"
 									type="button"
 									@click.stop="$emit('remove-item', item.item_code, item.uom)"
 									class="text-gray-400 hover:text-red-600 active:text-red-700 transition-colors flex-shrink-0 p-0.5 -m-0.5 touch-manipulation active:scale-90"
@@ -1093,7 +1094,7 @@
 										<button
 											type="button"
 											@click.stop="decrementQuantity(item)"
-											:disabled="item.is_resolved_barcode"
+											:disabled="item.is_resolved_barcode || isLockedFreeRow(item)"
 											:class="[
 												'w-6 h-6 sm:w-7 sm:h-7 flex items-center justify-center font-bold transition-colors touch-manipulation border-e',
 												item.is_resolved_barcode
@@ -1129,7 +1130,7 @@
 											@keydown.enter="$event.target.blur()"
 											type="text"
 											inputmode="decimal"
-											:disabled="item.is_resolved_barcode"
+											:disabled="item.is_resolved_barcode || isLockedFreeRow(item)"
 											:class="[
 												'w-16 sm:w-20 h-6 sm:h-7 text-center border-0 text-xs sm:text-sm font-bold focus:outline-none',
 												item.is_resolved_barcode
@@ -1146,7 +1147,7 @@
 										<button
 											type="button"
 											@click.stop="incrementQuantity(item)"
-											:disabled="item.is_resolved_barcode"
+											:disabled="item.is_resolved_barcode || isLockedFreeRow(item)"
 											:class="[
 												'w-6 h-6 sm:w-7 sm:h-7 flex items-center justify-center font-bold transition-colors touch-manipulation border-s',
 												item.is_resolved_barcode
@@ -1183,6 +1184,7 @@
 											@click="toggleUomDropdown(item.item_code, item.uom)"
 											:disabled="
 												item.is_resolved_barcode ||
+												isLockedFreeRow(item) ||
 												!item.item_uoms ||
 												item.item_uoms.length === 0
 											"
@@ -1590,48 +1592,19 @@ const {
 } = useCartSort(() => props.items);
 
 /**
- * Display-only merge: hide matching same-item free rows and show one combined line.
- * Cart data stays unchanged for offers and invoicing.
+ * Display cart lines as stored. Same-SKU GWP free gifts are their own row
+ * with a free-item badge (buy 2 get 1 free → 2 paid + 1 free after 3 scans).
  */
-function cartLineKey(item) {
-	return `${item.item_code}\0${item.uom || item.stock_uom || ""}`;
-}
-
 const displayCartItems = computed(() => {
 	const items = sortedItems.value;
-	const freeQtyByKey = new Map();
-	const paidKeys = new Set();
-
+	const merged = [];
 	for (const item of items) {
-		if (!item.is_free_item) {
-			paidKeys.add(cartLineKey(item));
+		if (item.is_free_item) {
+			merged.push({ ...item, _isStandaloneFreeRow: true });
 			continue;
 		}
-		const key = cartLineKey(item);
-		freeQtyByKey.set(
-			key,
-			(freeQtyByKey.get(key) || 0) + (Number.parseFloat(item.quantity) || 0)
-		);
-	}
-
-	const merged = [];
-	for (const item of items) {
-		if (item.is_free_item) continue;
-		const bundledFreeQty = freeQtyByKey.get(cartLineKey(item)) || 0;
-		merged.push(
-			bundledFreeQty > 0 ? { ...item, _bundledFreeQty: bundledFreeQty } : item
-		);
+		merged.push(item);
 	}
-
-	// Different-item product discounts add dedicated is_free_item rows (e.g. buy A get B).
-	// Those rows are not bundled onto a paid line — show them as their own cart lines.
-	for (const item of items) {
-		if (!item.is_free_item) continue;
-		const key = cartLineKey(item);
-		if (paidKeys.has(key)) continue;
-		merged.push({ ...item, _isStandaloneFreeRow: true });
-	}
-
 	return merged;
 });
 
@@ -2082,6 +2055,10 @@ function getInitials(name) {
  * Effective discount % for badges. Coupon max_amount caps are stored as
  * absolute amounts (discount_percentage=0), so derive % from amount/base.
  */
+function isLockedFreeRow(item) {
+	return Boolean(item?.is_free_item || item?._isStandaloneFreeRow);
+}
+
 function isGwpItem(item) {
 	return item?.discount_source === "gwp" || Number.parseFloat(item?.gwp_free_qty) > 0;
 }
@@ -2214,8 +2191,7 @@ function getSmartStep(quantity) {
  * @param {Object} item - Cart item to increment
  */
 function incrementQuantity(item) {
-	// Prevent editing resolved barcode items
-	if (item.is_resolved_barcode) return;
+	if (item.is_resolved_barcode || isLockedFreeRow(item)) return;
 
 	const step = getSmartStep(getDisplayQuantity(item));
 	const newPaidQty = Math.round((item.quantity + step) * 10000) / 10000;
@@ -2229,8 +2205,7 @@ function incrementQuantity(item) {
  * @param {Object} item - Cart item to decrement
  */
 function decrementQuantity(item) {
-	// Prevent editing resolved barcode items
-	if (item.is_resolved_barcode) return;
+	if (item.is_resolved_barcode || isLockedFreeRow(item)) return;
 
 	const step = getSmartStep(getDisplayQuantity(item));
 	const newPaidQty = Math.round((item.quantity - step) * 10000) / 10000;
@@ -2253,7 +2228,7 @@ function decrementQuantity(item) {
 
 function updateQuantity(item, value) {
 	// Prevent editing resolved barcode items
-	if (item.is_resolved_barcode) return;
+	if (item.is_resolved_barcode || isLockedFreeRow(item)) return;
 
 	const displayQty = Number.parseFloat(value);
 
@@ -2278,6 +2253,7 @@ function updateQuantity(item, value) {
  * @param {Object} item - Cart item that lost focus
  */
 function handleQuantityBlur(item) {
+	if (isLockedFreeRow(item)) return;
 	// When user leaves the input field, round and validate
 	if (!item.quantity || item.quantity <= 0) {
 		// If quantity is 0 or invalid, remove the item
diff --git a/POS/src/stores/posCart.js b/POS/src/stores/posCart.js
index 7742df180..4cd8a1a39 100644
--- a/POS/src/stores/posCart.js
+++ b/POS/src/stores/posCart.js
@@ -378,6 +378,7 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				price_list_rate: item.price_list_rate || item.rate,
 				discount_percentage: item.discount_percentage || 0,
 				discount_amount: item.discount_amount || 0,
+				is_free_item: item.is_free_item || 0,
 			})),
 		};
 	}
@@ -410,6 +411,9 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				item.discount_percentage = discountPct;
 				item.discount_amount = discountAmt;
 				item.pricing_rules = serverItem.pricing_rules;
+				item.discount_source = serverItem.discount_source || item.discount_source;
+				item.free_qty = Number.parseFloat(serverItem.free_qty) || 0;
+				item.gwp_free_qty = Number.parseFloat(serverItem.gwp_free_qty) || 0;
 				hasDiscounts = discountPct > 0 || discountAmt > 0;
 			}
 			// Otherwise preserve existing manual discount
@@ -434,17 +438,26 @@ export const usePOSCartStore = defineStore("posCart", () => {
 	 * @returns {void}
 	 */
 	function processFreeItems(freeItems) {
-		// Reset free_qty on all non-free items
+		// Restore qty previously carved into same-SKU free rows, then rebuild.
+		invoiceItems.value.forEach((item) => {
+			if (!item.is_free_item || Number(item.gwp_same_item_row) !== 1) return;
+			const freeQty = Number.parseFloat(item.quantity) || 0;
+			if (freeQty <= 0) return;
+			const paid = findPaidCartItem(item.item_code, item.uom || item.stock_uom);
+			if (paid) {
+				paid.quantity = (Number.parseFloat(paid.quantity) || 0) + freeQty;
+				recalculateItem(paid);
+			}
+		});
+
 		invoiceItems.value.forEach((item) => {
 			if (!item.is_free_item) {
 				item.free_qty = 0;
 			}
 		});
 
-		// Remove previously-added free item rows (they'll be re-added below if still valid)
 		invoiceItems.value = invoiceItems.value.filter((item) => !item.is_free_item);
 
-		// Early return if no free items
 		if (!Array.isArray(freeItems) || freeItems.length === 0) {
 			rebuildIncrementalCache();
 			return;
@@ -455,14 +468,16 @@ export const usePOSCartStore = defineStore("posCart", () => {
 			if (freeQty <= 0) continue;
 
 			const freeUom = freeItem.uom || freeItem.stock_uom;
-
-			// Check if this free item matches an existing (non-free) cart item
-			const cartItem = invoiceItems.value.find(
-				(item) =>
-					!item.is_free_item &&
-					item.item_code === freeItem.item_code &&
-					(item.uom || item.stock_uom) === freeUom
-			);
+			const cartItem = findPaidCartItem(freeItem.item_code, freeUom);
+
+			// Same SKU (GWP buy 2 get 1): split scanned units. Qty 3 → 2 paid + 1 free.
+			// Never auto-add a 4th unit on top of the 3 already in the cart.
+			const paidQty = cartItem ? Number.parseFloat(cartItem.quantity) || 0 : 0;
+			const carveFromPaid = Boolean(cartItem && paidQty > freeQty);
+			if (carveFromPaid) {
+				cartItem.quantity = paidQty - freeQty;
+				recalculateItem(cartItem);
+			}
 
 			const cf = freeItem.conversion_factor || cartItem?.conversion_factor || 1;
 			invoiceItems.value.push({
@@ -476,19 +491,33 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				tax_amount: 0,
 				amount: 0,
 				stock_qty: 0,
-				uom: freeUom,
-				stock_uom: freeItem.stock_uom || freeUom,
+				uom: cartItem?.uom || freeUom,
+				stock_uom: cartItem?.stock_uom || freeItem.stock_uom || freeUom,
 				conversion_factor: cf,
 				is_free_item: 1,
 				free_qty: freeQty,
+				discount_source: freeItem.discount_source || (carveFromPaid ? "gwp" : "free_item"),
+				gwp_same_item_row: carveFromPaid ? 1 : 0,
 				pricing_rules: freeItem.pricing_rules || null,
 				warehouse: freeItem.warehouse || cartItem?.warehouse,
+				image: cartItem?.image,
 			});
 		}
 
 		rebuildIncrementalCache();
 	}
 
+	function findPaidCartItem(itemCode, uom) {
+		if (!itemCode) return null;
+		const paid = invoiceItems.value.filter((item) => !item.is_free_item && item.item_code === itemCode);
+		if (!paid.length) return null;
+		if (uom) {
+			const matchedUom = paid.find((item) => (item.uom || item.stock_uom) === uom);
+			if (matchedUom) return matchedUom;
+		}
+		return paid[0];
+	}
+
 	/**
 	 * Extracts and normalizes the offer response from backend
 	 *
@@ -1165,6 +1194,97 @@ export const usePOSCartStore = defineStore("posCart", () => {
 		return applied;
 	}
 
+	/**
+	 * Offline GWP for a single SKU: cashier must scan paid + free units.
+	 * Buy 2 get 1 free needs qty 3, then splits 1 unit onto a free row.
+	 */
+	function applyOfflineGwpSameItem(offer, eligibleItems) {
+		const freeQty = Math.floor(Number.parseFloat(offer.free_qty) || 0);
+		const minQty = Number.parseFloat(offer.min_qty) || 0;
+		const maxQty = Number.parseFloat(offer.max_qty) || 0;
+		if (freeQty <= 0) return false;
+
+		const paidItems = eligibleItems.filter((item) => !item.is_free_item);
+		const codes = [...new Set(paidItems.map((item) => item.item_code).filter(Boolean))];
+		if (codes.length !== 1) {
+			return false;
+		}
+
+		const itemCode = codes[0];
+		const matching = invoiceItems.value.filter(
+			(item) => item.item_code === itemCode && !item.is_free_item
+		);
+		const existingFree = invoiceItems.value.filter(
+			(item) => item.item_code === itemCode && item.is_free_item
+		);
+		const totalQty = [...matching, ...existingFree].reduce(
+			(sum, item) => sum + (Math.floor(item.quantity || item.qty || 0) || 0),
+			0
+		);
+		const paidAfterFree = totalQty - freeQty;
+		if (totalQty < minQty + freeQty || paidAfterFree <= 0) return false;
+		if (minQty > 0 && paidAfterFree < minQty) return false;
+		if (maxQty > 0 && paidAfterFree > maxQty) return false;
+
+		const referenceItem = matching[0];
+		if (!referenceItem) return false;
+		const uomKey = referenceItem.uom || referenceItem.stock_uom;
+		if ((Number.parseFloat(referenceItem.quantity) || 0) > freeQty) {
+			referenceItem.quantity = (Number.parseFloat(referenceItem.quantity) || 0) - freeQty;
+			recalculateItem(referenceItem);
+		}
+
+		for (const item of matching) {
+			const pr = item.pricing_rules;
+			const prArr = Array.isArray(pr)
+				? [...pr]
+				: pr
+					? String(pr)
+							.split(",")
+							.map((s) => s.trim())
+							.filter(Boolean)
+					: [];
+			if (!prArr.includes(offer.name)) prArr.push(offer.name);
+			item.pricing_rules = prArr;
+		}
+
+		const existingFreeRow = invoiceItems.value.find(
+			(r) =>
+				r.is_free_item &&
+				r.item_code === itemCode &&
+				(r.uom || r.stock_uom) === uomKey
+		);
+		if (existingFreeRow) {
+			existingFreeRow.quantity = freeQty;
+			existingFreeRow.free_qty = freeQty;
+			existingFreeRow.gwp_same_item_row = 1;
+			existingFreeRow.discount_source = "gwp";
+		} else {
+			invoiceItems.value.push({
+				item_code: itemCode,
+				item_name: referenceItem.item_name || itemCode,
+				rate: 0,
+				price_list_rate: 0,
+				quantity: freeQty,
+				discount_amount: 0,
+				discount_percentage: 0,
+				tax_amount: 0,
+				amount: 0,
+				stock_qty: 0,
+				uom: uomKey,
+				stock_uom: referenceItem.stock_uom || uomKey,
+				conversion_factor: referenceItem.conversion_factor || 1,
+				is_free_item: 1,
+				free_qty: freeQty,
+				discount_source: "gwp",
+				gwp_same_item_row: 1,
+				pricing_rules: [offer.name],
+				warehouse: referenceItem.warehouse,
+			});
+		}
+		return true;
+	}
+
 	/**
 	 * Apply free item (product discount) offer offline
 	 * Handles: same_item (free item = purchased item) or specific free_item
@@ -1183,6 +1303,9 @@ export const usePOSCartStore = defineStore("posCart", () => {
 		if (isPromotionsAppInstalled() && offer.promotion_type === "Gift Pool") {
 			return applyOfflineGiftPool(offer, eligibleItems);
 		}
+		if (isPromotionsAppInstalled() && offer.promotion_type === "GWP") {
+			return applyOfflineGwpSameItem(offer, eligibleItems);
+		}
 		const freeQty = Number.parseFloat(offer.free_qty) || 0;
 		const sameItem = offer.same_item === 1;
 		const isRecursive = offer.is_recursive === 1;

From 1e53275b6a5028bbc16b908924d565c97a2c51c2 Mon Sep 17 00:00:00 2001
From: MostafaKadry <mostafa.kadry@brainwise.me>
Date: Tue, 25 Aug 2026 16:20:42 +0300
Subject: [PATCH 6/8] feat: implement POS authorization gate system with action
 registry, validation rules, and grant management

---
 POS/src/App.vue                               |   5 +-
 POS/src/index.css                             |   1 +
 pos_next/api/authorization.py                 | 200 +++++++++++++++
 pos_next/api/bootstrap.py                     |  22 ++
 pos_next/api/invoices.py                      |   4 +
 pos_next/api/test_authorization.py            |  58 +++++
 pos_next/authorization/__init__.py            |  21 ++
 pos_next/authorization/actions/__init__.py    |   5 +
 .../authorization/actions/sales_invoice.py    |  60 +++++
 pos_next/authorization/gate.py                | 113 +++++++++
 pos_next/authorization/grants.py              | 126 ++++++++++
 pos_next/authorization/log.py                 |  65 +++++
 pos_next/authorization/pin.py                 | 237 ++++++++++++++++++
 pos_next/authorization/policy.py              | 233 +++++++++++++++++
 pos_next/authorization/registry.py            | 108 ++++++++
 pos_next/authorization/tests/__init__.py      |   0
 pos_next/authorization/tests/helpers.py       |  90 +++++++
 .../tests/test_actions_sales_invoice.py       |  39 +++
 pos_next/authorization/tests/test_gate.py     |  73 ++++++
 pos_next/authorization/tests/test_grants.py   |  58 +++++
 pos_next/authorization/tests/test_log.py      |  45 ++++
 pos_next/authorization/tests/test_pin.py      | 179 +++++++++++++
 pos_next/authorization/tests/test_policy.py   | 195 ++++++++++++++
 pos_next/hooks.py                             |   2 +
 pos_next/modules.txt                          |   3 +-
 pos_next/pos_next_auth_gate/__init__.py       |   0
 .../pos_next_auth_gate/doctype/__init__.py    |   0
 .../pos_authorization_approver/__init__.py    |   0
 .../pos_authorization_approver.json           |  72 ++++++
 .../pos_authorization_approver.py             |   8 +
 .../doctype/pos_authorization_log/__init__.py |   0
 .../pos_authorization_log.json                | 115 +++++++++
 .../pos_authorization_log.py                  |   8 +
 .../pos_authorization_rule/__init__.py        |   0
 .../pos_authorization_rule.js                 |   8 +
 .../pos_authorization_rule.json               |  92 +++++++
 .../pos_authorization_rule.py                 |  26 ++
 .../test_pos_authorization_rule.py            |   9 +
 .../pos_authorization_settings/__init__.py    |   0
 .../pos_authorization_settings.json           |  83 ++++++
 .../pos_authorization_settings.py             |   9 +
 pos_next/public/js/user.js                    | 115 +++++++++
 42 files changed, 2482 insertions(+), 5 deletions(-)
 create mode 100644 pos_next/api/authorization.py
 create mode 100644 pos_next/api/test_authorization.py
 create mode 100644 pos_next/authorization/__init__.py
 create mode 100644 pos_next/authorization/actions/__init__.py
 create mode 100644 pos_next/authorization/actions/sales_invoice.py
 create mode 100644 pos_next/authorization/gate.py
 create mode 100644 pos_next/authorization/grants.py
 create mode 100644 pos_next/authorization/log.py
 create mode 100644 pos_next/authorization/pin.py
 create mode 100644 pos_next/authorization/policy.py
 create mode 100644 pos_next/authorization/registry.py
 create mode 100644 pos_next/authorization/tests/__init__.py
 create mode 100644 pos_next/authorization/tests/helpers.py
 create mode 100644 pos_next/authorization/tests/test_actions_sales_invoice.py
 create mode 100644 pos_next/authorization/tests/test_gate.py
 create mode 100644 pos_next/authorization/tests/test_grants.py
 create mode 100644 pos_next/authorization/tests/test_log.py
 create mode 100644 pos_next/authorization/tests/test_pin.py
 create mode 100644 pos_next/authorization/tests/test_policy.py
 create mode 100644 pos_next/pos_next_auth_gate/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.json
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_log/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.json
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.js
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.json
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/test_pos_authorization_rule.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/__init__.py
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.json
 create mode 100644 pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.py
 create mode 100644 pos_next/public/js/user.js

diff --git a/POS/src/App.vue b/POS/src/App.vue
index 93d31357f..f108f0cf6 100644
--- a/POS/src/App.vue
+++ b/POS/src/App.vue
@@ -2,15 +2,12 @@
 	<div>
 		<router-view :key="translationVersion" />
 		<Toast />
-		<AuthorizationDialog v-if="authGateInstalled" />
+		<AuthorizationDialog />
 	</div>
 </template>
 
 <script setup>
 import AuthorizationDialog from "@/components/common/AuthorizationDialog.vue";
 import Toast from "@/components/common/Toast.vue";
-import { isAuthGateInstalled } from "@/utils/promoApi";
 import { translationVersion } from "@/utils/translation";
-
-const authGateInstalled = isAuthGateInstalled();
 </script>
diff --git a/POS/src/index.css b/POS/src/index.css
index 2491328cc..927a90edb 100644
--- a/POS/src/index.css
+++ b/POS/src/index.css
@@ -7,6 +7,7 @@
 	--z-dialog-overlay: 400;
 	--z-dialog-content: 500;
 	--z-dropdown: 10000;
+	--z-authorization: 10010;
 }
 
 /* Apply Saudi Riyal symbol font to body for currency support */
diff --git a/pos_next/api/authorization.py b/pos_next/api/authorization.py
new file mode 100644
index 000000000..c73677009
--- /dev/null
+++ b/pos_next/api/authorization.py
@@ -0,0 +1,200 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Whitelisted endpoints for the POS authorization gate.
+
+None of these decide anything. The authority is
+:func:`pos_next.authorization.gate.enforce_document`, which runs on ``before_submit`` and
+refuses an action whose grant is missing, expired or bound to something else. These
+endpoints exist so the POS can ask *whether* approval is needed, *who* can give it, and
+*mint a grant* once someone has proved their PIN.
+"""
+
+import json
+
+import frappe
+from frappe import _
+from frappe.rate_limiter import rate_limit
+from frappe.utils import flt
+
+from pos_next.authorization import gate, grants, log, policy, registry
+from pos_next.authorization import pin as pin_store
+
+
+def _parse_context(context) -> dict:
+	"""Normalise the context a client sends alongside an authorization request."""
+	if isinstance(context, str):
+		context = json.loads(context) if context else {}
+
+	context = dict(context or {})
+
+	context["amount"] = abs(flt(context.get("amount")))
+	return context
+
+
+@frappe.whitelist()
+def get_authorization_policy(pos_profile: str | None = None) -> dict:
+	policy_map = {}
+	for action in registry.all_actions():
+		if gate.is_required(action.name, pos_profile):
+			policy_map[action.name] = True
+
+	return policy_map
+
+
+@frappe.whitelist()
+def get_authorizers(action: str, pos_profile: str | None = None, context=None) -> list[dict]:
+	action_def = registry.get(action)
+	if not action_def:
+		return []
+
+	context = _parse_context(context)
+	context.setdefault("pos_profile", pos_profile)
+
+	rule = policy.resolve_rule(action, context.get("pos_profile"))
+	if not rule:
+		return []
+
+	candidates = policy.eligible_approvers(rule, context)
+
+	if not rule.get("allow_self_approval"):
+		candidates.discard(frappe.session.user)
+
+	with_pin = pin_store.users_with_pin(candidates)
+	if not with_pin:
+		return []
+
+	rows = frappe.get_all(
+		"User",
+		filters={"name": ("in", list(with_pin))},
+		fields=["name as user", "full_name"],
+		order_by="full_name asc",
+	)
+	return rows
+
+
+@frappe.whitelist()
+def get_authorization_readiness(action: str, pos_profile: str | None = None) -> dict:
+	frappe.only_for("System Manager")
+
+	rule = policy.resolve_rule(action, pos_profile)
+	if not rule:
+		return {"rule": None, "ready": [], "missing_pin": []}
+
+	candidates = policy.eligible_approvers(rule, {"pos_profile": pos_profile})
+	with_pin = pin_store.users_with_pin(candidates)
+
+	return {
+		"rule": rule.name,
+		"ready": sorted(with_pin),
+		"missing_pin": sorted(candidates - with_pin),
+	}
+
+
+@frappe.whitelist()
+@rate_limit(limit=5, seconds=60)
+def request_grant(action: str, approver: str, pin: str, context=None) -> dict:
+	action_def = registry.get(action)
+	if not action_def:
+		return {"authorized": False, "message": _("Unknown authorization action")}
+
+	context = _parse_context(context)
+	pos_profile = context.get("pos_profile")
+
+	rule = policy.resolve_rule(action, pos_profile)
+	if not rule:
+		return {"authorized": False, "message": _("No authorization rule applies to this action.")}
+
+	def _deny(result: str, message: str) -> dict:
+		log.record(
+			action=action,
+			approver=approver,
+			result=result,
+			pos_profile=pos_profile,
+			reference=context.get("return_against"),
+		)
+		return {"authorized": False, "message": message}
+
+	if pin_store.is_locked_out(approver):
+		return _deny(
+			log.RESULT_LOCKED_OUT,
+			_("Too many failed attempts. Approval is locked for {0} minutes.").format(
+				pin_store.lockout_seconds() // 60
+			),
+		)
+
+	if not policy.is_approver(rule, approver, context):
+		return _deny(
+			log.RESULT_NOT_AUTHORIZED,
+			_("This user is not permitted to approve this action."),
+		)
+
+	if not pin_store.has_pin(approver):
+		return _deny(
+			log.RESULT_NO_PIN,
+			_("{0} has no authorization PIN yet. A System Manager can set one on the User record.").format(
+				approver
+			),
+		)
+
+	if not pin_store.verify(approver, pin):
+		locked = pin_store.register_failure(approver)
+		if locked:
+			return _deny(
+				log.RESULT_LOCKED_OUT,
+				_("Too many failed attempts. Approval is locked for {0} minutes.").format(
+					pin_store.lockout_seconds() // 60
+				),
+			)
+		return _deny(log.RESULT_INVALID_PIN, _("Incorrect PIN"))
+
+	pin_store.clear_failures(approver)
+	token = grants.issue(action, approver, action_def.binding(context))
+
+	return {
+		"authorized": True,
+		"grant_token": token,
+		"expires_in": grants.GRANT_TTL,
+		"approved_by": approver,
+	}
+
+
+@frappe.whitelist()
+def set_authorization_pin(user: str, new_pin: str, current_pin: str | None = None) -> dict:
+	user = user or frappe.session.user
+	pin_store.validate_format(new_pin)
+
+	if user == frappe.session.user:
+		if pin_store.has_pin(user) and not pin_store.verify(user, current_pin):
+			return {"success": False, "message": _("Current PIN is incorrect")}
+	else:
+		frappe.has_permission("User", ptype="write", doc=user, throw=True)
+
+	pin_store.set_pin(user, new_pin)
+	log.record(action="set_authorization_pin", approver=user, result=log.RESULT_PIN_SET)
+
+	return {"success": True, "message": _("PIN updated")}
+
+
+@frappe.whitelist()
+def clear_authorization_pin(user: str) -> dict:
+	"""Remove a user's PIN. System Manager only — this revokes their ability to approve."""
+	frappe.only_for("System Manager")
+
+	pin_store.clear_pin(user)
+	log.record(action="clear_authorization_pin", approver=user, result=log.RESULT_PIN_SET)
+
+	return {"success": True}
+
+
+@frappe.whitelist()
+def has_authorization_pin(user: str | None = None) -> dict:
+	user = user or frappe.session.user
+	if user != frappe.session.user:
+		frappe.has_permission("User", ptype="read", doc=user, throw=True)
+
+	return {
+		"has_pin": pin_store.has_pin(user),
+		"pin_length": pin_store.pin_length(),
+		"strict_pin_enforced": pin_store.strict_pin_enforced(),
+	}
diff --git a/pos_next/api/bootstrap.py b/pos_next/api/bootstrap.py
index 926cf057a..59d050b01 100644
--- a/pos_next/api/bootstrap.py
+++ b/pos_next/api/bootstrap.py
@@ -106,6 +106,8 @@ def get_initial_data():
 
 	result["pos_settings"] = _get_pos_settings(pos_profile)
 	result["payment_methods"] = _get_payment_methods(pos_profile_name)
+	result["authorization_policy"] = _get_authorization_policy(pos_profile_name)
+	result["authorization_pin_length"] = _get_authorization_pin_length()
 
 	return result
 
@@ -115,6 +117,26 @@ def get_initial_data():
 # =============================================================================
 
 
+def _get_authorization_policy(pos_profile_name):
+	try:
+		from pos_next.api.authorization import get_authorization_policy
+
+		return get_authorization_policy(pos_profile_name)
+	except Exception:
+		frappe.log_error(frappe.get_traceback(), "Get Authorization Policy Error")
+		return {}
+
+
+def _get_authorization_pin_length():
+	try:
+		from pos_next.authorization import pin as pin_store
+
+		return pin_store.pin_length()
+	except Exception:
+		frappe.log_error(frappe.get_traceback(), "Get Authorization PIN Length Error")
+		return 4
+
+
 def _get_user_language():
 	"""
 	Get user's language preference from User doctype.
diff --git a/pos_next/api/invoices.py b/pos_next/api/invoices.py
index a5a318bac..23effb528 100644
--- a/pos_next/api/invoices.py
+++ b/pos_next/api/invoices.py
@@ -1478,6 +1478,10 @@ def submit_invoice(invoice=None, data=None):
 		frappe.flags.ignore_account_permission = True
 		invoice_doc.save()
 
+		from pos_next.authorization.gate import TOKEN_FLAG
+
+		invoice_doc.flags[TOKEN_FLAG] = invoice.get("authorization_token") or data.get("authorization_token")
+
 		# Submit invoice
 		invoice_doc.submit()
 		invoice_submitted = True
diff --git a/pos_next/api/test_authorization.py b/pos_next/api/test_authorization.py
new file mode 100644
index 000000000..bba6c3d16
--- /dev/null
+++ b/pos_next/api/test_authorization.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.api.authorization — the endpoints themselves, not just the domain
+functions underneath them.
+
+request_grant() in particular is worth exercising end-to-end: it's the one place a
+stale reference to a since-renamed pin.py constant (LOCKOUT_SECONDS -> lockout_seconds())
+slipped through undetected, because every other authorization test calls pin_store /
+policy / grants directly rather than through this API layer.
+"""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.api.authorization import request_grant
+from pos_next.authorization import pin as pin_store
+from pos_next.authorization.tests.helpers import (
+	DUMMY_ACTION,
+	GOOD_PIN,
+	MANAGER,
+	OTHER_PIN,
+	ROLE,
+	make_role,
+	make_rule,
+	make_user,
+)
+
+
+class TestRequestGrant(FrappeTestCase):
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_role(ROLE)
+		make_user(MANAGER, [ROLE])
+		pin_store.set_pin(MANAGER, GOOD_PIN)
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		pin_store.clear_failures(MANAGER)
+		make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+
+	def test_wrong_pin_that_triggers_lockout_on_this_attempt_does_not_crash(self):
+		"""The exact path the stale LOCKOUT_SECONDS reference broke: a wrong PIN whose
+		failure count also crosses max_failures() on this very call.
+		"""
+		for _ in range(pin_store.max_failures() - 1):
+			pin_store.register_failure(MANAGER)
+
+		result = request_grant(DUMMY_ACTION, MANAGER, OTHER_PIN, context={})
+
+		self.assertFalse(result["authorized"])
+		self.assertIn("locked", result["message"].lower())
+
+	def test_correct_pin_grants_a_token(self):
+		result = request_grant(DUMMY_ACTION, MANAGER, GOOD_PIN, context={})
+		self.assertTrue(result["authorized"])
+		self.assertTrue(result["grant_token"])
diff --git a/pos_next/authorization/__init__.py b/pos_next/authorization/__init__.py
new file mode 100644
index 000000000..51ea42fdc
--- /dev/null
+++ b/pos_next/authorization/__init__.py
@@ -0,0 +1,21 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Generic POS authorization gate.
+
+Some action is attempted at the POS; if a ``POS Authorization Rule`` covers it, an
+approver identifies themselves and enters a PIN, the server issues a short-lived
+grant, and the action cannot complete without it.
+
+Public API::
+
+    from pos_next.authorization import gate, registry
+
+    gate.enforce_document(doc)  # doc_events entry point
+    gate.enforce_context(action, context, token)  # cart-level actions, no doc yet
+    registry.register(Action(...))  # plug in a new action
+"""
+
+from pos_next.authorization.registry import Action, register
+
+__all__ = ["Action", "register"]
diff --git a/pos_next/authorization/actions/__init__.py b/pos_next/authorization/actions/__init__.py
new file mode 100644
index 000000000..524b46174
--- /dev/null
+++ b/pos_next/authorization/actions/__init__.py
@@ -0,0 +1,5 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+
+from pos_next.authorization.actions import sales_invoice
diff --git a/pos_next/authorization/actions/sales_invoice.py b/pos_next/authorization/actions/sales_invoice.py
new file mode 100644
index 000000000..2bfccfe19
--- /dev/null
+++ b/pos_next/authorization/actions/sales_invoice.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Sales Invoice authorization actions.
+
+The only module in the authorization package that knows what a return is. Everything
+else — gate, grants, policy, PIN, log, dialog — is generic.
+
+Two actions rather than one, because the two paths carry different risk. A refund with
+no source invoice is the most abusable path in the system and most sites will want it
+gated more tightly than an ordinary return, so it gets its own rule.
+
+Note the relationship with ``allow_return_without_invoice`` in POS Settings: that setting
+still decides whether the path exists at all. A rule here is a *second* gate on top of
+it and can never re-open something the setting has closed.
+"""
+
+from frappe.utils import flt
+
+from pos_next.authorization.registry import Action, register
+
+ACTION_SALES_INVOICE_RETURN = "Sales Invoice Return"
+ACTION_RETURN_WITHOUT_INVOICE = "Sales Return Without Invoice"
+
+SALES_INVOICE = "Sales Invoice"
+
+
+def _is_return_against_invoice(doc) -> bool:
+	return bool(doc.get("is_return")) and bool(doc.get("return_against"))
+
+
+def _is_return_without_invoice(doc) -> bool:
+	return bool(doc.get("is_return")) and not doc.get("return_against")
+
+
+register(
+	Action(
+		name=ACTION_SALES_INVOICE_RETURN,
+		doctype=SALES_INVOICE,
+		applies=_is_return_against_invoice,
+		binding=lambda ctx: {
+			"pos_profile": ctx.get("pos_profile"),
+			"return_against": ctx.get("return_against"),
+			"amount": flt(ctx.get("amount")),
+		},
+	)
+)
+
+register(
+	Action(
+		name=ACTION_RETURN_WITHOUT_INVOICE,
+		doctype=SALES_INVOICE,
+		applies=_is_return_without_invoice,
+		binding=lambda ctx: {
+			"pos_profile": ctx.get("pos_profile"),
+			"customer": ctx.get("customer"),
+			"amount": flt(ctx.get("amount")),
+		},
+	)
+)
diff --git a/pos_next/authorization/gate.py b/pos_next/authorization/gate.py
new file mode 100644
index 000000000..5666b0afd
--- /dev/null
+++ b/pos_next/authorization/gate.py
@@ -0,0 +1,113 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""The gate itself — the only place an action is allowed through or refused.
+
+Two entry points, because not every gated action has a document:
+
+* :func:`enforce_document` is a ``doc_events`` hook. It asks the registry which actions
+  belong to this doctype, and enforces the ones that fire for this document.
+* :func:`enforce_context` is for actions raised from the cart — a discount override, a
+  price edit — where no document exists yet.
+
+Both are action-agnostic. Neither knows what a return is.
+"""
+
+import frappe
+from frappe import _
+from frappe.utils import flt, now_datetime
+
+from pos_next.authorization import grants, log, policy, registry
+
+#: Where the client's grant token rides. A transient ``doc.flags`` entry, never a
+#: DocField — nothing to persist, redact or leak, and a submission arriving by any other
+#: path simply has no flag and is refused.
+TOKEN_FLAG = "pos_auth_token"
+
+FIELD_AUTHORIZED_BY = "custom_authorized_by"
+FIELD_AUTHORIZED_AT = "custom_authorized_at"
+
+
+def enforce_document(doc, method=None):
+	"""``doc_events`` entry point. One generic hook line covers every document action."""
+	for action in registry.for_doctype(doc.doctype):
+		if action.applies and not action.applies(doc):
+			continue
+
+		_enforce(
+			action,
+			context_from_doc(doc),
+			doc.flags.get(TOKEN_FLAG),
+			reference=doc.name,
+			doc=doc,
+		)
+
+
+def enforce_context(action_name: str, context: dict, token: str | None, reference: str | None = None):
+	"""Enforce an action that has no document yet. Returns the grant, or ``None``."""
+	action = registry.get(action_name)
+	if not action:
+		frappe.throw(_("Unknown authorization action {0}").format(action_name))
+
+	return _enforce(action, context or {}, token, reference=reference)
+
+
+def is_required(action_name: str, pos_profile: str | None = None) -> bool:
+	"""Whether a rule currently gates ``action_name`` on this profile."""
+	return policy.resolve_rule(action_name, pos_profile) is not None
+
+
+def context_from_doc(doc) -> dict:
+	"""Normalised context for a document-triggered action.
+
+	``amount`` is absolute: return invoices carry a negative ``grand_total``, and the
+	binding compares magnitudes so the client and the server agree.
+	"""
+
+	as_dict = getattr(doc, "as_dict", None)
+
+	return {
+		"doc": as_dict() if callable(as_dict) else dict(doc),
+		"pos_profile": doc.get("pos_profile"),
+		"customer": doc.get("customer"),
+		"return_against": doc.get("return_against"),
+		"amount": abs(flt(doc.get("grand_total"))),
+	}
+
+
+def _enforce(action, context: dict, token: str | None, reference=None, doc=None):
+	rule = policy.resolve_rule(action.name, context.get("pos_profile"))
+	if not rule:
+		return None
+
+	grant = grants.consume(token, action.name, action.binding(context), reference) if token else None
+
+	if not grant:
+		log.record(
+			action=action.name,
+			result=log.RESULT_DENIED,
+			reference=reference,
+			pos_profile=context.get("pos_profile"),
+			survive_rollback=True,
+		)
+		approvers = policy.describe_approvers(rule)
+		frappe.throw(
+			_("{0} requires authorization by: {1}").format(frappe._(action.name), approvers)
+			if approvers
+			else _("{0} requires authorization.").format(frappe._(action.name)),
+			title=_("Authorization Required"),
+		)
+
+	if doc is not None:
+		doc.set(FIELD_AUTHORIZED_BY, grant["approver"])
+		doc.set(FIELD_AUTHORIZED_AT, now_datetime())
+
+	log.record(
+		action=action.name,
+		approver=grant["approver"],
+		result=log.RESULT_GRANTED,
+		reference=reference,
+		pos_profile=context.get("pos_profile"),
+	)
+
+	return grant
diff --git a/pos_next/authorization/grants.py b/pos_next/authorization/grants.py
new file mode 100644
index 000000000..3b227a09c
--- /dev/null
+++ b/pos_next/authorization/grants.py
@@ -0,0 +1,126 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Short-lived authorization grants.
+
+A grant is minted when an approver proves their PIN, and is spent when the gate lets an
+action through. It is deliberately narrow: bound to one action, one requester and one
+set of binding values, and dead within :data:`GRANT_TTL` seconds.
+
+**Consumption is compare-and-set, not delete.** Redis is not transactional with MariaDB.
+If a grant were deleted in ``before_submit`` and a later ``on_submit`` handler threw —
+wallet reversal, Magento LP and one-time offer usage all run there — the database would
+roll back with the grant already gone, and the approver would have to walk back to the
+till and approve a second time. Binding the grant to the document instead makes a retry
+of *that* document succeed while any other document still fails.
+"""
+
+import pickle
+import secrets
+
+import frappe
+from frappe.utils import flt
+
+GRANT_TTL = 180
+
+_AMOUNT_TOLERANCE = 0.01
+
+_KEY_PREFIX = "pos_auth_grant:"
+
+
+def _key(token: str) -> bytes:
+	return frappe.cache().make_key(f"{_KEY_PREFIX}{token}")
+
+
+def _read(key: bytes) -> dict | None:
+	try:
+		raw = frappe.cache().get(key)
+	except Exception:
+		return None
+	return pickle.loads(raw) if raw else None
+
+
+def _write(key: bytes, grant: dict) -> None:
+	frappe.cache().set(key, pickle.dumps(grant), ex=GRANT_TTL)
+
+
+def issue(action_name: str, approver: str, binding: dict) -> str:
+	"""Mint a grant for ``action_name``, approved by ``approver``. Returns the token."""
+	token = secrets.token_urlsafe(32)
+
+	_write(
+		_key(token),
+		{
+			"action": action_name,
+			"approver": approver,
+			"binding": binding or {},
+			"requested_by": frappe.session.user,
+			"consumed_by": None,
+		},
+	)
+
+	return token
+
+
+def consume(token: str, action_name: str, binding: dict, reference: str | None = None) -> dict | None:
+	"""Spend ``token`` for this action and binding, or return ``None``.
+
+	``reference`` is the thing being authorized — a document name, usually. The first
+	successful consume pins the grant to it; later consumes succeed only for that same
+	reference, so a retry works and a second document does not.
+	"""
+	if not token:
+		return None
+
+	key = _key(token)
+	grant = _read(key)
+	if not grant:
+		return None
+
+	if grant.get("action") != action_name:
+		return None
+
+	# The grant belongs to the session that asked for it. A token leaked to another
+	# terminal is useless there.
+	if grant.get("requested_by") != frappe.session.user:
+		return None
+
+	consumed_by = grant.get("consumed_by")
+	if consumed_by is not None and consumed_by != reference:
+		return None
+
+	if not binding_matches(grant.get("binding") or {}, binding or {}):
+		return None
+
+	grant["consumed_by"] = reference
+	_write(key, grant)
+
+	return grant
+
+
+def revoke(token: str) -> None:
+	"""Drop a grant early. Not used in the normal flow; handy for tests and cleanup."""
+	if token:
+		frappe.cache().delete(_key(token))
+
+
+def binding_matches(approved: dict, actual: dict) -> bool:
+	"""Whether the act being attempted is the one that was approved.
+
+	Action-agnostic: every key in ``approved`` must equal its counterpart, except
+	``amount``, which may be **lower** than approved but never higher. Dropping a line
+	after approval is fine; adding one needs a fresh approval.
+	"""
+	for field, approved_value in (approved or {}).items():
+		actual_value = (actual or {}).get(field)
+
+		if field == "amount":
+			if flt(actual_value) > flt(approved_value) + _AMOUNT_TOLERANCE:
+				return False
+			continue
+
+		# Treat "" and None as the same absence, so a blank return_against matches.
+		if (approved_value or None) != (actual_value or None):
+			return False
+
+	return True
diff --git a/pos_next/authorization/log.py b/pos_next/authorization/log.py
new file mode 100644
index 000000000..f713ae228
--- /dev/null
+++ b/pos_next/authorization/log.py
@@ -0,0 +1,65 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Audit trail for the authorization gate.
+
+Rows are written server-side with ``ignore_permissions=True``; the DocType grants no
+create/write/delete to anyone. An editable audit log is not an audit log.
+
+Denials raised from ``before_submit`` need care: :func:`frappe.throw` rolls the request
+back, which would take a freshly inserted log row with it. Those callers pass
+``survive_rollback=True``, which defers the insert onto ``frappe.db.after_rollback`` —
+that callback runs *after* Frappe has rolled back and opened a fresh transaction, so the
+row lands cleanly without carrying any partial document state with it.
+"""
+
+import frappe
+from frappe.utils import now_datetime
+
+LOG_DOCTYPE = "POS Authorization Log"
+
+RESULT_GRANTED = "Granted"
+RESULT_INVALID_PIN = "Invalid PIN"
+RESULT_NO_PIN = "No PIN Set"
+RESULT_NOT_AUTHORIZED = "Not Authorized"
+RESULT_LOCKED_OUT = "Locked Out"
+RESULT_DENIED = "Denied"
+RESULT_PIN_SET = "PIN Set"
+
+
+def record(
+	*,
+	action: str | None = None,
+	approver: str | None = None,
+	result: str | None = None,
+	reference: str | None = None,
+	pos_profile: str | None = None,
+	requested_by: str | None = None,
+	survive_rollback: bool = False,
+) -> None:
+	"""Write one audit row. Never raises — auditing must not break the till."""
+	payload = {
+		"doctype": LOG_DOCTYPE,
+		"timestamp": now_datetime(),
+		"action": action,
+		"requested_by": requested_by or frappe.session.user,
+		"approver": approver,
+		"result": result,
+		"reference": reference,
+		"pos_profile": pos_profile,
+	}
+
+	if survive_rollback:
+		frappe.db.after_rollback.add(lambda: _insert(payload, commit=True))
+		return
+
+	_insert(payload)
+
+
+def _insert(payload: dict, commit: bool = False) -> None:
+	try:
+		frappe.get_doc(payload).insert(ignore_permissions=True)
+		if commit:
+			frappe.db.commit()
+	except Exception:
+		frappe.log_error(frappe.get_traceback(), "POS Authorization Log Error")
diff --git a/pos_next/authorization/pin.py b/pos_next/authorization/pin.py
new file mode 100644
index 000000000..8692d1f15
--- /dev/null
+++ b/pos_next/authorization/pin.py
@@ -0,0 +1,237 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""POS authorization PIN — a hashed, POS-only secret.
+
+Key Security Properties:
+    - Session Isolation: Maintains a distinct __Auth record from desk login
+      passwords. Grants zero desk access and is verified exclusively by
+      :mod:`pos_next.authorization.gate`.
+    - Credential Decoupling: Updating the PIN does not impact login passwords,
+      and vice versa.
+    - Access Containment: Compromise via shoulder-surfing yields no backend
+      or desk access.
+
+"""
+
+from itertools import pairwise
+
+import frappe
+from frappe import _
+from frappe.query_builder import Table
+from frappe.utils import cint
+from frappe.utils.password import check_password, update_password
+
+PIN_FIELD = "pos_authorization_pin"
+
+SETTINGS_DOCTYPE = "POS Authorization Settings"
+
+#: Used whenever POS Authorization Settings hasn't been saved yet, or a field on it is
+#: left blank. Keeps the module secure and usable out of the box, with no setup step.
+DEFAULT_PIN_LENGTH = 4
+DEFAULT_MAX_FAILURES = 5
+DEFAULT_LOCKOUT_MINUTES = 15
+
+
+def _settings():
+	"""The POS Authorization Settings singleton, cached like any other Frappe single."""
+	return frappe.get_cached_doc(SETTINGS_DOCTYPE)
+
+
+def pin_length() -> int:
+	"""Digits an authorization PIN must have."""
+	return cint(_settings().get("pin_length")) or DEFAULT_PIN_LENGTH
+
+
+def max_failures() -> int:
+	"""Consecutive wrong PINs before an approver is locked out."""
+	return cint(_settings().get("max_failures")) or DEFAULT_MAX_FAILURES
+
+
+def lockout_seconds() -> int:
+	"""How long a lockout lasts, and the window over which failures accumulate."""
+	minutes = cint(_settings().get("lockout_minutes")) or DEFAULT_LOCKOUT_MINUTES
+	return minutes * 60
+
+
+def strict_pin_enforced() -> bool:
+	"""Whether trivially guessable PINs (repeats, straight runs) should be refused.
+
+	Unlike the numeric settings above, an unset value here must mean "on" — a blank
+	field should never silently weaken the default, so this doesn't fold falsy into a
+	fallback the way ``pin_length()``/``max_failures()`` do.
+	"""
+	value = _settings().get("enforce_strict_pin")
+	return True if value is None else bool(cint(value))
+
+
+def validate_format(pin: str) -> None:
+	"""Raise if ``pin`` is not an acceptable PIN. Called before any write."""
+	pin = (pin or "").strip()
+	length = pin_length()
+
+	if not pin.isdigit():
+		frappe.throw(_("PIN must contain digits only"), title=_("Invalid PIN"))
+
+	if len(pin) != length:
+		frappe.throw(_("PIN must be exactly {0} digits").format(length), title=_("Invalid PIN"))
+
+	if strict_pin_enforced() and _is_trivial(pin):
+		frappe.throw(
+			_("That PIN is too easy to guess. Avoid repeated digits and simple sequences."),
+			title=_("Invalid PIN"),
+		)
+
+
+def _is_trivial(pin: str) -> bool:
+	"""Every digit the same, or a straight ascending/descending run.
+
+	Algorithmic rather than a fixed list of "bad" PINs, so it isn't tied to any one PIN
+	length and doesn't need updating if ``pin_length`` above changes. Covers e.g. 0000,
+	1234, 4321, and the wrap-around cases 7890 and 0987 (7-8-9-0 and 0-9-8-7 are each a
+	straight run once you allow 9 to roll over to 0).
+	"""
+	digits = [int(ch) for ch in pin]
+
+	if len(set(digits)) == 1:
+		return True
+
+	steps = list(pairwise(digits))
+	ascending = all((b - a) % 10 == 1 for a, b in steps)
+	descending = all((a - b) % 10 == 1 for a, b in steps)
+	return ascending or descending
+
+
+def has_pin(user: str) -> bool:
+	"""True when ``user`` has an authorization PIN set."""
+	if not user:
+		return False
+
+	Auth = Table("__Auth")
+	rows = (
+		frappe.qb.from_(Auth)
+		.select(Auth.name)
+		.where(
+			(Auth.doctype == "User")
+			& (Auth.name == user)
+			& (Auth.fieldname == PIN_FIELD)
+			& (Auth.encrypted == 0)
+		)
+		.limit(1)
+	).run()
+
+	return bool(rows)
+
+
+def users_with_pin(users: set[str] | list[str]) -> set[str]:
+	"""Filter ``users`` down to those who have a PIN set, in one query.
+
+	Returns the **caller's** spelling of each id, not the one stored in ``__Auth``.
+	MariaDB matches these case-insensitively while Python set arithmetic does not, and
+	``__Auth`` can disagree on case with the table the caller resolved from (``Has Role``,
+	say). Echoing the input keeps callers like ``get_authorization_readiness`` from
+	reporting the same person as both ready and missing a PIN.
+	"""
+	users = [u for u in (users or []) if u]
+	if not users:
+		return set()
+
+	Auth = Table("__Auth")
+	rows = (
+		frappe.qb.from_(Auth)
+		.select(Auth.name)
+		.where(
+			(Auth.doctype == "User")
+			& (Auth.fieldname == PIN_FIELD)
+			& (Auth.encrypted == 0)
+			& (Auth.name.isin(users))
+		)
+	).run(pluck=True)
+
+	found = {str(row).casefold() for row in (rows or [])}
+	return {user for user in users if user.casefold() in found}
+
+
+def set_pin(user: str, pin: str) -> None:
+	"""Store ``pin`` for ``user``, hashed. Clears any active lockout."""
+	validate_format(pin)
+	update_password(user, pin, doctype="User", fieldname=PIN_FIELD)
+	clear_failures(user)
+
+
+def clear_pin(user: str) -> None:
+	"""Remove ``user``'s PIN. They can no longer approve anything."""
+	Auth = Table("__Auth")
+	(
+		frappe.qb.from_(Auth)
+		.delete()
+		.where((Auth.doctype == "User") & (Auth.name == user) & (Auth.fieldname == PIN_FIELD))
+	).run()
+	clear_failures(user)
+
+
+def verify(user: str, pin: str) -> bool:
+	"""True when ``pin`` is ``user``'s PIN.
+
+	Never raises ``frappe.AuthenticationError``. Frappe's request error handler calls
+	``login_manager.clear_cookies()`` for that exception type, which on a wrong PIN would
+	destroy the *cashier's* session because the approver mistyped. See
+	``pos_next/api/auth.py`` for the same landmine.
+	"""
+	if not user or not pin:
+		return False
+
+	try:
+		# delete_tracker_cache=False: a PIN check must not clear the user's failed *login*
+		# tracking. Those are separate security counters with a separate lockout.
+		check_password(user, pin, doctype="User", fieldname=PIN_FIELD, delete_tracker_cache=False)
+		return True
+	except frappe.AuthenticationError:
+		return False
+
+
+def _fail_key(user: str) -> str:
+	return f"pos_auth_pin_fail:{user}"
+
+
+def _lock_key(user: str) -> str:
+	return f"pos_auth_pin_lock:{user}"
+
+
+def is_locked_out(user: str) -> bool:
+	"""True when ``user`` has failed too often and may not approve for now."""
+	cache = frappe.cache()
+	try:
+		return bool(cache.get(cache.make_key(_lock_key(user))))
+	except Exception:
+		return False
+
+
+def register_failure(user: str) -> bool:
+	"""Count a failed attempt. Returns True when this attempt triggered a lockout."""
+	cache = frappe.cache()
+	try:
+		lockout = lockout_seconds()
+		key = cache.make_key(_fail_key(user))
+		count = cint(cache.incr(key))
+		if count == 1:
+			cache.expire(key, lockout)
+
+		if count >= max_failures():
+			cache.set(cache.make_key(_lock_key(user)), b"1", ex=lockout)
+			cache.delete(key)
+			return True
+	except Exception:
+		frappe.log_error(frappe.get_traceback(), "POS Authorization Lockout Error")
+
+	return False
+
+
+def clear_failures(user: str) -> None:
+	"""Reset the failure counter and any lockout for ``user``."""
+	cache = frappe.cache()
+	try:
+		cache.delete(cache.make_key(_fail_key(user)))
+		cache.delete(cache.make_key(_lock_key(user)))
+	except Exception:
+		frappe.log_error(frappe.get_traceback(), "POS Authorization Lockout Error")
diff --git a/pos_next/authorization/policy.py b/pos_next/authorization/policy.py
new file mode 100644
index 000000000..dee47adeb
--- /dev/null
+++ b/pos_next/authorization/policy.py
@@ -0,0 +1,233 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Which rule applies, and who may approve under it.
+
+A ``POS Authorization Rule`` carries a child table of approvers. Each row names either a
+Role (anyone holding it) or a specific User, and may carry a ``condition`` expression.
+Rows are **OR-ed**: a user is eligible if any row admits them. So one rule can read
+"any Nexus POS Manager, plus ahmed@example.com, plus Store Supervisor but only under
+50,000".
+
+Conditions follow the same shape as ``Notification Recipient``: ``frappe.safe_eval``,
+validated when the rule is saved and re-evaluated at approval time.
+"""
+
+import frappe
+from frappe import _
+from frappe.utils import flt, getdate, nowdate
+
+RULE_DOCTYPE = "POS Authorization Rule"
+
+APPROVER_TYPE_ROLE = "Role"
+APPROVER_TYPE_USER = "User"
+
+
+def resolve_rule(action_name: str, pos_profile: str | None = None):
+	"""The rule governing ``action_name`` here, or ``None`` when nothing is configured.
+
+	A rule naming this POS Profile wins over a catch-all rule (blank ``pos_profile``), so
+	one site can gate a single till more tightly than the rest.
+
+	Returning ``None`` is the common case on existing installations and means the action
+	proceeds exactly as it did before the gate existed.
+	"""
+	rules = frappe.get_all(
+		RULE_DOCTYPE,
+		filters={"action": action_name, "enabled": 1},
+		fields=["name", "pos_profile"],
+		order_by="modified desc",
+	)
+	if not rules:
+		return None
+
+	specific = [r for r in rules if r.pos_profile and r.pos_profile == pos_profile]
+	catch_all = [r for r in rules if not r.pos_profile]
+
+	chosen = specific or catch_all
+	if not chosen:
+		return None
+
+	return frappe.get_cached_doc(RULE_DOCTYPE, chosen[0].name)
+
+
+def validate_uniqueness(rule) -> None:
+	"""Reject a rule that duplicates another already-enabled one for the same action
+	and POS Profile (including two catch-all rules, both with a blank POS Profile).
+	"""
+	if not rule.get("enabled"):
+		return
+
+	own_profile = rule.get("pos_profile") or None
+
+	others = frappe.get_all(
+		RULE_DOCTYPE,
+		filters={"action": rule.action, "enabled": 1, "name": ("!=", rule.name or "")},
+		fields=["name", "pos_profile"],
+	)
+	conflict = next((r for r in others if (r.pos_profile or None) == own_profile), None)
+	if not conflict:
+		return
+
+	scope = own_profile or _("every POS Profile")
+	frappe.throw(
+		_(
+			"{0} already gates {1} for {2}. Disable it first, or edit it directly instead "
+			"of creating a duplicate"
+		).format(frappe.bold(conflict.name), frappe.bold(rule.action), frappe.bold(scope)),
+		title=_("Duplicate Rule"),
+	)
+
+
+def eligible_approvers(rule, context: dict | None = None) -> set[str]:
+	"""Every enabled user admitted by any row of ``rule``."""
+	users: set[str] = set()
+
+	for row in rule.get("approvers") or []:
+		if row.condition and not eval_condition(row.condition, context):
+			continue
+
+		if row.approver_type == APPROVER_TYPE_ROLE and row.role:
+			# Already filtered to enabled users by the join in users_with_role() —
+			# checking again per user here would be one extra query per role member
+			# for a fact the SQL already guarantees.
+			users |= users_with_role(row.role)
+		elif row.approver_type == APPROVER_TYPE_USER and row.user and _is_enabled(row.user):
+			users.add(row.user)
+
+	return users
+
+
+def is_approver(rule, user: str, context: dict | None = None) -> bool:
+	"""Whether ``user`` may approve under ``rule`` right now."""
+	if not user:
+		return False
+
+	if not rule.get("allow_self_approval") and user == frappe.session.user:
+		return False
+
+	return user in eligible_approvers(rule, context)
+
+
+def describe_approvers(rule) -> str:
+	"""Readable list of who can approve, for the denial message."""
+	parts = []
+	for row in rule.get("approvers") or []:
+		if row.approver_type == APPROVER_TYPE_ROLE and row.role:
+			parts.append(row.role)
+		elif row.approver_type == APPROVER_TYPE_USER and row.user:
+			parts.append(row.user)
+
+	return ", ".join(dict.fromkeys(parts))
+
+
+def validate_approvers(rule) -> None:
+	"""Reject a rule with no approvers — it would block the action for everyone,
+	permanently — and normalize each row to match its own approver_type.
+	"""
+	rows = rule.get("approvers") or []
+	if not rows:
+		frappe.throw(
+			_("Add at least one approver, otherwise this action can never be authorized."),
+			title=_("No Approvers"),
+		)
+
+	for row in rows:
+		if row.approver_type == APPROVER_TYPE_ROLE:
+			row.user = None
+			if not row.role:
+				frappe.throw(_("Row {0}: select a Role").format(row.idx))
+		elif row.approver_type == APPROVER_TYPE_USER:
+			row.role = None
+			if not row.user:
+				frappe.throw(_("Row {0}: select a User").format(row.idx))
+
+
+def users_with_role(role: str) -> set[str]:
+	"""Enabled users holding ``role``."""
+	HasRole = frappe.qb.DocType("Has Role")
+	User = frappe.qb.DocType("User")
+
+	rows = (
+		frappe.qb.from_(HasRole)
+		.inner_join(User)
+		.on(User.name == HasRole.parent)
+		.select(HasRole.parent)
+		.where((HasRole.role == role) & (HasRole.parenttype == "User") & (User.enabled == 1))
+	).run(pluck=True)
+
+	return set(rows or [])
+
+
+def _is_enabled(user: str) -> bool:
+	return bool(frappe.db.get_value("User", user, "enabled"))
+
+
+# ---------------------------------------------------------------------------
+# Conditions
+# ---------------------------------------------------------------------------
+
+
+def build_condition_context(context: dict | None = None) -> dict:
+	"""Names available inside a row ``condition``."""
+	context = context or {}
+
+	# frappe._dict returns None for missing keys, so `doc.customer_group` in a condition
+	# is safe both at validation time (empty doc) and at runtime.
+	doc = context.get("doc") or frappe._dict()
+	if not isinstance(doc, frappe._dict):
+		doc = frappe._dict(doc)
+
+	return {
+		"doc": doc,
+		"amount": flt(context.get("amount")),
+		"pos_profile": context.get("pos_profile"),
+		"customer": context.get("customer"),
+		"requested_by": frappe.session.user,
+		"nowdate": nowdate,
+		"getdate": getdate,
+	}
+
+
+def eval_condition(condition: str, context: dict | None = None, throw: bool = False) -> bool:
+	"""Evaluate a row condition.
+
+	A condition that blows up at runtime **skips its row** rather than breaking the gate —
+	one bad expression should not make every refund impossible. Set ``throw=True`` when
+	validating at save time, where failing loudly is the whole point.
+	"""
+	if not condition:
+		return True
+
+	try:
+		return bool(frappe.safe_eval(condition, None, build_condition_context(context)))
+	except Exception:
+		if throw:
+			raise
+		frappe.log_error(frappe.get_traceback(), "POS Authorization Condition Error")
+		return False
+
+
+def validate_conditions(rule) -> None:
+	"""Reject invalid conditions when the rule is saved, not at the till.
+
+	A broken expression discovered mid-refund, with a customer waiting, is the worst
+	possible time to find out.
+	"""
+	sample = {
+		"doc": frappe._dict(),
+		"amount": 0,
+		"pos_profile": rule.get("pos_profile"),
+		"customer": None,
+	}
+
+	for row in rule.get("approvers") or []:
+		if not row.condition:
+			continue
+		try:
+			eval_condition(row.condition, sample, throw=True)
+		except Exception:
+			frappe.throw(
+				_("The condition {0} in row {1} is invalid").format(frappe.bold(row.condition), row.idx),
+				title=_("Invalid Condition"),
+			)
diff --git a/pos_next/authorization/registry.py b/pos_next/authorization/registry.py
new file mode 100644
index 000000000..b14341fbb
--- /dev/null
+++ b/pos_next/authorization/registry.py
@@ -0,0 +1,108 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Registry of authorizable actions.
+
+An :class:`Action` is the only thing the gate knows about. Adding a new gated action —
+voiding an invoice, overriding a discount, editing a price — is one :func:`register`
+call plus, for document-triggered actions, one ``doc_events`` line in ``hooks.py``.
+
+Nothing else changes: not the gate, the grants, the PIN, the dialog or the log.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Action:
+	"""One authorizable action.
+
+	:param name: Both the stable key stored on ``POS Authorization Rule`` and the text
+		shown for it in the desk and the POS — one string, not a key plus a separate
+		label kept in sync by hand. Write it exactly as it should appear, e.g.
+		``"Sales Invoice Return"``, not ``"sales_invoice_return"``. Translated with
+		``frappe._()`` at every *display* site (never at registration time — module
+		import happens outside a request, where there is no language to translate
+		into — and never for storage/comparison: the raw string is what's saved,
+		matched and logged). **Never rename it once shipped** — existing rules
+		reference it, and renaming orphans them exactly like deleting it would. See
+		:func:`all_actions` for how this stays in step with the ``action`` Select on
+		``POS Authorization Rule``.
+	:param binding: ``(context: dict) -> dict``. What the grant is pinned to. The gate
+		treats the result as opaque: every key must match at enforcement time, except
+		``amount``, which may come in lower than approved but never higher.
+	:param doctype: Set for document-triggered actions, so ``enforce_document`` can find
+		them. Leave ``None`` for actions raised from the cart, before a document exists.
+	:param applies: ``(doc) -> bool``. For document-triggered actions, whether this action
+		fires for this particular document. ``None`` means "always, for this doctype".
+	"""
+
+	name: str
+	binding: Callable[[dict], dict]
+	doctype: str | None = None
+	applies: Callable[..., bool] | None = None
+
+
+_ACTIONS: dict[str, Action] = {}
+_LOADED = False
+
+
+def _ensure_loaded() -> None:
+	"""Import the shipped actions on first use.
+
+	Lazy rather than imported from ``hooks.py`` so the registry has no opinion about app
+	load order — a lesson from the import-time patching in ``pos_next/__init__.py``.
+	"""
+	global _LOADED
+	if _LOADED:
+		return
+
+	_LOADED = True
+	import pos_next.authorization.actions
+
+
+def register(action: Action) -> None:
+	"""Add ``action`` to the registry, replacing any action with the same name."""
+	if not isinstance(action, Action):
+		raise TypeError("register() expects an Action")
+	_ACTIONS[action.name] = action
+
+
+def get(name: str) -> Action | None:
+	"""The registered action called ``name``, or ``None``."""
+	_ensure_loaded()
+	return _ACTIONS.get(name)
+
+
+def for_doctype(doctype: str) -> list[Action]:
+	"""Every registered action triggered by documents of ``doctype``."""
+	_ensure_loaded()
+	return [action for action in _ACTIONS.values() if action.doctype == doctype]
+
+
+def all_actions() -> list[Action]:
+	"""Every registered action, ordered by name (which is also its display text).
+
+	``POS Authorization Rule.action`` is a hardcoded Select, not driven by this list at
+	runtime — its options in pos_authorization_rule.json must list the same names as
+	are registered here. Keeping the two in step is a one-line discipline, not
+	something worth a parity test: when you add an action, add its name to that
+	Select's options in the same change. Forgetting only affects the action you just
+	added — ``POSAuthorizationRule.validate_action()`` still refuses to save a rule
+	against anything not registered here, so a Select that's fallen behind can never
+	make an *existing* rule silently stop gating.
+	"""
+	_ensure_loaded()
+	return sorted(_ACTIONS.values(), key=lambda action: action.name)
+
+
+def clear(mark_loaded: bool = True) -> None:
+	"""Empty the registry. Tests only.
+
+	``mark_loaded`` keeps the shipped actions from being re-imported, so a test can work
+	with only the actions it registers itself.
+	"""
+	global _LOADED
+	_ACTIONS.clear()
+	_LOADED = mark_loaded
diff --git a/pos_next/authorization/tests/__init__.py b/pos_next/authorization/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/authorization/tests/helpers.py b/pos_next/authorization/tests/helpers.py
new file mode 100644
index 000000000..0dc1432cb
--- /dev/null
+++ b/pos_next/authorization/tests/helpers.py
@@ -0,0 +1,90 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Shared fixtures for the authorization test suite.
+
+Registers a dummy action at import time, shared across every test file below so they
+all exercise the same generic action rather than each registering their own. Import
+order across files doesn't matter: module-level code runs once per process no matter
+how many test files import this one.
+
+All fixtures are prefixed ``_PNXT_AUTH_`` so they can be cleaned up safely.
+"""
+
+import frappe
+
+from pos_next.authorization import registry
+from pos_next.authorization.registry import Action
+
+PREFIX = "_PNXT_AUTH_"
+# Frappe lowercases user ids on insert, so these must already be lowercase or every
+# comparison against a stored value fails.
+_U = PREFIX.lower()
+CASHIER = f"{_U}cashier@example.com"
+MANAGER = f"{_U}manager@example.com"
+OUTSIDER = f"{_U}outsider@example.com"
+ROLE = f"{PREFIX}Approver"
+
+GOOD_PIN = "8317"
+OTHER_PIN = "2946"
+
+# action is a hardcoded Select on POS Authorization Rule (see pos_authorization_rule.json)
+# and only ships two real values. A test-only action needs the "_T-" prefix Frappe's own
+# Select validation already exempts from the options check when frappe.flags.in_test is
+# set (frappe.model.base_document.BaseDocument._validate_selects) — the same convention
+# core uses for its own auto-generated test records. Without that prefix, saving a rule
+# for a made-up action would fail Select validation before ever reaching our own code.
+DUMMY_ACTION = "_T-pnxt-dummy-action"
+
+registry.register(
+	Action(
+		name=DUMMY_ACTION,
+		binding=lambda ctx: {"widget": ctx.get("widget"), "amount": ctx.get("amount")},
+	)
+)
+
+
+def make_user(email: str, roles: list[str] | None = None) -> str:
+	if not frappe.db.exists("User", email):
+		user = frappe.get_doc(
+			{
+				"doctype": "User",
+				"email": email,
+				"first_name": email.split("@")[0],
+				"send_welcome_email": 0,
+				"enabled": 1,
+			}
+		)
+		user.insert(ignore_permissions=True)
+	else:
+		user = frappe.get_doc("User", email)
+
+	for role in roles or []:
+		if not any(r.role == role for r in user.get("roles") or []):
+			user.append("roles", {"role": role})
+	user.save(ignore_permissions=True)
+	return email
+
+
+def make_role(name: str) -> str:
+	if not frappe.db.exists("Role", name):
+		frappe.get_doc({"doctype": "Role", "role_name": name, "desk_access": 0}).insert(
+			ignore_permissions=True
+		)
+	return name
+
+
+def make_rule(action: str, approvers: list[dict], **kwargs) -> object:
+	frappe.db.delete("POS Authorization Rule", {"action": action})
+	rule = frappe.get_doc(
+		{
+			"doctype": "POS Authorization Rule",
+			"action": action,
+			"enabled": 1,
+			"allow_self_approval": kwargs.get("allow_self_approval", 1),
+			"pos_profile": kwargs.get("pos_profile"),
+			"approvers": approvers,
+		}
+	)
+	rule.insert(ignore_permissions=True)
+	return rule
diff --git a/pos_next/authorization/tests/test_actions_sales_invoice.py b/pos_next/authorization/tests/test_actions_sales_invoice.py
new file mode 100644
index 000000000..2d39aec7c
--- /dev/null
+++ b/pos_next/authorization/tests/test_actions_sales_invoice.py
@@ -0,0 +1,39 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.actions.sales_invoice — the two shipped actions
+resolve on the right documents.
+"""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import gate, registry
+
+
+class TestSalesInvoiceActions(FrappeTestCase):
+	def test_return_against_invoice_selects_the_return_action(self):
+		from pos_next.authorization.actions.sales_invoice import (
+			ACTION_RETURN_WITHOUT_INVOICE,
+			ACTION_SALES_INVOICE_RETURN,
+		)
+
+		doc = frappe._dict({"doctype": "Sales Invoice", "is_return": 1, "return_against": "SINV-1"})
+		fired = [a.name for a in registry.for_doctype("Sales Invoice") if a.applies(doc)]
+		self.assertEqual(fired, [ACTION_SALES_INVOICE_RETURN])
+
+		doc = frappe._dict({"doctype": "Sales Invoice", "is_return": 1, "return_against": None})
+		fired = [a.name for a in registry.for_doctype("Sales Invoice") if a.applies(doc)]
+		self.assertEqual(fired, [ACTION_RETURN_WITHOUT_INVOICE])
+
+	def test_ordinary_sale_fires_nothing(self):
+		doc = frappe._dict({"doctype": "Sales Invoice", "is_return": 0})
+		fired = [a.name for a in registry.for_doctype("Sales Invoice") if a.applies(doc)]
+		self.assertEqual(fired, [])
+
+	def test_context_amount_is_absolute(self):
+		"""Return invoices carry a negative grand_total; bindings compare magnitudes."""
+		doc = frappe._dict(
+			{"doctype": "Sales Invoice", "is_return": 1, "grand_total": -1500, "pos_profile": "P"}
+		)
+		self.assertEqual(gate.context_from_doc(doc)["amount"], 1500)
diff --git a/pos_next/authorization/tests/test_gate.py b/pos_next/authorization/tests/test_gate.py
new file mode 100644
index 000000000..f204f3790
--- /dev/null
+++ b/pos_next/authorization/tests/test_gate.py
@@ -0,0 +1,73 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.gate.
+
+The important class here: it drives the whole gate through a **dummy action**
+registered in tests/helpers.py, touching no return code at all. If the framework has
+leaked return-specific assumptions, this fails immediately rather than six months from
+now when somebody tries to gate discounts.
+"""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import gate, grants, registry
+from pos_next.authorization import pin as pin_store
+from pos_next.authorization.tests.helpers import (
+	CASHIER,
+	DUMMY_ACTION,
+	GOOD_PIN,
+	MANAGER,
+	ROLE,
+	make_role,
+	make_rule,
+	make_user,
+)
+
+
+class TestAuthorizationFramework(FrappeTestCase):
+	"""The gate must work for an action it has never heard of before."""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_role(ROLE)
+		make_user(CASHIER)
+		make_user(MANAGER, [ROLE])
+		pin_store.set_pin(MANAGER, GOOD_PIN)
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		pin_store.clear_failures(MANAGER)
+
+	def test_dummy_action_flows_end_to_end_without_any_return_code(self):
+		"""Register an action, gate it, approve it, spend it — no Sales Invoice involved."""
+		make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+
+		self.assertTrue(gate.is_required(DUMMY_ACTION))
+
+		context = {"widget": "W-1", "amount": 500}
+		action = registry.get(DUMMY_ACTION)
+		self.assertIsNotNone(action)
+
+		token = grants.issue(DUMMY_ACTION, MANAGER, action.binding(context))
+		result = gate.enforce_context(DUMMY_ACTION, context, token, reference="W-1")
+
+		self.assertIsNotNone(result)
+		self.assertEqual(result["approver"], MANAGER)
+
+	def test_unregistered_action_is_rejected(self):
+		with self.assertRaises(frappe.ValidationError):
+			gate.enforce_context("_pnxt_not_a_real_action", {}, "irrelevant")
+
+	def test_no_rule_means_no_gate(self):
+		"""The live-client safety property: unconfigured actions behave as before."""
+		frappe.db.delete("POS Authorization Rule", {"action": DUMMY_ACTION})
+		self.assertFalse(gate.is_required(DUMMY_ACTION))
+		self.assertIsNone(gate.enforce_context(DUMMY_ACTION, {"widget": "W-1"}, None))
+
+	def test_missing_token_is_denied(self):
+		make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+		with self.assertRaises(frappe.ValidationError):
+			gate.enforce_context(DUMMY_ACTION, {"widget": "W-1", "amount": 10}, None)
diff --git a/pos_next/authorization/tests/test_grants.py b/pos_next/authorization/tests/test_grants.py
new file mode 100644
index 000000000..b0ed2f5be
--- /dev/null
+++ b/pos_next/authorization/tests/test_grants.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.grants — binding and consumption rules, pure logic,
+no documents.
+"""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import grants
+from pos_next.authorization.tests.helpers import CASHIER, DUMMY_ACTION, MANAGER
+
+
+class TestGrants(FrappeTestCase):
+	def setUp(self):
+		frappe.set_user("Administrator")
+
+	def test_grant_is_single_purpose_across_references(self):
+		token = grants.issue(DUMMY_ACTION, MANAGER, {"widget": "W-1"})
+		self.assertIsNotNone(grants.consume(token, DUMMY_ACTION, {"widget": "W-1"}, "DOC-A"))
+		# Same token, different document — refused.
+		self.assertIsNone(grants.consume(token, DUMMY_ACTION, {"widget": "W-1"}, "DOC-B"))
+
+	def test_grant_survives_retry_of_the_same_document(self):
+		"""Redis is not transactional with MariaDB; an on_submit failure must not burn it."""
+		token = grants.issue(DUMMY_ACTION, MANAGER, {"widget": "W-1"})
+		self.assertIsNotNone(grants.consume(token, DUMMY_ACTION, {"widget": "W-1"}, "DOC-A"))
+		self.assertIsNotNone(grants.consume(token, DUMMY_ACTION, {"widget": "W-1"}, "DOC-A"))
+
+	def test_grant_is_bound_to_its_action(self):
+		token = grants.issue(DUMMY_ACTION, MANAGER, {"widget": "W-1"})
+		self.assertIsNone(grants.consume(token, "some_other_action", {"widget": "W-1"}, "DOC-A"))
+
+	def test_unknown_token_is_refused(self):
+		self.assertIsNone(grants.consume("not-a-token", DUMMY_ACTION, {}, "DOC-A"))
+
+	def test_amount_binding_is_one_directional(self):
+		approved = {"return_against": "SINV-1", "amount": 100000}
+		self.assertTrue(grants.binding_matches(approved, {"return_against": "SINV-1", "amount": 80000}))
+		self.assertTrue(grants.binding_matches(approved, {"return_against": "SINV-1", "amount": 100000}))
+		self.assertFalse(grants.binding_matches(approved, {"return_against": "SINV-1", "amount": 120000}))
+
+	def test_non_amount_keys_must_match_exactly(self):
+		approved = {"return_against": "SINV-1", "amount": 100}
+		self.assertFalse(grants.binding_matches(approved, {"return_against": "SINV-2", "amount": 100}))
+
+	def test_blank_and_missing_are_the_same_absence(self):
+		approved = {"return_against": None, "customer": "CUST-1"}
+		self.assertTrue(grants.binding_matches(approved, {"return_against": "", "customer": "CUST-1"}))
+
+	def test_grant_is_bound_to_the_requesting_session(self):
+		token = grants.issue(DUMMY_ACTION, MANAGER, {"widget": "W-1"})
+		frappe.set_user(CASHIER)
+		try:
+			self.assertIsNone(grants.consume(token, DUMMY_ACTION, {"widget": "W-1"}, "DOC-A"))
+		finally:
+			frappe.set_user("Administrator")
diff --git a/pos_next/authorization/tests/test_log.py b/pos_next/authorization/tests/test_log.py
new file mode 100644
index 000000000..2edd9d676
--- /dev/null
+++ b/pos_next/authorization/tests/test_log.py
@@ -0,0 +1,45 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.log — the audit trail."""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import log
+from pos_next.authorization.tests.helpers import DUMMY_ACTION
+
+
+class TestAuditLog(FrappeTestCase):
+	def setUp(self):
+		frappe.set_user("Administrator")
+
+	def test_log_rows_are_written(self):
+		# Not a row-count delta: log.record(survive_rollback=True) deliberately escapes
+		# the test framework's own rollback (see log.py — that's what makes a denial
+		# audit-proof even though the enclosing invoice submission rolls back), so other
+		# tests in this same run can legitimately add rows around this one. Look for the
+		# specific row instead of counting the whole table.
+		#
+		# approver=Administrator, not MANAGER: this class is intentionally self-contained
+		# and creates no fixture users, and approver is a Link to User — a nonexistent
+		# approver would fail Link validation inside log._insert(), which swallows every
+		# exception ("auditing must not break the till"), so the row would silently never
+		# be written and this assertion would fail for a completely unrelated reason.
+		marker = frappe.generate_hash(length=8)
+		log.record(action=DUMMY_ACTION, approver="Administrator", result=log.RESULT_GRANTED, reference=marker)
+		self.assertTrue(frappe.db.exists(log.LOG_DOCTYPE, {"reference": marker, "approver": "Administrator"}))
+
+	def test_log_is_not_writable_by_pos_roles(self):
+		"""An editable audit log is not an audit log."""
+		meta = frappe.get_meta(log.LOG_DOCTYPE)
+		for perm in meta.permissions:
+			self.assertFalse(perm.get("create"), f"{perm.role} must not create log rows")
+			self.assertFalse(perm.get("write"), f"{perm.role} must not edit log rows")
+			self.assertFalse(perm.get("delete"), f"{perm.role} must not delete log rows")
+
+	def test_rule_is_system_manager_only(self):
+		"""If a cashier could edit rules, they could switch off their own gate."""
+		meta = frappe.get_meta("POS Authorization Rule")
+		roles = {perm.role for perm in meta.permissions}
+		self.assertEqual(roles, {"System Manager"})
diff --git a/pos_next/authorization/tests/test_pin.py b/pos_next/authorization/tests/test_pin.py
new file mode 100644
index 000000000..31105e01f
--- /dev/null
+++ b/pos_next/authorization/tests/test_pin.py
@@ -0,0 +1,179 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.pin — hashed storage, format rules, lockout, and the
+POS Authorization Settings that drive pin_length/max_failures/lockout/strict-mode.
+"""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import pin as pin_store
+from pos_next.authorization.tests.helpers import CASHIER, GOOD_PIN, OTHER_PIN, OUTSIDER, make_user
+
+SETTINGS_DOCTYPE = "POS Authorization Settings"
+
+
+def _apply_settings(**fields):
+	"""Update POS Authorization Settings the same way a System Manager would (a real
+	save, not raw db.set_value), so get_cached_doc() is correctly invalidated rather
+	than left holding a stale value.
+	"""
+	settings = frappe.get_single(SETTINGS_DOCTYPE)
+	settings.update(fields)
+	settings.save(ignore_permissions=True)
+
+
+class TestPin(FrappeTestCase):
+	"""Hashed storage, format rules and lockout.
+
+	Pins pin_length/enforce_strict_pin to what these tests assume for the whole class.
+	POS Authorization Settings is a real, live-editable singleton (see TestPinSettings
+	below) — on an actual site, someone may well have turned strict mode off or changed
+	the PIN length, and without pinning these here, that real configuration would make
+	these tests fail for a reason that has nothing to do with a code regression.
+	"""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_user(OUTSIDER)
+		cls._original_settings = frappe.get_single(SETTINGS_DOCTYPE).as_dict()
+		_apply_settings(pin_length=4, enforce_strict_pin=1)
+
+	@classmethod
+	def tearDownClass(cls):
+		_apply_settings(
+			pin_length=cls._original_settings.get("pin_length"),
+			enforce_strict_pin=cls._original_settings.get("enforce_strict_pin"),
+		)
+		super().tearDownClass()
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		pin_store.set_pin(OUTSIDER, GOOD_PIN)
+		pin_store.clear_failures(OUTSIDER)
+
+	def test_pin_round_trips(self):
+		self.assertTrue(pin_store.has_pin(OUTSIDER))
+		self.assertTrue(pin_store.verify(OUTSIDER, GOOD_PIN))
+		self.assertFalse(pin_store.verify(OUTSIDER, OTHER_PIN))
+
+	def test_pin_is_stored_hashed_not_encrypted(self):
+		"""encrypted=0 is Frappe's hashed lane; a Password DocField would be encrypted=1."""
+		row = frappe.db.sql(
+			"""select password, encrypted from `__Auth`
+			   where doctype='User' and name=%s and fieldname=%s""",
+			(OUTSIDER, pin_store.PIN_FIELD),
+			as_dict=True,
+		)
+		self.assertTrue(row)
+		self.assertEqual(row[0]["encrypted"], 0)
+		self.assertNotEqual(row[0]["password"], GOOD_PIN)
+		self.assertNotIn(GOOD_PIN, row[0]["password"])
+
+	def test_pin_never_raises_authentication_error(self):
+		"""A wrong PIN must not reach Frappe's handler, which would clear the cashier's cookies."""
+		try:
+			self.assertFalse(pin_store.verify(OUTSIDER, "0000"))
+		except frappe.AuthenticationError:
+			self.fail("verify() leaked AuthenticationError")
+
+	def test_format_rules(self):
+		for bad in ["123", "12345", "abcd", "12a4", ""]:
+			with self.assertRaises(frappe.ValidationError):
+				pin_store.validate_format(bad)
+
+	def test_trivial_pins_are_refused(self):
+		for bad in ["0000", "1111", "1234", "4321", "9999"]:
+			with self.assertRaises(frappe.ValidationError):
+				pin_store.validate_format(bad)
+
+	def test_lockout_after_consecutive_failures(self):
+		self.assertFalse(pin_store.is_locked_out(OUTSIDER))
+		locked = False
+		for _ in range(pin_store.max_failures()):
+			locked = pin_store.register_failure(OUTSIDER)
+		self.assertTrue(locked)
+		self.assertTrue(pin_store.is_locked_out(OUTSIDER))
+
+	def test_setting_a_pin_clears_the_lockout(self):
+		for _ in range(pin_store.max_failures()):
+			pin_store.register_failure(OUTSIDER)
+		self.assertTrue(pin_store.is_locked_out(OUTSIDER))
+		pin_store.set_pin(OUTSIDER, OTHER_PIN)
+		self.assertFalse(pin_store.is_locked_out(OUTSIDER))
+
+	def test_clear_pin_removes_approval_ability(self):
+		pin_store.clear_pin(OUTSIDER)
+		self.assertFalse(pin_store.has_pin(OUTSIDER))
+		self.assertFalse(pin_store.verify(OUTSIDER, GOOD_PIN))
+
+	def test_users_with_pin_filters_in_one_query(self):
+		pin_store.set_pin(OUTSIDER, GOOD_PIN)
+		pin_store.clear_pin(CASHIER)
+		self.assertEqual(pin_store.users_with_pin([OUTSIDER, CASHIER]), {OUTSIDER})
+
+
+class TestPinSettings(FrappeTestCase):
+	"""pin_length, max_failures, lockout and strict-mode all come from POS Authorization
+	Settings, not hardcoded constants — these prove settings actually drive behaviour.
+	"""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_user(OUTSIDER)
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		pin_store.clear_failures(OUTSIDER)
+		# get_cached_doc() lives in Redis, outside this test framework's DB-transaction
+		# rollback — a test that changes the singleton and doesn't put it back would
+		# leak its values into whatever runs next, test or real site alike. Snapshot
+		# here, restore via the same save() path (not raw db.set_value) in tearDown so
+		# the cache is correctly invalidated, not just the row.
+		self._original = frappe.get_single(SETTINGS_DOCTYPE).as_dict()
+
+	def tearDown(self):
+		_apply_settings(
+			pin_length=self._original.get("pin_length"),
+			max_failures=self._original.get("max_failures"),
+			lockout_minutes=self._original.get("lockout_minutes"),
+			enforce_strict_pin=self._original.get("enforce_strict_pin"),
+		)
+
+	def test_pin_length_is_enforced_from_settings(self):
+		_apply_settings(pin_length=6)
+		with self.assertRaises(frappe.ValidationError):
+			pin_store.validate_format(GOOD_PIN)  # 4 digits — now too short
+		pin_store.validate_format("246813")  # 6 digits, not trivial — accepted
+
+	def test_max_failures_is_read_from_settings(self):
+		_apply_settings(max_failures=2)
+		self.assertFalse(pin_store.register_failure(OUTSIDER))
+		self.assertTrue(pin_store.register_failure(OUTSIDER))
+		self.assertTrue(pin_store.is_locked_out(OUTSIDER))
+
+	def test_lockout_seconds_is_derived_from_minutes(self):
+		_apply_settings(lockout_minutes=1)
+		self.assertEqual(pin_store.lockout_seconds(), 60)
+
+	def test_strict_mode_off_allows_a_trivial_pin(self):
+		_apply_settings(enforce_strict_pin=0)
+		pin_store.validate_format("1234")  # would normally be refused
+
+	def test_strict_mode_on_refuses_trivial_pins_of_any_length(self):
+		_apply_settings(pin_length=6, enforce_strict_pin=1)
+		for bad in ["000000", "123456", "654321", "456789", "987654"]:
+			with self.assertRaises(frappe.ValidationError):
+				pin_store.validate_format(bad)
+
+	def test_trivial_detection_is_algorithmic_not_a_fixed_list(self):
+		"""Wrap-around runs (9->0, 0->9) and non-4-length pins must both be caught —
+		proof this isn't just the old hardcoded list with the numbers changed.
+		"""
+		self.assertTrue(pin_store._is_trivial("7890"))
+		self.assertTrue(pin_store._is_trivial("0987"))
+		self.assertTrue(pin_store._is_trivial("56789"))
+		self.assertFalse(pin_store._is_trivial("2946"))
diff --git a/pos_next/authorization/tests/test_policy.py b/pos_next/authorization/tests/test_policy.py
new file mode 100644
index 000000000..d31767b4d
--- /dev/null
+++ b/pos_next/authorization/tests/test_policy.py
@@ -0,0 +1,195 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Tests for pos_next.authorization.policy — rule resolution and approver eligibility."""
+
+import frappe
+from frappe.tests.utils import FrappeTestCase
+
+from pos_next.authorization import policy
+from pos_next.authorization.tests.helpers import (
+	CASHIER,
+	DUMMY_ACTION,
+	MANAGER,
+	OUTSIDER,
+	ROLE,
+	make_role,
+	make_rule,
+	make_user,
+)
+
+
+class TestApproverResolution(FrappeTestCase):
+	"""Role rows, User rows, OR-ing, conditions and self-approval."""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_role(ROLE)
+		make_user(CASHIER)
+		make_user(MANAGER, [ROLE])
+		make_user(OUTSIDER)
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+
+	def test_role_row_admits_any_holder(self):
+		rule = make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+		approvers = policy.eligible_approvers(rule, {})
+		self.assertIn(MANAGER, approvers)
+		self.assertNotIn(OUTSIDER, approvers)
+
+	def test_user_row_admits_only_that_user(self):
+		rule = make_rule(DUMMY_ACTION, [{"approver_type": "User", "user": OUTSIDER}])
+		approvers = policy.eligible_approvers(rule, {})
+		self.assertEqual(approvers, {OUTSIDER})
+
+	def test_rows_are_or_ed(self):
+		rule = make_rule(
+			DUMMY_ACTION,
+			[
+				{"approver_type": "Role", "role": ROLE},
+				{"approver_type": "User", "user": OUTSIDER},
+			],
+		)
+		approvers = policy.eligible_approvers(rule, {})
+		self.assertIn(MANAGER, approvers)
+		self.assertIn(OUTSIDER, approvers)
+
+	def test_false_condition_contributes_nobody(self):
+		rule = make_rule(
+			DUMMY_ACTION,
+			[{"approver_type": "Role", "role": ROLE, "condition": "amount > 50000"}],
+		)
+		self.assertEqual(policy.eligible_approvers(rule, {"amount": 100}), set())
+		self.assertIn(MANAGER, policy.eligible_approvers(rule, {"amount": 60000}))
+
+	def test_invalid_condition_is_rejected_at_save_not_at_the_till(self):
+		with self.assertRaises(frappe.ValidationError):
+			make_rule(
+				DUMMY_ACTION,
+				[{"approver_type": "Role", "role": ROLE, "condition": "this is not python ("}],
+			)
+
+	def test_runtime_condition_error_is_contained(self):
+		"""A condition that blows up must return False, not propagate.
+
+		Save-time validation catches almost everything (see the test above), so this is
+		the defensive path: whatever slips through must skip its row rather than make
+		every approval in the store impossible.
+		"""
+		self.assertFalse(policy.eval_condition("doc.missing.attribute > 1", {"amount": 1}))
+		self.assertFalse(policy.eval_condition("1 / 0", {"amount": 1}))
+
+		with self.assertRaises(Exception):
+			policy.eval_condition("doc.missing.attribute > 1", {"amount": 1}, throw=True)
+
+	def test_self_approval_is_allowed_by_default(self):
+		rule = make_rule(DUMMY_ACTION, [{"approver_type": "User", "user": MANAGER}])
+		frappe.set_user(MANAGER)
+		try:
+			self.assertTrue(policy.is_approver(rule, MANAGER, {}))
+		finally:
+			frappe.set_user("Administrator")
+
+	def test_self_approval_can_be_switched_off_per_rule(self):
+		rule = make_rule(
+			DUMMY_ACTION,
+			[{"approver_type": "User", "user": MANAGER}],
+			allow_self_approval=0,
+		)
+		frappe.set_user(MANAGER)
+		try:
+			self.assertFalse(policy.is_approver(rule, MANAGER, {}))
+		finally:
+			frappe.set_user("Administrator")
+
+	def test_rule_without_approvers_is_rejected(self):
+		with self.assertRaises(frappe.ValidationError):
+			make_rule(DUMMY_ACTION, [])
+
+	def test_unregistered_action_cannot_be_saved(self):
+		with self.assertRaises(frappe.ValidationError):
+			make_rule("_pnxt_never_registered", [{"approver_type": "Role", "role": ROLE}])
+
+
+class TestRuleResolution(FrappeTestCase):
+	"""Profile scoping."""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_role(ROLE)
+		make_user(MANAGER, [ROLE])
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		frappe.db.delete("POS Authorization Rule", {"action": DUMMY_ACTION})
+
+	def test_no_rule_returns_none(self):
+		self.assertIsNone(policy.resolve_rule(DUMMY_ACTION, None))
+
+	def test_catch_all_rule_applies_to_every_profile(self):
+		make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+		self.assertIsNotNone(policy.resolve_rule(DUMMY_ACTION, "ANY-PROFILE"))
+
+	def test_disabled_rule_does_not_gate(self):
+		rule = make_rule(DUMMY_ACTION, [{"approver_type": "Role", "role": ROLE}])
+		rule.enabled = 0
+		rule.save(ignore_permissions=True)
+		self.assertIsNone(policy.resolve_rule(DUMMY_ACTION, None))
+
+
+class TestRuleUniqueness(FrappeTestCase):
+	"""Two enabled rules must never compete for the same (action, POS Profile) —
+	resolve_rule() above would otherwise pick between them by whichever was modified
+	most recently, silently, with the "losing" rule still showing Enabled in the desk.
+	"""
+
+	@classmethod
+	def setUpClass(cls):
+		super().setUpClass()
+		make_role(ROLE)
+
+	def setUp(self):
+		frappe.set_user("Administrator")
+		frappe.db.delete("POS Authorization Rule", {"action": DUMMY_ACTION})
+
+	def _rule(self, pos_profile=None, enabled=1):
+		# ignore_links=True: these are fixture profile names, not real POS Profile
+		# records — irrelevant to the uniqueness check itself, which only compares the
+		# stored string.
+		doc = frappe.get_doc(
+			{
+				"doctype": "POS Authorization Rule",
+				"action": DUMMY_ACTION,
+				"enabled": enabled,
+				"pos_profile": pos_profile,
+				"approvers": [{"approver_type": "Role", "role": ROLE}],
+			}
+		)
+		doc.insert(ignore_permissions=True, ignore_links=True)
+		return doc
+
+	def test_two_enabled_rules_for_the_same_specific_profile_is_rejected(self):
+		self._rule(pos_profile="_PNXT_BRANCH_A")
+		with self.assertRaises(frappe.ValidationError):
+			self._rule(pos_profile="_PNXT_BRANCH_A")
+
+	def test_two_enabled_catch_all_rules_is_rejected(self):
+		self._rule(pos_profile=None)
+		with self.assertRaises(frappe.ValidationError):
+			self._rule(pos_profile=None)
+
+	def test_enabled_rules_for_different_profiles_are_both_allowed(self):
+		self._rule(pos_profile="_PNXT_BRANCH_A")
+		self._rule(pos_profile="_PNXT_BRANCH_B")  # must not raise
+
+	def test_a_disabled_rule_does_not_block_a_new_enabled_one(self):
+		self._rule(pos_profile="_PNXT_BRANCH_A", enabled=0)
+		self._rule(pos_profile="_PNXT_BRANCH_A")  # must not raise
+
+	def test_resaving_the_same_rule_does_not_self_conflict(self):
+		rule = self._rule(pos_profile="_PNXT_BRANCH_A")
+		rule.allow_self_approval = 0
+		rule.save(ignore_permissions=True)  # must not raise
diff --git a/pos_next/hooks.py b/pos_next/hooks.py
index dc72f00d6..df8b7a22e 100644
--- a/pos_next/hooks.py
+++ b/pos_next/hooks.py
@@ -52,6 +52,7 @@
 	"Customer": "public/js/customer.js",
 	"Pricing Rule": "public/js/pricing_rule.js",
 	"Promotional Scheme": "public/js/promotional_scheme.js",
+	"User": "public/js/user.js",
 }
 # doctype_list_js = {"doctype" : "public/js/doctype_list.js"}
 # doctype_tree_js = {"doctype" : "public/js/doctype_tree.js"}
@@ -157,6 +158,7 @@
 			"pos_next.api.wallet.validate_wallet_payment",
 			"pos_next.overrides.pricing_rule.apply_min_max_price_discounts",
 		],
+		"before_submit": "pos_next.authorization.gate.enforce_document",
 		"before_cancel": "pos_next.api.sales_invoice_hooks.before_cancel",
 		"on_submit": [
 			"pos_next.realtime_events.emit_stock_update_event",
diff --git a/pos_next/modules.txt b/pos_next/modules.txt
index 2d9e61a41..4333d474c 100644
--- a/pos_next/modules.txt
+++ b/pos_next/modules.txt
@@ -1 +1,2 @@
-POS Next
\ No newline at end of file
+POS Next
+POS Next Auth Gate
\ No newline at end of file
diff --git a/pos_next/pos_next_auth_gate/__init__.py b/pos_next/pos_next_auth_gate/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/__init__.py b/pos_next/pos_next_auth_gate/doctype/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/__init__.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.json b/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.json
new file mode 100644
index 000000000..cdbbab94a
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.json
@@ -0,0 +1,72 @@
+{
+ "actions": [],
+ "autoname": "hash",
+ "creation": "2026-08-10 00:00:00.000000",
+ "doctype": "DocType",
+ "editable_grid": 1,
+ "engine": "InnoDB",
+ "field_order": [
+  "approver_type",
+  "role",
+  "user",
+  "column_break_condition",
+  "condition"
+ ],
+ "fields": [
+  {
+   "columns": 2,
+   "default": "Role",
+   "fieldname": "approver_type",
+   "fieldtype": "Select",
+   "in_list_view": 1,
+   "label": "Approver Type",
+   "options": "Role\nUser",
+   "reqd": 1
+  },
+  {
+   "columns": 3,
+   "depends_on": "eval:doc.approver_type == \"Role\"",
+   "fieldname": "role",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "label": "Role",
+   "mandatory_depends_on": "eval:doc.approver_type == \"Role\"",
+   "options": "Role"
+  },
+  {
+   "columns": 3,
+   "depends_on": "eval:doc.approver_type == \"User\"",
+   "fieldname": "user",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "label": "User",
+   "mandatory_depends_on": "eval:doc.approver_type == \"User\"",
+   "options": "User"
+  },
+  {
+   "fieldname": "column_break_condition",
+   "fieldtype": "Column Break"
+  },
+  {
+   "columns": 3,
+   "description": "Optional. Python expression, e.g. <code>amount &gt; 50000</code>. Available names: doc, amount, pos_profile, customer, requested_by, nowdate, getdate. Leave blank to always apply.",
+   "fieldname": "condition",
+   "fieldtype": "Data",
+   "in_list_view": 1,
+   "label": "Condition"
+  }
+ ],
+ "index_web_pages_for_search": 0,
+ "istable": 1,
+ "links": [],
+ "modified": "2026-08-10 00:00:00.000000",
+ "modified_by": "Administrator",
+ "module": "POS Next Auth Gate",
+ "name": "POS Authorization Approver",
+ "owner": "Administrator",
+ "permissions": [],
+ "sort_field": "modified",
+ "sort_order": "DESC",
+ "states": [],
+ "track_changes": 0
+}
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.py
new file mode 100644
index 000000000..670757837
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_approver/pos_authorization_approver.py
@@ -0,0 +1,8 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+from frappe.model.document import Document
+
+
+class POSAuthorizationApprover(Document):
+	pass
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/__init__.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.json b/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.json
new file mode 100644
index 000000000..cbd51d3f7
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.json
@@ -0,0 +1,115 @@
+{
+ "actions": [],
+ "autoname": "format:AUTH-LOG-{#####}",
+ "creation": "2026-08-10 00:00:00.000000",
+ "doctype": "DocType",
+ "editable_grid": 0,
+ "engine": "InnoDB",
+ "field_order": [
+  "timestamp",
+  "action",
+  "result",
+  "column_break_who",
+  "requested_by",
+  "approver",
+  "section_break_context",
+  "reference",
+  "pos_profile"
+ ],
+ "fields": [
+  {
+   "fieldname": "timestamp",
+   "fieldtype": "Datetime",
+   "in_list_view": 1,
+   "label": "Timestamp",
+   "read_only": 1,
+   "search_index": 1
+  },
+  {
+   "fieldname": "action",
+   "fieldtype": "Data",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Action",
+   "read_only": 1,
+   "search_index": 1
+  },
+  {
+   "fieldname": "result",
+   "fieldtype": "Select",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Result",
+   "options": "Granted\nInvalid PIN\nNo PIN Set\nNot Authorized\nLocked Out\nDenied\nPIN Set",
+   "read_only": 1,
+   "search_index": 1
+  },
+  {
+   "fieldname": "column_break_who",
+   "fieldtype": "Column Break"
+  },
+  {
+   "fieldname": "requested_by",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Requested By",
+   "options": "User",
+   "read_only": 1
+  },
+  {
+   "fieldname": "approver",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "in_standard_filter": 1,
+   "label": "Approver",
+   "options": "User",
+   "read_only": 1
+  },
+  {
+   "fieldname": "section_break_context",
+   "fieldtype": "Section Break"
+  },
+  {
+   "fieldname": "reference",
+   "fieldtype": "Data",
+   "label": "Reference",
+   "read_only": 1,
+   "search_index": 1
+  },
+  {
+   "fieldname": "pos_profile",
+   "fieldtype": "Link",
+   "in_standard_filter": 1,
+   "label": "POS Profile",
+   "options": "POS Profile",
+   "read_only": 1
+  }
+ ],
+ "in_create": 1,
+ "index_web_pages_for_search": 0,
+ "links": [],
+ "modified": "2026-08-10 00:00:00.000000",
+ "modified_by": "Administrator",
+ "module": "POS Next Auth Gate",
+ "name": "POS Authorization Log",
+ "owner": "Administrator",
+ "permissions": [
+  {
+   "export": 1,
+   "read": 1,
+   "report": 1,
+   "role": "System Manager"
+  },
+  {
+   "export": 1,
+   "read": 1,
+   "report": 1,
+   "role": "Nexus POS Manager"
+  }
+ ],
+ "sort_field": "timestamp",
+ "sort_order": "DESC",
+ "states": [],
+ "track_changes": 0
+}
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.py
new file mode 100644
index 000000000..a2534c587
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_log/pos_authorization_log.py
@@ -0,0 +1,8 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+from frappe.model.document import Document
+
+
+class POSAuthorizationLog(Document):
+	pass
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/__init__.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.js b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.js
new file mode 100644
index 000000000..5e306645b
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.js
@@ -0,0 +1,8 @@
+// Copyright (c) 2026, BrainWise and contributors
+// For license information, please see license.txt
+
+// frappe.ui.form.on("POS Authorization Rule", {
+// 	refresh(frm) {
+
+// 	},
+// });
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.json b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.json
new file mode 100644
index 000000000..bed03cd57
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.json
@@ -0,0 +1,92 @@
+{
+ "actions": [],
+ "autoname": "format:AUTH-RULE-{#####}",
+ "creation": "2026-08-10 00:00:00",
+ "doctype": "DocType",
+ "editable_grid": 1,
+ "engine": "InnoDB",
+ "field_order": [
+  "action",
+  "pos_profile",
+  "column_break_main",
+  "enabled",
+  "allow_self_approval",
+  "section_break_approvers",
+  "approvers"
+ ],
+ "fields": [
+  {
+   "description": "Which POS action this rule gates.",
+   "fieldname": "action",
+   "fieldtype": "Select",
+   "in_list_view": 1,
+   "label": "Action",
+   "options": "Sales Invoice Return\nSales Return Without Invoice",
+   "reqd": 1
+  },
+  {
+   "description": "Leave blank to apply to every POS Profile. A rule naming a profile takes precedence over a blank one.",
+   "fieldname": "pos_profile",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "label": "POS Profile",
+   "options": "POS Profile"
+  },
+  {
+   "fieldname": "column_break_main",
+   "fieldtype": "Column Break"
+  },
+  {
+   "default": "1",
+   "fieldname": "enabled",
+   "fieldtype": "Check",
+   "in_list_view": 1,
+   "label": "Enabled"
+  },
+  {
+   "default": "1",
+   "description": "When enabled, an approver may authorize an action they started themselves.",
+   "fieldname": "allow_self_approval",
+   "fieldtype": "Check",
+   "label": "Allow Self Approval"
+  },
+  {
+   "fieldname": "section_break_approvers",
+   "fieldtype": "Section Break",
+   "label": "Approvers"
+  },
+  {
+   "fieldname": "approvers",
+   "fieldtype": "Table",
+   "label": "Approvers",
+   "options": "POS Authorization Approver",
+   "reqd": 1
+  }
+ ],
+ "links": [],
+ "modified": "2026-08-12 14:21:20.786243",
+ "modified_by": "Administrator",
+ "module": "POS Next Auth Gate",
+ "name": "POS Authorization Rule",
+ "naming_rule": "Expression (old style)",
+ "owner": "Administrator",
+ "permissions": [
+  {
+   "create": 1,
+   "delete": 1,
+   "email": 1,
+   "export": 1,
+   "print": 1,
+   "read": 1,
+   "report": 1,
+   "role": "System Manager",
+   "share": 1,
+   "write": 1
+  }
+ ],
+ "row_format": "Dynamic",
+ "sort_field": "modified",
+ "sort_order": "DESC",
+ "states": [],
+ "track_changes": 1
+}
\ No newline at end of file
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.py
new file mode 100644
index 000000000..ed22d676c
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/pos_authorization_rule.py
@@ -0,0 +1,26 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+import frappe
+from frappe import _
+from frappe.model.document import Document
+
+from pos_next.authorization import policy, registry
+
+
+class POSAuthorizationRule(Document):
+	def validate(self):
+		self.validate_action()
+		policy.validate_approvers(self)
+		policy.validate_conditions(self)
+		policy.validate_uniqueness(self)
+
+	def validate_action(self):
+		if not self.action:
+			return
+
+		if not registry.get(self.action):
+			frappe.throw(
+				_("{0} is not a registered authorization action.").format(frappe.bold(self.action)),
+				title=_("Unknown Action"),
+			)
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/test_pos_authorization_rule.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/test_pos_authorization_rule.py
new file mode 100644
index 000000000..e6fce6b2b
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_rule/test_pos_authorization_rule.py
@@ -0,0 +1,9 @@
+# Copyright (c) 2026, BrainWise and Contributors
+# See license.txt
+
+# import frappe
+from frappe.tests.utils import FrappeTestCase
+
+
+class TestPOSAuthorizationRule(FrappeTestCase):
+	pass
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/__init__.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.json b/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.json
new file mode 100644
index 000000000..eb06a9c3d
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.json
@@ -0,0 +1,83 @@
+{
+ "actions": [],
+ "creation": "2026-08-12 00:00:00.000000",
+ "doctype": "DocType",
+ "engine": "InnoDB",
+ "field_order": [
+  "pin_length",
+  "column_break_pin",
+  "enforce_strict_pin",
+  "section_break_lockout",
+  "max_failures",
+  "column_break_lockout",
+  "lockout_minutes"
+ ],
+ "fields": [
+  {
+   "default": "4",
+   "description": "Digits required in an authorization PIN. Changing this only affects PINs set from now on. existing PINs keep working at their original length.",
+   "fieldname": "pin_length",
+   "fieldtype": "Int",
+   "label": "PIN Length",
+   "non_negative": 1,
+   "reqd": 1
+  },
+  {
+   "fieldname": "column_break_pin",
+   "fieldtype": "Column Break"
+  },
+  {
+   "default": "1",
+   "description": "Reject PINs that are trivially guessable.",
+   "fieldname": "enforce_strict_pin",
+   "fieldtype": "Check",
+   "label": "Enforce Strict PIN"
+  },
+  {
+   "fieldname": "section_break_lockout",
+   "fieldtype": "Section Break",
+   "label": "Lockout"
+  },
+  {
+   "default": "5",
+   "description": "Consecutive wrong PINs before an approver is locked out of granting authorization.",
+   "fieldname": "max_failures",
+   "fieldtype": "Int",
+   "label": "Max Failed Attempts",
+   "non_negative": 1,
+   "reqd": 1
+  },
+  {
+   "fieldname": "column_break_lockout",
+   "fieldtype": "Column Break"
+  },
+  {
+   "default": "15",
+   "description": "How long the lockout lasts, and the window over which failed attempts accumulate.",
+   "fieldname": "lockout_minutes",
+   "fieldtype": "Int",
+   "label": "Lockout Duration (minutes)",
+   "non_negative": 1,
+   "reqd": 1
+  }
+ ],
+ "index_web_pages_for_search": 0,
+ "issingle": 1,
+ "links": [],
+ "modified": "2026-08-12 00:00:00.000000",
+ "modified_by": "Administrator",
+ "module": "POS Next Auth Gate",
+ "name": "POS Authorization Settings",
+ "owner": "Administrator",
+ "permissions": [
+  {
+   "read": 1,
+   "role": "System Manager",
+   "write": 1
+  }
+ ],
+ "sort_field": "modified",
+ "sort_order": "DESC",
+ "states": [],
+ "track_changes": 1
+}
diff --git a/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.py b/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.py
new file mode 100644
index 000000000..e65afc172
--- /dev/null
+++ b/pos_next/pos_next_auth_gate/doctype/pos_authorization_settings/pos_authorization_settings.py
@@ -0,0 +1,9 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+# import frappe
+from frappe.model.document import Document
+
+
+class POSAuthorizationSettings(Document):
+	pass
diff --git a/pos_next/public/js/user.js b/pos_next/public/js/user.js
new file mode 100644
index 000000000..324fd49f3
--- /dev/null
+++ b/pos_next/public/js/user.js
@@ -0,0 +1,115 @@
+// Copyright (c) 2026, BrainWise and contributors
+// For license information, please see license.txt
+
+
+
+frappe.ui.form.on("User", {
+	refresh(frm) {
+		if (frm.is_new()) {
+			return;
+		}
+		frappe
+			.call("pos_next.api.authorization.has_authorization_pin", { user: frm.doc.name })
+			.then((r) => {
+				const has_pin = Boolean(r.message && r.message.has_pin);
+
+				const pin_length = (r.message && r.message.pin_length) || 4;
+				const strict_pin_enforced = Boolean(r.message && r.message.strict_pin_enforced);
+				const is_self = frm.doc.name === frappe.session.user;
+
+				frm.add_custom_button(
+					has_pin ? __("Change POS Authorization PIN") : __("Set POS Authorization PIN"),
+					() => show_pin_dialog(frm, has_pin, is_self, pin_length, strict_pin_enforced),
+					__("POS")
+				);
+
+				if (has_pin && frappe.user.has_role("System Manager")) {
+					frm.add_custom_button(
+						__("Remove POS Authorization PIN"),
+						() => remove_pin(frm),
+						__("POS")
+					);
+				}
+			});
+	},
+});
+
+function show_pin_dialog(frm, has_pin, is_self, pin_length, strict_pin_enforced) {
+
+	const needs_current = has_pin && is_self;
+	const strictness_hint = strict_pin_enforced
+		? __("Avoid repeated digits and simple sequences. ")
+		: "";
+
+	const dialog = new frappe.ui.Dialog({
+		title: __("POS Authorization PIN"),
+		fields: [
+			{
+				fieldname: "current_pin",
+				fieldtype: "Password",
+				label: __("Current PIN"),
+				depends_on: `eval:${needs_current}`,
+				hidden: !needs_current,
+				reqd: needs_current,
+				length: pin_length,
+			},
+			{
+				fieldname: "new_pin",
+				fieldtype: "Password",
+				label: __("New PIN"),
+				reqd: 1,
+				length: pin_length,
+				description: __("Exactly {0} digits", [pin_length]),
+			},
+			{ fieldname: "confirm_pin", fieldtype: "Password", label: __("Confirm PIN"), reqd: 1, length: pin_length },
+			{
+				fieldtype: "HTML",
+				options: `<p class="text-muted small">${strictness_hint}${__(
+					"This PIN authorizes POS actions only. it cannot be used to sign in."
+				)}</p>`,
+			},
+		],
+		primary_action_label: __("Save"),
+		primary_action(values) {
+			if (values.new_pin !== values.confirm_pin) {
+				frappe.msgprint(__("The two PINs do not match"));
+				return;
+			}
+
+			frappe
+				.call("pos_next.api.authorization.set_authorization_pin", {
+					user: frm.doc.name,
+					new_pin: values.new_pin,
+					current_pin: values.current_pin,
+				})
+				.then((r) => {
+					if (r.message && r.message.success) {
+						dialog.hide();
+						frappe.show_alert({ message: __("PIN updated"), indicator: "green" });
+						frm.refresh();
+					} else if (r.message) {
+						frappe.msgprint(r.message.message || __("Could not update the PIN"));
+					}
+				});
+		},
+	});
+
+	dialog.show();
+}
+
+function remove_pin(frm) {
+	frappe.confirm(
+		__(
+			"Remove the POS authorization PIN for {0}? They will no longer be able to approve POS actions.",
+			[frm.doc.name]
+		),
+		() => {
+			frappe
+				.call("pos_next.api.authorization.clear_authorization_pin", { user: frm.doc.name })
+				.then(() => {
+					frappe.show_alert({ message: __("PIN removed"), indicator: "orange" });
+					frm.refresh();
+				});
+		}
+	);
+}

From 6e0b904182cbe3be9dea7bbf0c82dfa639ee8b8a Mon Sep 17 00:00:00 2001
From: MostafaKadry <mostafa.kadry@brainwise.me>
Date: Wed, 26 Aug 2026 18:08:20 +0300
Subject: [PATCH 7/8] feat: add Item Price test protection and support for
 extensible POS offer strategies

---
 POS/src/stores/posCart.js                     |  54 ++++++++-
 POS/src/stores/posOffers.js                   |   3 +
 .../utils/__tests__/offerStrategies.spec.js   |  68 +++++++++++
 POS/src/utils/offerStrategies.js              |  99 ++++++++++++++++
 pos_next/__init__.py                          |  12 ++
 pos_next/overrides/test_setup_compat.py       | 106 ++++++++++++++++++
 6 files changed, 338 insertions(+), 4 deletions(-)
 create mode 100644 POS/src/utils/__tests__/offerStrategies.spec.js
 create mode 100644 POS/src/utils/offerStrategies.js
 create mode 100644 pos_next/overrides/test_setup_compat.py

diff --git a/POS/src/stores/posCart.js b/POS/src/stores/posCart.js
index 4cd8a1a39..8d49b3545 100644
--- a/POS/src/stores/posCart.js
+++ b/POS/src/stores/posCart.js
@@ -1,4 +1,10 @@
 import { isPromotionsAppInstalled } from "@/utils/promoApi";
+import {
+	allowsAutoDiscountStacking,
+	getStrategyForOffer,
+	loadOfferStrategyPlugins,
+	offerStrategyOrder,
+} from "@/utils/offerStrategies";
 import { useInvoice } from "@/composables/useInvoice";
 import { usePOSOffersStore } from "@/stores/posOffers";
 import { usePOSSettingsStore } from "@/stores/posSettings";
@@ -378,6 +384,12 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				price_list_rate: item.price_list_rate || item.rate,
 				discount_percentage: item.discount_percentage || 0,
 				discount_amount: item.discount_amount || 0,
+				pricing_rules: item.pricing_rules || "",
+				is_already_discounted: item.is_already_discounted || 0,
+				discount_source: item.discount_source || "",
+				item_group: item.item_group,
+				brand: item.brand,
+				amount: item.amount,
 				is_free_item: item.is_free_item || 0,
 			})),
 		};
@@ -418,6 +430,12 @@ export const usePOSCartStore = defineStore("posCart", () => {
 			}
 			// Otherwise preserve existing manual discount
 
+			if (serverItem.is_already_discounted !== undefined) {
+				item.is_already_discounted = serverItem.is_already_discounted ? 1 : 0;
+			}
+			item.is_accumulative_discount =
+				serverItem.discount_source === "accumulative_promotion" ? 1 : 0;
+
 			recalculateItem(item);
 		});
 
@@ -877,6 +895,8 @@ export const usePOSCartStore = defineStore("posCart", () => {
 							item.discount_percentage = 0;
 							item.discount_amount = 0;
 							item.pricing_rules = [];
+							item.is_already_discounted = 0;
+							item.is_accumulative_discount = 0;
 							recalculateItem(item);
 						}
 					});
@@ -976,7 +996,11 @@ export const usePOSCartStore = defineStore("posCart", () => {
 
 			const newlyAppliedOffers = [];
 
-			for (const offer of newOffers) {
+			const orderedOffers = [...newOffers].sort(
+				(a, b) => offerStrategyOrder(b) - offerStrategyOrder(a)
+			);
+
+			for (const offer of orderedOffers) {
 				// Determine offer type: "Item Price" (discount) or "Give Product" (free item)
 				const isProductDiscount = offer.offer === "Give Product";
 
@@ -1053,6 +1077,11 @@ export const usePOSCartStore = defineStore("posCart", () => {
 	 * @returns {boolean} True if discount was applied
 	 */
 	function applyOfflinePriceDiscount(offer, eligibleItems) {
+		const strategy = getStrategyForOffer(offer);
+		if (strategy) {
+			return strategy.apply(offer, eligibleItems, { recalculateItem });
+		}
+
 		const discountType = offer.discount_type || offer.rate_or_discount;
 		const discountPercentage = Number.parseFloat(offer.discount_percentage) || 0;
 		const discountAmount = Number.parseFloat(offer.discount_amount) || 0;
@@ -1061,12 +1090,27 @@ export const usePOSCartStore = defineStore("posCart", () => {
 		let applied = false;
 
 		for (const item of eligibleItems) {
+			const stacks =
+				offer.promotion_type === "Auto Discount" && allowsAutoDiscountStacking(item);
+
+			if (offer.promotion_type === "Auto Discount" && item.is_already_discounted && !stacks) {
+				continue;
+			}
+
 			// Only apply if no existing pricing rule
-			if (item.pricing_rules && item.pricing_rules.length > 0) continue;
+			if (item.pricing_rules && item.pricing_rules.length > 0 && !stacks) continue;
 
 			if (discountType === "Discount Percentage" && discountPercentage > 0) {
-				item.discount_percentage = discountPercentage;
-				item.pricing_rules = [offer.name];
+				if (stacks) {
+					const base = Number.parseFloat(item.discount_percentage) || 0;
+					const itemMax = Number.parseFloat(item.max_discount) || 0;
+					const total = base + discountPercentage;
+					item.discount_percentage = Math.min(total, itemMax > 0 ? itemMax : 100, 100);
+					item.pricing_rules = [...(item.pricing_rules || []), offer.name];
+				} else {
+					item.discount_percentage = discountPercentage;
+					item.pricing_rules = [offer.name];
+				}
 				recalculateItem(item);
 				applied = true;
 			} else if (discountType === "Discount Amount" && discountAmount > 0) {
@@ -1849,6 +1893,8 @@ export const usePOSCartStore = defineStore("posCart", () => {
 					if (item.pricing_rules && item.pricing_rules.length > 0) {
 						item.discount_percentage = 0;
 						item.discount_amount = 0;
+						item.is_already_discounted = 0;
+						item.is_accumulative_discount = 0;
 						recalculateItem(item);
 					}
 				});
diff --git a/POS/src/stores/posOffers.js b/POS/src/stores/posOffers.js
index 0ba2540cd..110db7bfc 100644
--- a/POS/src/stores/posOffers.js
+++ b/POS/src/stores/posOffers.js
@@ -1,4 +1,5 @@
 import { promoApi } from "@/utils/promoApi";
+import { loadOfferStrategyPlugins } from "@/utils/offerStrategies";
 import { defineStore } from "pinia";
 import { computed, ref } from "vue";
 import { call } from "@/utils/apiWrapper";
@@ -379,6 +380,8 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 	 * @returns {Promise<boolean>} True if offers are available (fetched or cached)
 	 */
 	async function ensureOffersFetched(posProfile) {
+		await loadOfferStrategyPlugins();
+
 		// Skip fetching offers if POS Profile has ignore_pricing_rule enabled
 		const shiftStore = usePOSShiftStore();
 		if (shiftStore.currentProfile?.ignore_pricing_rule) {
diff --git a/POS/src/utils/__tests__/offerStrategies.spec.js b/POS/src/utils/__tests__/offerStrategies.spec.js
new file mode 100644
index 000000000..fc0a1dbcd
--- /dev/null
+++ b/POS/src/utils/__tests__/offerStrategies.spec.js
@@ -0,0 +1,68 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+	allowsAutoDiscountStacking,
+	clearOfferStrategies,
+	getOfferStrategy,
+	getStrategyForOffer,
+	offerStrategyOrder,
+	registerOfferStrategy,
+} from "@/utils/offerStrategies";
+
+/**
+ * The registry is pos_next's half of the offer-strategy seam. It must stay
+ * usable with nothing registered — that is the shape a site without
+ * posnext_promotions runs in — and must never need to know a mode's name.
+ */
+describe("offer strategy registry", () => {
+	beforeEach(() => clearOfferStrategies());
+
+	it("resolves nothing when no app has registered", () => {
+		expect(getOfferStrategy("Accumulative")).toBeUndefined();
+		expect(getStrategyForOffer({ apply_discount_on_price: "Accumulative" })).toBeUndefined();
+		expect(offerStrategyOrder({ apply_discount_on_price: "Accumulative" })).toBe(0);
+		expect(allowsAutoDiscountStacking({ is_accumulative_discount: 1 })).toBe(false);
+	});
+
+	it("resolves a registered strategy by the offer's cross-cart mode", () => {
+		const strategy = { order: 100, apply: () => true };
+		registerOfferStrategy("Accumulative", strategy);
+
+		expect(getStrategyForOffer({ apply_discount_on_price: "Accumulative" })).toBe(strategy);
+		expect(getStrategyForOffer({ apply_discount_on_price: "Min" })).toBeUndefined();
+		expect(getStrategyForOffer({})).toBeUndefined();
+	});
+
+	it("orders strategy-backed offers ahead of plain ones", () => {
+		registerOfferStrategy("Accumulative", { order: 100, apply: () => true });
+
+		const offers = [
+			{ name: "plain" },
+			{ name: "accum", apply_discount_on_price: "Accumulative" },
+			{ name: "other", apply_discount_on_price: "Min" },
+		];
+		const ordered = [...offers].sort((a, b) => offerStrategyOrder(b) - offerStrategyOrder(a));
+
+		expect(ordered[0].name).toBe("accum");
+	});
+
+	it("delegates the Auto Discount stacking decision to the strategy", () => {
+		registerOfferStrategy("Accumulative", {
+			apply: () => true,
+			allowsAutoDiscountStacking: (item) => Boolean(item.is_accumulative_discount),
+		});
+
+		expect(allowsAutoDiscountStacking({ is_accumulative_discount: 1 })).toBe(true);
+		expect(allowsAutoDiscountStacking({})).toBe(false);
+	});
+
+	it("rejects a malformed registration instead of breaking the cart", () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+		registerOfferStrategy("Accumulative", { order: 1 }); // no apply()
+		registerOfferStrategy("", { apply: () => true });
+
+		expect(getOfferStrategy("Accumulative")).toBeUndefined();
+		expect(warn).toHaveBeenCalled();
+		warn.mockRestore();
+	});
+});
diff --git a/POS/src/utils/offerStrategies.js b/POS/src/utils/offerStrategies.js
new file mode 100644
index 000000000..275e75005
--- /dev/null
+++ b/POS/src/utils/offerStrategies.js
@@ -0,0 +1,99 @@
+/**
+ * Registry for offer discount strategies contributed by optional apps.
+ *
+ * `pos_next` owns the plain price-discount paths (percentage / amount / rate).
+ * Modes that need cart-wide reasoning — today only `Accumulative`, owned by
+ * posnext_promotions — are registered here at runtime instead of being coded
+ * into posCart.js. The cart asks the registry by `offer.apply_discount_on_price`
+ * and falls through to its built-in path when nothing is registered, so
+ * `pos_next` never imports the satellite and stays buildable without it.
+ *
+ * Only the OFFLINE cart consults these. Online, the server's apply_offers is the
+ * single source of truth and its result is stamped verbatim; a strategy is the
+ * offline mirror of a server-side pass and must produce the same numbers.
+ *
+ * A strategy is a plain object:
+ *
+ *   {
+ *     order?: number,                        // higher runs first (default 0)
+ *     apply(offer, eligibleItems, ctx),      // -> boolean, true if a line changed
+ *     claimsLine?(item),                     // -> boolean, this strategy owns the line
+ *     allowsAutoDiscountStacking?(item),     // -> boolean, Auto Discount may stack on it
+ *   }
+ *
+ * `ctx` carries host callbacks the strategy is not allowed to import:
+ *   { recalculateItem }
+ */
+
+const strategies = new Map();
+
+/** Register (or replace) the strategy handling one `apply_discount_on_price` mode. */
+export function registerOfferStrategy(mode, strategy) {
+	if (!mode || !strategy || typeof strategy.apply !== "function") {
+		console.warn("[posCart] ignoring invalid offer strategy for mode:", mode);
+		return;
+	}
+	strategies.set(mode, strategy);
+}
+
+/** The strategy for a mode, or undefined when the host should handle it itself. */
+export function getOfferStrategy(mode) {
+	if (!mode) return undefined;
+	return strategies.get(mode);
+}
+
+/** The strategy for an offer, resolved from its cross-cart mode. */
+export function getStrategyForOffer(offer) {
+	return getOfferStrategy(offer?.apply_discount_on_price);
+}
+
+/**
+ * Ordering weight for an offer. Strategies that claim lines exclusively must run
+ * before the plain paths, or a first-come rule takes the line they needed.
+ */
+export function offerStrategyOrder(offer) {
+	return Number(getStrategyForOffer(offer)?.order) || 0;
+}
+
+/** Whether any registered strategy allows an Auto Discount to stack on this line. */
+export function allowsAutoDiscountStacking(item) {
+	for (const strategy of strategies.values()) {
+		if (strategy.allowsAutoDiscountStacking?.(item)) return true;
+	}
+	return false;
+}
+
+/** Test seam — drops every registration. */
+export function clearOfferStrategies() {
+	strategies.clear();
+}
+
+let loaded = null;
+
+/**
+ * Load strategy plugins shipped by installed optional apps.
+ *
+ * Resolved at runtime from `/assets/<app>/...`, which Frappe serves from each
+ * app's `public/` directory. The URL is built at call time and marked
+ * `@vite-ignore` so the bundler leaves it alone — `pos_next` must build with no
+ * knowledge of the satellite. Idempotent, and a failure is non-fatal: the cart
+ * keeps working with its built-in paths.
+ */
+export async function loadOfferStrategyPlugins() {
+	if (loaded) return loaded;
+
+	loaded = (async () => {
+		const { isPromotionsAppInstalled } = await import("@/utils/promoApi");
+		if (!isPromotionsAppInstalled()) return;
+
+		const url = "/assets/posnext_promotions/pos/offer-strategies.js";
+		try {
+			const plugin = await import(/* @vite-ignore */ url);
+			await plugin.register?.({ registerOfferStrategy });
+		} catch (error) {
+			console.error("[posCart] failed to load promotions offer strategies:", error);
+		}
+	})();
+
+	return loaded;
+}
diff --git a/pos_next/__init__.py b/pos_next/__init__.py
index eb49f20b5..c4662b13f 100644
--- a/pos_next/__init__.py
+++ b/pos_next/__init__.py
@@ -90,3 +90,15 @@ def _promotions_installed():
 	patch_round_floats_in_compat(document_module)
 except Exception:
 	pass
+
+# Stop `bench run-tests` from wiping a working site's Item Prices. ERPNext's
+# before_tests hook deletes the whole table with raw SQL and commits, leaving no
+# Deleted Document trail. Opt in per site with `preserve_item_prices_in_tests`.
+try:
+	from erpnext.setup import utils as _erpnext_setup_utils
+
+	from pos_next.overrides.test_setup_compat import patch_before_tests
+
+	patch_before_tests(_erpnext_setup_utils)
+except Exception:
+	pass
diff --git a/pos_next/overrides/test_setup_compat.py b/pos_next/overrides/test_setup_compat.py
new file mode 100644
index 000000000..95b6056e3
--- /dev/null
+++ b/pos_next/overrides/test_setup_compat.py
@@ -0,0 +1,106 @@
+# Copyright (c) 2026, BrainWise and contributors
+# For license information, please see license.txt
+
+"""Keep ``bench run-tests`` from wiping a working site's Item Prices.
+
+ERPNext's ``before_tests`` hook (``erpnext/setup/utils.py``) runs
+
+	frappe.db.sql("delete from `tabItem Price`")
+
+unconditionally and then commits. Frappe fires that hook at the start of *every*
+``bench run-tests`` invocation — narrowing the run with ``--module`` or
+``--doctype`` picks which tests execute, not whether the hook runs — so a single
+test run against a site holding real data destroys every Item Price on it.
+
+Because the wipe is raw SQL it never goes through ``delete_doc``: no
+``Deleted Document`` rows and no ``Version`` history are written, so the records
+cannot be reconstructed afterwards. Only a database backup gets them back.
+
+Frappe ships ``--skip-before-tests`` for this, but it has to be remembered on
+every command and forgetting once is unrecoverable. When
+``preserve_item_prices_in_tests`` is set in the site's ``site_config.json`` this
+patch snapshots the rows, lets ERPNext's setup run untouched, then puts back
+whatever it removed. Sites that leave the flag unset — CI, throwaway test sites
+— keep stock ERPNext behaviour, which the ERPNext suite itself relies on.
+
+Item Price is a flat DocType (no child tables), so a row-level copy is a
+faithful snapshot. The restore deliberately avoids ``CREATE``/``DROP TABLE``:
+Frappe raises ``ImplicitCommitError`` for DDL issued while a transaction holds
+writes, which is exactly the state ``before_tests`` runs in.
+"""
+
+from __future__ import annotations
+
+import frappe
+
+SITE_CONFIG_FLAG = "preserve_item_prices_in_tests"
+
+# Chunked so a large price list cannot trip MAX_WRITES_PER_TRANSACTION.
+RESTORE_CHUNK_SIZE = 500
+
+
+def _preserve_enabled() -> bool:
+	try:
+		return bool(frappe.conf.get(SITE_CONFIG_FLAG))
+	except Exception:
+		return False
+
+
+def _restore_item_prices(rows) -> None:
+	"""Put snapshotted rows back, leaving anything created meanwhile intact.
+
+	``REPLACE`` rather than ``INSERT``: ERPNext's own test records may have
+	recreated some of these primary keys by the time we run.
+	"""
+	if not rows:
+		return
+
+	columns = list(rows[0].keys())
+	collist = ", ".join(f"`{column}`" for column in columns)
+	row_placeholder = "(" + ", ".join(["%s"] * len(columns)) + ")"
+
+	for start in range(0, len(rows), RESTORE_CHUNK_SIZE):
+		chunk = rows[start : start + RESTORE_CHUNK_SIZE]
+		values = []
+		for row in chunk:
+			values.extend(row[column] for column in columns)
+		frappe.db.sql(
+			f"REPLACE INTO `tabItem Price` ({collist}) VALUES "
+			+ ", ".join([row_placeholder] * len(chunk)),
+			values,
+		)
+		frappe.db.commit()
+
+
+def patch_before_tests(utils_module) -> None:
+	"""Wrap ``erpnext.setup.utils.before_tests`` so it cannot drop Item Prices.
+
+	The hook is resolved by dotted path at call time (``frappe.get_attr``), so
+	rebinding the module attribute here is enough — no ERPNext file is edited.
+	"""
+	original = getattr(utils_module, "before_tests", None)
+	if original is None or getattr(original, "_pos_next_preserves_item_prices", False):
+		return
+
+	def before_tests_preserving_item_prices():
+		if not _preserve_enabled():
+			return original()
+
+		try:
+			snapshot = frappe.db.sql("SELECT * FROM `tabItem Price`", as_dict=True)
+		except Exception:
+			# Never let the guard itself break a test run.
+			return original()
+
+		try:
+			return original()
+		finally:
+			try:
+				_restore_item_prices(snapshot)
+			except Exception:
+				frappe.log_error(
+					frappe.get_traceback(), "POS Next: failed to restore Item Prices after before_tests"
+				)
+
+	before_tests_preserving_item_prices._pos_next_preserves_item_prices = True
+	utils_module.before_tests = before_tests_preserving_item_prices

From 5d4c16f25b6bb6e52561a082591838a6c7645915 Mon Sep 17 00:00:00 2001
From: MohamedAliSmk <mohamedalismk@cgmail.com>
Date: Sun, 6 Sep 2026 14:32:22 +0300
Subject: [PATCH 8/8] Enhance customer creation and offer validation in POS

- Updated CreateCustomerDialog.vue to require a selected country code for customer submission and improved mobile number handling.
- Enhanced posCart.js and posOffers.js to include gross and net amount calculations for offer validation, ensuring accurate eligibility checks based on item discounts.
- Refactored customer group and territory resolution logic in customers.py to prefer non-group entries, improving customer creation reliability.
---
 .../components/sale/CreateCustomerDialog.vue  | 34 ++++++-
 POS/src/components/sale/InvoiceCart.vue       |  6 +-
 POS/src/pages/POSSale.vue                     |  1 +
 POS/src/stores/__tests__/posOffers.spec.js    | 70 -------------
 POS/src/stores/posCart.js                     | 91 ++++++++++++++---
 POS/src/stores/posOffers.js                   | 97 +++++++++++++++++--
 pos_next/api/customers.py                     | 80 ++++++++++++---
 7 files changed, 266 insertions(+), 113 deletions(-)
 delete mode 100644 POS/src/stores/__tests__/posOffers.spec.js

diff --git a/POS/src/components/sale/CreateCustomerDialog.vue b/POS/src/components/sale/CreateCustomerDialog.vue
index ee3831765..4b641ce13 100644
--- a/POS/src/components/sale/CreateCustomerDialog.vue
+++ b/POS/src/components/sale/CreateCustomerDialog.vue
@@ -426,7 +426,11 @@ const hasValidCustomerName = computed(() => {
 });
 
 const canSubmitCustomer = computed(
-	() => hasValidCustomerName.value && Boolean(phoneNumber.value) && hasPermission.value
+	() =>
+		hasValidCustomerName.value &&
+		Boolean(phoneNumber.value) &&
+		Boolean(selectedCountryCode.value) &&
+		hasPermission.value
 );
 
 const currentCountryCode = computed(() => {
@@ -461,10 +465,17 @@ const selectCountry = (country) => {
 	updateTerritoryFromCountry();
 };
 
+const DEFAULT_MOBILE_ISD = "+20";
+
 const updateMobileNumber = () => {
-	customerData.value.mobile_no = phoneNumber.value
+	if (!phoneNumber.value) {
+		customerData.value.mobile_no = "";
+		return;
+	}
+	// Never persist a leading "-" when ISD is still unresolved
+	customerData.value.mobile_no = selectedCountryCode.value
 		? `${selectedCountryCode.value}-${phoneNumber.value}`
-		: "";
+		: phoneNumber.value;
 };
 
 const handleClickOutside = (event) => {
@@ -549,7 +560,15 @@ const applyDefaultCountryCode = async () => {
 		return;
 	}
 
-	setCountryFromProfileValue(profileCountry);
+	const applied = setCountryFromProfileValue(profileCountry);
+	if (!applied && !selectedCountryCode.value) {
+		const fallback =
+			resolveCountryIsd(DEFAULT_MOBILE_ISD) ||
+			countriesStore.countries[0]?.isd ||
+			DEFAULT_MOBILE_ISD;
+		selectedCountryCode.value = fallback;
+		log.warn(`Falling back to default ISD ${fallback}`);
+	}
 	defaultCountryApplied.value = true;
 };
 
@@ -608,7 +627,12 @@ const createCustomerResource = createResource({
 	},
 	onError: (error) => {
 		log.error("Error creating customer", error);
-		showError(error.message || __("Failed to create customer"));
+		const message =
+			error?.messages?.[0] ||
+			error?.message ||
+			(typeof error === "string" ? error : null) ||
+			__("Failed to create customer");
+		showError(message);
 	},
 });
 
diff --git a/POS/src/components/sale/InvoiceCart.vue b/POS/src/components/sale/InvoiceCart.vue
index e4826bc49..2bfa881ce 100644
--- a/POS/src/components/sale/InvoiceCart.vue
+++ b/POS/src/components/sale/InvoiceCart.vue
@@ -1897,8 +1897,10 @@ const displayDiscountAmount = computed(() => {
 		(sum, item) => sum + (Number.parseFloat(item.discount_amount) || 0),
 		0
 	);
-	// Fall back to store total when items haven't been stamped yet (e.g. header coupon)
-	return lineDiscounts > 0 ? lineDiscounts : props.discountAmount;
+	const storeDiscount = Number.parseFloat(props.discountAmount) || 0;
+	// Prefer the larger value: store total includes header/additional discounts;
+	// line sum is fresher when offer stamps land before the incremental cache.
+	return Math.max(lineDiscounts, storeDiscount);
 });
 
 /**
diff --git a/POS/src/pages/POSSale.vue b/POS/src/pages/POSSale.vue
index 35cd5c858..ba4141682 100644
--- a/POS/src/pages/POSSale.vue
+++ b/POS/src/pages/POSSale.vue
@@ -365,6 +365,7 @@
 								:discount-amount="cartStore.totalDiscount"
 								:grand-total="cartStore.grandTotal"
 								:pos-profile="shiftStore.profileName"
+								:company="shiftStore.profileCompany"
 								:currency="shiftStore.profileCurrency"
 								:applied-offers="cartStore.appliedOffers"
 								:warehouses="profileWarehouses"
diff --git a/POS/src/stores/__tests__/posOffers.spec.js b/POS/src/stores/__tests__/posOffers.spec.js
deleted file mode 100644
index eab206052..000000000
--- a/POS/src/stores/__tests__/posOffers.spec.js
+++ /dev/null
@@ -1,70 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { setActivePinia, createPinia } from "pinia";
-
-vi.mock("@/utils/apiWrapper", () => ({ call: vi.fn() }));
-vi.mock("@/utils/offline", () => ({ isOffline: () => false }));
-vi.mock("@/utils/offline/workerClient", () => ({ offlineWorker: {} }));
-vi.mock("@/utils/offline/db", () => ({
-	getOneTimeRedemptions: vi.fn(), setOneTimeRedemptions: vi.fn(), addOneTimeRedemptions: vi.fn(),
-}));
-vi.mock("@/stores/posShift", () => ({ usePOSShiftStore: () => ({}) }));
-globalThis.__ = (s, args = []) => String(s).replace(/\{(\d+)\}/g, (_, i) => args[i]);
-
-import { usePOSOffersStore } from "@/stores/posOffers";
-
-// Invoice ACC-SINV-2026-00165 / 00167: SKU009 x1 @150 (50% off), 9505 x2 @90.
-// gross = 330, net = 255.
-const SNAPSHOT = {
-	subtotal: 330, netSubtotal: 255, itemCount: 3,
-	itemCodes: ["SKU009", "9505"], itemGroups: ["Demo Item Group"], brands: [],
-	itemQuantities: { SKU009: 1, "9505": 2 },
-	itemGroupQuantities: { "Demo Item Group": 3 },
-	brandQuantities: {},
-	itemAmounts: { SKU009: 150, "9505": 180 },
-	itemGroupAmounts: { "Demo Item Group": 330 },
-	brandAmounts: {},
-};
-
-describe("offer amount gate mirrors the server basis", () => {
-	let store;
-	beforeEach(() => {
-		setActivePinia(createPinia());
-		store = usePOSOffersStore();
-		store.updateCartSnapshot(SNAPSHOT);
-	});
-
-	it("PRLE-0013: Transaction max_amt=260 gates on net 255, not gross 330", () => {
-		const offer = { name: "PRLE-0013", apply_on: "Transaction", max_amt: 260 };
-		expect(store.getEligibleItemAmount(offer)).toBe(255);
-		expect(store.checkOfferEligibility(offer).eligible).toBe(true);
-	});
-
-	it("Transaction rule is still rejected when the net total really exceeds max_amt", () => {
-		const offer = { name: "X", apply_on: "Transaction", max_amt: 200 };
-		expect(store.checkOfferEligibility(offer).eligible).toBe(false);
-	});
-
-	it("Item Code rule gates on that item's gross line amount, not the cart", () => {
-		// SKU009 alone is 150 gross; cart is 330.
-		const offer = { name: "Y", apply_on: "Item Code", eligible_items: ["SKU009"], min_amt: 200 };
-		expect(store.getEligibleItemAmount(offer)).toBe(150);
-		expect(store.checkOfferEligibility(offer).eligible).toBe(false);
-		expect(store.getUnlockAmount(offer)).toBe(50);
-
-		const ok = { ...offer, min_amt: 120 };
-		expect(store.checkOfferEligibility(ok).eligible).toBe(true);
-	});
-
-	it("Item Group rule sums only the matching lines", () => {
-		const offer = {
-			name: "Z", apply_on: "Item Group",
-			eligible_item_groups: ["Demo Item Group"], min_amt: 300,
-		};
-		expect(store.getEligibleItemAmount(offer)).toBe(330);
-		expect(store.checkOfferEligibility(offer).eligible).toBe(true);
-	});
-
-	it("offers with no scope metadata fall back to the gross subtotal", () => {
-		expect(store.getEligibleItemAmount({ name: "W" })).toBe(330);
-	});
-});
diff --git a/POS/src/stores/posCart.js b/POS/src/stores/posCart.js
index 8d49b3545..e08672977 100644
--- a/POS/src/stores/posCart.js
+++ b/POS/src/stores/posCart.js
@@ -1475,10 +1475,34 @@ export const usePOSCartStore = defineStore("posCart", () => {
 	}
 
 	/**
-	 * Builds cart snapshot for offer validation
+	 * Gross and net amount of a single cart line, on the same basis the server
+	 * uses when gating min_amt/max_amt.
+	 *
+	 * Mirrors buildOfferEvaluationPayload (which sends
+	 * `price_list_rate: item.price_list_rate || item.rate`) and the net-rate
+	 * derivation in apply_offers, which folds item discounts back into the
+	 * pricing items as `price_list_rate * (1 - discount_percentage / 100)`
+	 * before handing the cart total to ERPNext's transaction engine.
+	 */
+	function offerLineAmounts(item) {
+		const qty = item.quantity || 0;
+		const listRate = Number.parseFloat(item.price_list_rate || item.rate) || 0;
+		const gross = qty * listRate;
+		const discountPct = Number.parseFloat(item.discount_percentage) || 0;
+		return { gross, net: gross * (1 - discountPct / 100) };
+	}
+
+	/** Cart total after item-level discounts — the server's `doc.total`. */
+	function offerNetSubtotal(items) {
+		return items.reduce((sum, item) => sum + offerLineAmounts(item).net, 0);
+	}
+
+	/**
+	 * Builds cart snapshot for offer validation.
+	 * Paid lines only — free gifts must not inflate min_qty/max_qty/min_amt checks.
 	 */
 	function buildCartSnapshot() {
-		const items = invoiceItems.value;
+		const items = invoiceItems.value.filter((item) => !item.is_free_item);
 		const totalQty = items.reduce((sum, item) => sum + (item.quantity || 0), 0);
 		const itemCodes = items.map((item) => item.item_code);
 		const itemGroups = items.map((item) => item.item_group).filter(Boolean);
@@ -1491,24 +1515,33 @@ export const usePOSCartStore = defineStore("posCart", () => {
 		const itemGroupQuantities = {};
 		// brandQuantities: { brand: total_qty } - quantity per brand
 		const brandQuantities = {};
+		// Gross line amounts (qty * price_list_rate) per scope, for min_amt/max_amt
+		const itemAmounts = {};
+		const itemGroupAmounts = {};
+		const brandAmounts = {};
 
 		for (const item of items) {
 			const qty = item.quantity || 0;
+			const { gross } = offerLineAmounts(item);
 
 			// Aggregate by item code
 			if (item.item_code) {
 				itemQuantities[item.item_code] = (itemQuantities[item.item_code] || 0) + qty;
+				itemAmounts[item.item_code] = (itemAmounts[item.item_code] || 0) + gross;
 			}
 
 			// Aggregate by item group
 			if (item.item_group) {
 				itemGroupQuantities[item.item_group] =
 					(itemGroupQuantities[item.item_group] || 0) + qty;
+				itemGroupAmounts[item.item_group] =
+					(itemGroupAmounts[item.item_group] || 0) + gross;
 			}
 
 			// Aggregate by brand
 			if (item.brand) {
 				brandQuantities[item.brand] = (brandQuantities[item.brand] || 0) + qty;
+				brandAmounts[item.brand] = (brandAmounts[item.brand] || 0) + gross;
 			}
 		}
 
@@ -1518,10 +1551,15 @@ export const usePOSCartStore = defineStore("posCart", () => {
 			itemCodes: [...new Set(itemCodes)],
 			itemGroups: [...new Set(itemGroups)],
 			brands: [...new Set(brands)],
-			// New: quantity maps for accurate min_qty/max_qty validation
+			// Quantity maps for accurate min_qty/max_qty validation
 			itemQuantities,
 			itemGroupQuantities,
 			brandQuantities,
+			// Amount bases for min_amt/max_amt validation
+			netSubtotal: offerNetSubtotal(items),
+			itemAmounts,
+			itemGroupAmounts,
+			brandAmounts,
 		};
 	}
 
@@ -1712,52 +1750,74 @@ export const usePOSCartStore = defineStore("posCart", () => {
 	let cachedItemQuantities = {};
 	let cachedItemGroupQuantities = {};
 	let cachedBrandQuantities = {};
+	let cachedItemAmounts = {};
+	let cachedItemGroupAmounts = {};
+	let cachedBrandAmounts = {};
 
 	function syncOfferSnapshot() {
 		// Only sync if values are initialized
 		if (subtotal.value !== undefined && invoiceItems.value) {
-			// Create hash for item codes and quantities to detect actual changes
-			const currentHash = invoiceItems.value
-				.map((item) => `${item.item_code}:${item.quantity}`)
+			// Paid lines only — free gifts must not inflate min_qty/max_qty checks
+			const paidItems = invoiceItems.value.filter((item) => !item.is_free_item);
+
+			// Create hash for paid item codes and quantities to detect actual changes.
+			// price_list_rate is part of the key because the cached amount maps
+			// below are money, not just counts — a price list change with an
+			// otherwise identical cart must invalidate them.
+			const currentHash = paidItems
+				.map(
+					(item) =>
+						`${item.item_code}:${item.quantity}:${item.price_list_rate || item.rate}`
+				)
 				.join(",");
 
 			// Only recalculate expensive operations if items actually changed
 			if (currentHash !== previousItemCodesHash) {
-				cachedItemCodes = invoiceItems.value.map((item) => item.item_code);
+				cachedItemCodes = paidItems.map((item) => item.item_code);
 				cachedItemGroups = [
-					...new Set(invoiceItems.value.map((item) => item.item_group).filter(Boolean)),
+					...new Set(paidItems.map((item) => item.item_group).filter(Boolean)),
 				];
 				cachedBrands = [
-					...new Set(invoiceItems.value.map((item) => item.brand).filter(Boolean)),
+					...new Set(paidItems.map((item) => item.brand).filter(Boolean)),
 				];
 
 				// Build quantity maps for accurate offer validation
 				cachedItemQuantities = {};
 				cachedItemGroupQuantities = {};
 				cachedBrandQuantities = {};
+				cachedItemAmounts = {};
+				cachedItemGroupAmounts = {};
+				cachedBrandAmounts = {};
 
-				for (const item of invoiceItems.value) {
+				for (const item of paidItems) {
 					const qty = item.quantity || 0;
+					const { gross } = offerLineAmounts(item);
 
 					if (item.item_code) {
 						cachedItemQuantities[item.item_code] =
 							(cachedItemQuantities[item.item_code] || 0) + qty;
+						cachedItemAmounts[item.item_code] =
+							(cachedItemAmounts[item.item_code] || 0) + gross;
 					}
 					if (item.item_group) {
 						cachedItemGroupQuantities[item.item_group] =
 							(cachedItemGroupQuantities[item.item_group] || 0) + qty;
+						cachedItemGroupAmounts[item.item_group] =
+							(cachedItemGroupAmounts[item.item_group] || 0) + gross;
 					}
 					if (item.brand) {
 						cachedBrandQuantities[item.brand] =
 							(cachedBrandQuantities[item.brand] || 0) + qty;
+						cachedBrandAmounts[item.brand] =
+							(cachedBrandAmounts[item.brand] || 0) + gross;
 					}
 				}
 
 				previousItemCodesHash = currentHash;
 			}
 
-			// Calculate total quantity (sum of all item quantities, not line count)
-			const totalQty = invoiceItems.value.reduce((sum, item) => {
+			// Calculate total quantity (sum of all paid item quantities, not line count)
+			const totalQty = paidItems.reduce((sum, item) => {
 				return sum + (item.quantity || 0);
 			}, 0);
 
@@ -1770,6 +1830,13 @@ export const usePOSCartStore = defineStore("posCart", () => {
 				itemQuantities: cachedItemQuantities,
 				itemGroupQuantities: cachedItemGroupQuantities,
 				brandQuantities: cachedBrandQuantities,
+				// Recomputed every sync, not cached with the maps above: item
+				// discounts change without any item/qty/price change (the server
+				// stamps them back onto the cart after apply_offers).
+				netSubtotal: offerNetSubtotal(paidItems),
+				itemAmounts: cachedItemAmounts,
+				itemGroupAmounts: cachedItemGroupAmounts,
+				brandAmounts: cachedBrandAmounts,
 			});
 		}
 	}
diff --git a/POS/src/stores/posOffers.js b/POS/src/stores/posOffers.js
index 110db7bfc..8f8d28362 100644
--- a/POS/src/stores/posOffers.js
+++ b/POS/src/stores/posOffers.js
@@ -22,6 +22,14 @@ const defaultSnapshot = () => ({
 	itemQuantities: {}, // { item_code: qty }
 	itemGroupQuantities: {}, // { item_group: qty }
 	brandQuantities: {}, // { brand: qty }
+	// Amount basis for min_amt/max_amt validation. The server does NOT use one
+	// figure for every offer — see getEligibleItemAmount:
+	//   apply_on = "Transaction"  -> netSubtotal (cart, after item discounts)
+	//   apply_on = Item/Group/Brand -> gross amount of the matching lines only
+	netSubtotal: 0,
+	itemAmounts: {}, // { item_code: qty * price_list_rate }
+	itemGroupAmounts: {}, // { item_group: qty * price_list_rate }
+	brandAmounts: {}, // { brand: qty * price_list_rate }
 });
 
 function getDiscountSortValue(offer) {
@@ -132,8 +140,22 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 				? snapshot.brandQuantities
 				: {};
 
+		// Amount maps mirroring the server's min_amt/max_amt bases.
+		const asAmountMap = (value) =>
+			value && typeof value === "object" ? value : {};
+		const netSubtotal = Number.isFinite(Number.parseFloat(snapshot.netSubtotal))
+			? Number.parseFloat(snapshot.netSubtotal)
+			: subtotal;
+		const itemAmounts = asAmountMap(snapshot.itemAmounts);
+		const itemGroupAmounts = asAmountMap(snapshot.itemGroupAmounts);
+		const brandAmounts = asAmountMap(snapshot.brandAmounts);
+
 		cartSnapshot.value = {
 			subtotal,
+			netSubtotal,
+			itemAmounts,
+			itemGroupAmounts,
+			brandAmounts,
 			itemCount,
 			itemCodes,
 			itemGroups,
@@ -206,13 +228,66 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 		return cartSnapshot.value.itemCount || 0;
 	}
 
+	/**
+	 * Resolves the amount an offer's min_amt/max_amt must be compared against.
+	 *
+	 * The server uses two different bases depending on the rule's scope, so a
+	 * single cart figure cannot mirror it:
+	 *
+	 * - apply_on = "Transaction" -> ERPNext gates on `doc.total`
+	 *   (apply_pricing_rule_on_transaction), i.e. the whole cart AFTER
+	 *   item-level discounts. Comparing the gross subtotal here rejects offers
+	 *   the server would grant.
+	 * - apply_on = Item Code / Item Group / Brand -> ERPNext gates on
+	 *   `qty * price_list_rate` of the MATCHING lines only (filter_pricing_rules),
+	 *   at list price, ignoring discounts other rules put on those lines.
+	 *   Comparing the whole cart here accepts offers the server would reject.
+	 *
+	 * This is the amount-side counterpart of getEligibleItemQuantity.
+	 *
+	 * @param {Object} offer - The offer to check
+	 * @returns {number} Amount to compare against min_amt / max_amt
+	 */
+	function getEligibleItemAmount(offer) {
+		const itemAmounts = cartSnapshot.value.itemAmounts || {};
+		const itemGroupAmounts = cartSnapshot.value.itemGroupAmounts || {};
+		const brandAmounts = cartSnapshot.value.brandAmounts || {};
+		const sumOver = (keys, map) => keys.reduce((sum, key) => sum + (map[key] || 0), 0);
+
+		if (offer?.apply_on === "Item Code") {
+			const eligibleItems = offer.eligible_items || [];
+			if (eligibleItems.length > 0) {
+				return sumOver(eligibleItems, itemAmounts);
+			}
+		} else if (offer?.apply_on === "Item Group") {
+			const eligibleGroups = offer.eligible_item_groups || [];
+			if (eligibleGroups.length > 0) {
+				if (eligibleGroups.includes("All Item Groups")) {
+					return cartSnapshot.value.subtotal || 0;
+				}
+				return sumOver(eligibleGroups, itemGroupAmounts);
+			}
+		} else if (offer?.apply_on === "Brand") {
+			const eligibleBrands = offer.eligible_brands || [];
+			if (eligibleBrands.length > 0) {
+				return sumOver(eligibleBrands, brandAmounts);
+			}
+		} else if (offer?.apply_on === "Transaction") {
+			// Post-item-discount cart total — what `doc.total` carries server-side.
+			return cartSnapshot.value.netSubtotal || 0;
+		}
+
+		// Offers without usable scope metadata: fall back to the gross cart
+		// subtotal, the pre-existing behaviour for every offer.
+		return cartSnapshot.value.subtotal || 0;
+	}
+
 	/**
 	 * Checks if an offer is eligible based on current cart state
 	 * @param {Object} offer - The offer to check
 	 * @returns {Object} {eligible: boolean, reason: string|null}
 	 */
 	function checkOfferEligibility(offer) {
-		const subtotal = cartSnapshot.value.subtotal || 0;
 		const itemCount = cartSnapshot.value.itemCount || 0;
 		const cartItemCodes = cartSnapshot.value.itemCodes || [];
 		const cartItemGroups = cartSnapshot.value.itemGroups || [];
@@ -311,16 +386,19 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 			};
 		}
 
-		// Check minimum amount (still uses total subtotal)
-		if (offer?.min_amt && subtotal < offer.min_amt) {
+		// Check min/max amount against the same basis the server uses for this
+		// offer's scope — net cart total for Transaction rules, gross amount of
+		// the matching lines otherwise. See getEligibleItemAmount.
+		const eligibleAmount = getEligibleItemAmount(offer);
+
+		if (offer?.min_amt && eligibleAmount < offer.min_amt) {
 			return {
 				eligible: false,
 				reason: __("Minimum cart value of {0} required", [offer.min_amt]),
 			};
 		}
 
-		// Check maximum amount (still uses total subtotal)
-		if (offer?.max_amt && subtotal > offer.max_amt) {
+		if (offer?.max_amt && eligibleAmount > offer.max_amt) {
 			return {
 				eligible: false,
 				reason: __("Maximum cart value exceeded ({0})", [offer.max_amt]),
@@ -361,9 +439,11 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 	const autoEligibleCount = computed(() => autoEligibleOffers.value.length);
 
 	function getUnlockAmount(offer) {
-		const subtotal = cartSnapshot.value.subtotal || 0;
-		if (offer?.min_amt && subtotal < offer.min_amt) {
-			return offer.min_amt - subtotal;
+		// Same basis as the eligibility gate, or the prompt would ask for an
+		// amount that does not actually unlock the offer.
+		const eligibleAmount = getEligibleItemAmount(offer);
+		if (offer?.min_amt && eligibleAmount < offer.min_amt) {
+			return offer.min_amt - eligibleAmount;
 		}
 		return 0;
 	}
@@ -467,6 +547,7 @@ export const usePOSOffersStore = defineStore("posOffers", () => {
 		setAvailableOffers,
 		clearOffers,
 		checkOfferEligibility,
+		getEligibleItemAmount,
 		getUnlockAmount,
 		ensureOffersFetched,
 		setOneTimeContext,
diff --git a/pos_next/api/customers.py b/pos_next/api/customers.py
index a12604a70..5dc2092f0 100644
--- a/pos_next/api/customers.py
+++ b/pos_next/api/customers.py
@@ -130,22 +130,8 @@ def create_customer(
 		pos_profile=pos_profile,
 	)
 
-	resolved_customer_group = customer_group
-	if not resolved_customer_group:
-		resolved_customer_group = frappe.db.get_single_value("Selling Settings", "customer_group")
-	if not resolved_customer_group:
-		resolved_customer_group = (
-			frappe.db.get_value("Customer Group", {"is_group": 0}, "name", order_by="lft")
-			or "All Customer Groups"
-		)
-
-	resolved_territory = territory
-	if not resolved_territory:
-		resolved_territory = frappe.db.get_single_value("Selling Settings", "territory")
-	if not resolved_territory:
-		resolved_territory = (
-			frappe.db.get_value("Territory", {"is_group": 0}, "name", order_by="lft") or "All Territories"
-		)
+	resolved_customer_group = _resolve_leaf_customer_group(customer_group)
+	resolved_territory = _resolve_leaf_territory(territory)
 
 	customer = frappe.get_doc(
 		{
@@ -189,6 +175,68 @@ def create_customer(
 	return customer.as_dict()
 
 
+def _is_leaf_customer_group(name):
+	"""True when name exists and is not a group node."""
+	if not name:
+		return False
+	return frappe.db.get_value("Customer Group", name, "is_group") == 0
+
+
+def _is_leaf_territory(name):
+	"""True when name exists and is not a group node."""
+	if not name:
+		return False
+	return frappe.db.get_value("Territory", name, "is_group") == 0
+
+
+def _resolve_leaf_customer_group(customer_group=None):
+	"""
+	Resolve a non-group Customer Group for POS creates.
+
+	Selling Settings often defaults to 'All Customer Groups' (is_group=1), which
+	ERPNext rejects on Customer.validate. Prefer an explicit leaf, then Selling
+	Settings only if it is a leaf, then any leaf group.
+	"""
+	candidates = [
+		customer_group,
+		frappe.db.get_single_value("Selling Settings", "customer_group"),
+	]
+	for name in candidates:
+		if _is_leaf_customer_group(name):
+			return name
+
+	leaf = frappe.db.get_value("Customer Group", {"is_group": 0}, "name", order_by="lft")
+	if leaf:
+		return leaf
+
+	frappe.throw(_("No non-group Customer Group found. Please create one in Customer Group."))
+
+
+def _resolve_leaf_territory(territory=None):
+	"""Resolve a Territory ERPNext will accept on Customer (prefer non-group)."""
+	candidates = [
+		territory,
+		frappe.db.get_single_value("Selling Settings", "territory"),
+	]
+	for name in candidates:
+		# Territory allows selecting group nodes in some setups; prefer leaves.
+		if _is_leaf_territory(name):
+			return name
+		# Keep an existing non-empty territory if the leaf check failed only
+		# because the record is missing (avoid wiping a valid leaf passed in).
+		if name and frappe.db.exists("Territory", name) and not _is_leaf_territory(name):
+			continue
+		if name and frappe.db.exists("Territory", name):
+			return name
+
+	leaf = frappe.db.get_value("Territory", {"is_group": 0}, "name", order_by="lft")
+	if leaf:
+		return leaf
+
+	# Last resort — ERPNext ships with this; better than failing create.
+	return "All Territories"
+
+
 def get_default_loyalty_program(company):
 	"""
 	Get the default loyalty program for a company.