VimirLab Reward Points

VimirLab Reward Points - Configuration Manual

1. Plugin Overview

VimirLab Reward Points is a comprehensive customer loyalty system that enables merchants to:

• Award reward points to customers based on purchase amounts
• Allow customers to redeem points for discounts
• Manage store credits from refunds or promotions
• Combine both points and credits for payment
• Configure flexible payment restrictions
• Handle refunds with customer preferences

2. Installation

1. Go to Extensions → My Extensions in Shopware Admin
2. Find "VimirLab Reward Points" and click Install
3. Click Activate after installation completes
4. Clear cache: Settings → System → Caches & indexes → Clear cache
5. Access configuration: Extensions → My Extensions → VimirLab Reward Points → Configuration

3. Configuration Settings

3.1 Maximum Redeem Point Limit

• Default: 1000 points
• Description: Maximum points redeemable in a single order
• Example: Set to 5000 allows customers to redeem up to 5000 points per order

3.2 Percentage of Points Per Order

• Default: 5%
• Description: Percentage of order value converted to reward points
• Formula: Points Earned = (Order Value × Percentage) ÷ 100
• Example: 5% means $100 order earns 5 points (if 100 points = $1)

3.3 Currency Point Mapping

• Format: CURRENCY_CODE:POINTS_PER_UNIT (one per line)
• Example:
  USD:100 (100 points = $1)
  EUR:150 (150 points = €1)
  GBP:120 (120 points = £1)

3.4 Enable Points Earning

• Default: Enabled
• Description: Allow customers to earn points on purchases

3.5 Enable Credit Earning

• Default: Enabled
• Description: Allow customers to earn product-specific credits

3.6 Maximum Order Credits Per Order

• Default: 100.00
• Description: Maximum credits usable in a single order (0 = unlimited)
• Example: Set to 500 allows max $500 credits per order

3.7 Maximum Order Credits Percentage

• Default: 50%
• Range: 0-100
• Description: Maximum percentage of cart payable with credits
• Example: 50% on $100 order = max $50 with credits

3.8 Minimum Order Value to Use Credits

• Default: 0.00
• Description: Minimum cart total required to use credits (0 = no minimum)

3.9 Allow Full Payment with Credits

• Default: Enabled
• Description: Allow 100% payment with credits/points
• When Disabled: Customers must use payment method for at least some amount

3.10 Minimum Payment Percentage Required

• Default: 0%
• Range: 0-100
• Description: Minimum % that must be paid with regular payment methods
• Priority: Overrides "Allow Full Payment" setting
• Examples:
  • 0% + Full Payment Enabled = 100% payment with credits allowed
  • 10% = Customer must pay at least 10% with payment method
  • 25% = Customer must pay at least 25% with payment method

4. Customer Setup

4.1 Creating Reward Levels (Optional)

1. Go to Catalogues → Reward Levels
2. Click Add Reward Level
3. Enter: Name (e.g., "Silver"), Points Required (e.g., 1000)
4. Enable and Save

4.2 Adding Product Credits

1. Go to Catalogues → Products
2. Select product → Custom fields tab
3. Set Product Credits (Fixed Amount) (e.g., 5.00)
4. Save - customers earn these credits when buying this product

4.3 Manual Point/Credit Adjustment

1. Go to Customers → Overview
2. Select customer → Custom fields tab
3. Edit Reward Points or Order Credits
4. Save

5. How Customers Use the System

5.1 Earning Points

Points are automatically earned when:

• Customer completes an order
• Points calculated on cash portion only (excludes credits/points used)
• Formula: Cash Paid × Percentage ÷ Currency Rate

5.2 Using Reward Points at Checkout

1. Customer sees "Reward Points" section on checkout
2. Views available points and conversion rate
3. Enters points to redeem
4. Clicks Apply - discount applies immediately
5. Can click Remove to undo

5.3 Using Order Credits at Checkout

1. Customer sees "Order Credits" section
2. Views available credits and maximum usable
3. Enters credit amount
4. Clicks Apply Credits
5. Can click Remove to undo

5.4 Combining Points and Credits

Example Order: $1,170.85

• Apply 5000 points ($50 discount) → Remaining: $1,120.85
• Apply $1,120.85 credits → Remaining: $0.00 (if full payment allowed)
• Order completes without payment method

5.5 Customer Refund Preferences

1. Customer goes to Account → Payment methods
2. Selects refund preference:
   • Original Payment Method: Refund to card/payment
   • Store Credits: Refund as store credits
3. Saves preference

6. Refund Management

6.1 Processing Refunds

1. Go to Orders → Overview
2. Select order
3. Process refund normally through Shopware
4. Plugin automatically:
   • Restores used reward points to customer
   • Restores used order credits to customer
   • Deducts earned points (based on cash portion)
   • Applies customer's refund preference

6.2 Refund Preference Handling

Original Payment Method:

• Cash portion refunded to payment method
• Used credits restored to customer account
• Used points restored to customer account
• Earned points deducted (cash portion only)

Store Credits:

• Cash portion converted to new store credits
• Used credits restored separately
• Used points restored to customer account
• Earned points deducted (cash portion only)

7. Testing Guide

Test Scenario 1: Basic Point Earning

1. Configure: 5% points, USD:100
2. Create test order: $100
3. Complete order
4. Expected: Customer earns 500 points (5% of $100)
5. Verify in customer custom fields

Test Scenario 2: Point Redemption

1. Give customer 5000 points manually
2. Create cart worth $100
3. Customer applies 5000 points at checkout
4. Expected: $50 discount applied (5000 ÷ 100 = $50)
5. Order total: $50

Test Scenario 3: Combined Payment

1. Give customer 5000 points and $100 credits
2. Create cart worth $150
3. Apply 5000 points ($50 discount) → $100 remaining
4. Apply $100 credits → $0 remaining
5. Expected: Order completes with $0 payment

Test Scenario 4: Minimum Payment Requirement

1. Set Minimum Payment Percentage: 10%
2. Create cart worth $100
3. Try to apply $100 credits
4. Expected: Error - must pay at least $10 with payment method
5. Maximum credits allowed: $90

Test Scenario 5: Refund Handling

1. Customer places $100 order using $50 credits
2. Customer earns ~250 points (5% of $50 cash)
3. Process full refund
4. Expected:
   • $50 credits restored
   • ~250 points deducted
   • $50 refunded to payment method (or store credits based on preference)

8. Troubleshooting

Issue: Points not being earned

• Check: Enable Points Earning is ON
• Check: Percentage is set (e.g., 5)
• Check: Currency mapping exists for order currency
• Verify: Order status is completed/paid

Issue: Credits cannot be used

• Check: Enable Credit Earning is ON
• Check: Cart total meets minimum order value
• Check: Not exceeding maximum credits per order
• Check: Not exceeding percentage limit
• Verify: Customer has available credits

Issue: Cannot pay full amount with credits

• Check: Allow Full Payment with Credits is ENABLED
• Check: Minimum Payment Percentage is 0%
• Check: Customer has sufficient credits/points
• Check: Maximum percentage limit allows it

Issue: Wrong refund amount

• Verify: Order custom fields show correct used credits/points
• Check: Customer refund preference is set correctly
• Review: Order details in admin for transaction history

9. Important Notes

• Points are earned on cash portion only: Portions paid with credits/points don't earn points
• Refunds are intelligent: System tracks what was used and restores accurately
• Currency matters: Ensure currency mappings are configured for all store currencies
• Cache clearing: Clear cache after configuration changes
• Customer levels: Optional feature - works without creating levels
• Product credits: Optional - only set on products you want to offer bonus credits

10. Support & Documentation

For additional support:

• Review order custom fields for detailed transaction data
• Check customer custom fields for current balances
• Verify configuration settings match intended behavior
• Clear Shopware cache after any configuration changes
• Test in staging environment before production use

Quick Reference

Default Configuration for Testing:

• Points Percentage: 5%
• USD Currency: 100 points = $1
• Max Points: 1000 per order
• Max Credits: 100.00 per order
• Max Credits %: 50% of cart
• Min Order Value: 0.00
• Full Payment: Enabled
• Min Payment %: 0%

Configuration for Strict Control:

• Points Percentage: 3%
• Max Points: 500 per order
• Max Credits: 50.00 per order
• Max Credits %: 25% of cart
• Min Order Value: 25.00
• Full Payment: Disabled
• Min Payment %: 20%

Configuration for Maximum Flexibility:

• Points Percentage: 10%
• Max Points: 10000 per order
• Max Credits: 0 (unlimited)
• Max Credits %: 0 (no limit)
• Min Order Value: 0.00
• Full Payment: Enabled
• Min Payment %: 0%