> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chift.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Activating the data layer
The data layer is **opt-in**.
To enable the data layer on your environment:
1. **Reach out to your CSM** at Chift.
2. Together, you agree on the **sync timing** that fits your use case (how often the sync runs). The cadence directly drives how fresh the data layer data will be for your end-users.
3. Chift activates the sync. An initial run backfills historical data into the data layer store; the recurring sync then keeps it up to date at the agreed cadence.
Once the initial sync completes, the data layer is ready to serve reads for that connection.
The first sync can take a while on connections with a lot of historical data — plan the activation accordingly. Until it finishes, a read sent with `x-chift-datalayer: true` is rejected with `409 ERROR_DATALAYER_SYNC_PENDING` rather than returning empty data. Wait for the first `account.datalayer.refresh_executed` webhook, or read live in the meantime — see [Use it on a request](#use-it-on-a-request).
## Configuring the data layer
Once the feature is enabled on your account, you manage it yourself from the **Data layer** settings page in the Chift platform. Every vertical that supports the data layer appears as its own card, and each is configured independently.
For each vertical you can control:
Turn the data layer on for the vertical. The card shows how many entities are currently selected.
Under **Entities**, tick the resources you want the sync to keep in the data layer store — for accounting that's folders, chart of accounts, journals, journal entries, invoices, partners, VAT codes and book years (see [Overview](/guides/datalayer/overview#whats-covered-today)). Only the entities you select are synced and served through the header, so leave out anything you don't need to keep each run lean.
The **automatic** enable mode (default) turns the data layer on the moment a consumer activates a matching connector, so it's ready without any per-connection action. Switch to **manual** if you'd rather enable it yourself on each connection.
Set the window the first sync backfills — see [below](#choosing-how-much-history-to-load).
### Choosing how much history to load
The first sync backfills historical data into the data layer store. By default it loads the **last 12 months**, but you can widen or narrow that initial window from the same settings page. The value you set is applied each time the data layer is enabled on a connection.
The start-date control offers a few modes:
| Mode | What the first sync loads |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default** | The last 12 months. |
| **Today** | Only data from today onward. |
| **Relative period** | A number of **months**, **years**, or **fiscal years** back. Fiscal years anchor to the connection's book years and are available for **accounting** only; the page shows a live preview of the resolved start date. |
| **Full history** | Everything, with no lower date bound. |
| **Custom date** | A specific date you pick. |
**Full history** and long periods make the first sync pull much more data, so it takes longer to complete. Pick the shortest window that covers your use case.
If you enable the data layer manually from your own backend, you can pass the same window directly to the [`enable_datalayer`](/api-reference/endpoints/datalayer/enable-the-datalayer-sync-for-a-connection) endpoint through its `from_date`, `fiscal_years_back` (accounting only) or `full_history` body options — mutually exclusive, and taking precedence over the settings-page value.
### Scoping to specific folders or locations
By default the data layer syncs every top-level entity the connection exposes — all accounting folders, or all POS locations. When you enable the data layer manually from your own backend, you can narrow it to a **subset** by passing an `entity_filter` to the [`enable_datalayer`](/api-reference/endpoints/datalayer/enable-the-datalayer-sync-for-a-connection) endpoint:
* `folder_ids` — for accounting connections, the folders to sync.
* `location_ids` — for POS connections, the locations to sync.
Only the listed entities are then synced and served through the header; the rest are left out. The ids are checked against the connection's live folders/locations at sync time, so a stale or unknown id fails the run with `ERROR_DATALAYER_ENTITY_NOT_AVAILABLE` rather than silently syncing nothing. Omit `entity_filter` to sync everything (the default).
## Use it on a request
Reading from the data layer is a **per-request** choice, controlled entirely by the `x-chift-datalayer` request header. It accepts three values, so you decide per request whether an unavailable data layer should error or quietly fall back to a live read:
| Header value | Data layer available | Data layer unavailable |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| *omitted* / `false` | — | Served live from the source (default behavior). |
| `true` | Served from the data layer. | Rejected with an error (`400`/`409`) — for example `409 ERROR_DATALAYER_SYNC_PENDING` before the first sync completes. |
| `if_available` | Served from the data layer. | Served live from the source instead of erroring. |
To serve a given call from the data layer, send `x-chift-datalayer: true`:
```http theme={null}
GET /accounting/journal-entries
x-chift-datalayer: true
```
The endpoint, parameters and response shape are exactly the same as the regular unified API call — the response is just computed from Chift's data layer store rather than fetched live from the source. You can freely mix data-layer and live reads within the same integration and on the same connection, and reach for `if_available` when you'd rather get a live answer than an error (for example while the first sync is still running) without branching on the connection's state yourself.
### Knowing which source served a response
Every response to a request that opted into the data layer (`true` or `if_available`) carries an **`x-chift-datalayer-source`** header telling you which path actually served it:
* `x-chift-datalayer-source: datalayer` — served from the data layer store.
* `x-chift-datalayer-source: classic` — served live from the source.
This lets a caller using `if_available` tell whether a given response came fresh from the source or from the last sync.
## Reading data you just wrote
Because writes go to the source and the data layer is updated only by the sync, a record you have just created or updated is not yet in the data layer until the next sync run.
The pattern is simple: **just don't send the `x-chift-datalayer` header on that read**. The call then goes through the live unified API and returns the up-to-date record from the source. On subsequent reads where freshness is no longer critical, you can send the header again.
## Monitoring
The sync that feeds the data layer is a standard Chift sync, so you can monitor it the same way as any other sync. See [Syncs](/guides/syncs/overview) for the general overview and [Troubleshooting](/syncs/troubleshooting) for the most common failure modes.