> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/platform/accounts-contacts.md).

# Accounts

***

## 1. Overview

An account is a customer — or a prospect, reseller or subsidiary — and everything Younium needs to trade with them. It is the record that answers who is billed, in what currency, on what payment terms, with what tax treatment, to which address, and by which delivery method.

Because those answers are held once on the account, they flow onto everything sold to it. An order takes its payment term, currency, invoice template and batch group from the account unless you override them; an invoice takes its address and delivery method the same way. Creating an order or a quote surfaces these defaults — together with the account's tax template, default addresses, and any custom fields whose names match — directly from the account, without needing separate access to the account record itself. Setting an account up correctly is what makes everything downstream come out right without repeated data entry.

Accounts also record who looks after the customer and who signed them, sit in a **customer tier**, group for reporting through **segments**, and carry the ledger accounts that [revenue recognition](/platform/revenue-recognition.md) needs.

***

## 2. Core Concepts

### Account

| Field                                     | Description                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| **Name**                                  | The customer's name                                                                |
| **Account number**                        | Assigned automatically unless you supply one                                       |
| **Account type**                          | Customer, reseller, subsidiary, prospect or other (see below)                      |
| **Description**                           | Free text                                                                          |
| **Inactive**                              | Marks an account as no longer trading, without deleting it                         |
| **Image**                                 | The customer's logo                                                                |
| **Site**, **Year founded**, **Employees** | Company details held for reference and reporting                                   |
| **Org number** / **Tax reg. nr**          | Registration numbers, used on invoices and for tax validation                      |
| **Tax number validation status**          | Where validation of the tax registration number has reached                        |
| **Parent account** / **Subsidiaries**     | The account hierarchy                                                              |
| **Currency**                              | The currency the account trades in. Falls back to the legal entity's base currency |
| **Payment term**                          | The default payment term for the account's orders and invoices                     |
| **Tax template**                          | The account's tax treatment                                                        |
| **Our reference** / **Your reference**    | References carried onto orders and invoices                                        |

**Ownership and tier:**

| Field             | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| **Owner**         | The Younium user responsible for the account, typically the customer success manager |
| **Signed by**     | The Younium user who closed the deal, typically the sales representative             |
| **Customer tier** | The [customer tier](#customer-tier) the account belongs to                           |

Owner, Signed by and Customer tier are all optional. They are available as columns, filters and export fields in account lists, where a user without a name shows as their email address.

**Invoicing:**

| Field                                                                       | Description                                                                       |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Invoice address** / **Delivery address**                                  | The account's default addresses, with their countries available for reporting     |
| **Invoice template**                                                        | The document template used for the account's invoices                             |
| **Invoice Batch Group**                                                     | Which billing run the account's invoices join                                     |
| **Invoice setting group**                                                   | The reminder sequence used for this account — see [Billing](/platform/billing.md) |
| **Invoice delivery method**                                                 | How invoices reach the customer                                                   |
| **Invoice email** / **Invoice email Cc** / **Reminder email**               | Where invoices and reminders are sent                                             |
| **Disable Invoice Reminders**                                               | Excludes the account from reminders entirely                                      |
| **Attach UBL to invoice** / **Attach Zugferd XML to invoice**               | Whether electronic invoice formats are attached for this account                  |
| **E-Invoice Address**, **E-Invoice address scheme**, **E-Invoice Operator** | The account's electronic invoicing identity                                       |

**Ledger and integrations:**

| Field                                                        | Description                                                                                                                                                                       |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Accounts receivable**                                      | The receivable account the customer's invoices post to                                                                                                                            |
| Unbilled accounts receivable, contract asset                 | Required for order-based [revenue recognition](/platform/revenue-recognition.md) when booking on order activation                                                                 |
| **Stripe credential status** / **GoCardless mandate status** | Whether the account has a usable payment method or mandate with the provider                                                                                                      |
| **External ERP Id** / **External CRM Id**                    | Identifiers used when matching the account in a connected system                                                                                                                  |
| **Source**                                                   | How the account was created, for example UI, API, Paywall, Quotes, Import or HubSpot. Read-only and set once at creation; see [Orders](/platform/orders.md#source) for the values |

**Balances**, maintained by Younium rather than entered:

| Field                                          | Description                                                                       |
| ---------------------------------------------- | --------------------------------------------------------------------------------- |
| **Balance**                                    | What the account currently owes: posted invoice totals less what has been settled |
| **Last invoiced**                              | When the account was last invoiced                                                |
| **Invoice count** / **Invoiced total, ex tax** | How many invoices the account has, and what they come to                          |

### Account type

| Type           | Use                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------- |
| **Customer**   | A trading customer                                                                           |
| **Reseller**   | A partner who sells on your behalf                                                           |
| **Subsidiary** | A child account under a parent — see below                                                   |
| **Prospect**   | Not yet a customer. An account cannot stay a prospect once an order or invoice references it |
| **Other**      | Anything that does not fit the above                                                         |

### Subsidiaries

A subsidiary account sits under a **Parent account**, which is how you model a customer group where the parts are tracked separately but may be billed together.

**Invoice subsidiary** decides which way that works: usage recorded on the subsidiary is either invoiced to the subsidiary itself, or rolled up and invoiced to the parent. Use it where a group wants one invoice covering several of its entities, while still seeing each entity's consumption separately.

### Addresses

An address belongs to an account and can be used as an invoice or delivery address on the account, and on the orders, invoices and quotes raised for it.

| Field                                                                           | Description                                  |
| ------------------------------------------------------------------------------- | -------------------------------------------- |
| **Name** / **Description**                                                      | How the address is labelled when you pick it |
| **Street**, **Street 2**, **City**, **Zip**, **State**, **County**, **Country** | The address itself                           |

The account nominates a **default invoice address** and a **default delivery address**. Orders copy from those defaults when they are created, so changing an account's default address does not retrospectively change addresses on orders already placed.

Adding addresses is part of creating or updating an account, but changing an existing address is done on the address itself — an account update will not alter an address it already has.

Deleting an address removes it from any deleted orders that still referenced it, then removes the address.

> **Note on tax resolution:** Tax comes from the most specific setting available. A tax template on the charge wins over one on the order, which wins over the account's **Tax template**. So an account-level template sets the norm, and an individual charge can depart from it where a product is taxed differently.

### Account segment

A segment is a named group of accounts, used for filtering and reporting. Segments belong to a **Group**, which is how related segments are kept together — a group called Region holding segments Nordics, DACH and UK, for example.

| Field                    | Description                                   |
| ------------------------ | --------------------------------------------- |
| **Name**                 | The segment's name                            |
| **Group**                | Required. The grouping the segment belongs to |
| **Description**          | Free text                                     |
| **Account segment type** | How membership is decided (see below)         |

| Segment type         | Membership                                                   |
| -------------------- | ------------------------------------------------------------ |
| **List**             | The accounts you name explicitly                             |
| **Segment by field** | Grouped automatically by the value of a chosen account field |
| **Custom**           | Every account matching the conditions you define             |

A custom segment's conditions are evaluated against the account's fields whenever the segment is used, so membership follows the data rather than needing maintenance. Field names in conditions have to match the account's configured fields.

Segments are used by [Insights](/platform/reporting-analytics.md) dashboards and widgets.

### Customer tier

A customer tier is a single classification an account carries, such as Enterprise, Mid-market or SMB. Tiers are maintained per legal entity under **Settings › Accounts › Customer tiers**, and each account belongs to at most one.

| Field        | Description                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**     | Required, at most 200 characters, and unique within the legal entity. Leading and trailing spaces are removed, and names that differ only in capitalisation count as the same name |
| **Accounts** | Read-only. The number of accounts in the tier                                                                                                                                      |

A tier that any account uses cannot be deleted. The refusal names each tier in use with its number of accounts, so the accounts can be moved to another tier first. Renaming a tier changes the name on every account in it.

Anyone who can view accounts can see the tiers; creating, renaming and deleting them requires permission to update accounts.

> **Note on customer tier vs segment:** A customer tier is a field on the account, set directly and held once. A [segment](#account-segment) is a list of accounts built for filtering and reporting, and an account can appear in many segments.

### Settings

These defaults are applied to new accounts and can be overridden on the account.

| Setting                                             | Description                                                                            |
| --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Default account type                                | The type proposed for a new account                                                    |
| Default invoice delivery method                     | How new accounts' invoices are delivered                                               |
| Default our reference                               | The reference carried onto new accounts                                                |
| Default payment term                                | The payment term applied to new accounts                                               |
| Default invoice template                            | The invoice document template                                                          |
| Default invoice batch group                         | Which billing run new accounts join                                                    |
| Default accounts receivable                         | The receivable account new accounts post to                                            |
| Default unbilled accounts receivable                | Required for order-based revenue recognition                                           |
| Default tax template                                | The tax treatment applied to new accounts                                              |
| Default UBL attachment / Default ZUGFeRD attachment | Whether electronic invoice formats are attached                                        |
| Default invoice fee template                        | The [invoice fee template](/platform/billing.md#invoice-fees) attached to new accounts |

***

## 3. Creating and Updating Accounts

Creating an account validates it, applies the defaults above, assigns an account number, fills in any custom field defaults, records the creation in the account's history, and publishes the account-created event.

Validation requires a name, a currency, a valid account type, and an invoice delivery method the legal entity supports. An account cannot be created as a **prospect** if orders or invoices already reference it.

Updating an account revalidates it and compares the update with the stored account. If something changed, Younium saves it, records the change in the account's history, and publishes the account-changed event. New addresses and custom fields are added; existing addresses and subsidiaries are left alone, and a custom field that does not belong to the account is ignored.

> **Note on updates that change nothing:** An update that leaves the account and its custom fields exactly as stored saves nothing, adds no history entry and publishes no account-changed event, so webhook subscribers are not notified. Integrations that send the account on every synchronisation therefore no longer fill the history with identical entries. Updating an account that does not exist is rejected with an "Account not found" error.

### Owner and Signed by

**Owner** and **Signed by** are picked from the users of your Younium tenant. Anyone who can view accounts can see the list of users to pick from, without needing access to user administration.

| Rule                       | Behaviour                                                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Picking a user             | Only an active user of the tenant can be picked. Picking an inactive user is refused with the user's name, and a user from another tenant is not found |
| Deactivating a picked user | The user stays on the account and keeps showing by name. The field is only rechecked when it is changed                                                |
| Deleting a user            | The user is removed from **Owner** and **Signed by** on every account in the tenant                                                                    |
| Clearing                   | A blank value clears the field                                                                                                                         |

A customer tier given on an account must exist; one deleted in the meantime is refused with "The customer tier was not found. It may have been deleted."

Through the public API (v2), creating and updating an account accepts `owner` and `signedBy` as a user's email address or user id, and `customerTier` as the tier's name or id. The account is returned with `owner` and `signedBy` as the user's id, name and email address, and `customerTier` as its id and name; each is empty when not set.

A **prospect** can be created from a minimal set of details — name, references, email and currency — which is what lets a lead be captured before there is enough information for a full account.

### Online payment details

Where Stripe is active, an account can hold the customer and payment method it uses for collection. Before accepting a payment method, Younium checks with Stripe that it exists and belongs to the given customer; a payment method that fails this check, or belongs to a different customer, is rejected rather than stored. Revoking a payment method detaches it at Stripe and clears it from the account, so the two cannot disagree. Adding, removing or changing an account's online payment details, whether from the API or from Stripe activity such as a customer completing setup, a customer being deleted at Stripe, or bank account verification progressing or failing, publishes the account-changed event. **Stripe credential status** shows whether a usable payment method is present; **GoCardless mandate status** does the same for a direct debit mandate.

### Importing accounts in bulk

Accounts can also be created in bulk from a CSV file. Each column in the file is matched to an account field by its label, so the header row must use the same field labels shown on the account form; a header that does not match a field stops the import before any accounts are created. A template listing the current field labels is available to download before preparing the file.

**Customer tier** is matched to an existing tier by name. **Owner** and **Signed by** are matched to a user by the user field chosen for the lookup, typically the email address. The same rules as on the account form apply, so an inactive user cannot be newly picked, and a row that is refused leaves its account unchanged.

The file must be a **.csv** file no larger than 15 MB. A different file extension, an oversized file, or an unexpected content type is rejected up front, before any accounts are created, with the reason given in the error.

### Importing accounts with the Data Management Tool

The Data Management Tool can also import accounts from a mapped source file. Account appears in its entity list with a single operation, **Import**, once the feature is enabled for the tenant; until then the entity is not listed and the tool refuses Account requests. Importing requires both the permission to import accounts in the Data Management Tool and the permission to create accounts.

Each source row is one account, including its invoice and delivery address, so the source data needs a column that identifies each account. **Name** is the recommended field to map. Rows go through the same account creation as the account form, so number assignment, defaults, history and the account-created event behave as in section 3.

| Rule                                         | Behaviour                                                                                                                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**                                     | Required. A row without a name fails validation                                                                                                                                |
| **Currency**                                 | Optional. Left empty, the account takes the legal entity's base currency. A currency code or id is accepted                                                                    |
| **Parent account**                           | An existing account, given by account number, id or name. The account type then defaults to **Subsidiary**                                                                     |
| **Account type**                             | **Subsidiary** is refused unless a parent account is given                                                                                                                     |
| **Invoice address** and **Delivery address** | Each is created as a new address and becomes the account's default for that purpose. If any address field is set, the address country is required                              |
| **Invoice email Cc**                         | Every address must be a valid email address                                                                                                                                    |
| References                                   | Payment term, tax template, accounts receivable, unbilled accounts receivable, invoice batch group, invoice setting group and invoice template are matched to existing records |

> **Note on failed rows:** As with other Data Management Tool imports, one invalid row stops the whole run before any account is created.

***

## 4. Deleting an Account

An account can only be deleted once nothing financial depends on it. Younium refuses deletion, and tells you what to clear first:

| Blocker                                                       | What to do first                       |
| ------------------------------------------------------------- | -------------------------------------- |
| The account has invoices                                      | Cancel them                            |
| The account has orders, as the account or the invoice account | Delete them                            |
| The account has quotes                                        | Delete them                            |
| A quote or order is shared between this account and another   | Delete both accounts together          |
| The account has subsidiaries                                  | Remove or reassign them                |
| Charges are billed through the account for a subsidiary       | Resolve the subsidiary invoicing first |

The subsidiaries check applies to a parent account on its own: checking whether a single account can be deleted, checking several accounts at once, and deleting the account all refuse it while it has at least one subsidiary, even if the subsidiary is not part of the request. The refusal reads "Account has one or more subsidiaries account linked. Please remove subsidiaries first."

Where deletion is allowed, Younium removes the account, its deletable draft orders and quotes, its history and its addresses together, so nothing is left orphaned.

The alternative to deleting is **Inactive**, which stops an account being used for new business while keeping its history intact. For a customer who has traded, that is almost always what you want.

***

## 5. What Younium Tracks per Account

| Capability                   | What it gives you                                                                                    |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| Invoicing metrics            | When the account was last invoiced, and its current balance — posted invoice totals less settlements |
| Account balance              | The total outstanding across the account's open posted invoices                                      |
| Electronic invoicing address | The account's e-invoicing identity, resolved for the operator and scheme in use                      |
| DATEV customer export        | Customer data in the form the [DATEV](/erp-and-accounting-integrations/datev.md) export expects      |

### Account statement

An **account statement** is the account's invoice and payment history over a period, produced as a document. It is what a customer is sent when they query what they owe, and what an auditor is given when the account's receivables have to be evidenced.

The statement is generated for a date range and produced from a document template, so it carries the legal entity's details, the account's details and its invoice address, and can be branded like any other document Younium produces. The template chosen must itself be an account statement template; picking one set up for something else is rejected before the statement is produced.

**What appears on it.** The statement lists two kinds of line, ordered by date:

| Line       | Included when                                                             |
| ---------- | ------------------------------------------------------------------------- |
| An invoice | Its invoice date falls within the period                                  |
| A payment  | Its payment date falls within the period, and the payment has been posted |

Unposted payments never appear, and are not counted anywhere on the statement. A payment entered but not yet posted therefore leaves the account looking unpaid, which is the correct reading — nothing has been accounted for yet. This depends on the payment itself being posted, not on its batch: a payment added to a batch that was already posted, left behind when the batch was only partly posted, or reverted after posting stays off the statement until it is posted.

The **Account Balance Report** follows the same rule, so for the same date its figures agree with the statement and with the invoice's settled and unsettled amounts.

A payment line shows the amount settled against the invoice, including any write-off taken against it, together with the financial account the payment was received into.

**How the balance works.** The statement opens with the balance carried into the period: everything invoiced before the start date, less everything settled before it. Each line then moves that balance — an invoice raises it, a payment reduces it — so the closing figure is the balance at the end date and the reader can follow how it got there.

**Amounts outstanding.** Alongside the running balance, the statement carries the total still unsettled and breaks it down by how overdue it is:

| Band             | Meaning                        |
| ---------------- | ------------------------------ |
| **Current**      | Not yet due                    |
| **1–30 days**    | Up to a month overdue          |
| **31–60 days**   | One to two months overdue      |
| **61–90 days**   | Two to three months overdue    |
| **Over 90 days** | More than three months overdue |

This is the part a credit controller uses, since it separates a large balance that is not yet due from a small one that is badly overdue.

> **Note on accounts trading in more than one currency:** Amounts are never converted. Younium produces a separate statement section per currency the account has been invoiced in, each with its own opening balance, running balance, total outstanding and ageing bands. An account invoiced in two currencies gets two sets of figures rather than one consolidated total, because summing them would be meaningless.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/platform/accounts-contacts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
