# Service models

A service model is a bundle of settings that a parent account hands down to the customer companies under it. It is how a partner makes every customer pay through the same [payment channel](https://code.salaxy.com/integration/payment-channels.md) and post to the same [accounting models](https://code.salaxy.com/integration/accounting-models.md), without configuring each company by hand. Salaxy creates and updates the models for you.

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Your technical account owns a service model. The service model carries a payment channel, an accounting model and a payslip setting. It applies to every customer company under the technical account, and each company reads the settings from it. (Purple: Salaxy provisions it. One service model reaches every customer company under the owner.)*

## What a service model is

A service model belongs to one account, the **owner**: your technical account, or an accounting firm. A customer company that sits under the owner reads the owner's model and takes its settings from it.

A model has sections. Each section is switched on by its own flag in `features`, and only a switched-on section overrides the company's own settings.

| Section (flag) | What it sets for the company |
|---|---|
| Payments (`payments`) | The available payment channels and the default channel. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md). |
| Accounting (`accounting`) | The accounting models (targets) and the default one. See [Accounting models](https://code.salaxy.com/integration/accounting-models.md). |
| Cost accounting (`costAccounting`) | The dimensions (cost centres). |
| Holiday (`holiday`) | Holiday pay and holiday accrual settings. |
| Incomes Register (`irDelivery`) | The certificate used when filing on the company's behalf. |
| Reporting (`reporting`) | The report layout template and logo. |
| Messaging (`messaging`) | Payslip delivery methods and worker notifications. |
| Use cases (`usecase`), pay statistics (`payStats`), forms (`forms`) | Further optional settings. |

Three sections are always copied and have no flag: **pricing**, **branding** (logo and design) and **site** (the web app a company is sent to).

## What the model fixes for the customer

A section that is switched on is **locked** in practice: the model's values replace the company's own, and a change made in the company's settings is overwritten the next time they are read. Salaxy has no separate "restricted account" setting; a locked section is a section with its flag on.

- **Locked** means the same payment channel, the same accounting models and the same payslip setting for every customer company. Decide this with Salaxy at project start, and record the locked sections in your integration design document.
- **Not locked** means the flag is off. The customer, or its accounting firm, edits that part freely.
- **Pricing** is changed only by Salaxy. An attempt to change pricing through the API fails with a generic `400`.
- **Opt-out.** Each section also has a `denyServiceModel` setting on the company side. When it is on, the company keeps its own settings for that section even if the model says override. It is for one-off exceptions and is not meant as a normal path.

The cascade replaces whole lists. For example, with `payments` on, the company's list of payment channels is replaced by the model's list. Do not store your own data inside a company's channel list; it will be overwritten.

## Who provisions it

| Step | Who |
|---|---|
| Create and update a service model | Salaxy |
| Decide which customers get which model | You, agreed with Salaxy |
| Link a model to an accounting firm or a company | Salaxy, usually as part of onboarding that customer |

You do not create service models through the API. The record of which models exist for your project, in test and in production, sits in your integration design document: model name, id and owner account.

The owner's default model has the owner's account id as its id. Production needs its own models, which Salaxy creates.

## How a company gets a model

- **By the parent link.** A customer company reads the model of its primary parent: usually your technical account in a two-tier set-up, or the accounting firm in a three-tier one. See [Account structure](https://code.salaxy.com/integration/account-structure.md).
- **By id.** An account carries an optional `serviceModelId`. If it is empty, the company falls back to the **default model of its parent**, the one whose id equals the parent's account id. If the parent has no default model, nothing is applied and the company keeps its own settings.
- **At creation.** When you create a company with `POST /v03/api/partner/company`, its settings are stored at once, so the company has its model straight away. See [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md).
- **Test accounts.** Accounts made with `POST /v03/api/test/accounts` get no model until their settings are saved once: read `GET /v03/api/settings/company` and post the same body back to `POST /v03/api/settings/company`.

An accounting firm that has its own customer companies needs its own default model, because its customers read the firm's models and not yours. Ask Salaxy to set it up when you add such a firm.

## Endpoints

You normally only read. The CRUD endpoints exist, but changing a model is Salaxy's job.

| Method | Path | Purpose |
|---|---|---|
| GET | `/v03/api/service-models` | Search the models of the signed-in account (OData; `$search` free text). |
| GET | `/v03/api/service-models/{id}` | One model. |
| GET | `/v03/api/service-models/new` | A model with default values, not stored. |
| POST | `/v03/api/service-models` | Create or update. Salaxy does this. |
| DELETE | `/v03/api/service-models/{id}` | Delete. The owner's default model cannot be deleted. |

The same paths exist under `/v04/api/`. The endpoints work on the signed-in account's own models. Called with a token of another account, a read by id returns an empty result, not `404`. Sign in as the owner to read its models. The reference page is [ServiceModel](https://code.salaxy.com/reference/rest/servicemodel.md).

```http
GET https://test-secure.salaxy.com/v03/api/service-models
Authorization: Bearer {owner-account-token}
```

## Test and production

- **Test** has your models from project start, so you can build against the real settings. Test and demo share data.
- **Production** needs its own model. Salaxy creates it, usually with the same name as in test.
- **A change to a model** reaches the companies that read it. Ask Salaxy before a change that affects live customers.

## Test it

1. Create a customer company on test with `POST /v03/api/partner/company`, using a [partner token](https://code.salaxy.com/integration/partner-account.md).
2. Sign in as the company and call `GET /v03/api/settings/company`. Check `payments.channels` and `accounting.targets`: they should match the service model.
3. Call `GET /v03/api/session/current` with the same token and compare `settings.paymentChannels`. The two views should agree.

## Checklist

- You have agreed with Salaxy which sections are locked and which customers get which model.
- The model exists in test and in production, and you have its id.
- Your code does not write to a locked section; a company's own value is overwritten.
- New accounting firms with their own customers get a default model.
- You do not store your own data in a company's channel list.

**Next:** [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md)
