> 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-minimum-staffing.md).

# Advanced Minimum Staffing

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

Advanced Minimum Staffing allows you to define how many employees should be present at specific times of the week.

Instead of using one minimum staffing requirement for all opening hours, you can define different minimums depending on the day and time.

For example, a store might need:

| Weekday: | Time: | Minimum employees: |
| -------- | ----- | ------------------ |
| Monday   | 09:00 | 2                  |
| Monday   | 10:00 | 3                  |
| Friday   | 16:00 | 5                  |
| Saturday | 12:00 | 6                  |

This gives SameSystem a more realistic understanding of the minimum staffing required throughout the week.

***

### Why use Advanced Minimum Staffing?

Staffing requirements are rarely the same throughout the entire day.

A store may, for example, need more employees during:

* Opening and closing the store.
* Deliveries.
* Lunch periods.
* Peak customer hours.
* Weekends.
* Other operationally important periods.

Advanced Minimum Staffing makes it possible to represent these requirements when SameSystem calculates recommended staffing.

{% hint style="info" %}
The configured minimum acts as a floor for the staffing recommendation. If the business requires at least 3 employees at a particular hour, SameSystem will not recommend fewer than 3 employees for that hour.
{% endhint %}

***

### Standard vs. Advanced Minimum Staffing

SameSystem also has a standard inimum employees on floor setting.

Think of this as your default minimum staffing requirement.

Advanced Minimum Staffing is then used for the days and hours where you need something different.

#### Example

Assume your standard minimum is:

> **2 employees on the floor**

You could add the following advanced requirements:

| Weekday: | Time: | Minimum employees: |
| -------- | ----- | ------------------ |
| Friday   | 16:00 | 4                  |
| Friday   | 17:00 | 4                  |
| Saturday | 11:00 | 5                  |
| Saturday | 12:00 | 5                  |

For the specified hours, SameSystem uses the advanced values.

For hours without an advanced value, SameSystem continues to use the standard minimum of **2 employees**.

This means you only need to configure the hours that are different from your normal requirement.

***

### Using periods

Advanced Minimum Staffing can also change over time.

For example, you might have different requirements during the Christmas period:

**Normal period**

> Saturday 12:00 → minimum 4 employees

**Christmas period**

> Saturday 12:00 → minimum 7 employees

Periods make it possible to define when a particular set of staffing requirements should apply.

A period can have:

* A start and end date, or
* A start date with no end date.

This is useful for seasonal changes, temporary business requirements, or permanent changes that should take effect from a specific date.

#### Apply periods

An update **does not replace all existing periods**. Instead, the periods in the request are added or updated in the same way as when using **Add period** in the UI.

When a new period overlaps an existing period:

* 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 so that the new period fits in.
* Existing periods that do not overlap the new period are left unchanged.
* Gaps between periods are also kept.

After the update, all periods are sorted by `start_date`.

{% hint style="warning" %}
**Important :** Periods within the same request **must not overlap each other**.
{% endhint %}

#### Delete periods

There is no separate endpoint for deleting periods.

To clear all existing periods, send one open-ended period with a `start_date` that is the same as or earlier than the earliest existing period.

To clear the values for a specific date range, send a period with:

```
"values": []
```

The period will still exist, but without any values.

Sending an empty list:

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

does not make any changes. The API returns `200 OK`, and all existing periods remain unchanged.

***

> **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.

### Client and department settings

Advanced Minimum Staffing can be configured centrally or for individual departments.

#### Client level

Defines the default configuration for all departments.

This is useful when many departments should follow the same minimum staffing rules.

Use the endpoint below to get all client-level periods:

[`GET /api/v1/{clientToken}/settings/client/advanced_minimum_staffing`](/api-v1-reference/settings-advanced-minimum-staffing/get-advanced-minimum-staffing-settings-for-client-level.md#get-clienttoken-settings-client-advanced_minimum_staffing)

Use the endpoint below to apply periods on the client level:

[`PUT /api/v1/{clientToken}/settings/client/advanced_minimum_staffing`](/api-v1-reference/settings-advanced-minimum-staffing/apply-advanced-minimum-staffing-settings-on-the-client-level.md#put-clienttoken-settings-client-advanced_minimum_staffing)

#### Department level

An individual department can have its own configuration when its staffing requirements differ from the client standard.

> **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.

For example:

**Client**

> Saturday 12:00 → minimum 4 employees

**Large city store**

> Saturday 12:00 → minimum 7 employees

The city store can therefore have its own staffing requirements without changing the configuration for all other departments.

Use the endpoint below to get all department-level periods:

[`GET   /api/v1/{clientToken}/settings/shop/advanced_minimum_staffing`](/api-v1-reference/settings-advanced-minimum-staffing/get-advanced-minimum-staffing-settings-for-the-department-shop-level.md)

You can use query parameter `?shop_id={id}` to specify the id of the department you need to fetch data for. 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.

Use the endpoint below to apply periods on the department level:

[`PUT   /api/v1/{clientToken}/settings/shop/advanced_minimum_staffing`](/api-v1-reference/settings-advanced-minimum-staffing/apply-advanced-minimum-staffing-settings-for-the-department-shop-level.md)

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.

***

### How department overrides work

By default, a department uses the client configuration.

However, once a department gets its own Advanced minimum staffing configuration, that configuration becomes the department's own set of rules.

{% hint style="info" %}
A department override is a complete configuration, not just a few exceptions added on top of the client configuration.

Once the department has its own override, later changes to the client configuration are not automatically reflected in that department.
{% endhint %}

This distinction is important when deciding whether staffing rules should be managed centrally or individually.

***

### Example

Imagine a retail company with 50 stores.

Most stores can use the same minimum staffing requirements:

| Weekday: | Time: | Minimum employees: |
| -------- | ----- | ------------------ |
| Monday   | 09:00 | 2                  |
| Friday   | 16:00 | 4                  |
| Saturday | 12:00 | 5                  |

These rules can be maintained centrally at the **client level.**

One large flagship store has significantly more customers on Saturdays and therefore needs:

| Weekday: | Time: | Minimum employees: |
| -------- | ----- | ------------------ |
| Saturday | 11:00 | 8                  |
| Saturday | 12:00 | 10                 |
| Saturday | 13:00 | 10                 |

That department can have its own configuration while the remaining stores continue to use the client configuration.

***

### Key concepts

**Default minimum**\
The standard *Minimum employees on floor* value is used when no advanced value exists for an hour.

**Advanced minimum**\
Defines a specific minimum for a weekday and hour.

**Period**\
Defines when a set of advanced minimum staffing requirements applies.

**Client configuration**\
The default configuration that departments can inherit.

**Department override**\
A department-specific configuration used instead of the client configuration.

***

### Integration possibilities

Advanced minimum staffing can also be maintained through the SameSystem API.

This can be useful if minimum staffing requirements are calculated or maintained in another system and should automatically be transferred to SameSystem.

Typical examples include:

* External forecasting solutions
* Store planning tools
* Customer-specific business rule engines

The integration can manage the configuration centrally at client level or for individual departments.

For technical implementation details, see API Reference → Advanced Minimum Staffing.

***

### 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-minimum-staffing.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.