> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocky.global/llms.txt
> Use this file to discover all available pages before exploring further.

# ORGANIZER FEES DOCUMENTATION

# Organizer Fees Documentation

## Overview

The Organizer Fees system allows event organizers to configure different types of management fees that can be applied to their events. These fees can be configured to be paid either by the participant or absorbed by the organizer.

## Fee Types

The system supports three types of organizer fees:

### 1. Fixed Amount Fee (`TYPE_MONTHLY`)

* **Description**: A fixed amount charged per registration
* **Configuration**: Set a fixed price in the organizer's tariff configuration
* **Payment**: Can be paid by either participants or organizer
* **Use Case**: Fixed service fees per registration

### 2. Percentage Fee (`TYPE_PERCENTAGE`)

* **Description**: A percentage of the event subtotal
* **Configuration**: Set a percentage value (e.g., 5% of event cost)
* **Payment**: Can be paid by either participants or organizer
* **Use Case**: Commission-based fees

### 3. Combined Fee (`TYPE_COMBINED`)

* **Description**: Fixed amount + percentage of subtotal
* **Configuration**: Set both a fixed amount and percentage
* **Payment**: Can be paid by either participants or organizer
* **Use Case**: Complex fee structures

## Configuration Flow

### 1. Organizer Tariff Setup

Organizers configure their tariff types in the admin panel:

* Navigate to organizer management
* Set tariff type (Monthly/Percentage/Combined)
* Configure amounts and percentages
* Activate the tariff

### 2. Event Configuration

For each event, organizers can configure:

* **Who pays**: Participant or Organizer
* **Flexibility**: All fee types can be paid by either participants or organizer

### 3. Checkout Integration

The fees are automatically calculated and applied during checkout:

* Fees are calculated based on event subtotal
* Added to subtotal before tax calculation
* Displayed as "Tarifa de servicio" in checkout summary

## Database Schema

### Orders Table

```sql theme={null}
-- New columns added for organizer fees
organizer_fees DECIMAL(10,2) DEFAULT 0.00
organizer_fees_details JSON NULL
```

### Organizer Fees Details Structure

```json theme={null}
{
    "tariff_id": 1,
    "tariff_name": "Premium Plan",
    "tariff_type": "percentage",
    "percentage": 5.0,
    "calculated_amount": 12.50
}
```

## Implementation Details

### Controller Logic

The `CheckoutController` includes a `calculateOrganizerFees()` method that:

1. Checks if participant pays fees (`participant_pays_fees`)
2. Retrieves organizer tariff configuration
3. Calculates fees based on tariff type
4. Returns fee amount and details

### Fee Calculation Logic

```php theme={null}
// Fixed Monthly
$feeAmount = floatval($organizerTariff->total_price ?? 0);

// Percentage
$percentage = floatval($organizerTariff->percentage ?? 0);
$feeAmount = round(($subtotal * $percentage / 100), 2);

// Combined
$fixedAmount = floatval($organizerTariff->total_price ?? 0);
$percentage = floatval($organizerTariff->percentage ?? 0);
$percentageAmount = round(($subtotal * $percentage / 100), 2);
$feeAmount = $fixedAmount + $percentageAmount;
```

### Tax Calculation

**Important**: Fees are added to the subtotal before tax calculation:

```
1. Calculate event subtotal
2. Apply discounts
3. Calculate organizer fees on discounted subtotal
4. Add fees to subtotal → subtotalWithFees
5. Calculate tax on subtotalWithFees
6. Total = subtotalWithFees + tax
```

## Frontend Integration

### Checkout Display

The checkout page shows organizer fees in the summary:

```blade theme={null}
@if (session('organizer_fees', 0) > 0)
    <div class="col-md-6 text-left organizer-fees-block">
        Tarifa de servicio
    </div>
    <div class="col-md-6 text-right organizer-fees-block" id="organizerFees">
        {{ number_format(session('organizer_fees', 0), 2) }}{{ $currency }}
    </div>
@endif
```

### JavaScript Updates

Dynamic updates when:

* Discounts are applied/removed
* Products are added/removed from cart
* Cart totals are recalculated

## Validation Rules

### Frontend Validation

* All fee types can be paid by either participants or organizer
* No restrictions based on fee type

### Backend Validation

```php theme={null}
// In ManagementFeesController
// No restrictions - all fee types can be paid by either party
```

## Configuration Interface

### Management Fees Page

* Shows current organizer tariff configuration
* Displays tariff type, amounts, and percentages
* Allows selection of payment responsibility
* Flexible payment options for all fee types

### Admin Interface

* Organizer tariff management
* Fee type configuration
* Activation/deactivation controls

## Testing

### Unit Tests

The system includes comprehensive unit tests in `tests/Unit/OrganizerFeesTest.php`:

* Tests all fee types (fixed, percentage, combined)
* Tests discount combinations
* Tests edge cases (inactive tariffs, no fees)
* Tests payment responsibility logic

### Test Scenarios

1. **No fees configured**: Verify no fees are charged
2. **Fixed amount fee**: Verify either party can pay
3. **Percentage fee**: Verify calculation and payment options
4. **Combined fee**: Verify complex calculations
5. **With discounts**: Verify fees calculated on discounted amounts
6. **Inactive tariff**: Verify no fees when tariff is disabled

## API Integration

### Checkout Endpoints

All checkout endpoints return organizer fees in responses:

```json theme={null}
{
    "subtotal": "100.00",
    "organizer_fees": "5.00",
    "tax": "19.95",
    "total": "124.95",
    "organizer_fees_details": {
        "tariff_type": "percentage",
        "percentage": 5.0
    }
}
```

### Session Storage

Organizer fees are stored in session for consistency:

```php theme={null}
session([
    'organizer_fees' => $organizerFees,
    'organizer_fees_details' => $organizerFeesData['fee_details']
]);
```

## Migration Guide

### Database Migration

```bash theme={null}
php artisan migrate
```

This adds the required columns to the orders table.

### Configuration Steps

1. Set up organizer tariffs in admin panel
2. Configure events to use organizer fees
3. Set payment responsibility (participant/organizer)
4. Test checkout flow

## Troubleshooting

### Common Issues

1. **Fees not appearing in checkout**
   * Check if `participant_pays_fees` is enabled
   * Verify organizer tariff is active
   * Check tariff configuration

2. **Incorrect tax calculation**
   * Ensure fees are added before tax calculation
   * Verify `subtotalWithFees` logic

3. **Fixed fees showing as participant option**
   * Check tariff type validation
   * Verify frontend/backend validation alignment

### Debug Information

Enable logging to track fee calculations:

```php theme={null}
\Log::debug('Organizer fees calculation', [
    'event_id' => $event->id,
    'subtotal' => $subtotal,
    'fee_amount' => $feeAmount,
    'fee_details' => $feeDetails
]);
```

## Future Enhancements

* Multiple fee structures per organizer
* Fee tiers based on event size
* Promotional fee waivers
* Fee analytics and reporting
* Automated fee collection