> For the complete documentation index, see [llms.txt](https://docs.samesystem.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samesystem.dev/business-guides/scheduling/productive-hours.md).

# Productive hours

{% hint style="info" %}
Only available in API v1
{% endhint %}

The `daily_stats` endpoint returns the calculated productive hours and productive salary cost per day for a department.

It can be used by external systems that need SameSystem's calculated productivity figures for reporting, analytics, forecasting, or other integrations.

**Endpoint:**

[GET /api/v1/{clientToken}/schedule/daily\_stats](/api-v1-reference/schedule/get-productive-hours.md)

Both `start_date` and `end_date` are required and included in the requested period as query parameters:

`GET /api/v1/{clientToken}/schedule/daily_stats?start_date=2026-04-01&end_date=2026-04-02`

The response contains one entry per date:

```json
{
  "2026-04-01": {
    "productive_hours": 9.5,
    "productive_salary": 1234.5
  },
  "2026-04-02": {
    "productive_hours": 0.0,
    "productive_salary": 0.0
  }
}
```

Days without productive work return `0.0` for both values.

### How do we calculate productive hours?

Productive hours are not necessarily the same as scheduled working hours.

SameSystem calculates productive hours based on the scheduled working time after breaks and applies the productivity settings relevant to each part of the shift.

Depending on the configuration, the calculation can include:

* Employee productivity
* Task productivity
* Zone productivity

The endpoint does not read one productivity multiplier stored on a shift. It splits scheduled work into time segments and combines the productivity settings that apply to each segment.

For a segment without a task:

```
productive hours = hours after breaks × zone factor × employee factor
```

For a segment assigned to a task:

```
productive hours = hours after breaks × zone factor × task factor × employee factor
```

A percentage becomes a factor by dividing it by 100. For example, `80%` becomes `0.80`.

### Productivity sources

The employee factor uses the first available value in this order:

1. Productivity percentage on the contract.
2. Productivity configured for the contract's role.
3. `100%` when neither is configured.

```mermaid
flowchart TD
    A{Contract productivity configured?} -->|Yes| B[Use contract percentage]
    A -->|No| C{Role productivity configured?}
    C -->|Yes| D[Use role percentage]
    C -->|No| E[Use 100 percent]

```

#### Task factor

Time covered by a task uses the task type's productivity percent. Time not assigned to a task is treated as `100%` task productivity.

#### Zone factor

Time assigned to a zone uses the zone's productivity percentage. Time without a zone adjustment is treated as `100%` zone productivity.

#### Bonuses

Bonuses are not another multiplier for `productive_hours`; they can only add to `productive_salary`.

A regular bonus contributes productive salary when all of the following are true:

* [x] The bonus type is valid on the date.
* [x] The calendar line contains a matching bonus fragment or matching rule-generated bonus fragment.
* [x] The fragment amount is present and non-zero.
* [x] An uncertain bonus is confirmed. The endpoint does not request inclusion of unconfirmed uncertain bonuses.

For a timed bonus, the bonus is calculated using the productivity-adjusted duration that overlaps the bonus fragment. For an untimed regular bonus, its stored fragment amount is used. A lend-out bonus contributes productive salary only when it is timed.

The bonus fragment's explicit rate is used when present; otherwise the configured bonus calculation determines its amount. Applicable salary extras are then added.

```mermaid
flowchart TD
    A["Applicable bonus fragment"] --> B{"Timed?"}
    B -->|"Yes"| C["Use productivity-adjusted duration"]
    B -->|"No - regular work"| D["Use stored amount"]
    B -->|"No - lend-out"| X["Exclude from productive salary"]
    C --> E["Apply bonus rate and salary extras"]
    D --> E
    E --> F["Add to productive salary only"]

```

### Break handling

Break segments are removed before productivity factors are applied. Consequently, a shift from `10:00` to `18:00` with a 30-minute break contributes `7.5` hours before any employee, task, or zone adjustment.

```mermaid
flowchart LR
    A["10:00 shift starts"] --> B["4.0 working hours"]
    B --> C["14:00 to 14:30 break"]
    C --> D["3.5 working hours"]
    D --> E["18:00 shift ends"]
    E --> F["7.5 hours after breaks"]

```

### Examples

#### Example 1: Two employees at 100% productivity

On 2026-04-01:

| Employee  | Shift       | Break     | Calculation | Productive hours |
| --------- | ----------- | --------- | ----------- | ---------------: |
| John Doe  | 10:00–18:00 | 0.5 hours | `8.0 - 0.5` |              7.5 |
| Jane Doe  | 12:00–14:00 | None      | `2.0`       |              2.0 |
| **Total** |             |           | `7.5 + 2.0` |          **9.5** |

On 2026-04-02 there are no registered working shifts, so `productive_hours` is `0.0`.

#### Example 2: Employee productivity

An eight-hour shift has a 30-minute break and the employee's contract productivity is `80%`:

| Stage                 | Hours/factor |        Result |
| --------------------- | -----------: | ------------: |
| Scheduled shift       |    8.0 hours |     8.0 hours |
| Remove break          |   −0.5 hours |     7.5 hours |
| Employee productivity |        ×0.80 | **6.0 hours** |

```
Productive hours : (8.0 - 0.5) × 0.80 = 6.0 
```

#### Example 3: Employee and task productivity

Of the 7.5 hours after breaks, two hours use a task configured at `50%`. The employee is configured at `80%`; no zone adjustment applies.

| Segment               |  Duration | Task factor | Adjusted before employee factor |
| --------------------- | --------: | ----------: | ------------------------------: |
| Non-task time         | 5.5 hours |        1.00 |                       5.5 hours |
| Task time             | 2.0 hours |        0.50 |                        1.0 hour |
| Combined              |           |             |                       6.5 hours |
| Employee productivity |           |       ×0.80 |                   **5.2 hours** |

#### Example 4: Employee, task, and zone productivity

For a two-hour task segment with employee productivity `80%`, task productivity `50%`, and zone productivity `120%`:

| Input                 |          Value |
| --------------------- | -------------: |
| Segment duration      |      2.0 hours |
| Zone factor           |           1.20 |
| Task factor           |           0.50 |
| Employee factor       |           0.80 |
| **Productive result** | **0.96 hours** |

```
Productive hours = 2.0 × 0.80 × 0.50 × 1.20 = 0.96 hours
```

### Productive salary

Productive salary is calculated per productive fragment and then summed:

```
productive salary = productive fragment hours × applicable hourly rate
```

The applicable rate can be the employee's calculated hourly salary or a fixed zone/lend-out rate. Salary extras may be included. Applicable productive bonus salary is added separately, so the daily value is not always reproducible as one daily hourly rate multiplied by the final daily productive-hours total.

<br>

```mermaid
flowchart TD
    A[Productive hours for one fragment] --> B{Fixed rate applies?}
    B -->|Yes| C[Use fixed rate with applicable salary extras]
    B -->|No| D[Use calculated hourly salary]
    C --> E[Fragment productive salary]
    D --> E
    E --> F[Sum fragments for the date]
    G[Applicable productive bonuses] --> H[Bonus productive salary]
    H --> F

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.samesystem.dev/business-guides/scheduling/productive-hours.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.