=== TipJoy - Tips for WooCommerce ===
Contributors: ecomtrackify
Tags: tips, tipping, woocommerce, checkout, donation
Requires at least: 5.8
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.0.10
WC requires at least: 5.0
WC tested up to: 9.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The easiest WooCommerce tip plugin. Let customers tip your team at cart and checkout with fixed amounts, percentages, or custom tips.

== Description ==

**TipJoy** is the simplest way to add a tipping option to your WooCommerce store. Customers can leave a tip for your team directly on the cart, checkout, or mini cart — with just one click.

No complex setup. No bloat. Just a clean, lightweight tip widget that works out of the box with any WooCommerce theme and payment gateway.

= Who Is This For? =

TipJoy is built for any WooCommerce store where customers might want to show appreciation:

* **Restaurants & food delivery** — Accept tips on online orders
* **Cafes & coffee shops** — Digital tip jar at checkout
* **Salons & spas** — Let clients tip their stylist or therapist
* **Delivery & courier services** — Tip the driver at checkout
* **Nonprofits & creators** — Collect donations alongside purchases
* **Any service-based business** — Boost team morale and revenue

= Key Features =

* **3 Display Locations** — Cart page, checkout page, and mini cart widget
* **Fixed Tip Amounts** — Preset tip buttons (e.g., $2, $5, $10, $20) that customers can select with one click
* **Percentage Tips** — Calculate tips based on order subtotal (e.g., 5%, 10%, 15%, 20%)
* **Custom Amount** — "Other" button lets customers enter any tip amount with configurable min/max limits
* **"No Tip" Option** — Customers can easily decline — no pressure, no guilt
* **One-Click Auto-Apply** — Tip is added instantly on click, no extra submit button needed
* **Tip Persistence** — Selected tip stays when navigating between cart and checkout
* **Remove Tip** — Customers can remove their tip at any time before payment
* **WooCommerce Blocks Support** — Works with both classic shortcode-based and block-based cart/checkout pages
* **HPOS Compatible** — Full support for WooCommerce High-Performance Order Storage
* **Customizable Messages** — Set your own widget title, description, button labels, and thank-you message
* **Tip Dashboard** — View total revenue, tip count, conversion rate, average tip, and recent transactions
* **View Tracking** — Track how many customers see the tip widget vs. how many actually tip
* **Live Preview** — Preview your tip widget styling directly in admin settings before saving
* **Lightweight** — No jQuery UI, no heavy dependencies. Clean code, fast loading
* **Developer Friendly** — 23+ hooks and filters for customization and extensibility
* **Translation Ready** — Fully translatable with standard WordPress i18n

= How It Works =

1. Install and activate the plugin
2. Go to **TipJoy > Settings** and configure your tip amounts
3. Choose where to show the widget (cart, checkout, mini cart)
4. Customers see tip options and select an amount with one click
5. The tip is added as a fee line item to the WooCommerce order
6. Track your tip revenue in the **TipJoy > Dashboard**

= Pro Features =

Upgrade to [TipJoy Pro](https://ecomtrackify.com/tipjoy-woocommerce) for advanced features:

* **Post-Purchase Tipping** — Collect tips on the order received page and order details page (My Account), even after payment
* **Shortcode [tipjoy]** — Place a standalone tip form anywhere — blog posts, pages, sidebars, or page builders
* **42+ Hook Positions** — Choose exactly where the widget appears with granular WooCommerce hook selection
* **Advanced Styling** — Customize fonts, colors, borders, border radius, and button layout (inline or spaced)
* **Full Statistics** — Date range filtering, performance by location, complete transaction log
* **Remove Branding** — Hide the "Powered by TipJoy" link
* **Priority Support** — Get help directly from the TipJoy team

Learn more at [ecomtrackify.com/tipjoy-woocommerce](https://ecomtrackify.com/tipjoy-woocommerce).

== Installation ==

1. Upload the `tipjoy` folder to the `/wp-content/plugins/` directory, or install directly through the WordPress plugin screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Make sure **WooCommerce** is installed and active.
4. Navigate to **TipJoy > Settings** to configure your tip options.
5. That's it! The tip widget will appear on your cart and checkout pages.

== Frequently Asked Questions ==

= Does this work with WooCommerce Blocks? =

Yes! TipJoy is fully compatible with both classic shortcode-based and block-based cart and checkout pages. It automatically detects block pages and injects the widget via JavaScript.

= Can customers enter a custom tip amount? =

Yes. Enable the "Custom Amount" option in settings. Customers click the "Other" button to enter any amount within the min/max range you configure.

= Can customers remove a tip after adding one? =

Yes. After selecting a tip, customers can click "No Tip" to remove it, or select a different amount. The tip can be changed or removed at any time before payment.

= Where does the tip appear on the order? =

Tips are added as a fee line item on the WooCommerce order, labeled "Tips". It appears in the order totals alongside shipping, taxes, and other fees.

= How is the percentage tip calculated? =

Percentage tips are calculated based on the cart **subtotal** (product total only), excluding shipping, taxes, and other fees.

= Does this work with all payment gateways? =

Yes. Since tips are added as a standard WooCommerce cart fee before payment, they work with any payment gateway — Stripe, PayPal, Square, and all others.

= Can I change the tip amounts? =

Yes. Go to **TipJoy > Settings > Tip Amounts** to configure fixed amounts, percentage amounts, or enable custom amounts with min/max limits.

= Is this HPOS compatible? =

Yes. TipJoy declares full compatibility with WooCommerce High-Performance Order Storage (HPOS).

= Can I show tips on the mini cart? =

Yes. Enable "Mini Cart" in **TipJoy > Settings > Display** to show the tip widget in the mini cart sidebar or dropdown.

= Does this slow down my site? =

No. TipJoy is lightweight with no external API calls, no heavy dependencies, and scripts are only loaded on WooCommerce pages where the widget is active.

= Does this work with my theme? =

Yes. TipJoy uses standard WooCommerce hooks and clean CSS that works with any properly coded theme. It has been tested with popular themes including Flatsome, Astra, Storefront, OceanWP, and Kadence.

= What is TipJoy Pro? =

TipJoy Pro is an optional add-on that extends the free plugin with post-purchase tipping, shortcode support, advanced styling, full statistics, and more display locations. Learn more at [ecomtrackify.com/tipjoy-woocommerce](https://ecomtrackify.com/tipjoy-woocommerce).

== Screenshots ==

1. Tip widget on the cart page with fixed amounts
2. Tip widget on checkout page before order notes
3. Tip widget on order received page (Order completed)
4. TipJoy Dashboard showing tip statistics
5. TipJoy Settings — Display Locations
6. TipJoy Settings — Tip Amounts configuration
7. TipJoy Settings — Message configuration

== Changelog ==

= 1.0.10 =
* Fix: `Uncaught ReferenceError: wp is not defined` on classic shortcode-based themes (Storefront, Flatsome, OceanWP, Astra, etc.) — the block-fallback inject script now guards `typeof wp !== 'undefined'` before accessing `wp.hooks`.
* Fix: developer HTML comments inside the tip widget template leaked as visible text on the checkout page of some classic themes (Storefront) when the order review table was re-rendered via AJAX. Comments removed from `tip-widget.php` — functional output unchanged.
* Fix: also exclude `PENDING_PAYMENT` transactions from the Dashboard "Recent Transactions" list (totals were already fixed in 1.0.9).

= 1.0.9 =
Fixes dashboard totals to exclude unpaid post-purchase tips, hides the widget on empty carts, and prevents double tips when another tipping plugin is active.

* Fix: excluded post-purchase tips with `PENDING_PAYMENT` status from Dashboard totals — only PAID tips count toward revenue.
* Fix: empty cart on Cart / Mini Cart / Checkout pages no longer renders the tip widget.
* Fix: widget no longer stacks on top of an existing tip fee — detects tip-like fees/items from any tipping plugin (TipJoy, WooCommerce Tipping, YITH Tips, gratuity-style plugins).
* Fix: tip widget no longer appears on `/checkout/order-pay/{id}/` of a tip order (prevented tip-on-tip stacking).
* Fix: per-request location dedup for cart-context renders — prevents duplicate widget when a third-party plugin fires the same WC hook twice.
* Dev: new filters — `tipjoy_tip_name_patterns`, `tipjoy_context_has_tip`, `tipjoy_empty_cart_skip_locations`.

= 1.0.8 =
* Initial release
* Cart, checkout, and mini cart tipping
* Fixed, percentage, and custom tip amounts
* Auto-apply tip on button click (no extra submit button)
* WooCommerce Blocks compatibility with JS fallback injection
* HPOS compatibility declared
* Basic dashboard with 30-day statistics
* Customizable messages (title, description, labels)
* Preview tip widget in admin settings
* Pro features preview (locked) to showcase upgrade options
* 20 hooks/filters for extensibility

== Upgrade Notice ==

= 1.0.10 =
Critical compatibility fix — resolves a JavaScript error (`wp is not defined`) and visible developer comments on the checkout page of classic themes (Storefront, Flatsome, OceanWP, Astra, etc.). Recommended for all users.

= 1.0.9 =
Fixes dashboard totals to exclude unpaid post-purchase tips, hides the widget on empty carts, and prevents double tips when another tipping plugin is active.

= 1.0.8 =
Initial release of TipJoy — add tipping to your WooCommerce store.
