wc-tier-and-package-prices/README.md

# WooCommerce Tier and Package Prices

__THIS PROJECT IS 100% VIBE-CODED USING CLAUDE.AI__

A powerful WooCommerce plugin that adds tier pricing and package pricing functionality to your products with configurable quantities at fixed prices.

## Features

### Tier Pricing (Volume Discounts)
- Set quantity-based pricing tiers
- Automatic discounts when customers buy in larger quantities
- Display savings percentage and amount
- Dynamically updates price based on quantity selected

### Package Pricing
- Create fixed-price packages with specific quantities
- Example: 10 pieces for $50, 25 pieces for $100
- Custom labels for packages (e.g., "Starter Pack", "Value Bundle")
- One-click package selection on product pages

### Admin Features
- Easy-to-use product meta boxes for adding tiers and packages
- Global settings page under WooCommerce menu with sub-tabs
- Configure display position (before/after add to cart, after price)
- Enable/disable tier or package pricing independently
- Sortable pricing rules
- License management with secure HMAC signature verification

### Frontend Features
- Beautiful pricing tables on product pages
- Responsive design for mobile devices
- Visual highlighting of active tier/package
- Real-time price updates when quantity changes
- Cart integration with proper price calculations
- Clear pricing indicators in cart

## Installation

1. Upload the `wc-tier-and-package-prices` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Make sure WooCommerce is installed and activated

### Automated Releases

This project uses a Gitea CI/CD pipeline for automated releases. When a version tag (e.g., `v1.4.0`) is pushed:

1. Code is checked out with git submodules (dependencies bundled)
2. The pipeline validates the plugin version matches the tag
3. Composer dependencies are installed (production only)
4. Translation files are compiled (.po → .mo)
5. A release package is created with proper exclusions
6. SHA256 checksum is generated
7. Release is published to Gitea with changelog notes extracted from CHANGELOG.md

The `magdev/wc-licensed-product-client` library is bundled as a git submodule to avoid private repository authentication during CI/CD.

## Configuration

### Global Settings

Navigate to **WooCommerce > Tier & Package Prices** to configure:

- **Enable Tier Pricing**: Turn on/off volume discounts
- **Enable Package Pricing**: Turn on/off fixed-price packages
- **Display Pricing Table**: Show/hide pricing tables on product pages
- **Display Position**: Choose where to show pricing tables

### Product Settings

When editing a product, scroll to the **Product data** panel:

1. Click on the **General** tab
2. Scroll down to find **Tier Pricing** and **Package Pricing** sections

#### Adding Tier Pricing

1. Click "Add Tier" button
2. Set minimum quantity (e.g., 10)
3. Set price per unit (e.g., 9.99)
4. Add more tiers as needed
5. Tiers are automatically sorted by quantity

**Example:**
- 1-9 items: $12.00 each (regular price)
- 10-24 items: $10.00 each (tier 1)
- 25-49 items: $8.50 each (tier 2)
- 50+ items: $7.00 each (tier 3)

#### Adding Package Pricing

1. Click "Add Package" button
2. Set exact quantity (e.g., 10)
3. Set fixed price for that quantity (e.g., 99.99)
4. Optionally add a custom label (e.g., "Starter Pack")
5. Add more packages as needed

**Example:**
- Package 1: 10 pieces for $95 (labeled "Small Bundle")
- Package 2: 25 pieces for $200 (labeled "Value Pack")
- Package 3: 50 pieces for $350 (labeled "Business Pack")

## How It Works

### Price Calculation Priority

1. **Package Price** (highest priority): If the exact quantity matches a package, the package price applies
2. **Tier Price**: If no package match, the highest applicable tier price is used
3. **Regular Price**: If no tier or package applies, the regular product price is used

### Frontend Display

- Pricing tables show all available tiers and packages
- Current tier/package is highlighted based on selected quantity
- Prices update dynamically when quantity changes
- Package buttons allow one-click quantity selection

### Cart Behavior

- Correct prices are applied in the cart
- Cart shows whether tier or package pricing is applied
- Subtotals are calculated correctly
- Compatible with WooCommerce checkout process

## File Structure

```
wc-tier-and-package-prices/
├── wc-tier-and-package-prices.php    # Main plugin file (v1.4.0)
├── .gitea/workflows/
│   └── release.yml                   # CI/CD release pipeline
├── includes/
│   ├── class-wc-tpp-admin.php        # Admin settings integration
│   ├── class-wc-tpp-settings.php     # WooCommerce settings page
│   ├── class-wc-tpp-product-meta.php # Product meta boxes
│   ├── class-wc-tpp-frontend.php     # Frontend display logic
│   ├── class-wc-tpp-cart.php         # Cart price calculations
│   └── class-wc-tpp-template-loader.php # Twig template engine
├── templates/
│   ├── admin/
│   │   ├── tier-row.twig            # Tier pricing input row
│   │   └── package-row.twig         # Package pricing input row
│   └── frontend/
│       ├── pricing-table.twig        # Main pricing display wrapper
│       ├── tier-pricing-table.twig   # Tier pricing table
│       └── package-pricing-display.twig # Package selection UI
├── assets/
│   ├── css/
│   │   ├── admin.css                 # Admin styles
│   │   └── frontend.css              # Frontend styles
│   └── js/
│       ├── admin.js                  # Admin JavaScript
│       └── frontend.js               # Frontend JavaScript
├── languages/
│   ├── wc-tier-package-prices.pot    # Translation template
│   ├── wc-tier-package-prices-*.po   # Translation sources
│   └── wc-tier-package-prices-*.mo   # Compiled translations
├── lib/                               # Bundled libraries (git submodules)
│   └── wc-licensed-product-client/    # License client library
├── vendor/                            # Composer dependencies (generated)
├── CHANGELOG.md                       # Complete version history
├── INSTALLATION.md                    # Installation guide
├── QUICKSTART.md                      # Quick start guide
├── USAGE_EXAMPLES.md                  # Usage examples
└── README.md                          # This file
```

## Requirements

- WordPress 6.0 or higher (tested up to 6.9.x)
- WooCommerce 8.0 or higher (tested up to 10.x)
- PHP 8.3 or higher (required since v1.3.0)

### Compatibility

- ✅ **WooCommerce 10.x**: Fully compatible with the latest WooCommerce release
- ✅ **WordPress 6.9.x**: Tested and verified with WordPress 6.9.x
- ✅ **HPOS (High-Performance Order Storage)**: Full support for WooCommerce Custom Order Tables
- ✅ **Block-based Themes**: Compatible with modern WordPress block themes
- ✅ **Multisite**: Works on WordPress multisite installations

## Frequently Asked Questions

**Q: Can I use both tier pricing and package pricing on the same product?**
A: Yes! Package pricing takes priority when the exact quantity matches.

**Q: What happens if a customer changes the quantity in the cart?**
A: The price will automatically recalculate based on the new quantity.

**Q: Can I set different tiers for different products?**
A: Yes, each product can have its own tier and package pricing configuration.

**Q: Does this work with variable products?**
A: Yes! Since version 1.2.0, the plugin fully supports variable products. Each variation can have its own independent tier and package pricing configuration.

## Support

For bug reports and feature requests, please use the plugin's support forum or contact the developer.

## License

This plugin is licensed under the GPL v2 or later.

## Changelog

### Version 1.4.0 - 2026-01-29

__Current Release__ - CI/CD Release Pipeline

- __New__: Gitea CI/CD release pipeline for automated builds and releases
- __New__: Git submodule for `magdev/wc-licensed-product-client` library
- __Changed__: Composer now uses path repository for bundled license client
- __DevOps__: Automated version validation, translation compilation, and release publishing

See [CHANGELOG.md](CHANGELOG.md) for complete details.

### Version 1.3.1 - 2026-01-27

Secure License Client

- __Changed__: Switched to `SecureLicenseClient` with HMAC-SHA256 response signature verification
- __New__: Server Secret configuration field for secure communication with license server
- __Security__: Response signatures verified using HMAC-SHA256 with license-specific derived keys

### Version 1.3.0 - 2026-01-25

__Breaking Changes__ - PHP 8.3+ Required

- __Breaking__: Minimum PHP version increased from 7.4 to 8.3
- __New__: License management via `magdev/wc-licensed-product-client` library
- __New__: Settings page split into "General" and "License" sub-tabs
- __New__: AJAX-based license validation and activation with visual feedback
- __New__: License status caching with daily auto-refresh
- __New__: PHP version check with admin notice for incompatible servers

### Version 1.2.0 - 2025-12-29

Variable Product Support

- __New__: Full support for WooCommerce variable products with variation-level pricing
- __New__: Each variation can have independent tier and package pricing configuration
- __New__: AJAX-powered dynamic pricing table display when variations are selected
- __Changed__: Admin templates converted to table structure for better layout
- __Fixed__: Quantity restrictions now work correctly per-variation
- 100% backward compatible - no breaking changes

### Recent Major Updates

#### Version 1.1.7 - Enhanced Tier Pricing
- Added optional text labels for tier pricing
- Clickable tier rows that auto-populate quantity field
- Add to Cart button auto-disable when quantity is invalid

#### Version 1.1.4 - WooCommerce Blocks Support
- Full support for WooCommerce block-based cart and checkout
- Quantity restrictions work with both classic and block carts
- Enhanced "View Options" button styling

#### Version 1.1.0 - Package Quantity Restrictions
- Global and per-product package quantity restrictions
- Prevents customers from ordering non-package quantities
- Automatic quantity field hiding when restrictions enabled

#### Version 1.0.1 - Twig Template Engine
- Migrated to Twig templating system
- Enhanced security with automatic HTML escaping
- Added German (Switzerland, Informal) translation

#### Version 1.0.0 - Initial Release
- Tier pricing functionality (quantity-based discounts)
- Package pricing functionality (fixed-price bundles)
- WooCommerce HPOS compatibility
- Multilingual support (English, German)

For complete version history, see [CHANGELOG.md](CHANGELOG.md)

## Credits

Developed by Marco Graetsch for WooCommerce store owners who need flexible pricing options.