# Usage Examples

**Plugin Version:** 1.1.20
**Last Updated:** 2025-12-23

## Example 1: T-Shirt Store with Volume Discounts

### Tier Pricing Setup

For a t-shirt that normally costs $20:

| Min Quantity | Price per Unit | Customer Saves |
|--------------|----------------|----------------|
| 1            | $20.00         | -              |
| 10           | $18.00         | $2.00 (10%)    |
| 25           | $16.00         | $4.00 (20%)    |
| 50           | $14.00         | $6.00 (30%)    |

**How to configure:**
1. Edit your t-shirt product
2. Set regular price to $20.00
3. Add tier: Min Qty = 10, Price = $18.00, Label = "Bulk Discount"
4. Add tier: Min Qty = 25, Price = $16.00, Label = "Volume Pricing"
5. Add tier: Min Qty = 50, Price = $14.00, Label = "Wholesale Rate"
6. Save product

**Customer experience:**
- Buys 5 shirts: $20.00 each = $100.00 total
- Buys 15 shirts: $18.00 each = $270.00 total (saves $30)
- Buys 30 shirts: $16.00 each = $480.00 total (saves $120)

## Example 2: Office Supplies with Package Deals

### Package Pricing Setup

For pens that normally cost $2.00 each:

| Package      | Quantity | Fixed Price | Price per Unit |
|--------------|----------|-------------|----------------|
| Single       | 1        | $2.00       | $2.00          |
| Small Pack   | 12       | $20.00      | $1.67          |
| Value Pack   | 24       | $36.00      | $1.50          |
| Bulk Pack    | 50       | $65.00      | $1.30          |

**How to configure:**
1. Edit your pen product
2. Set regular price to $2.00
3. Add package: Qty = 12, Price = $20.00, Label = "Small Pack"
4. Add package: Qty = 24, Price = $36.00, Label = "Value Pack"
5. Add package: Qty = 50, Price = $65.00, Label = "Bulk Pack"
6. Save product

**Customer experience:**
- Customer sees package cards on product page
- Clicks "Select Package" for "Value Pack"
- Quantity automatically set to 24
- Price shows $36.00 (not $48.00)

## Example 3: Combined Tier and Package Pricing

### Coffee Beans Store

For premium coffee beans at $15.00 per bag:

**Tier Pricing:**
- 1-4 bags: $15.00 each
- 5-9 bags: $14.00 each
- 10+ bags: $13.00 each

**Package Deals:**
- Monthly subscription: 4 bags for $50.00 ($12.50 each)
- Quarterly bundle: 12 bags for $140.00 ($11.67 each)

**How to configure:**
1. Set regular price: $15.00
2. Add tier: Min Qty = 5, Price = $14.00
3. Add tier: Min Qty = 10, Price = $13.00
4. Add package: Qty = 4, Price = $50.00, Label = "Monthly Box"
5. Add package: Qty = 12, Price = $140.00, Label = "Quarterly Bundle"

**Customer scenarios:**
- Buys 3 bags: $15.00 each = $45.00
- Buys 4 bags: Gets prompted for Monthly Box at $50.00
- Buys 6 bags: $14.00 each = $84.00 (tier pricing)
- Buys 12 bags: Gets Quarterly Bundle at $140.00 (package beats tier)

## Example 4: Promotional Packages

### Seasonal Gift Sets

Regular mug price: $10.00

**Package Deals:**
- Pair Pack: 2 mugs for $18.00 (10% off)
- Family Set: 4 mugs for $32.00 (20% off)
- Office Bundle: 10 mugs for $70.00 (30% off)

**Configuration:**
- Package 1: Qty = 2, Price = $18.00, Label = "Perfect Pair"
- Package 2: Qty = 4, Price = $32.00, Label = "Family Set"
- Package 3: Qty = 10, Price = $70.00, Label = "Office Bundle"

## Example 5: Quantity Restrictions (New in v1.1.0)

### Party Supplies with Fixed Packages

For products that should ONLY be sold in specific package quantities:

**Product:** Balloons - Regular price $1.00 each

**Package Configuration:**
- Package 1: Qty = 12, Price = $10.00, Label = "Dozen Pack"
- Package 2: Qty = 24, Price = $18.00, Label = "Party Pack"
- Package 3: Qty = 50, Price = $40.00, Label = "Event Pack"

**How to configure:**
1. Edit balloon product
2. Set regular price to $1.00
3. Add packages as shown above
4. **Check "Restrict to package quantities only"** (per-product setting)
5. Save product

**Customer experience:**
- Quantity input field is hidden on product page
- Customer MUST select a package using the package selection buttons
- Attempting to add custom quantities via URL or API will fail with validation error
- Cart displays selected package quantity (cannot be edited)
- "View Options" button appears on shop/category pages instead of "Add to Cart"

**When to use quantity restrictions:**
- Pre-packaged items (dozen eggs, 6-pack drinks, etc.)
- Products with fixed manufacturing quantities
- Promotional bundles where you don't want individual sales
- Subscription boxes with specific item counts

## Example 6: Tier Labels for Enhanced UX (New in v1.1.7)

### Office Supplies with Clickable Tiers

**Product:** Premium Notebooks - Regular price $8.00 each

**Tier Configuration with Labels:**
- Tier 1: Min Qty = 5, Price = $7.50, Label = "Small Business Discount"
- Tier 2: Min Qty = 10, Price = $7.00, Label = "Wholesale Pricing"
- Tier 3: Min Qty = 25, Price = $6.50, Label = "Corporate Rate"

**Customer experience:**
- Tier labels appear below quantity in pricing table (italicized)
- Clicking a tier row auto-fills the quantity field with that tier's minimum quantity
- Smooth scroll animation highlights the quantity field
- Add to Cart button automatically disables when quantity is 0 or invalid

**Benefits of tier labels:**
- Helps customers understand pricing context
- Makes tiers more appealing with descriptive names
- Improves conversion by highlighting value propositions
- Clickable rows improve user experience

## Tips for Best Results

### Tier Pricing Best Practices

1. **Progressive Discounts**: Make higher quantities more attractive
   - Good: 10 items = 10% off, 25 items = 20% off, 50 items = 30% off
   - Bad: 10 items = 20% off, 25 items = 15% off

2. **Clear Break Points**: Use round numbers for quantities
   - Good: 10, 25, 50, 100
   - Avoid: 7, 23, 47, 93

3. **Meaningful Savings**: Ensure discounts are worth the extra purchase
   - Minimum 5-10% per tier level
   - Higher tiers should have progressively better deals

4. **Use Labels** (v1.1.7+): Add descriptive labels to tiers
   - "Wholesale Price" instead of just showing the number
   - "Bulk Discount", "Volume Pricing", "Corporate Rate"
   - Makes pricing more professional and appealing

### Package Pricing Best Practices

1. **Strategic Quantities**: Match common use cases
   - 12-pack (dozen)
   - 24-pack (two dozen)
   - 6-pack (half dozen)

2. **Compelling Labels**: Make packages attractive
   - "Starter Pack" instead of "10-piece"
   - "Family Bundle" instead of "4-pack"
   - "Business Value Pack" instead of "50-piece"

3. **Sweet Spot Pricing**: Price just below psychological barriers
   - $99.99 instead of $100.00
   - $49.95 instead of $50.00

### Combining Both Strategies

1. Use **packages** for common quantities (6, 12, 24)
2. Use **tiers** for flexible volume discounts (10+, 25+, 50+)
3. Packages take priority when exact match exists
4. Tiers fill the gaps between packages

## Display Position Recommendations

- **Before Add to Cart**: Best for products where pricing is the main decision factor
- **After Add to Cart**: Good for impulse purchases and upsells
- **After Price**: Ideal for clean product pages, keeps info near the price

## Testing Your Setup

1. Add a product to your store
2. Configure tier/package pricing
3. View the product page in an incognito window
4. Test different quantities
5. Verify prices update correctly
6. Add to cart and check cart totals
7. Complete a test checkout

## Common Scenarios

### Wholesale Store
- Tier 1: 10+ items = wholesale price tier 1
- Tier 2: 50+ items = wholesale price tier 2
- Tier 3: 100+ items = wholesale price tier 3

### Subscription Box
- Package 1: 1 month (4 items) = $40
- Package 2: 3 months (12 items) = $108 (10% off)
- Package 3: 6 months (24 items) = $192 (20% off)

### Event Supplies
- Package 1: Small party (10 pieces) = $50
- Package 2: Medium party (25 pieces) = $110
- Package 3: Large party (50 pieces) = $200
- Package 4: Event package (100 pieces) = $350

## WooCommerce Blocks Compatibility (v1.1.4+, Fixed in v1.1.20)

This plugin is **fully compatible** with WooCommerce block-based cart and checkout:

### Supported Block Types
- Cart Block (`woocommerce/cart`)
- Mini Cart Block (`woocommerce/mini-cart`)
- Checkout Block (`woocommerce/checkout`)
- All Store API endpoints

### Block-Specific Features
- Quantity restrictions work in block-based carts
- Package-restricted products hide quantity selectors in blocks
- Tier and package pricing applies correctly in block checkout
- Mini cart displays correct prices and restrictions

### Technical Notes
- v1.1.20 fixed critical fatal error in WooCommerce Blocks
- Uses `woocommerce_store_api_product_quantity_editable` filter
- Works with both classic and block-based themes
- No configuration needed - blocks work automatically

### Testing Your Block Setup
1. Add block-based cart to a page (`/cart`)
2. Add mini-cart block to your header
3. Add block-based checkout to a page (`/checkout`)
4. Test tier pricing, package pricing, and quantity restrictions
5. Verify prices calculate correctly at checkout