# Dimensions (cost centres)

A **dimension** is a cost-accounting tag such as a cost centre, project or department. Push your own dimensions into Salaxy, tag salary calculations with them, and the accounting data you read back carries your coding.

Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. The endpoints are account-scoped: the company is the one you act as, see [Impersonation](https://code.salaxy.com/security/impersonation.md).

*Diagram: Dimensions have two layers. A definition is the catalogue, for example Project with its options; you push it to Salaxy through the settings endpoints. A value is the usage: a salary calculation or one of its rows is tagged with a dimension id and an option. The accounting data that Salaxy produces carries the values on each ledger entry. (You push the catalogue once; every calculation then carries values from it into the accounting data.)*

## Two layers

| Layer | What it is | Where it goes |
|---|---|---|
| **Definition** (`CostAccountingDimensionDefinition`) | The catalogue: `id`, `label`, `options[]`, `allowCostSharing`, `scope` | The settings endpoints below |
| **Value** (`CostAccountingDimension`) | The usage: `{ id, value, percent }` | On the calculation, **not** through the settings endpoints |

An option in `options[]` has a `value`, a `text` and, for hierarchies, a `path` (the path to the option, not including the value itself). `scope` says where the dimension is offered: `none`, `calculation`, `row` or `hidden`.

A value goes in `accounting.dimensions` on a whole calculation, or in `accounting.dimensions` on a single row. `percent` splits one cost between several values. It needs `allowCostSharing: true` on the definition.

## Which fits you?

### You master the catalogue

Fits when your system is the only place where dimensions are edited. Post the whole list every time.

**You master the catalogue: how it works:**
Use `POST /v03/api/settings/dimensions/all`. It **replaces** all definitions with the ones you post. A definition you leave out is **deleted**.

If a customer can also edit dimensions in the Salaxy user interface, a periodic `/all` push silently discards their edits. Use this option only when you are sure they cannot.

### Salaxy and the customer share the catalogue

Fits when dimensions are also edited in Salaxy, or you push only changes.

**Shared catalogue: how it works:**
Save or remove **one** definition at a time with `POST /v03/api/settings/dimensions` and `DELETE /v03/api/settings/dimensions/{id}`. Definitions you do not touch stay as they are.

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v03/api/settings/dimensions` | All definitions of the account |
| `GET` | `/v03/api/settings/dimensions/{id}` | One definition |
| `POST` | `/v03/api/settings/dimensions` | Save **one** definition |
| `DELETE` | `/v03/api/settings/dimensions/{id}` | Remove one definition |
| `POST` | `/v03/api/settings/dimensions/all` | **Replace all** definitions with the posted array |

A definition:

```json
{
  "id": "project",
  "label": "Project",
  "allowCostSharing": true,
  "scope": "calculation",
  "options": [
    { "value": "P100", "text": "Website renewal" },
    { "value": "P200", "text": "Mobile app" }
  ]
}
```

A calculation tagged with a value (only the relevant part is shown). A row uses the same shape in its own `accounting.dimensions`. The `percent` field of a value is for cost sharing; check its scale in the [REST reference](https://code.salaxy.com/reference/rest-api.md) before you use it.

```json
{
  "accounting": {
    "dimensions": [
      { "id": "project", "value": "P100" }
    ]
  }
}
```

## Where definitions live

| Container | Effect |
|---|---|
| Account settings (`costAccounting.dimensions`) | The company's own catalogue. This is what the endpoints above read and write |
| Service model (`costAccounting.dimensions`) | Defaults handed from your technical account down to every customer company. Provisioned by Salaxy, so it is a project decision, not code you write. See [Service models](https://code.salaxy.com/integration/service-models.md) |

The [company settings](https://code.salaxy.com/integration/company-settings.md) page covers the other parts of the settings object.

## Reading values back

Accounting data carries a `dimension` field on each ledger entry. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md).

## Test it

1. Post a definition with `POST /v03/api/settings/dimensions` and read it with `GET /v03/api/settings/dimensions`.
2. Create a calculation (see [Salary calculations](https://code.salaxy.com/integration/calculations.md)) and add the value to `accounting.dimensions`.
3. Read the accounting data for the calculation and check that the entries carry the `dimension` values.

## Checklist

- You decided who masters the catalogue: you (`/all`) or shared (single save and delete).
- You never post a partial list to `/all`.
- Values go on the calculation or row, not through the settings endpoints.
- `percent` is used only on dimensions with `allowCostSharing: true`.

**Next:** [Worktime import](https://code.salaxy.com/integration/worktime-import.md)
