# Lohnabrechnung Documentation

**Last Updated:** 2026-01-09

**Note:** This documentation has been enhanced with workflows from comprehensive helpdesk analysis. See `docs/content/helpdesk/MASTER_ANALYSIS_SUMMARY.md` for details.

## Basic Information

- **Feature Name:** Lohnabrechnung (Payroll)
- **Slug:** lohnabrechnung
- **Status:** Available
- **Related Product Pages:**
  - `v2/pages/product_payroll.php` (Standard)
  - `v2/pages/product_payroll_neu.php` (Payroll Plus)
  - `v2/pages/product_payroll_alt.php` (Alternative)
  - Product page: https://www.ordio.com/payroll
  - Payroll Plus: https://www.ordio.com/payroll (Payroll Plus features)

**Note:** This documentation consolidates content from all three payroll product page variants. Payroll Plus represents the latest evolution with fully integrated net payroll calculation.

## Overview

Ordio Payroll automatisiert deine Lohnabrechnung sicher und effizient. Spare Zeit, minimiere Fehlerquellen und behalte jederzeit den Überblick im Team. Mit Ordio Payroll Plus erledigst du die komplette Nettolohnabrechnung direkt in Ordio – nahtlos integriert, automatisiert und ohne externe Lohnbüros. In nur 60 Sekunden vom Schichtplan zur fertigen Lohnabrechnung.

## Use Cases

### Small Business Payroll Automation

**Scenario:** A small restaurant with 15 employees needs to automate payroll processing, currently spending 10+ hours per week on manual calculations and external payroll services.

**Process:**

1. Manager accesses Payroll section in Ordio
2. System automatically pulls time tracking data from shifts
3. Reviews calculated gross wages for all employees
4. Clicks "Run Payroll" button
5. System calculates net wages, taxes, and social contributions automatically
6. Reviews digital payslips
7. Approves and releases payroll
8. Employees receive payslips via app/email
9. DATEV export generated automatically for accounting

**Benefits:** Saves 10 hours per week, reduces errors by 95%, eliminates external payroll service costs, ensures legal compliance, provides real-time visibility.

### Payroll Plus: 60-Second Net Payroll

**Scenario:** A restaurant chain wants fully integrated payroll without external payroll offices, processing net payroll directly in Ordio.

**Process:**

1. All relevant data automatically collected (working hours, allowances, absences)
2. Manager reviews gross wages at month-end
3. Clicks "Run Payroll" - system calculates net wages in 60 seconds
4. Reviews digital payslips with full transparency
5. Approves and releases
6. No manual data transfer to external systems needed
7. All calculations compliant with current German law

**Benefits:** Complete independence from external payroll offices, 60-second processing time, full transparency, automatic legal compliance, cost savings.

### Multi-Location Payroll Management

**Scenario:** A retail chain with 10 locations needs centralized payroll management with location-specific settings and unified reporting.

**Process:**

1. Central HR manager accesses payroll dashboard for all locations
2. Each location processes payroll independently with location-specific rules
3. Central manager has oversight of all payroll activities
4. Unified reporting across all locations
5. Consolidated DATEV export for accounting
6. Location-specific cost analysis and budgeting

**Benefits:** Centralized oversight with local flexibility, consistent payroll policies, comprehensive reporting, efficient multi-location management.

### Complex Payroll Scenarios

**Scenario:** A healthcare facility needs to handle overtime, night shift allowances, bonuses, deductions, and various employment types (full-time, part-time, temporary).

**Process:**

1. System automatically calculates overtime from time tracking
2. Applies night shift, weekend, and holiday allowances based on rules
3. Processes bonuses and special payments
4. Handles deductions (taxes, social insurance, voluntary contributions)
5. Calculates different rates for different employment types
6. Generates compliant payslips for all scenarios
7. Exports data for accounting and compliance

**Benefits:** Handles complex scenarios automatically, ensures accuracy, maintains legal compliance, reduces manual calculation errors.

### Restaurant Payroll with Tips and Allowances

**Scenario:** A restaurant needs to process payroll including tips, service charges, and various shift allowances while maintaining compliance.

**Process:**

1. Time tracking data automatically imported
2. Tips and service charges entered manually or imported from POS
3. System applies shift allowances (night, weekend, holiday)
4. Calculates tax-free and taxable allowances separately
5. Processes all deductions
6. Generates compliant payslips
7. Exports to DATEV for accounting

**Benefits:** Handles complex restaurant payroll scenarios, ensures tip reporting compliance, automates allowance calculations, maintains accuracy.

## Target Audience

### Primary Users

**HR Managers:**

- Daily responsibility for payroll processing
- Need automated calculation and compliance assurance
- Require integration with time tracking and shift planning
- Benefit from reduced manual work and error reduction

**Payroll Administrators:**

- Process payroll for multiple employees
- Need comprehensive feature set for complex scenarios
- Require DATEV integration and export capabilities
- Benefit from real-time processing and error reduction

**Accountants/Steuerberater:**

- Review and approve payroll calculations
- Need DATEV-compatible exports
- Require compliance documentation
- Benefit from automated calculations and transparent reporting

**Business Owners:**

- Need cost control and efficiency
- Require compliance assurance
- Want independence from external services (Payroll Plus)
- Benefit from time savings and cost reduction

### Secondary Users

**Finance Teams:**

- Need payroll data for budgeting and forecasting
- Require cost analysis and reporting
- Benefit from integrated financial data

**Operations Managers:**

- Coordinate payroll across locations
- Need visibility into labor costs
- Benefit from integrated shift planning and payroll

### Industries

**Restaurants & Hospitality:**

- Complex shift patterns and allowances
- Tips and service charges
- High employee turnover
- Peak season variations
- **Payroll Plus:** Specifically designed for restaurant industry

**Retail:**

- Part-time and full-time mix
- Holiday season variations
- Multi-location management
- Flexible scheduling

**Healthcare:**

- 24/7 operations
- Complex shift allowances
- Compliance-critical
- Various employment types

**Service Businesses:**

- Field service scheduling
- Multi-location coordination
- Flexible work arrangements
- Skill-based pay rates

**All Industries:**

- Any business with employees
- Need for automated payroll
- Compliance requirements
- Integration with time tracking

## Key Functionality

### Core Capabilities

- **Automatische Lohnabrechnung:** Fully automated payroll calculation from time tracking data
- **Direkte DATEV-Integration:** Direct integration with DATEV Lodas and DATEV Lohn und Gehalt
- **Steuer- und Sozialversicherungsberechnung:** Automatic calculation of taxes and social insurance contributions
- **Überstunden- und Zuschlagserfassung:** Automatic overtime and allowance calculation (night, weekend, holiday shifts)
- **Lohnabrechnungs-Export:** Export to DATEV, Addison, CSV/Excel formats
- **Mitarbeiter-Self-Service:** Employees can view payslips, request advances, update tax information
- **Gesetzeskonforme Dokumentation:** Compliant documentation and archiving
- **Fehlerreduktion um 95%:** 95% error reduction through automation

### Payroll Plus Features

**Fully Integrated Net Payroll:**

- Complete net payroll calculation directly in Ordio
- No external payroll offices needed
- 60-second processing time
- Automatic data integration from all Ordio modules

**AI-Powered Automation:**

- Intelligent calculation rules
- Automatic compliance updates
- Smart error detection
- Predictive analytics

**Restaurant-Specific Features:**

- Designed specifically for restaurant industry
- Handles complex shift patterns
- Tip and service charge processing
- Peak season optimization

### Advanced Features

**Comprehensive Feature Set (47+ Features):**

- Personal-Stammdaten (Employee master data)
- Elektronische Arbeitsunfähigkeitsbescheinigung (eAU)
- Flexible Arbeitszeitmodelle (Flexible work models)
- Max- und Min-Stunden (Max and min hours)
- Wochen- und Monatsgrenzen für Stunden (Weekly and monthly hour limits)
- Stundenlöhne, Monatslöhne, Tagelöhne (Hourly, monthly, daily wages)
- Gleitzeit (Flexible working hours)
- Arbeitsbereich-abhängige Stundenlöhne (Department-dependent hourly rates)
- Arbeitszeitkonto (Working time account)
- Überstunden, Minus-Stunden (Overtime, undertime)
- Nachtzuschläge, Sonntagszuschläge, Feiertagszuschläge (Night, Sunday, holiday allowances)
- Individuelle Zuschläge (Custom allowances)
- Steuerfreie und steuerpflichtige Zuschläge (Tax-free and taxable allowances)
- Zulagenkonto (Allowance account)
- Befristete Arbeitsverträge (Fixed-term contracts)
- Probezeit (Probation period)
- Dynamischer Urlaubsanspruch (Dynamic vacation entitlement)
- 13-Wochen-Durchschnitt (13-week average)
- Überstunden abgelten (Overtime compensation)
- Zusatzzahlungen (Additional payments)
- Vorschüsse (Advances)
- Exporte zu DATEV Lodas, DATEV Lohn und Gehalt, Addison, Lohn AG, Lohnconsult, Agenda, CSV/Excel
- Reporting mit Arbeitgeberkosten (Reporting with employer costs)
- Rentenversicherungspflichtbefreiung (Pension insurance exemption)
- Urlaubs- und Abwesenheitsmanagement (Vacation and absence management)
- Digitale Lohnsteuerbescheinigungen (Digital tax certificates)
- Automatisierte Abrechnungszyklen (Automated payroll cycles)
- Datenschutz nach DSGVO (GDPR-compliant data protection)
- Vermögenswirksame Leistungen (Asset-building benefits)
- Geldwerte Vorteile (Benefits in kind)
- Lohnfortzahlung (Continued wage payment)

**Real-Time Processing:**

- Live payroll overview
- Instant updates when data changes
- Real-time calculation preview
- Immediate error detection

**Integration Capabilities:**

- Seamless integration with Schichtplanung (shift planning)
- Automatic data from Zeiterfassung (time tracking)
- Integration with Abwesenheiten (absences)
- Connection to Dokumentenmanagement (document management)

## Technical Implementation

### File Structure

**Frontend Files:**

- **PHP:**
  - `v2/pages/product_payroll.php` (~1275 lines) - Standard payroll page
  - `v2/pages/product_payroll_neu.php` (~1570 lines) - Payroll Plus page
  - `v2/pages/product_payroll_alt.php` (~616 lines) - Alternative version
- **JavaScript:**
  - `/v2/js/lead-capture-triggers.min.js` - Lead capture and form tracking
  - Custom Alpine.js components for interactive features
  - Scroll progress animations
  - Payroll calculation preview
- **CSS:**
  - `/v2/css/product-pages.min.css` - Shared product pages stylesheet
  - Tailwind CSS utility classes
  - Custom animations and transitions

**Dependencies:**

**Backend Systems:**

- Payroll calculation engine
- Tax and social insurance calculation system
- DATEV integration service
- Employee database and management system
- Time tracking system integration
- Shift planning system integration
- Absence management integration
- Document management integration
- Notification system (email, push)
- Reporting and analytics engine

**External Integrations:**

- DATEV Lodas
- DATEV Lohn und Gehalt
- Addison
- Lohn AG
- Lohnconsult
- Agenda
- CSV/Excel export
- Email service for payslip delivery
- Mobile app backend API

**Frontend Libraries:**

- Alpine.js for reactive UI components
- Tailwind CSS for styling
- AOS (Animate On Scroll) for animations
- Custom scroll progress tracking

### API Endpoints

**Payroll Processing:**

- `POST /api/payroll/calculate` - Calculate payroll for period
- `GET /api/payroll/{period}` - Get payroll data for period
- `POST /api/payroll/{period}/approve` - Approve payroll
- `POST /api/payroll/{period}/release` - Release payroll to employees
- `GET /api/payroll/employees/{id}` - Get employee payroll history

**DATEV Integration:**

- `POST /api/payroll/export/datev` - Export to DATEV format
- `GET /api/payroll/export/datev/{period}` - Download DATEV export
- `POST /api/payroll/import/datev` - Import DATEV data

**Employee Self-Service:**

- `GET /api/payroll/payslips` - Get employee payslips
- `GET /api/payroll/payslips/{id}` - Get specific payslip
- `POST /api/payroll/advances/request` - Request advance payment
- `PUT /api/payroll/tax-info` - Update tax information

**Reporting:**

- `GET /api/payroll/reports/summary` - Payroll summary report
- `GET /api/payroll/reports/costs` - Employer cost report
- `GET /api/payroll/reports/export` - Export reports (CSV, Excel, PDF)

**Payroll Plus:**

- `POST /api/payroll-plus/calculate-net` - Calculate net payroll (60-second process)
- `GET /api/payroll-plus/status` - Get Payroll Plus status
- `POST /api/payroll-plus/waitlist` - Join Payroll Plus waitlist

## User Experience

### Detailed User Flow

#### Flow 1: Standard Payroll Processing

1. **Access Payroll:**

   - Manager logs into Ordio
   - Navigates to "Lohnabrechnung" section
   - System displays payroll dashboard with current period

2. **Review Data:**

   - System automatically pulls time tracking data
   - Shows calculated hours, overtime, allowances
   - Displays any missing data or errors
   - Manager reviews and corrects if needed

3. **Calculate Payroll:**

   - Manager clicks "Calculate Payroll"
   - System calculates gross wages, taxes, social insurance
   - Shows preview of all calculations
   - Manager reviews for accuracy

4. **Approve and Release:**

   - Manager approves payroll
   - System generates digital payslips
   - Payslips sent to employees via email/app
   - DATEV export generated automatically

5. **Archive and Report:**
   - Payroll data archived for compliance
   - Reports generated for accounting
   - Data available for future reference

#### Flow 2: Payroll Plus - 60-Second Net Payroll

1. **Automatic Data Collection:**

   - System automatically collects all relevant data:
     - Working hours from time tracking
     - Allowances from shift planning
     - Absences from absence management
     - Employee master data

2. **Review Gross Wages:**

   - Manager reviews calculated gross wages
   - System highlights any anomalies
   - Manager makes adjustments if needed

3. **One-Click Calculation:**

   - Manager clicks "Run Payroll"
   - System calculates net wages in 60 seconds
   - All calculations compliant with current German law
   - Automatic tax and social insurance calculation

4. **Review and Approve:**

   - Manager reviews digital payslips
   - Full transparency on all calculations
   - Approves and releases

5. **Complete Integration:**
   - No manual data transfer needed
   - No external payroll office required
   - All data stays in Ordio
   - Automatic compliance updates

#### Flow 3: Employee Viewing Payslip

1. **Access Payslip:**

   - Employee logs into Ordio app or web
   - Navigates to "Lohnabrechnung" section
   - Views list of payslips

2. **View Details:**

   - Opens specific payslip
   - Views gross pay, deductions, net pay
   - Sees breakdown of all calculations
   - Downloads PDF if needed

3. **Request Advance (if available):**
   - Employee can request advance payment
   - System calculates available advance amount
   - Manager receives notification
   - Advance processed in next payroll

### Detailed Workflows from Helpdesk

The following workflows are based on helpdesk documentation and provide step-by-step guides for common Lohnabrechnung tasks.

#### Workflow: Creating Wage Rules (Lohnregeln)

**Purpose:** Set up wage rules for employees to define how their wages are calculated

**Note:** This workflow covers the new wage system update. If you're unsure if it's active for you, contact support via chat or support@ordio.com.

**Step-by-Step Process:**

1. **Set Employment Relationship (Anstellungsverhältnis):**

   - **Unlimited (Unbefristet):** Standard permanent employment
   - **Fixed-term (Befristet):** Enter start and end date of fixed-term contract
   - **Short-term employment (Kurzfristige Beschäftigung):** For seasonal or temporary workers
   - **Probation period (Probezeit):** Optional - enter probation duration or date
   - These settings ensure legal deadlines and special regulations are correctly applied

2. **Define Compensation (Vergütung):**

   - **Daily wage (Tageslohn):** Fixed amount per day
   - **Hourly wage (Stundenlohn):** Rate per hour worked
   - **Monthly salary (Monatsgehalt):** Fixed monthly amount
   - **Additional compensation components:**
     - Benefits in kind (Geldwerte Vorteile): e.g., company car, vouchers
     - Function allowance (Funktionszulage): Additional pay for specific work areas (for hourly wage employees)

3. **Set Working Time Model (Arbeitszeitmodell):**

   **Option A: Flexible Working Days (Flexible Arbeitstage):**

   - Set minimum and maximum weekly hours (e.g., 35-40 hours/week)
   - Ideal for flextime or variable assignments
   - **Note:** Holiday compensation considerations apply

   **Option B: Fixed Working Days (Feste Arbeitstage):**

   - Work on fixed days (e.g., Monday to Friday)
   - Enter daily hours (e.g., 8 hours per day)
   - **Optional settings:**
     - ✅ **Automatic holiday compensation:** Holidays automatically counted as worked time
     - ✅ **Activate working time account:** Tracks plus/minus hours for transparent reporting
     - ✅ **Activate flextime (Gleitzeit):**
       - Absences can be compensated with specific daily rate despite flexible working times
       - Holidays can be automatically compensated (unlike pure flexible working days)

4. **Set Vacation Entitlement (Urlaubsanspruch):**

   - Determine annual vacation entitlement (e.g., 30 days)
   - Optionally set different start date (e.g., for mid-year entry)
   - **Dynamic vacation calculation:** Useful for temporary workers, but NOT suitable for permanent employees

5. **Define Allowances (Zuschläge):**

   - **Holiday allowance (Feiertagszuschlag):** Set percentage or amount
   - **Sunday allowance (Sonntagszuschlag):** Set percentage or amount
   - **Night allowance (Nachtzuschlag):** Set percentage or amount
   - **Custom allowances (Individuelle Zuschläge):**
     - Create individual allowances
     - Name them
     - Set percentage (e.g., +25% for Sunday work)

6. **Save & Use Templates:**

   - Review all settings
   - Option to save wage rule as template
   - Perfect for future use with employees with similar model
   - Save wage rule
   - System applies rule to payroll calculations

**Important Notes:**

- Wage rules can usually be adjusted/changed if errors occurred during creation
- Changes can be made retroactively, for ongoing wage rules, and for future periods
- Only delete wage rules in rare cases (see deletion workflow)

#### Workflow: Deleting Wage Rules (Lohnregeln löschen)

**Purpose:** Permanently delete a wage rule that is no longer needed

**When to Delete:**

Only delete a wage rule in rare cases, and only if:

- You no longer need the wage information from the outdated wage rule
- The employee has not yet recorded relevant working hours in the period covered by the wage rule

**Important Warning:**

- If you delete the wage rule and create a new one, already recorded working hours will be evaluated according to the NEW wage rule
- This can affect historical payroll calculations
- Consider editing the existing wage rule instead of deleting it

**Process:**

1. **Access Wage Rule:**

   - Go to employee's wage rule
   - Click "Lohnregel ändern" (Change Wage Rule)

2. **Enable Editing:**

   - Confirm the switch/toggle to enable editing mode
   - Wage rule becomes editable

3. **Delete Wage Rule:**
   - Scroll down to "Lohnregel löschen" section (red field)
   - Click delete option
   - Confirm deletion
   - Wage rule is permanently removed

**Alternative: Edit Instead of Delete**

- Most errors can be fixed by editing the wage rule
- Changes can be made:
  - Retroactively (for past periods)
  - For ongoing wage rules
  - For future periods
- Editing preserves historical data and calculations

#### Workflow: Configuring Allowances in Wage Rules

**Purpose:** Set up allowances (Zuschläge) for night work, Sundays, holidays, etc.

**Steps:**

1. **Access Wage Rule:**

   - Open employee's wage rule
   - Navigate to "Zuschläge" or "Allowances" section

2. **Configure Standard Allowances:**

   - **Night allowances:**
     - Set time range (e.g., 20:00 - 06:00)
     - Set percentage or fixed amount
     - Define which days apply
   - **Sunday allowances:**
     - Set percentage or amount
     - Configure exceptions if needed
   - **Holiday allowances:**
     - Set rates for public holidays
     - Configure regional holidays

3. **Tax-Free vs. Taxable:**

   - Mark each allowance as:
     - **Tax-free (steuerfrei):** Not counted toward taxable income
     - **Taxable (steuerpflichtig):** Counted toward taxable income
   - Important for €556 tax-free limit compliance

4. **Special Rules:**

   - **Allowances only after X hours:**
     - Set minimum working hours (e.g., after 6th hour)
     - Allowance only applies if threshold met
   - **Allowances only for overtime:**
     - Allowance applies only to overtime hours
     - Regular hours excluded
   - **Custom conditions:**
     - Create custom rules per employee
     - Apply to specific work areas or shift types

5. **Save Configuration:**
   - Review settings
   - Save allowances
   - System applies automatically in payroll calculations

#### Workflow: Entering Absences in Payroll

**Purpose:** Record absences (vacation, sick leave) and configure compensation

**Steps:**

1. **Access Absence Entry:**

   - Go to Lohnabrechnung section
   - Navigate to employee's payroll
   - Find "Abwesenheiten" or "Absences" section

2. **Select Absence Type:**

   - Vacation (Urlaub)
   - Sick leave (Krankheit)
   - Other absence types

3. **Enter Absence Details:**

   - Select date range
   - Enter start and end dates
   - System calculates total absence days/hours

4. **Configure Compensation:**

   - Choose compensation method:
     - **Fixed hours:** Set specific hours to pay
     - **Based on shift plan:** Pay according to scheduled shifts
     - **Average wage:** Calculate based on average earnings
   - System shows preview of compensation amount

5. **Combine with Allowances:**

   - If enabled, allowances calculated proportionally
   - System applies legal requirements automatically
   - Preview shows total compensation including allowances

6. **Save Absence:**
   - Review compensation calculation
   - Save absence entry
   - System includes in next payroll run

#### Workflow: Entering Advance Payment (Lohnvorschuss)

**Purpose:** Record advance payments to employees

**Steps:**

1. **Access Advance Entry:**

   - Go to employee's wage rule or payroll
   - Find "Vorschüsse" or "Advances" section

2. **Enter Advance Details:**

   - Enter advance amount
   - Select date of advance
   - Add notes (reason, etc.)

3. **System Processing:**

   - Advance recorded
   - Deducted from next payroll automatically
   - Visible in payslip as deduction
   - Tracked in advance account

4. **Review:**
   - View advance history
   - See remaining balance
   - Track repayment status

#### Workflow: Deleting Wage Rules

**Purpose:** Remove wage rules that are no longer needed

**Steps:**

1. **Access Wage Rules:**

   - Navigate to Lohnregeln section
   - Find wage rule to delete

2. **Check Dependencies:**

   - System checks if rule is used in active payroll
   - Verifies no historical payroll data depends on rule

3. **Delete Rule:**
   - If safe to delete, confirm deletion
   - Rule removed from active rules
   - Historical data preserved

**Note:** Rules with historical payroll data typically cannot be deleted but can be deactivated.

#### Workflow: Payroll Plus Setup

**Purpose:** Set up Payroll Plus for fully integrated net payroll

**Prerequisites:**

- Payroll Plus subscription active
- Employee master data complete
- Time tracking data available

**Setup Steps:**

1. **Access Payroll Plus Setup:**

   - Navigate to Payroll Plus section
   - Go to "Einrichtung" or "Setup"

2. **Configure Payroll Groups (Abrechnungsgruppen):**

   - Create payroll groups
   - Assign employees to groups
   - Set payroll cycles (monthly, bi-weekly, etc.)

3. **Configure Payroll Package (Lohnpaket):**

   - Select payroll package type
   - Configure calculation rules
   - Set up tax and social insurance settings

4. **Set Up eAU Query:**

   - Configure electronic sick note (eAU) integration
   - Enable automatic query from health insurance
   - Set up notification preferences

5. **Configure DLS Export:**

   - Set up DATEV DLS export
   - Configure export format
   - Test export functionality

6. **Complete Setup:**
   - Review all configurations
   - Run test payroll
   - Verify calculations
   - Activate Payroll Plus

#### Workflow: Payroll Evaluation and Export (Lohnauswertung)

**Purpose:** Generate payroll evaluation and export data for tax advisor/accountant

**Important:** Payroll evaluation can only be done for **full months** due to legal requirements and DATEV transfer compatibility. While you can export at any date during the month (e.g., 24th), this may require corrections in the following month for employees paid by hours worked (e.g., Minijobber), as actual times may differ from previously paid hours.

**Recommended:** Set billing period to the **last or first day of the month** to ensure DATEV transfer works correctly and data is immediately ready for your tax advisor.

**Alternative:** Use Arbeitszeiten menu > Excel export with "Zusammenfassung pro Mitarbeiter" for mid-month exports (e.g., 24th to 24th). This shows all actual worked hours and absences, but **does NOT** consider wage limits (e.g., €556/month for Minijobber) or manual corrections/additional payments. These would need to be communicated separately to your tax advisor.

**Prerequisites:**

1. **Configure Tax Advisor (Steuerberater):**

   - Go to Einstellungen > Steuerberater > Benachrichtigungen
   - Enter email address
   - Go to 'Lohnnebenkosten' tab
   - Enter Mandanten- (client) and Beraternummer (advisor number) for DATEV export

2. **Configure Wage Costs & Wage Types (Lohnnebenkosten & Lohnarten):**

   - Discuss with tax advisor whether wage costs and/or wage types should be configured
   - Find settings in 'Lohnnebenkosten' tab
   - **Note:** Standard employment relationships (Geringfügig beschäftigt, Vollzeit, etc.) are automatically assigned to wage types
   - You can add custom employment relationships and link them to wage types

3. **Assign Wage Rules (Lohnregeln):**

   - Ensure all employees have wage rules assigned
   - Check in Mitarbeiterliste under 'Anstellungsverhältnis' column
   - Only employees with wage rules appear in evaluation

4. **Assign Employee Numbers (Personalnummern):**

   - Ensure all employees have employee numbers assigned
   - Employee numbers must match those in DATEV for DATEV evaluation

5. **Review Working Hours:**
   - Ensure all change requests for working hours are reviewed and processed
   - Check for incorrectly recorded or automatically ended shifts
   - Verify all time entries are correct

**Export Process:**

1. **Update Data:**

   - Click "Daten aktualisieren" (Update Data)
   - Info field shows current data status
   - System refreshes all payroll data

2. **Select Export:**

   - Choose export option
   - Select export format:
     - **DATEV Lodas:** For DATEV Lodas format
     - **DATEV Lohn und Gehalt:** For DATEV Lohn und Gehalt format
     - **Excel:** For Excel format (alternative method)

3. **Configure Format Details (for DATEV Lodas):**

   - Adjust format details as needed
   - Set export parameters
   - Configure date range

4. **Export:**

   - Click "Exportieren" (Export)
   - System generates export file
   - File downloads automatically

5. **Send to Tax Advisor:**
   - Forward exported file to tax advisor or payroll office
   - Include any additional notes if needed

**Special Notes:**

- **For .ini Format:** Select 'Datev Lohn und Gehalt' export and click the blue ".ini-Export" button at the bottom
- **Error Checking:** If errors appear in evaluation, check troubleshooting guide for possible causes and corrections
- **Video Guide:** Interactive video tutorial available in helpdesk

**Use Cases:**

- Monthly payroll processing
- Preparing data for tax advisor
- Exporting payroll data for accounting
- Mid-month reporting (using Excel alternative)

**Purpose:** Export payroll data for accounting/steuerberater (tax advisor)

**Prerequisites:**

1. **Steuerberater Setup:**

   - Go to Settings > Steuerberater > Benachrichtigungen
   - Enter email address
   - Go to Reiter 'Lohnnebenkosten' (tab)
   - Enter Mandanten- and Beraternummer for DATEV export

2. **Lohnnebenkosten & Lohnarten:**

   - Discuss with Steuerberater whether to configure Lohnnebenkosten and/or Lohnarten
   - Configure in Settings > Lohnnebenkosten
   - **Tip:** Standard employment types (Geringfügig beschäftigt, Vollzeit, etc.) are automatically assigned to Lohnarten. You can add custom employment types and link them to Lohnarten.

3. **Wage Rules (Lohnregeln):**

   - Ensure all employees have wage rules assigned
   - Check in employee list under 'Anstellungsverhältnis' (Employment Type)
   - Only employees with wage rules appear in evaluation

4. **Personal Numbers:**

   - Ensure all employees have Personalnummern (employee numbers) assigned
   - Must match Personalnummern in DATEV system

5. **Review Working Hours:**
   - Process all change requests (Änderungsanträge)
   - Review and correct incorrectly recorded shifts
   - Handle automatically ended shifts
   - Ensure all time entries are accurate

**Payroll Period:**

- **Full Month Required:** For legal and DATEV transfer reasons, only full months can be evaluated
- **Mid-Month Export:** Can export mid-month (e.g., 24th), but:
  - Remaining days (25th-31st) may need correction next month
  - For hourly employees (e.g., Minijobber), if actual hours differ from prepaid hours, overpayment or underpayment may occur
- **Recommendation:** Set evaluation period to last/first day of month for accurate DATEV transfer
- **Alternative:** Use Arbeitszeiten > Excel export with "Zusammenfassung pro Mitarbeiter" for mid-month reports
  - Shows actual worked hours and absences
  - **Note:** Does not respect wage limits (e.g., €556 for Minijobber) or manual corrections - these must be communicated separately to Steuerberater

**Export Process:**

1. **Update Data:**

   - Click "Daten aktualisieren" (Update Data)
   - Info field shows current data status
   - Ensures latest data is included

2. **Select Export:**

   - Choose export option
   - Select format:
     - DATEV Lodas
     - DATEV Lohn und Gehalt
     - Excel
     - Other formats

3. **Configure Format Details:**

   - For DATEV Lodas: Adjust format details as needed
   - For DATEV Lohn und Gehalt: Can select .ini-format export (click blue .ini-Export link)

4. **Export:**

   - Click "Exportieren" (Export)
   - File generated
   - Download file

5. **Send to Steuerberater/Lohnbüro:**
   - Forward file to tax advisor or payroll office
   - Include any additional information (manual corrections, wage limits, etc.)

**Troubleshooting:**

- If errors appear in evaluation, check:
  - Missing wage rules
  - Missing personal numbers
  - Unprocessed change requests
  - Incorrect time entries
  - Missing employee data

#### Workflow: Payroll Plus Payroll Run Process

**Purpose:** Execute complete payroll run with Payroll Plus

**Steps:**

1. **Prepare Payroll Period:**

   - Select payroll period
   - System automatically collects:
     - Working hours from time tracking
     - Allowances from shift planning
     - Absences from absence management
     - Employee master data

2. **Review Gross Wages:**

   - System calculates gross wages
   - Review calculations
   - Check for anomalies
   - Make adjustments if needed

3. **Run Payroll:**

   - Click "Run Payroll" or "Lohnlauf starten"
   - System calculates net wages in 60 seconds
   - All calculations compliant with German law
   - Automatic tax and social insurance calculation

4. **Review Payslips:**

   - Review digital payslips for all employees
   - Check calculations
   - Verify deductions
   - Full transparency on all calculations

5. **Approve and Release:**

   - Approve payroll
   - Release payslips to employees
   - Employees receive notifications
   - Payslips available in app and web portal

6. **Export:**
   - Generate DATEV DLS export
   - Export for accounting
   - Archive payroll data

### UI Components

**Payroll Dashboard:**

- **Layout:** Overview with period selector, employee list, status indicators
- **Elements:**
  - Current payroll period selector
  - Employee list with payroll status
  - Progress indicators
  - Action buttons (Calculate, Approve, Export)
  - Summary cards (total payroll, employees, status)
- **Interactions:** Click to view details, filter by status, bulk actions
- **Visual Design:** Clean dashboard with clear status indicators

**Payroll Calculation Interface:**

- **Layout:** Step-by-step calculation view
- **Elements:**
  - Data review section
  - Calculation preview
  - Error/warning indicators
  - Approval buttons
- **Interactions:** Review data, approve calculations, export
- **Visual Design:** Clear calculation breakdown with visual indicators

**Payslip View:**

- **Layout:** Digital payslip with all details
- **Elements:**
  - Employee information
  - Gross pay breakdown
  - Deductions (taxes, social insurance)
  - Net pay
  - Year-to-date totals
  - Download PDF button
- **Interactions:** View details, download, print
- **Visual Design:** Professional payslip design matching legal requirements

**DATEV Export Interface:**

- **Layout:** Export options and status
- **Elements:**
  - Export format selector (DATEV Lodas, DATEV Lohn und Gehalt, etc.)
  - Period selector
  - Export button
  - Download link
  - Export history
- **Interactions:** Select format, export, download
- **Visual Design:** Simple export interface with clear options

**Payroll Plus Interface:**

- **Layout:** Simplified one-click payroll interface
- **Elements:**
  - "Run Payroll" button
  - Status indicator (60-second countdown)
  - Results preview
  - Approval interface
- **Interactions:** One-click processing, review, approve
- **Visual Design:** Streamlined interface emphasizing speed and simplicity

## Visual Documentation

### Screenshots

**Payroll Dashboard:**

- **File:** `/v2/img/screenshots/payroll-dashboard.webp`
- **Alt Text:** "Lohnabrechnung dashboard showing payroll overview and employee calculations"
- **Caption:** Main payroll dashboard with employee list and calculation status

**Calculation View:**

- **File:** `/v2/img/screenshots/payroll-calculation.webp`
- **Alt Text:** "Lohnabrechnung calculation view showing hours, deductions, and net pay"
- **Caption:** Detailed payroll calculation interface with breakdown of all components

**DATEV Export:**

- **File:** `/v2/img/screenshots/payroll-datev-export.webp`
- **Alt Text:** "Lohnabrechnung DATEV export interface showing export options"
- **Caption:** DATEV export interface with format selection and download options

**Payroll Plus - 60 Seconds:**

- **File:** `/v2/img/screenshots/payroll-plus-60-seconds.webp`
- **Alt Text:** "Payroll Plus 60-second payroll processing interface"
- **Caption:** Payroll Plus streamlined interface showing one-click payroll processing

### Diagrams

**User Flow Diagram:**

- **File:** `/v2/img/diagrams/payroll-user-flow.svg`
- **Description:** Complete flow from time tracking → payroll calculation → DATEV export
- **Use Case:** Understanding the end-to-end payroll process

**Integration Diagram:**

- **File:** `/v2/img/diagrams/payroll-integration.svg`
- **Description:** How Payroll integrates with Schichtplanung, Zeiterfassung, Abwesenheiten, and DATEV

**Payroll Plus Architecture:**

- **File:** `/v2/img/diagrams/payroll-plus-architecture.svg`
- **Description:** Payroll Plus architecture showing automatic data integration and 60-second processing

## Maintenance

### Update Schedule

- **Regular updates:** Monthly feature enhancements and bug fixes
- **Compliance updates:** Quarterly updates for tax law changes, social insurance adjustments, minimum wage updates
- **DATEV integration:** As needed for DATEV format updates
- **Legal compliance:** Immediate updates for new labor laws and regulations
- **Integration updates:** As needed for system integrations

### Common Updates

- **Tax table updates:** Annual or as needed for tax law changes
- **Social insurance updates:** Quarterly updates for contribution rates
- **Minimum wage updates:** As announced by government
- **DATEV format updates:** When DATEV releases new formats
- **Feature enhancements:** Based on user feedback and industry needs
- **Performance optimization:** Ongoing improvements to calculation speed
- **Mobile app updates:** Enhance mobile payslip viewing and self-service features

## Related Documentation

- [Product Pages Inventory](../../pages/product-pages/PRODUCT_PAGES_INVENTORY.md)
- [Product Features Inventory](../PRODUCT_FEATURES_INVENTORY.md)
- [Zeiterfassung Documentation](zeiterfassung-documentation.md) - Time tracking integration
- [Schichtplanung Documentation](schichtplanung-documentation.md) - Shift planning integration
- [Abwesenheiten Documentation](abwesenheiten-documentation.md) - Absence management integration

## Related Cursor Rules

- [product-pages.mdc](../../../../.cursor/rules/product-pages.mdc)
- [shared-patterns.mdc](../../../../.cursor/rules/shared-patterns.mdc)
- [global.mdc](../../../../.cursor/rules/global.mdc)