# Real vs Forecast Mode

Verso API supports two execution modes for payroll calculations: **Real Mode** and **Forecast Mode**. Understanding when to use each mode is essential for effective payroll management.

## Mode Comparison

| Aspect | Real Mode | Forecast Mode |
|--------|-----------|---------------|
| **Purpose** | Official payroll records | Simulations and previews |
| **Data Persistence** | Permanent record | Stored separately |
| **Affects History** | Yes | No |
| **Use Case** | Final payroll run | What-if scenarios |
| **Identifier** | No `forecast` field | Requires `forecast` field |

## Real Mode

Real mode creates official payroll records that become part of the employee's permanent history.

### When to Use

- Monthly payroll processing
- Final salary calculations
- Year-end reconciliation
- Official pay slip generation

### Example

```json title="POST /payrolls/{payrollId}/cases (Real Mode)"
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "case": {
    "caseName": "Remuneration",
    "values": [
      { "caseFieldName": "HeuresTravaillees", "value": "151.67", "start": "2025-01-01T00:00:00Z" },
      { "caseFieldName": "TauxHoraire", "value": "12.50", "start": "2025-01-01T00:00:00Z" }
    ]
  }
}
```


## Forecast Mode

Forecast mode runs simulations that are stored separately from official records, ideal for previews and what-if scenarios.

### When to Use

- Employee net pay previews
- Bonus impact simulations
- Salary increase projections
- Benefits change calculations
- Testing before production

### Example

```json title="POST /payrolls/{payrollId}/cases (Forecast Mode)"
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "forecast": "preview-jan2025-emp2",
  "case": {
    "caseName": "Remuneration",
    "values": [
      { "caseFieldName": "HeuresTravaillees", "value": "151.67", "start": "2025-01-01T00:00:00Z" },
      { "caseFieldName": "TauxHoraire", "value": "12.50", "start": "2025-01-01T00:00:00Z" }
    ]
  }
}
```

### Forecast Identifier Strategies

#### Historized Forecasts

Create unique identifiers to keep multiple simulation versions:

```json
{
  "forecast": "salary-review.2025-01-15T10:30:00Z"
}
```

Use this approach when you need to:
- Compare multiple scenarios
- Track simulation history
- Audit forecast decisions

#### Ephemeral Forecasts

Reuse the same identifier to overwrite previous results:

```json
{
  "forecast": "current-preview"
}
```

Use this approach when you need to:
- Show real-time updates
- Minimize storage usage
- Display latest projection only

## Workflow Example

### Step 1: Simulate with Forecast

```json title="Forecast Payrun"
{
  "name": "January_Preview",
  "payrunName": "Monthly",
  "userIdentifier": "payroll-admin@company.com",
  "forecast": "jan-2025-preview",
  "periodStart": "2025-01-01T00:00:00Z",
  "employeeIdentifiers": ["jean.dupont@company.com"]
}
```

### Step 2: Review Results

Check the simulation results and validate calculations.

### Step 3: Run Real Payroll

Once validated, run the same calculation without the `forecast` field:

```json title="Real Payrun"
{
  "name": "January_Official",
  "payrunName": "Monthly",
  "userIdentifier": "payroll-admin@company.com",
  "periodStart": "2025-01-01T00:00:00Z",
  "employeeIdentifiers": ["jean.dupont@company.com"]
}
```

## Data Isolation

Forecast and Real data are completely isolated:

```
┌─────────────────────────────────────┐
│           Database                   │
│  ┌───────────────┐ ┌──────────────┐ │
│  │  Real Data    │ │ Forecast Data│ │
│  │               │ │              │ │
│  │ • Official    │ │ • Simulations│ │
│  │ • Permanent   │ │ • Temporary  │ │
│  │ • Auditable   │ │ • Isolated   │ │
│  └───────────────┘ └──────────────┘ │
└─────────────────────────────────────┘
```

## Use Case: Employee Self-Service

:::tip
Use Forecast mode to let employees preview their expected net pay before the official payroll run. This reduces payroll queries and improves transparency.
:::

```
Employee Portal Flow:
1. Employee enters expected hours/overtime
2. API runs forecast calculation
3. Employee sees projected net pay
4. HR runs official payroll later
```

## Next Steps

- [Quickstart](/quickstart) - Complete payroll workflow
- [Case Fields Reference](/reference/case-fields) - Available input fields
- [Error Handling](/guides/error-handling) - Handling API errors