> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# User-Facing Configurations

> Requirements for the settings an accounting integration must show bookkeepers: connection parameters, accounting mappings, Dimension selection, closed periods, auto-posting and description formats. Use it when designing the setup screen. For logging, see Non-Functional Requirements.

This page describes the settings your integration must expose to users. Bookkeepers use these settings to set up the integration, then review and update them over time.

The Export API does not store these settings. You build and store them in your integration. Four Integration Design pages tell you to read a value from "the integration configuration" or from user configuration. This page defines those values:

* [Accounts Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounts-mapping.md#required-account-configuration) uses the [accounting settings](#accounting-settings).
* [Tags Sync: Dimension Selection](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection.md) uses the [dimension selection](#dimension-selection).
* [Accounting Periods](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounting-periods.md#3-closed-period-handling-integration-configuration) uses [closed period handling](#closed-period-handling).
* [Posting Behaviour](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-posting-behaviour.md#1-read-posting-configuration-integration-configuration) uses [auto-posting](#auto-posting).

Each setting is marked **Essential** or **Optional**. Build every Essential setting. Build an Optional setting if your users need that behaviour.

The screenshots on this page are visual examples only. They show one way to present a setting. Your labels, layout and styling can differ, as long as the setting behaves as described.

## Implementation

* [Export Integration Workflow Guide](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md): workflow context for the Level 1 export, which depends on these settings

## Settings Overview

| Setting | Type | Affects |
| - | - | - |
| [Connection parameters](#connection-parameters) | Essential, if the Accounting System needs them | All imports and exports |
| [Accounting settings](#accounting-settings) | Essential | [Accounts Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounts-mapping.md) |
| [Dimension selection](#dimension-selection) | Essential | [Tags Sync](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-overview.md) |
| [Closed period handling](#closed-period-handling) | Essential | [Accounting Periods](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounting-periods.md) |
| [Auto-posting](#auto-posting) | Optional | [Posting Behaviour](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-posting-behaviour.md) |
| [Custom description](#custom-description) | Optional | The description sent with each entry |
| [Custom data fields](#custom-data-fields) | Optional | Other entry fields, such as a reference field |

## Connection Parameters

**Essential, if the Accounting System requires them.**

Some Accounting Systems need extra information after the connection is made. Examples are a subsidiary or an environment. Your integration must know these values before it imports data such as the chart of accounts, tax codes and Tags.

If your Accounting System needs post-connection parameters, you must expose a dedicated configuration for them.

* Show a drop-down to select the subsidiary, if it applies.
* Show a drop-down to select the environment, if it applies.
* Add any other setting your Accounting System needs.

Do not start an import until the user has saved these values.

## Accounting Settings

**Essential.**

Accounting settings tell your integration where to record each type of expense. They support card expenses, out-of-pocket expenses and their reimbursements, and invoices from Pleo's Invoice product.

Split the settings into two clearly labelled sections. Give each section a title and a short statement of its purpose.

### Global Accounting Settings

Global settings apply to all expense types. A common example is the journal setup.

| Option | Behaviour |
| - | - |
| Single journal | The integration records all Pleo expenses in one journal. This includes card expenses, out-of-pocket expenses and invoices. |
| Separate journals | The integration records each expense type in its own journal. Use one journal for card expenses, one for out-of-pocket expenses and, if it applies, one for invoices. Invoices rarely need a separate journal. |

If you offer separate journals, show the journal choice for each expense type inside the section for that type.

### Expense-Specific Accounting Settings

Add one section for each group of expense types. Use these groups: card expenses, out-of-pocket expenses with their reimbursements, and invoices.

The settings in each section depend on your Accounting System. The following list is not complete.

* Journal mapping
* Account mapping
* Employee account mapping, if it applies
* Vendor mapping, if it applies

For example, a typical setup contains the following selections.

![Example settings screen with three sections: Card Expenses, Reimbursements and Invoices, each with journal and account drop-downs](https://mintcdn.com/pleo-61d4d38b/EjElIx0WAgzjZ4iB/images/current/accounting-integrations/user-configs-and-non-functional-reqs/visual-example-expense-specific-acc-settings.png?fit=max\&auto=format\&n=EjElIx0WAgzjZ4iB\&q=85\&s=7fc3f2374467c7771831588b4670f51a)

Visual example of expense-specific accounting settings.

| Section | Settings |
| - | - |
| Card Expenses | Journal for card expenses Account for Pleo balance |
| Reimbursements | Journal for reimbursements Account for balance owed to employees Account for external reimbursements (optional) |
| Invoices | Journal for invoices and payments Accounts payable |

The names above come from the settings screen. [Accounts Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounts-mapping.md#required-account-configuration) uses these names for the same accounts:

| Setting | Name in Accounts Mapping |
| - | - |
| Account for Pleo balance | Pleo Wallet Account |
| Account for balance owed to employees | Pleo Out-of-Pocket Account |
| Accounts payable | Accounts Payable Account (fallback) |

The integration does not need a setting for the Contra account. A bookkeeper or admin sets one Contra account for each currency in Pleo, and Pleo passes it in the Export Item.

Pleo does not send a Contra account for external reimbursements, because they are paid outside Pleo. The optional "Account for external reimbursements" setting is the account the integration uses to book them.

The selected accounts and journals feed [Accounts Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounts-mapping.md). If a required value is missing when an Export Item is processed, the integration must fail that item with `failureReasonType` set to `missing_configuration`.

### Usability Requirements

Make the setup easy to complete, so users avoid mistakes. Apply these rules to every setting on this page.

* Use short, clear labels.
* Add a tooltip or help text that explains each setting.
* Validate the input, so users cannot save an invalid configuration.
* Let users save a configuration and reuse it.
* Use a drop-down wherever possible, so users select a value instead of typing it.

## Dimension Selection

**Essential.**

Users must choose which Accounting Dimensions the integration imports as Tag Groups in Pleo. The integration must show only the available and active Dimensions for the connected company.

Use a toggle for each Dimension if the Accounting System has five or fewer static Dimensions. Use up to five drop-downs if Dimensions are custom or there are more than five static Dimensions.

For example, with a few static Dimensions, show one toggle for each Dimension.

![Example Import dimensions setting with one toggle for each of three Dimensions: Projects, Cost Types and Departments](https://mintcdn.com/pleo-61d4d38b/EjElIx0WAgzjZ4iB/images/current/accounting-integrations/user-configs-and-non-functional-reqs/visual-example-import-dimension-toggle.png?fit=max\&auto=format\&n=EjElIx0WAgzjZ4iB\&q=85\&s=d20af3b563e6b7691546621e53bc6c4e)

Visual example of Dimension selection with toggles.

For custom Dimensions, show drop-downs, as in this example.

![Example Import dimensions setting with three drop-downs labelled Dimension 1, Dimension 2 and Dimension 3](https://mintcdn.com/pleo-61d4d38b/EjElIx0WAgzjZ4iB/images/current/accounting-integrations/user-configs-and-non-functional-reqs/visual-example-import-dimensions-dropdown.png?fit=max\&auto=format\&n=EjElIx0WAgzjZ4iB\&q=85\&s=c77d8209a51eb162192ed1f99c4cd6e9)

Visual example of Dimension selection with drop-downs.

The rules for showing, refreshing, auto-selecting and deselecting Dimensions are on [Dimension Selection](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection.md). Follow that page, so the two do not drift apart.

## Closed Period Handling

**Essential, if your integration supports posting expenses to the next open period.**

Bookkeepers need to export expenses that fall in a closed accounting period without reopening the period. Your integration decides whether it can post such expenses to the next open period. If it can, provide a toggle that lets bookkeepers opt in or out. If it can't, you don't need this setting.

* Give the toggle a clear title and a short description. A suitable title is "Expense rollover".
* Explain in the description what happens when the original expense date falls in a closed period. For example, the integration pushes the expense to the next open period.
* When the toggle is off, the integration posts with the original date. If the Accounting System rejects it, the integration fails the Export Item with a clear error.

![Example Export settings with an Expense rollover toggle and a short description explaining that expenses move to the next open accounting period](https://mintcdn.com/pleo-61d4d38b/EjElIx0WAgzjZ4iB/images/current/accounting-integrations/user-configs-and-non-functional-reqs/visual-example-opt-in-out-closing-period.png?fit=max\&auto=format\&n=EjElIx0WAgzjZ4iB\&q=85\&s=816438d157d83d959057aaf296b5f363)

Visual example of the closed period toggle.

[Accounting Periods](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-accounting-periods.md) explains how the integration applies this setting during export.

## Auto-Posting

**Optional.**

Provide a setting that lets bookkeepers choose whether the integration creates entries as finalised (posted) or leaves them as drafts. Auto-posting reduces the manual work of moving each entry to its final state.

If the bookkeeper has not set it, or your integration cannot tell what they chose, create entries as drafts. [Posting Behaviour](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-posting-behaviour.md) describes how to map this setting to the posting states of your Accounting System.

## Custom Description

**Optional.**

Provide a setting that lets bookkeepers build the description attached to each entry. A clear description gives them the context they need when they review entries in the Accounting System.

Let users combine the following elements.

* Static text
* The order of the fields
* Data fields from the Export Item, such as the note, the employee name, the vendor name, the original currency or the supplier currency

A token-based editor works well. Users add and remove data fields as tokens, and type static text between them.

![Example Note Format field with static text and removable tokens for Note, Employee Initials and Total Amount, and available tokens below for Employee Name, Supplier and Original Currency](https://mintcdn.com/pleo-61d4d38b/EjElIx0WAgzjZ4iB/images/current/accounting-integrations/user-configs-and-non-functional-reqs/visual-example-custom-description-note-fields.png?fit=max\&auto=format\&n=EjElIx0WAgzjZ4iB\&q=85\&s=092ed0f83e2691ec99eeeb6cca8e16c9)

Visual example of a custom description editor.

## Custom Data Fields

**Optional.**

Some Accounting Systems have fields on an entry that are separate from the description. A common example is a reference field. Bookkeepers use these fields to attach extra information that fits how they work, such as an identifier they later search for or report on.

If your Accounting System has such fields, provide a setting that lets bookkeepers choose which Pleo data the integration sends to each one.

### How It Differs from Custom Description

The custom description is one free-text field. Bookkeepers build it from static text and data fields. A custom data field is a separate field in the Accounting System. The bookkeeper chooses what to send to each field on its own, so each field can hold a different piece of data.

### What to Build

* Show the fields of your Accounting System that the integration can write to.
* For each field, let the bookkeeper choose a data field from the Export Item. Offer the same data fields as for the custom description, such as the note, the employee name, the vendor name, the original currency or the supplier currency.
* Make every field optional. A bookkeeper does not have to fill them all.
* If your Accounting System has fields at both the entry level and the line level, show which level each field belongs to.
* Check the length and format limits of each field in your Accounting System, and validate the choice before the bookkeeper saves it.

### Example: SAP Business One

A journal entry in SAP Business One has reference fields, called Ref. 1, Ref. 2 and Ref. 3, in addition to its remarks. Users fill them with extra information about a posting, such as an invoice number. The fields help with tracing and analysing bookings, and they can appear in reports.

For an integration with SAP Business One, the setting could look like this.

| Reference field | Data sent from Pleo |
| - | - |
| Ref. 1 | Vendor name |
| Ref. 2 | Employee name |
| Ref. 3 | Original currency |

With this setup, a bookkeeper can find all entries for one vendor by searching on Ref. 1. This table is an example only. The data that bookkeepers can choose depends on your integration and your Accounting System.

Use the same approach as for the custom description, so users configure all text fields in one way.

***

## What Comes Next?

* [Non-Functional Requirements](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/integration-design-non-functional-requirements.md)

***

## Related Reading

* [Integration Design Catalogue](https://developers.pleo.io/docs/current/integration-design/accounting-integrations/integration-design-overview.md)
* [Export Integration Workflow Guide](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md)
* [AS/ERP Processing Workflow Guide](https://developers.pleo.io/docs/current/guides/accounting-system-processing-workflow-guide.md)

***
