Appearance
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 and post to the same accounting models, without configuring each company by hand. Salaxy creates and updates the models for you.
Examples use the test environment; see Environments for demo and production.
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. |
Accounting (accounting) | The accounting models (targets) and the default one. See Accounting models. |
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
denyServiceModelsetting 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.
- 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. - Test accounts. Accounts made with
POST /v03/api/test/accountsget no model until their settings are saved once: readGET /v03/api/settings/companyand post the same body back toPOST /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.
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
- Create a customer company on test with
POST /v03/api/partner/company, using a partner token. - Sign in as the company and call
GET /v03/api/settings/company. Checkpayments.channelsandaccounting.targets: they should match the service model. - Call
GET /v03/api/session/currentwith the same token and comparesettings.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.

