=== VSW Bogo Offer On Category ===
Contributors:       vaibhavsweb
Tags:               woocommerce, bogo, buy one get one, discount, free product, category, promotion
Requires at least:  5.8
Tested up to:       7.0
Requires PHP:       7.4
Stable tag:         1.0.1
License:            GPL-2.0-or-later
License URI:        https://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 6.0
WC tested up to:    7.0

Flexible Buy X Get Y Free promotions per WooCommerce product category. Supports B1G1, B1G2, B2G2, B3G3 and more. Cheapest item always free automatically.

== Description ==

**VSW Bogo Offer On Category** lets you run powerful Buy X Get Y Free promotions on your WooCommerce store, configured per product category. No coupon codes, no complex setup — just pick a category, choose a deal type, and the plugin does the rest automatically.

= How It Works =

1. Go to the top-level **BOGO Offers** menu in your WordPress admin sidebar.
2. Click **+ Add Rule**, select a product category (e.g. *ProductCat*, *ProductCat1*).
3. Choose a deal type — *Buy 1 Get 1 Free*, *Buy 1 Get 2 Free*, *Buy 2 Get 2 Free*, and many more.
4. Save. The offer is live immediately — no page reload needed.

When a customer adds qualifying products from that category to their cart, the plugin automatically identifies the cheapest items and sets their price to ₹0. The cart, mini-cart sidebar, and checkout all reflect the correct discounted total instantly.

= Supported Deal Types =

* **Buy 1 Get 1 Free** (B1G1) — Classic BOGO
* **Buy 1 Get 2 Free** (B1G2)
* **Buy 1 Get 3 Free** (B1G3)
* **Buy 2 Get 1 Free** (B2G1)
* **Buy 2 Get 2 Free** (B2G2)
* **Buy 2 Get 3 Free** (B2G3)
* **Buy 3 Get 1 Free** (B3G1)
* **Buy 3 Get 2 Free** (B3G2)
* **Buy 3 Get 3 Free** (B3G3)
* **Buy 4 Get 3 Free** (B4G3)
* **Buy 4 Get 4 Free** (B4G4)

= Key Features =

* ✅ **Category-based rules** — each rule targets one product category independently
* ✅ **Auto cheapest detection** — the cheapest items in each group are always free
* ✅ **set_price(0) engine** — free items are truly set to ₹0, so subtotal, mini-cart, and checkout all show the correct total
* ✅ **Works in mini-cart sidebar** — Hurray! banner and ₹0 price appear in the cart drawer immediately after adding items
* ✅ **AJAX-powered** — discount updates without page reload when items are added to cart
* ✅ **Quantity scaling** — 4 items with B1G1 = 2 free; 6 items with B2G2 = 4 free
* ✅ **Multiple simultaneous rules** — run B1G1 on ProductCat and B2G2 on Bangles at the same time
* ✅ **Pause / resume rules** — temporarily disable a rule without deleting it
* ✅ **"Hurray!" celebration banner** — animated red card with confetti shown in cart and mini-cart when discount triggers
* ✅ **"Buy X Get Y Free On [Category]" badge** — shown under the free item's name in the cart
* ✅ **Free item price display** — shows ₹0.00 with strikethrough original price
* ✅ **Teaser notice** — purple banner tells customers about available offers before they add enough items
* ✅ **Variable product support** — works with simple and variable products
* ✅ **HPOS compatible** — WooCommerce High-Performance Order Storage ready
* ✅ **Top-level admin menu** — "BOGO Offers" appears independently in the WordPress sidebar
* ✅ **Translation-ready** — full `.pot` file included
* ✅ **No coding required**

= Example Scenarios =

**Buy 1 Get 1 Free on ProductCat:**
Customer adds Product A (₹799) + ProductCat B (₹399) → B is free → Cart total ₹799 ✅

**Buy 2 Get 2 Free on ProductCate:**
Customer adds 4 Product priced ₹600, ₹500, ₹400, ₹300 → cheapest 2 (₹300 + ₹400) free → Total ₹1,100 ✅

**Buy 1 Get 2 Free on ProductCates:**
Customer adds 3 Product priced ₹500, ₹300, ₹200 → cheapest 2 (₹200 + ₹300) free → Total ₹500 ✅

= Privacy =

This plugin does not collect, store, or transmit any personal data. It uses WooCommerce session storage only to cache active discount details within a shopping session.

== Installation ==

**From the WordPress Plugin Directory (recommended):**

1. Go to **Plugins → Add New** in your WordPress admin.
2. Search for **VSW Bogo Offer On Category**.
3. Click **Install Now**, then **Activate**.
4. Go to **BOGO Offers → Add Rule** in your sidebar and create your first promotion.

**Manual installation:**

1. Download the plugin `.zip` file.
2. Go to **Plugins → Add New → Upload Plugin**.
3. Upload the `.zip` and click **Install Now**, then **Activate**.
4. Go to **BOGO Offers → Add Rule** to configure.

**Requirements:**

* WordPress 5.8 or higher
* WooCommerce 6.0 or higher
* PHP 7.4 or higher

== Frequently Asked Questions ==

= Does it work with sale prices? =

Yes. The plugin reads the current effective price (`get_price()`) — which returns the sale price when a product is on sale — not the regular/MRP price. So if a product's sale price is ₹799, that's what the discount calculation uses.

= Does it work with variable products? =

Yes. The plugin correctly identifies the parent product ID for variations when checking category membership, so variable products are fully supported.

= What if a product belongs to multiple categories? =

The plugin checks each active rule's category independently. A product in two BOGO-enabled categories participates in both calculations. Each rule's discount is applied separately.

= Can I run different deal types for different categories at the same time? =

Absolutely. Create one rule for Product with B1G1 and another for Bangles with B2G2. Both run independently in the same cart session.

= What happens with 3 items and a B1G1 rule? =

B1G1 has a group size of 2. With 3 items you get 1 complete group (1 free) and 1 leftover item at full price. Only complete groups trigger the deal.

= Does it update the mini-cart sidebar total? =

Yes. Because the plugin uses `set_price(0)` on free items (rather than a fee/coupon approach), WooCommerce naturally recalculates the subtotal correctly everywhere — full cart page, mini-cart widget, and checkout order review.

= Is the discount compatible with WooCommerce coupons? =

Yes. The BOGO discount is applied at the price level. WooCommerce coupons work on top of the already-discounted prices.

= Does it support multisite? =

Yes. Each site on a multisite network has its own independent set of BOGO rules. The `uninstall.php` file cleans up data from all sites on deletion.

= Can I translate the plugin? =

Yes. All strings use `__()` and `esc_html__()` with the text domain `vsw-bogo-offer-on-category`. A `.pot` file is included in the `languages/` folder.

= What data does the plugin store? =

A single WordPress option: `cbogo_rules` (an array of rule definitions). No personal data is stored. Deleting the plugin removes all data via `uninstall.php`.

== Screenshots ==

1. Admin Rules List — all active BOGO rules shown as cards with deal type badge, category, and visual dot preview (purple = paid, green = free).
2. Add New Rule page — step-by-step category picker and deal type selector with live preview showing the exact cart label.
3. Mini-cart sidebar — Hurray! red banner appears instantly after qualifying items are added, showing savings and free items.
4. Full cart page — free item shows ₹0.00 with strikethrough original price, BOGO badge under product name, and correct cart total.

== Changelog ==

= 1.0.0 =
* Initial release.
* 11 deal types: B1G1, B1G2, B1G3, B2G1, B2G2, B2G3, B3G1, B3G2, B3G3, B4G3, B4G4.
* Category-based rules with pause/resume and delete.
* Top-level "BOGO Offers" WordPress admin menu independent of WooCommerce.
* Live preview on Add Rule page.
* set_price(0) discount engine — correct subtotal in mini-cart, cart, and checkout.
* Animated "Hurray!" red banner in cart and mini-cart sidebar.
* Free item badge ("Buy X Get Y Free On [Category]") under product name.
* ₹0.00 with strikethrough original price on free cart items.
* Teaser notice when offer is available but not yet triggered.
* AJAX fragment updates — discount appears without page reload.
* HPOS (High-Performance Order Storage) compatibility.
* Multisite support via uninstall.php.
* Full i18n with .pot file.
* WordPress.org coding standards compliant.

== Upgrade Notice ==

= 1.0.0 =
Initial release — no upgrade steps required.

= 1.0.1 =
Fixed Bugs In Cart