> 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/forecast/advanced-employee-capacity.md).

# Advanced Employee Capacity

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

The Advanced Employee Capacity endpoints allows you to configure how many visitors or customers one employee is expected to handle per working hour.

It is used by SameSystem when calculating recommended staffing based on forecasted traffic.

For example, you can define that on Monday between 09:00 and 10:00:

* 0–5 visitors → one employee can handle 1 visitor per hour
* 6 or more visitors → one employee can handle 2 visitors per hour

This makes it possible to adjust employee capacity depending on how busy the department is.

### Client and department settings

Advanced Employee Capacity can be configured at two levels:

**Client level**

Defines the default configuration for all departments.

**Department level**

A department can have its own configuration instead of using the client-level settings.

A department without its own override inherits the client configuration.

> **Important:** Once a department has its own override, its own list is used instead of the client list. Client and department periods are not dynamically combined

***

### Endpoints

#### Client level

Returns the Advanced Employee Capacity periods configured for the client:

[GET /api/v1/{clientToken}/settings/client/advanced\_employee\_capacity](/api-v1-reference/settings-advanced-employee-capacity/get-advanced-employee-capacity-settings-for-the-client-level.md)

Adds or updates periods at client level:

[PUT /api/v1/{clientToken}/settings/client/advanced\_employee\_capacity](/api-v1-reference/settings-advanced-employee-capacity/apply-advanced-employee-capacity-settings-for-the-client-level.md)

#### Department level

Returns the Advanced Employee Capacity periods that currently apply to the selected department:

[GET /{ctx\_token}/api/v1/settings/shop/advanced\_employee\_capacity](/api-v1-reference/settings-advanced-employee-capacity/get-advanced-employee-capacity-settings-for-the-department-shop-level.md)

Adds or updates periods for a specific department:

[PUT /{ctx\_token}/api/v1/settings/shop/advanced\_employee\_capacity](/api-v1-reference/settings-advanced-employee-capacity/apply-advanced-employee-capacity-settings-for-the-department-shop-level.md)

`PUT` and `PATCH` behave the same way for these endpoints.

For department-level endpoints, you can use query parameter `?shop_id={id}` to specify the id of the department you need to update. If you use the query parameter `?use_custom_id=1`, you can force the system to find the department based on the external department id.

***

### Period fields

| Field:       | Description:                                                      |
| ------------ | ----------------------------------------------------------------- |
| `target`     | What the capacity is based on. Must be `visitors` or `customers`. |
| `start_date` | First date the period applies. Format: `YYYY-MM-DD`.              |
| `end_date`   | Last date the period applies. Use `null` for no end date.         |
| `values`     | Capacity rules for specific weekdays and hours.                   |

The `visitors` and `customers` targets are maintained independently. This means periods for both targets may use the same dates.

### Capacity values

Each entry in `values` defines a traffic range and its employee capacity.

| Field:              | Description:                                                   |
| ------------------- | -------------------------------------------------------------- |
| `wday`              | Weekday from `1` to `7`. `1` = Monday and `7` = Sunday.        |
| `hour`              | Hour of the day from `0` to `23`.                              |
| `starting_quantity` | First visitor/customer quantity included in this tier.         |
| `ending_quantity`   | Last quantity included. Use `null` for no upper limit.         |
| `value`             | Number of visitors/customers one employee can handle per hour. |

#### Capacity tiers

You can define multiple capacity tiers for the same weekday and hour.

For example:

```json
[
  {
    "wday": 1,
    "hour": 9,
    "starting_quantity": 0,
    "ending_quantity": 5,
    "value": 1.0
  },
  {
    "wday": 1,
    "hour": 9,
    "starting_quantity": 6,
    "ending_quantity": null,
    "value": 2.0
  }
]
```

This creates two tiers for Monday at 09:00:

| Traffic:  | Capacity: |
| --------- | --------- |
| 0–5       | 1.0       |
| 6 or more | 2.0       |

Tiers for the same weekday and hour must:

* start at `0`;
* have no gaps;
* not overlap;
* end with a tier where `ending_quantity` is `null`.

A single tier is also valid:

```json
{
  "wday": 1,
  "hour": 9,
  "starting_quantity": 0,
  "ending_quantity": null,
  "value": 2.0
}
```

This means the capacity is always `2.0`, regardless of the amount of traffic.

***

### How updates work

An update **does not replace all existing periods.**

Instead, the periods in the request are added to or applied on top of the existing periods, similar to using **Add period** in SameSystem.

When a new period overlaps an existing period for the same target:

* If the new period completely covers an existing period, the existing period is replaced.
* If the new period covers only part of an existing period, the existing period is shortened or split to make room for the new period.
* Periods that do not overlap are left unchanged.
* Gaps between periods are kept.

For example, if this period already exists:

```
01 Jan ─────────────────────────────── 31 Dec
                  Capacity A
```

and you add:

```
              01 Jun ───── 30 Jun
                    Capacity B
```

the resulting configuration becomes:

```
01 Jan ─ 31 May | 01 Jun ─ 30 Jun | 01 Jul ─ 31 Dec
   Capacity A   |    Capacity B    |    Capacity A
```

The same logic is applied separately to the `visitors` and `customers` targets.

### Clearing a period

There is no separate DELETE endpoint.

To create a date range where Advanced Employee Capacity has no values, send:

```json
{
  "target": "visitors",
  "start_date": "2026-09-01",
  "end_date": "2026-09-30",
  "values": []
}
```

The regular **Employee Capacity** settings are used for dates/hours where no advanced capacity value applies.

Sending:

```
{
  "periods": []
}
```

does **not** delete existing periods. It makes no changes.

***

### Permissions

<table><thead><tr><th width="119">Action:</th><th>Who is allowed:</th></tr></thead><tbody><tr><td>read</td><td>Any one of: <em>Forecasting hub</em> permission (any level), <em>Forecasting setup</em> permission (any level), or the client admin / region manager / department manager role within the same client.</td></tr><tr><td>update</td><td><em>Forecasting setup</em> permission with <strong>full access</strong> for the department in context.</td></tr></tbody></table>

A user who fails the rule gets `401`:

{% code overflow="wrap" %}

```json
{ "status": "unauthorized", "description": "Invalid/expired token or this user is not authorized for this action." }
```

{% endcode %}

The body is the same as for an invalid token. The API does not distinguish “no such permission” from “bad token”.&#x20;


---

# 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/forecast/advanced-employee-capacity.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.