> 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/platform-configuration.md). # Platform & Configuration *** ## 1. Overview This is the configuration the rest of Younium depends on: the companies you trade as, the currencies and exchange rates your figures are expressed in, the fiscal calendar your accounting closes against, and the custom fields that let you record what Younium does not hold as standard. It is worth setting up deliberately, because much of it becomes difficult to change later. Base currency cannot be changed once you have active orders. An accounting period cannot be reopened while a later one is closed. A custom field cannot be renamed once values are stored against it. None of that is arbitrary — each rule exists because changing the setting would contradict data already recorded. Everything here is scoped either to the tenant as a whole, or to the **legal entity** you are working in. *** ## 2. Legal Entities A legal entity is a company you trade as within your Younium tenant. Data and operations are scoped to whichever legal entity you have selected, so a business running several companies keeps their customers, orders, invoices and accounting apart while administering them in one place. | Field | Description | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Name** / **Short name** | The company's name, and a short form for documents | | **Organization Number** / **Tax Registration Number** | Registration numbers printed on invoices | | **Address**, **Email**, **Phone** | The company's own details | | **Base currency** | The currency the entity reports in | | **Bank Account**, **IBAN**, **BIC**, **Bankgiro**, **FIK creditor account** | Bank details printed on invoices and payment slips | | **Has parent** | Whether the entity sits under another | | **Virtual** | Marks an entity used to consolidate others rather than trade in its own right | | **Group reporting exchange rates** | Includes the entity in group-level exchange rate reporting | | **Export currency code for currency amount field** | Exports the currency code alongside amounts, for systems that expect them separately | A legal entity also carries the switches that enable each integration and several product features. Those are described in the article for the integration or feature concerned rather than here. ### Switching between legal entities You select which legal entity you are working in, and Younium confirms it belongs to your tenant before switching. Everything you then see and do — and everything the API returns — is scoped to that entity. ### Changing base currency Base currency can only be changed while the change would not contradict figures already recorded. Younium refuses it when: * Any **active order** exists, because its amounts are already expressed against the current base currency. * Any **exchange rate** points *to* the current base currency, because those rates would become meaningless. In practice this means base currency is a decision to get right during implementation. *** ## 3. Currencies and Exchange Rates ### Currencies A currency has a **Code** and a **Description**, and is scoped to a legal entity. One currency per entity is its base currency, shown as **Is base currency**. A currency can be deleted only when nothing uses it: no accounts, orders, invoices or quotes, and it is not the base currency. Deleting one removes the exchange rates to and from it, since those cannot survive without it. Adding a currency that already exists is rejected rather than duplicated. ### Exchange rates An exchange rate converts between two currencies over a period. | Field | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------- | | **From currency** / **To currency** | The pair being converted. Where the target is omitted through the API, base currency is assumed | | **Exchange Rate** | The rate itself | | **Effective from** / **Effective to** | The period the rate applies to | Rates can be maintained by hand or imported automatically from the ECB, OANDA or Sveriges Riksbank — see [Currency & Exchange Rates](/currency-and-exchange-rates-integrations/currency-exchange-rates.md). An imported rate that overlaps an existing period for the same pair is not applied, and the conflict is reported. Base currency amounts are derived from these rates across the platform, which is why an exchange rate pointing to the current base currency blocks changing it. *** ## 4. Custom Fields Custom fields let you record information Younium does not hold as standard — on accounts, orders, charges, invoices, subscriptions, measurements, usage and more. Once defined, a custom field behaves like any other field: it appears on the entity, can be set through the API, and can be used in reports, queries and account segments. | Field | Description | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Entity | Which record the field belongs to. Required | | Key | The field's identifier. Required, must start with a letter, and may contain only letters, digits and underscores. Unique per entity, without regard to letter case | | Name | The label shown to users. Required | | Type | Text, list, entity reference, and the other supported types | A **list** field can take its options and default from a reusable **custom field list**, so the same set of values can be shared across several fields and maintained in one place. An **entity** field references another record, such as an account or a user. A value written to a custom field is matched to its key without regard to letter case, and is always stored under the field's key exactly as configured — so setting a value on `region` and one on `Region` update the same field rather than creating two. ### What can and cannot be changed later Younium protects a custom field once it holds data: | Change | When it is refused | | ----------------------------------------- | ------------------------------------------------------------------------------------- | | Renaming the entity or key | Once any record holds a value for the field. The stored values are keyed on that name | | Deleting the field | Once any record holds a value for it | | Editing or deleting through custom fields | For financial dimension fields, which are managed as financial dimensions instead | Renaming a list, or changing its defaults, may be restricted while its values are in use. The practical consequence: choose the key carefully when you create the field, because the label can be changed afterwards and the key cannot. *** ## 5. Accounting Periods An accounting period is one interval in your fiscal calendar. Periods hold the journals that posting produces, and they are what revenue recognition recognises revenue into. | Field | Description | | ------------------------------------------------------ | ------------------------------------------------------------------ | | **Start date** / **End date** | The interval the period covers | | **Fiscal year**, **Fiscal quarter**, **Fiscal period** | Where the period sits in your fiscal calendar | | **Calendar year**, **Calendar month** | The calendar equivalent, where your fiscal year does not follow it | | **Closed** / **Closed date** | Whether the period is closed, and when it was closed | | **Description** | Free text | Periods are generated in bulk. Younium validates the parameters — how many periods, how they align to your fiscal calendar, and the year and month to start from — before creating anything. You can always see which periods are open, and which is the current one: the earliest period that is still open. ### Closing a period Closing a period is what fixes its figures. Younium checks two things first, and refuses the close if either fails: | Check | Why it blocks | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Deferred revenue in the period is not yet recognised | Closing would leave revenue you have earned unrecognised, in a period you can no longer post to | | The period has unposted journals | Those entries would never reach the ledger | You can run the validation without closing anything, which is the way to see what is outstanding before you commit. It reports draft orders and draft invoices dated inside the period, recurring and usage charges that fall due for invoicing within the period but have not yet been invoiced, and orders set to auto-renew whose term ends inside the period without a renewal in place. Evergreen subscriptions are covered by the same charge check as termed ones: a charge with no end date is judged only by how far it has been invoiced, so it is reported whenever that falls behind the period, exactly as a termed charge would be. On a successful close, Younium may generate and post the contract asset journals for the period, and publishes an event for each journal posted so integrations can pick them up. The response names the journals it created. ### Reopening a period A closed period can be reopened only when no later period is still closed. Later periods have to be opened first, working backwards. This is deliberate: reopening an earlier period while a later one is closed would allow entries that the later close has already accounted for. ### Revenue recognition journal Recognising deferred revenue for a period builds its revenue recognition journal. Younium discards any unposted journal already on the period first, so the journal is built from current data rather than a stale draft, then produces the new one from the deferred amounts outstanding. You see a summary before it is posted. See [Revenue recognition](/platform/revenue-recognition.md) for how the amounts in it were scheduled. ### Journals and reports in a period Beyond the revenue recognition journal, you can post a journal, review a journal summary, and list the journals belonging to a period. Two tax reports read from the same data: a **tax summary** aggregating by tax category and template, and a **periodic EU tax** report listing EU tax lines on posted and settled invoices by account. ### Deleting periods Periods can be deleted in bulk, subject to checks on what they contain — a period holding journals or recognised revenue cannot be removed. *** ## 6. Field Definitions Every field in Younium — standard as well as custom — has a definition holding its name, its label and its type. These definitions are what let reports, queries and account segments offer you valid fields and describe them properly. You do not normally need to think about this, with one exception: when you build a report or a segment condition, the fields you can choose and the names you refer to them by come from these definitions. A condition naming a field that does not exist will not resolve. *** ## 8. Outgoing E-mail Younium sends invoices, reminders, quotes and notifications by e-mail, and it sends them through your own mail account rather than on your behalf from Younium. Until outgoing e-mail is configured, nothing that relies on sending will work. E-mail settings live under **Settings → E-mail → E-mail settings**, and one of three methods is chosen there. | Method | Use when | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Custom SMTP settings** | You have an SMTP server, user name and password of your own — including a mail-sending service such as an account with a delivery provider | | **Microsoft** | Your mail is on Microsoft 365 and you want Younium to send through a registered application | | **Gmail** | Your mail is on Google Workspace and you want Younium to send as one of its accounts | Only one method is active. Where more than one is configured, Microsoft takes precedence over Google, and Google over SMTP. ### Settings that apply to every method | Setting | Description | | ------------------------- | ---------------------------------------------------------------------------------- | | **Senders email** | The address mail is sent from | | **Display name** | The name shown alongside that address | | **Subject** | The default subject, used whenever the action sending the mail does not supply one | | **Message** | The default body, on the same basis | | **Disable sending email** | Stops Younium sending mail at all, without discarding the configuration | **Disable sending email** is the setting to reach for when configuring a test environment against a live mail account, since it prevents mail reaching real customers while everything else behaves normally. > **Note on Gmail and the sender address:** With SMTP and Microsoft, Younium sets the from address and display name from the settings above. With Gmail, Google sets them from the connected account, so **Senders email** and **Display name** do not control what the recipient sees. ### SMTP An SMTP configuration needs the server, the port, and the user name and password to authenticate with. **Enable SSL** decides how the connection is secured: with it on, Younium connects over SSL directly; with it off, it upgrades the connection to TLS where the server offers it. Getting the port and the SSL setting to agree is the usual difficulty, and Younium's messages are specific about it. A failure to connect points at the server address; a timeout points at the server or the port; a certificate failure suggests port 465 where SSL is on, or turning SSL off where the server's certificate cannot be verified. A server that answers but does not speak SMTP is reported as such rather than as a credentials problem. ### Microsoft Sending through Microsoft 365 uses an application you register in your own Microsoft tenant, and Younium needs four values from it: the application identifier, the tenant identifier, a client secret, and the identifier of the mailbox to send from. The client secret is stored but never shown again. Younium indicates that a secret is held rather than displaying it, and leaving the field empty when saving keeps the existing one — so the rest of the configuration can be changed without re-entering the secret. ### Gmail Connecting Google Workspace is done by saving the settings and then completing Google's consent flow, which Younium starts for you. The permission to send mail on the account's behalf has to be granted during that flow; if it is not, the connection completes but every attempt to send afterwards fails for want of permission. Where that happens, disconnect and connect again rather than retrying the send. Each save of the settings while **Gmail** is selected issues a fresh consent link, replacing any link issued by an earlier save. That link works only once: completing it a second time, or returning to Google on an old or bookmarked one, fails silently and leaves you back on the e-mail settings page without connecting — save the settings again to get a current link. Disconnecting is done from the Google account rather than from Younium: Younium's access appears among the account's connections to third-party applications, and revoking it there ends the connection. Reconnecting also starts with revoking, because Google will not present the consent flow again while an existing grant stands. ## 7. Tax Templates A **tax template** holds the tax rates a legal entity charges, broken down by where the customer is. It is the answer to "what tax goes on this invoice line", and it is resolved from the customer's address rather than set by hand on each invoice. A template carries a name, a description, the period it is effective for, and the financial account that tax posts to. A template without a tax account cannot be used — Younium refuses to calculate tax on it and names the template, since the tax would otherwise have nowhere to post. Which template applies 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**. See [Accounts](/platform/accounts-contacts.md) for how that resolution works. ### Tax details Inside a template, each **tax detail** is one geographic case: a set of address criteria, up to three tax rates, and a tax category. | Field | What it does | | ---------------------------------------- | -------------------------------------------------------------------------------------------- | | **Country** | The country the detail applies to | | **State**, **County**, **City**, **Zip** | Narrower criteria, for jurisdictions where tax varies below country level | | **Tax 1**, **Tax 2**, **Tax 3** | The rates to apply. Each rate that is set produces its own tax line | | **Tax Category** | The category the tax is reported under, which also determines whether it counts as EU tax | | **External tax engine** | Whether tax for this case is calculated by a connected tax service instead of by these rates | A tax detail must carry a tax category. Younium refuses to calculate tax on a detail without one, naming the country and template, because a tax amount with no category cannot be reported. Adding a country to Younium does not add tax for it. A template needs a tax detail for that country before an invoice to a customer there can be produced, which is why a new market usually surfaces first as a failed invoice. ### How a tax detail is matched to an address Younium scores every tax detail in the template against the customer's address, counting how many of country, state, county, city and zip agree. Comparison ignores case, and a criterion only counts where both the detail and the address have a value — a detail leaving **City** empty is not thereby a match for every city, it simply does not score on city. The detail with the highest score applies. This is what lets one template hold a country-wide rate alongside a city-specific override: the override scores higher wherever it applies, and the country-wide rate applies everywhere else. > **Note on equally specific tax details:** Where two details tie for the highest score, Younium treats the address as having no tax details at all rather than choosing between them. The invoice fails with a message naming the address and the template, which reads like a missing tax detail while the real cause is two competing ones. If an invoice will not produce and the country plainly is in the template, look for a duplicate or an overlapping detail before adding another. An address with no country cannot be matched at all, and produces the same failure. ### How the rates are applied Each rate that is set on the matched detail produces a separate tax line on the invoice, named after the tax category and posted to the template's tax account. Two rates mean two lines, not one combined rate. Each rate is applied to the line's own amount rather than to the amount plus the preceding tax, so rates do not compound. Where the charge's price already includes tax, Younium works the tax back out of the amount instead of adding it on top. *** ## 9. Financial Accounts A financial account is one entry in your chart of accounts — the destination that payment methods, tax templates and other configuration point to when they need somewhere to post an amount. See [Payments](/platform/payments.md) for how a payment method uses one, and section 7 above for how a tax template's account is chosen. | Field | Description | | ----------------------------------------- | --------------------------------------------------------------------------------------- | | **Code** | Identifies the account. Required, and must be unique within the legal entity | | **Name** | Required | | **Description** | Free text | | **Inactive** | Marks the account as no longer in use | | **External ERP Id** / **External CRM Id** | The account's identifier in a connected system, used to match it during synchronisation | | **External code** | The account's code in a connected system, where that differs from its own **Code** | Saving a financial account requires both **Code** and **Name** — either left blank is refused. Both are trimmed of leading and trailing whitespace before saving, and a **Code** already used by another financial account in the legal entity is refused, whatever its case: `AR-100` and `ar-100` are treated as the same code. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/platform/platform-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.