# Member Offers (Hot Deals & Exclusive Offers) — Access, Calculation and Booking Logic

How the live offer logic works in the karma-club-member plugin for both offer types:

- **Hot Deal** (`type: hot_deal`)
- **Exclusive Offer** (`type: exclusive_offer`). The admin console calls this **Exclusive Discovery** (`EXCLUSIVE_DISCOVERY` maps to `exclusive_offer`).

Covered: who can see and book an offer, how the price is calculated, and how booking options are built and booked.

Based on reading the code and the live reference data (29 offers: 22 Hot Deal, 7 Exclusive Offer). Nothing was run against live data.

---

## 1. Overview

Both types use the **same offer structure and the same engine**. An offer has:

- a resort and a list of unit codes
- travel dates and a booking window
- the roles allowed to see it
- display content (tagline, price text, inclusions, T&Cs)

The type mainly changes **who it is for**, **how it is labelled**, **how it is paid for**, and **which options are shown**.

Where the price comes from:

| Booking channel | Price source |
|---|---|
| Member app | **Travel rules**: a points / nights table per resort + unit, matched by date, roles and stay length (section 5) |
| Legacy website booking engine | **Offer pricing fields** (`calculation_mode`, `occp_price`, `price`, `phase_3_*`…), applied as cash on top of the room rate (section 6) |

### 1.1 Hot Deal vs Exclusive Offer at a glance

| | Hot Deal | Exclusive Offer |
|---|---|---|
| Type id used by the engine | 1 | 2 |
| Who it targets (live data) | Points / KRR / KC Elite / Traditional owners (`type_krr`, `contract_kc_elite`, `type_point` + Discovery combos, `type_tradn`) | Karma Club **Discovery** members (`contract_kcd_*_nindia`, `contract_kcde_*_nindia`) |
| Typical offer id | `candidasa2607` | `candidasa2607kcd` (same resort, "kcd" variant) |
| Price paid with | **Points** (daily / weekly season tables) | **Nights entitlement**, 1 night per night stayed (section 5.5) |
| Extra condition | — | Member must **own a qualifying unit type** (`owned_unit_<code>`) |
| Options shown | **Only** options priced by a travel rule | **All** options: offer options **plus** normal exchange options |
| Label | "Hot Deal" (or `label_by`) | "Exclusive Offer" (labels for tagline, inclusions and T&Cs) |
| T&Cs wording | "Hot Deals are available only to…" | "Exclusive Offers are available only to…" |
| Per-unit limit in T&Cs | Up to 2 units per membership | Up to 2 units for one week, or 1 unit for two weeks, per resort |

> **Labels vs type.** `label_by: exclusive_offer` only changes the label. Karma Jimbaran (`kj2607`) and Karma Kandara (`kandara2607`) are **type Hot Deal** but are **shown** as "Exclusive Offer". They follow all the Hot Deal rules.

---

## 2. Access — who can see and book

The checks are layered. A member must pass every layer.

### 2.1 Member status

- The member must be **Active**, **Pending Trade-in**, or **Expired**. Anyone else is denied.
- Members with `contract_kcd_india`, `status_open_india` or `contract_discovery_india` are blocked with "Please contact Karma Concierge for bookings". So **India Discovery members cannot use either offer type**. The live Exclusive Offers target non-India Discovery only.

### 2.2 Member roles

Every member carries a set of roles (e.g. `type_krr`, `contract_kc_elite`, `contract_kcd_nindia`, `contract_india`, `legal_owner`, `family_member`). Extra roles are added automatically:

- `owned_unit_<unit code>`: the unit type the member owns. **This drives Exclusive Offer pricing.**
- `mid-<member number>` and `_account_id_<member number>`: let an offer target one specific member.

### 2.3 Role matching rules

A `roles` list is an **OR** list. Each entry is one of:

| Entry | Matches when |
|---|---|
| `"type_krr"` | The member has that role |
| `{ "and": [a, b, c] }` | The member has **all** of them |
| `{ "or": [a, b] }` | The member has **any** of them |
| `"negation": true` on an object | The result of that object is inverted |

The first entry that matches grants access. The same rules apply to offer roles, override roles and travel-rule roles.

Examples from live data:

```json
// Hot Deal — candidasa2607
"roles": ["type_krr", "contract_kc_elite",
          { "and": ["contract_kc_elite_non", "type_point", "contract_n_discovery"] },
          "type_tradn"]

// Exclusive Offer — candidasa2607kcd
"roles": ["contract_kcd_nindia", "contract_kcd25_nindia", "contract_kcd2509_nindia",
          "contract_kcde_nindia", "contract_kcde25_nindia", "contract_kcde2509_nindia"]
```

### 2.4 Offer visibility

An offer is visible only when **all** of these hold:

1. Now is on or after `starts`, when set. Live offers use `__starts`, which turns this check off, so in practice only `expires` applies.
2. Now is on or before `expires`, when set.
3. The member matches the offer's `roles`, when set.

Then, if the offer has `override` entries, the **first** one whose roles match replaces the offer's settings. Examples:

- `INR` for `contract_india`: India T&Cs or prices.
- `KCDE` on Exclusive Offers: separate settings for KCDE members.
- `Elite` / `KRR` on Jimbaran.

Defaults when missing: type = Hot Deal, currency = `US$`, guest only = no, guest fee = 0.

### 2.5 Family member and India rules (building options and booking)

| Member | Result |
|---|---|
| Legal owner | Allowed |
| Family member + `contract_nindia` | Allowed |
| Family member + `contract_india` | Allowed only with `type_point` + `contract_kc_in_nindia`. Otherwise "Sorry, access denied for family member." |
| Family member booking for a guest | Not allowed |
| India club member | Maximum **2 units** per booking |

Same for both types.

### 2.6 Repeat-booking rules (per member, both types)

The member's existing **Hot Deal / Member Offer** bookings are checked together, so a Hot Deal booking also counts against Exclusive Offers and the other way round. For the **same resort and the same unit type**:

- A stay that starts on another stay's check-out day, or ends on its check-in day, is rejected: "not valid for consecutive reservations".
- A check-in within **30 days** of another check-in is rejected: "not valid for the booking in same property within any thirty day period".

If this check fails, **no travel rules apply**, so the member gets no offer price.

### 2.7 Resort and unit access

- If a unit has its own `roles` and the member doesn't match them, the unit is hidden.
- A member without normal access to a resort can still get an offer option if a travel rule matches. Only the offer price is shown.
- Blackout dates keep the unit visible but allow **offer prices only**.
- Some units have inventory caps for specific member groups (e.g. Points + Lite + Discovery, or KCDE non-India).

### 2.8 Member-area offer cards

The offer cards in the member area are separate content entries (one list for Hot Deals, one for Exclusive Offers). Each card has its own permission rules (AND / OR groups, deny groups, negation) and start / end dates; expired cards are removed. A card is shown only if the member has:

- a contract currency (India → INR, non-India → USD), **and**
- a servicing office (India → HML, Bali → IVO, or EU).

A card's price text is converted to the member's currency. For Hot Deal cards, a price text of `auto` takes the offer's `master_info.price`.

---

## 3. Stay validation (both types)

| Rule | Detail |
|---|---|
| Date format | Arrival and departure must be exact dates. Arrival must be before departure |
| Inside the offer's travel dates | `check_in <= arrival < check_out` and `check_in <= departure <= check_out`, using the offer's `master_info.check_in` / `check_out` (not `travel_between`) |
| Past dates | Arrival cannot be in the past |
| Availability | Every night must have at least the requested quantity free |
| Resort closed | No options if the resort or front office is closed on the check-in or check-out date |
| Children | Missing child ages default to **10** |

### Allowed nights (calendar)

The calendar is built from **all visible offers of the same type** at that resort.

| Calculation mode | Minimum nights | Maximum nights |
|---|---|---|
| `phase-3` (all live offers) | `phase_3_min_night` (default 4) | `phase_3_max_night`, else the smaller of `night` and 7 |
| `phase-2` / `discount` | `min_tiers_night` (default 3) | same |

When `occp_price` is set, only the night counts present for the unit's occupancy are allowed.

---

## 4. Booking options — which options a member sees

For each unit, the engine builds every option the member could book (exchange points, nights, paid rates…). A travel rule match marks an option as an **offer option**.

| Type | Options returned |
|---|---|
| Hot Deal | **Only offer options**. If no travel rule matches, the unit shows nothing |
| Exclusive Offer | **Everything**: offer options plus the normal exchange options for that unit |

A rule with `expose_option: true` (used on live rules of both types) shows the offer option **and** the standard option side by side.

---

## 5. Calculation — app (travel rules)

### 5.1 What a travel rule is

Travel rules are stored per **resort → unit code → list of rules**. A unit code can also point to another unit's rules (an alias, e.g. `PM` uses `PDLX`). A rule holds:

- matching conditions (dates, roles, stay length, booking window)
- a **price table** (`unit_points`) in points or nights
- optional cash on top (`plus_pay`)
- an optional caption, inclusions, T&Cs and occupancy cap

Hot Deal and Exclusive Offer rules sit in the **same list** for a unit. A rule can be tagged `hot_deal_type: 1` or `2`, but **this tag is not checked**. Which rule applies depends only on the member's roles and the other conditions.

### 5.2 Rule matching

Rules are checked in order. The **first** rule that passes all conditions is used.

| Condition | Key | Rule |
|---|---|---|
| Roles | `roles`, then `override` | Member must match. An override can swap settings by role |
| Check-in day | `with_checkin_day` (default on; live rules turn it off), `valid_checkin_days` | Check-in or check-out must fall on a resort check-in day / allowed day |
| Travel window | `travel_between` | Check-in and check-out must be inside one window (or check-in only, if `from_to_by_checkin_date`) |
| Booking window | `confirm_from`, `confirm_to` | Today must be inside it (live rules: `confirm_to` only) |
| Stay length | `min_nights`, `max_nights` | Total nights must be inside it |
| Already used | `rule_id` | A rule is used once |

On a match, the rule's `unit_points` **replaces** the unit's normal table. Its `booking_caption`, `max_occ`, T&Cs and inclusions are used too.

If the matched rule prices at **0** (e.g. no table for this member), the engine tries the **next rule**, then falls back to normal pricing.

### 5.3 Season

Each resort maps **week numbers to season names**, e.g. red = weeks 1-52. Names are free text; white / blue / red by convention.

- Week number counts from the resort's check-in weekday.
- Week 53 is treated as week 1.
- No matching season → 0.

### 5.4 Hot Deal pricing (points)

A Hot Deal rule has a **points table** directly on the rule. Live example (Candidasa):

```json
"unit_points": {
  "daily":  { "red": 14.25, "white": 12.75, "blue": 12 },
  "weekly": { "red": 90,    "white": 82.5,  "blue": 75 },
  "accept_peaks": true, "accept_early_bird": false, "accept_late_break": false
}
```

Role overrides inside the rule swap in a different table, e.g. `ELITE_NON_INDIA` (KC Elite + non-India) has higher daily / weekly values, and `ELITE_INDIA` has India T&Cs.

Base points are tried in this order:

1. **Weekly**, when the stay is 7+ nights (or 5-6 nights inside the weekly window with no specific night price).
   - Uses `weekly[season]`.
   - If the week crosses two seasons, the cheaper one is used.
   - If `daily × nights` is cheaper, that is used instead.
2. **Short break**: `short_break_3` / `short_break_4` / `short_break`. Valid only for 3 nights starting on a check-in day, or 4 nights ending on one.
3. **Fixed nights**: `nights_N[season]`.
4. **Daily**: sum of `daily[season]` for each night. A daily value can be a number, by weekday, or by latest travel date.

`use_calculation_offer_202405: true` instead picks the **cheapest** mix of daily, short break and weekly for the check-in weekday. Live rules set it to false.

**Worked example (Candidasa Hot Deal, white season):**
- 3 nights = 3 × 12.75 = **38.25 → 38 points**
- 7 nights = weekly 82.5, which is cheaper than 7 × 12.75 = 89.25 → **82.5 → 83 points**

(Rounding is to the nearest whole point.)

### 5.5 Exclusive Offer pricing (nights, by unit owned)

A live Exclusive Offer rule has **no price table of its own**. The table comes from an **override keyed on the unit type the member owns**:

```json
"override": {
  "owned_unit_T0": { "roles": ["owned_unit_T0"], "settings": { "unit_points": {
      "nights_1": { "red": "1", "white": "1", "blue": "1", "__points_suffix": "Nights" },
      "nights_2": { "red": "2", ... },
      ...
      "nights_7": { "red": "7", "white": "7", "blue": "7", "__points_suffix": "Nights" } } } },
  "owned_unit_T1": { ... }, "owned_unit_T2": { ... }
}
```

What this means:

- **Charged in Nights entitlement, not points.** N nights cost N nights in every season. `__points_suffix: "Nights"` sets the option currency to Nights.
- **The member must own a qualifying unit type.** The rule for unit **T0** accepts owners of T0, T1 or T2. The rule for **T1** accepts owners of T1 or T2. The rule for **T2** accepts T2 owners only. Owners can book their own unit type **or a smaller one**.
- **Not an owner of a qualifying type:** no table, so the rule prices at 0. The engine falls back to the normal options, which Exclusive Offers still show (section 4).
- Stay length on live rules: **1-7 nights**. Occupancy cap `max_occ: 2`.

Exception: some offers of type Exclusive Offer reuse **points-based** rules. Live example: `mentari2607` at Karma Kandara has normal `daily` / `weekly` tables with Elite and INR overrides. Those are priced like Hot Deals (5.4) but still show all options.

### 5.6 Peak dates, early bird, late break (both types)

- **Peak dates** come from the resort's hide / peak settings (yearly dates, months, specific dates, "from today to").
- **Late break** = check-in within **45 days** of today.
- **Early bird** = check-in **1 year or more** away.
- Both need to be switched on for the resort and can be excluded per unit.

| Situation | Result |
|---|---|
| Rule has `accept_peaks: false` and the stay includes a peak date | Rule fails (no offer price) |
| Rule matched + early bird / late break + rule accepts it (`accept_early_bird` / `accept_late_break`) | Price **halved** |
| Rule matched but doesn't accept early bird / late break | No halving (live Hot Deal rules: both off) |
| No rule + early bird / late break + peak nights | Daily pricing with non-peak nights at half, capped at the weekly price for 5-7 nights |
| Peak season marked weekly-only | Only 7 / 14 / 21-night stays from a check-in day |

### 5.7 Additions after the base price

| Addition | Effect |
|---|---|
| `kc_elite` table | `contract_kc_elite` members get the KC Elite version (suffix "KC Elite Points") |
| `extra.points` / `extra.price` | Fixed extra points or cash |
| `plus`, `plus_peak_dates` | Extra charge for all nights, or for peak nights only |
| `plus_pay.price` | Cash per night, or per person by age (adult / under-age bands) × nights |
| `plus_pay.price_N` | Fixed cash for exactly N nights |
| `plus_pay.peak_dates` | Cash or points supplement on peak nights |
| `plus_pay` public-rate difference | Difference to the public rate with 25% or 20% off |
| Currency | Cash is converted to INR or IDR for those members |
| `calculation_per_person` | × (adults + children). In the unit search this uses the unit's **maximum** occupancy |
| `alter_by_public_rate: rule1` | If the average public rate is below a minimum: points = round(avg × 0.7 / 5.5 × nights), with 6-7 nights counted as 5 |
| Resort-level `off_percent` | points × (100 − off) / 100. Applies to normal points, not travel-rule prices |

Long or mixed-season stays are split into segments, priced separately and added. If any segment is 0, the rule fails. The final value is rounded.

---

## 6. Calculation — legacy website (cash from offer fields, both types)

The website booking engine prices an offer in **cash (offer currency, default US$)** on top of the unit's room rate. The formulas are the same for both types; the type only filters which offers are used and sets the label.

### 6.1 Before pricing

1. The unit must be in the offer's `unit_code` list.
2. The stay must be inside `travel_between`, or inside `min_date` / `max_date` (used by Jimbaran / Kandara).
3. If the stay is longer than `night` and `allow_breakdown` is on (default), the stay is priced in blocks of `night` nights, sliding day by day until checkout lands on a Saturday or the stay ends.
4. If `start_day` is set (e.g. `Sat`), check-in must be on that weekday.

### 6.2 Which formula is used

| `calculation_mode` | `calculation_mode_phase_3` | Formula |
|---|---|---|
| `phase-3` (all live offers) | — (default) | Flat price table (6.3) |
| `phase-3` | `discount` | % off room rate (6.4) |
| `phase-3` | `discount_bar_25` | % off rebuilt public rate (6.5) |
| `phase-2` | — | 7-night tiers (6.6) |
| anything else | — | Phase-1 tiers (6.7) |

After the formula, if the member matches `price_add.roles`, add `price_add.percent`% or `price_add.value`, then round.

### 6.3 Phase-3 — flat price table

- Minimum nights = `phase_3_min_night` (default **4**).
- Maximum nights = `phase_3_max_night`; if not set, 7 (or **21** when `weekly` is false).
- Both the requested nights and the total stay must be inside min-max. Otherwise price = 0 and the offer's `booking` text is shown as the reason.

Price lookup, by the unit's maximum occupancy:

1. `occp_price[occupancy][nights]`:
   - a number is the price;
   - `checkin_days: {<weekday>: price}` gives a price by check-in day;
   - a check-in-day entry can hold `travel_date_price: [{from, until, price}]` for a price by date range.
2. No entry for that night count and `weekly` is false → `nights × occp_price[occupancy]["1"]`.
3. `occp_price[occupancy]` is a single number → used only when nights = `night`.
4. No `occp_price` → `price`, when occupancy = `occp`.

### 6.4 Phase-3 `discount`

- Minimum nights = `phase_3_min_night` (default **3**).
- Percent = `price` if set, otherwise from `occp_price[occupancy][nights]`.
- **Price = room rate − room rate × percent / 100**

### 6.5 Phase-3 `discount_bar_25`

- **Percent is a number:** full public rate = room rate × 100 / 75. **Price = full rate − full rate × percent / 100.**
- **Percent is a weekday table** (`gl_discount`): each night = normal rate × (100 − that weekday's percent, or the `__peak` percent on peak nights) / 100 × exchange rate, summed. Any missing weekday → 0.

### 6.6 Phase-2

- Works only when `night` = 7.
- Price = `price` + 100 per `tiers_occp` step above `occp`, or `price` only when occupancy = `occp`.
- Under 5 nights: price × 0.2 × nights, if nights ≥ `min_tiers_night` (default 3), else 0.

### 6.7 Phase-1

- `price` as date ranges (`daily` / `weekly`, plus a weekday `default`) → priced per night or week by range.
- Flat `price` when nights = `night`.
  - `tiers_night`: −10% per step below `night`.
  - `tiers_occp`: +50% per step above `occp`.
  - Occupancy ≠ `occp` without tiers → 0.

### 6.8 Inclusions and labels

- Inclusions cost text is shown only when nights ≥ `inclusions_cost_min_nights` (default 7 in phase-3, 5 in phase-2). It goes after the inclusions if `inclusions_cost_bottom` is on, otherwise before.
- Caption: from `label_by`, otherwise the type.
  - `hot_deal` → "Hot Deal"
  - `exclusive_offer` → "Exclusive Offer"
  - `pay_hot_deal` / `pay_exclusive_offer` → "Pay - …"
- Exclusive Offer pages use "Exclusive Offer Inclusions:" and "Exclusive Offer Terms & Conditions:" headings.
- `occ_up_to` caps the displayed maximum occupancy.

---

## 7. Booking (both types)

### 7.1 Multi-unit quote

- Party size must fit: quantity × unit capacity ≥ people travelling, and quantity ≤ people travelling.
- Adults and children are spread across units, highest capacity first. Each unit needs at least one adult.
- Same-kind options are combined: price × qty, fees × qty, added together, cash rounded up.
- Mixed currencies, or a price of 0, are dropped. If any requested unit has no option, there is no result.
- The quote is held for **15 minutes**. The booking must use the same option.

### 7.2 How each option type is booked

| Option paid with | Typical offer | Booking flow |
|---|---|---|
| Points + cash, Nights + cash, paid rate | Hot Deal with `plus_pay` | Points balance checked → space on hold **35 min** → member pays (cash + GST + card fee for card) → payment must match exactly → booking confirmed, points deducted |
| Points only | Most Hot Deals | Hold and confirm in one go; confirmation finishes in the background |
| Nights only | **Exclusive Offer (Discovery)** | Space is put **on hold for Karma Concierge** to process. Member sees "Your booking of space has been put on hold for Karma Concierge to process it on your behalf." |

Entitlement rules:
- Points / nights come from the **soonest-expiring** active entitlement first.
- Entitlements that expire before arrival are skipped.
- All of it must come from the **same resort** entitlement.
- A second unit of the same type that needs 0 points is booked as "Second Unit against Entitlement".

**Recorded booking type:** offer bookings are recorded as **Hot Deal** for both offer types. They count together in the 30-day / consecutive rules (2.6).

**Payment provider:** Razorpay for India charge-centre members (unless `contract_kc_in_nindia`), Flywire otherwise.

**Failure:** if any unit fails to hold, all units held so far are released.

---

## 8. Logic gaps found

**Both types**

1. The offer ID isn't checked when building multi-unit options, and isn't re-checked at booking. An expired offer can still be booked from a cached quote.
2. The repeat-booking rules (2.6) apply when building options, not at booking.
3. The party size doesn't filter units in the first search. Every unit is priced at full occupancy, which also inflates per-person pricing.
4. The calendar uses **all** offers of the same type at that resort, not the selected one.
5. In `discount` / `discount_bar_25`, prices by travel date never apply, because of a variable mix-up.
6. The same key `price` is a **percent** in the discount modes but an **amount** in phase-3 / phase-1. Default minimum nights are 3 in the discount modes and 4 in phase-3.
7. Local holds expire after 35 minutes, but nothing releases the space early; it stays held until the booking system's own expiry (about 3 business days).
8. If a points-only background confirmation fails, nothing is rolled back.
9. Live offers use `__starts`, so the booking-window start isn't enforced. Only expiry is.

**Exclusive Offer specific**

10. Travel rules ignore `hot_deal_type`. The type 1 / type 2 tags on live rules do nothing; separation relies entirely on **roles**. A Discovery member with a role on a Hot Deal rule would get Hot Deal pricing inside an Exclusive Offer search, and the other way round.
11. Exclusive Offers aren't limited to offer options, so members see normal exchange options next to the offer.
12. If the cached quote expires, it is rebuilt **as a Hot Deal** (type 1), so a Nights-only Exclusive Offer option may disappear at booking time. *Unverified.*
13. The Nights-only option goes to Concierge instead of instant confirmation. If instant booking is expected for Exclusive Offers, that is a gap.
14. Not owning a qualifying unit type silently falls back to normal pricing, with no message explaining why the offer price isn't shown.
15. India Discovery members are blocked outright (2.1), even if an Exclusive Offer's roles would match them.

---

## 9. What the console must configure for each type

| Setting | Hot Deal | Exclusive Offer |
|---|---|---|
| Offer type | Hot Deal | Exclusive Discovery (maps to `exclusive_offer`) |
| Offer roles | WP roles of the target owners, e.g. `type_krr`, `contract_kc_elite`, `type_tradn` | Discovery roles: `contract_kcd_nindia`, `contract_kcd25_nindia`, `contract_kcd2509_nindia`, `contract_kcde_nindia`, `contract_kcde25_nindia`, `contract_kcde2509_nindia` |
| Travel-rule price | `daily` / `weekly` points by season (+ Elite / INR overrides) | No top-level table. `override` per `owned_unit_<code>` with `nights_1`…`nights_7` = 1…7 and `__points_suffix: "Nights"` |
| Rule roles | Same as offer roles (plus `travel_rule`) | Same Discovery roles |
| Rule conditions | `travel_between`, `confirm_to`, `max_nights` 7, `max_occ` 2, `expose_option` true, `with_checkin_day` false | Same, plus `min_nights` 1 |
| Caption / T&Cs | "Hot Deal", Hot Deal T&Cs | "Exclusive Offer", Exclusive Offer T&Cs |
| Label | `label_by: pay_hot_deal` (live) | Same in live data. Use `exclusive_offer` to show the "Exclusive Offer" label |

> The console's Travel Rules tab is currently **shown only for Hot Deals**. Exclusive Offers need the same tab, with support for `owned_unit_*` overrides, or they cannot be priced from the console.
