> 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/data-management-tool.md).

# Data Management Tool

***

## 1. Overview

The Data Management Tool loads and changes data in Younium in bulk from a spreadsheet. You upload a file, tell Younium which column holds which field, and choose what to do with the rows: create new records, edit existing ones, or amend orders with a change order. It is how a customer base is migrated into Younium, how a catalogue of products is set up in one go, and how a change that has to reach hundreds of orders is made without editing each one by hand.

The tool works on three kinds of record: **orders**, **products** and **accounts**. Each has its own set of operations, and each operation offers its own columns. Every row is processed by the same rules as the equivalent change made in Younium itself, so an order created from a file is versioned, booked and numbered exactly like an order created on screen, and a row the product would refuse is refused here too.

A run happens in two stages. Younium first checks the whole file and stops before writing anything if any row is wrong, so a file either goes in or it does not. Only when every row is valid does it write them, one at a time, and report what it created or changed.

***

## 2. Core Concepts

### Entity and operation

The **entity** is the kind of record a file works on: Order, Product or Account. The **operation** is what the file does to it.

| Entity      | Operations             |
| ----------- | ---------------------- |
| **Order**   | Import, Edit, Change   |
| **Product** | Import, Update, Upsert |
| **Account** | Import                 |

### Mapping

Mapping pairs each column in the file with a field in Younium. A column that is not mapped is ignored, and Younium lists it in the result so nothing is dropped unnoticed. One column cannot be mapped to two fields.

### Group keys

A single record often spans several rows: an order with three products, or a product with tiered prices in two currencies. **Group keys** tell Younium which rows belong together. Each entity has a hierarchy of levels, and each level has a key column.

| Entity      | Levels, from top to bottom                                                 |
| ----------- | -------------------------------------------------------------------------- |
| **Order**   | Order → Order Product → Order Product Charge → Order Product Charge detail |
| **Product** | Product → Charge Plan → Charge → ChargeDetails                             |
| **Account** | Account                                                                    |

Rows that share the same key at a level become one record at that level. For an order, rows with the same order key form one order, their order product keys split it into products, their charge keys split each product into charges, and their detail keys split a charge into price tiers. A key only groups rows within the file. It does not have to match anything already in Younium, and it is never stored.

The top-level key must always be mapped. A row whose top-level key is empty becomes a record of its own. A lower-level key may be left unmapped when the file does not use that level, but if a row has values for a level whose key cell is empty, the row is refused.

### Reference fields

Many fields point at an existing record: an account, a product, a payment term, a currency. In a file, these are written as text and Younium finds the record. Most accept the record's number, name or id. Where a name matches more than one record, the row is refused rather than guessed.

### Mapping template

A mapping, together with the date format and decimal separator chosen for the file, can be saved as a **mapping template** and reused. See [Mapping templates](#8-mapping-templates).

***

## 3. How a Run Works

### Checking the file

Before anything is written, Younium checks every row: that the mapping is complete, that rows group cleanly, that each value has the right type and format, that every reference resolves, and that the record would pass the same rules as in Younium itself.

If any row fails, **nothing is written**. The result lists every error with the row it came from, and the file can be corrected and run again. This is what makes a file safe to rerun: a failed check leaves Younium exactly as it was.

The mapping can also be checked on its own, before a run. This quicker check covers the mapping, grouping, value types and formats, but not references or business rules, so a file that passes it can still fail the full check.

### Writing the rows

Once every row passes the check, Younium writes the records one at a time and shows progress as it goes. Each record succeeds or fails on its own. A record that fails at this stage is reported with its error, and the run carries on with the next one.

> **Note on partial results:** The check is all-or-nothing, the writing is not. Records written before a failure stay written. Read the result before running a file again, and remove the rows that already succeeded, or an Import will create them a second time.

### Cancelling

A run can be cancelled while it is in progress. Cancelled during the check, nothing is written. Cancelled while records are being written, Younium stops before the next record, and the records already written stay.

### The result

Each run returns a log grouped by kind:

| Group                 | Contains                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Errors**            | Problems with data, validation, mapping or grouping, and records that failed to write, each with the row it came from. Row numbers count the header as row 1 |
| **Operation results** | One line per record created or changed, with its number                                                                                                      |
| **Info**              | Notes about the run, such as a recommended field left unmapped                                                                                               |
| **Warnings**          | Warnings raised during the run                                                                                                                               |
| **Not mapped**        | Columns in the file that were not mapped to any field                                                                                                        |

The log belongs to the run. It is not kept after the result has been shown.

***

## 4. Values in the File

| Value                               | Rule                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Empty cell**                      | Ignored. An empty cell never overwrites anything, so in Edit, Change, Update and Upsert a field keeps its current value unless the file gives it a new one                                                                                                                                                                                                                                    |
| **Clearing a field**                | Write `NULL`, `CLEAR` or `[EMPTY]` (in any case) to remove a field's value. On a field that takes several values, this removes all of them. Mandatory fields and fields with a fixed list of values cannot be cleared, and the row is refused with a message naming the field                                                                                                                 |
| **Dates**                           | Written in the date format chosen for the file: YYYY-MM-DD (the default), MM/DD/YYYY, DD/MM/YYYY or DD-MM-YYYY. Fields that hold a time also accept the date followed by a time in HH:mm or HH:mm:ss                                                                                                                                                                                          |
| **Numbers**                         | Written with the decimal separator chosen for the file, comma by default. Spaces are ignored. A number that uses the other separator, including as a thousands separator, is refused                                                                                                                                                                                                          |
| **Checkboxes**                      | true, false, yes or no                                                                                                                                                                                                                                                                                                                                                                        |
| **Fixed lists**                     | Values such as a charge model or an order type are matched regardless of case and spacing, so *Sales Order* and *salesorder* are both accepted                                                                                                                                                                                                                                                |
| **Several values in one cell**      | Where a field takes several values, such as invoice fee templates or product features, separate them with a comma, a semicolon or the word AND (in any letter case), and mix them freely: *Admin fee, Paper invoice fee*, *Admin fee; Paper invoice fee* and *Admin fee AND Paper invoice fee* are equivalent. Spaces around a value are ignored and a value repeated in the cell counts once |
| **Values that contain a separator** | Wrap the value in double quotes to keep a comma, a semicolon or AND as part of it, for example *"Support AND hosting", Admin fee*. A doubled quote inside a quoted value is a literal quote. A quote only counts at the start of a value and must be closed and followed by a separator or the end of the cell, otherwise it is read as an ordinary character                                 |
| **Empty rows**                      | A file may contain at most five completely empty rows. More than that and the file is refused as a whole                                                                                                                                                                                                                                                                                      |

**Custom fields.** Every operation offers the custom fields you have configured for each level it covers, under their own names. Clearing a custom field removes its value.

***

## 5. Orders

### Import

Import creates new orders, each with its products, charges and price tiers. Rows that share an order key become one order.

| Level                           | Fields                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order**                       | **Account** (required), Status (**Draft** or **Active**), Order type, Subscription type, invoice account, invoice and delivery addresses, payment term, currency, invoice currency, payment method, billing period, invoice batch group, invoice template, invoice fee template, effective start and end dates, order date, initial term, renewal term, notice period, auto-renewal, invoice separate, references, description, remarks, and the external ERP and CRM ids                                                                     |
| **Order Product**               | **Product** (required when the level is used), charge plan, product name, external ids                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Order Product Charge**        | **Charge** (required when the level is used), picked from the product's charges by charge number, name or id. Also charge model and type, start and end options, milestones, effective start and end, quantity, price period, billing day, billing period, billing timing, period alignment, usage rating, unit of measure, revenue recognition rule, tax template, revenue accounts, invoiced-to date, estimated and ordered quantities, tax included, invoice lines per tier, tier decimal precision, description, remarks and external ids |
| **Order Product Charge detail** | **Tier** (required when the level is used), description, price base, price, list price, discount percentage or amount, from and to quantity, and whether the last tier is infinite                                                                                                                                                                                                                                                                                                                                                            |

An imported order follows the same rules as one created in Younium. An evergreen subscription cannot have an initial term, a renewal term, auto-renewal or a notice period. Terms and notice periods cannot be negative. An active sales order needs an order date. An order that is not invoiced separately cannot carry its own payment term, invoice template or our reference. The invoice fee template applies only to orders that are invoiced separately; on other orders it is ignored. See [Orders](https://docs.younium.com/platform/orders.md) and [Billing](https://docs.younium.com/platform/billing.md) for what each field does.

### Edit

Edit changes descriptive and invoicing fields on existing orders **without creating a new version**. It is meant for corrections: a reference typed wrongly at migration, a missing external id, a new invoice template.

| Level                           | Fields Edit can change                                                                                                                                                                                                                    |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order**                       | **Order** (required, by number, name or id), description, remarks, notice period, references, external ids, invoice batch group, use account invoice batch group, disable invoicing, payment term, invoice template, invoice fee template |
| **Order Product**               | **Order Product** (by number or id), product name, external ids                                                                                                                                                                           |
| **Order Product Charge**        | **Order Product Charge** (required when the level is used), description, remarks, external ids, invoice subsidiary                                                                                                                        |
| **Order Product Charge detail** | The detail's id, and its description                                                                                                                                                                                                      |

Fields that are not offered here, such as prices, dates or quantities, are changed with **Change**.

On an order that is not invoiced separately, the payment term and references cannot be changed, and an invoice template given in the file is not kept. Invoice fee templates given in the file replace all the order's existing fee templates, and clearing the field removes them all. Changing the notice period recalculates the notice date.

> **Note on previous versions:** Edit can target a previous version of an order, but only to change text and custom fields. A row that changes anything else on a previous version is refused with an error naming the fields. See [Editing previous versions](https://docs.younium.com/platform/orders.md#editing-previous-versions).

Where scheduled price adjustments are in use, Edit also offers the price adjustment columns, so a schedule can be set on many orders from one file. See [Scheduled Price Adjustments](https://docs.younium.com/platform/scheduled-price-adjustments.md).

### Change

Change amends existing orders with a **change order**: each order in the file gets a new version from the effective change date, with its bookings and metrics recalculated, exactly as an amendment made in Younium. Use it for price changes, quantity changes, term changes and adding products.

| Level                           | Fields                                                                                                                                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Order**                       | **Order** (required), **Effective change date** (required), and most of the order fields offered by Import, plus disable invoicing, **Booking notes**, **Booking change type** and **Booking classification** |
| **Order Product**               | **Order Product** (by number or id) to change an existing product, or **Product number** to add a product from the catalogue, with an optional charge plan. Also product name and external ids                |
| **Order Product Charge**        | The charge, identified by **Order Product Charge** or by **Charge number** on the order product, and the same charge fields as Import, plus specific date for first invoice and invoice subsidiary            |
| **Order Product Charge detail** | The detail's id or **Tier**, description, price base, price, list price, discount percentage or amount, and from and to quantity                                                                              |

**Price tiers.** On a charge with one price, the row's values update it, and if several rows target it, the last one wins. On a volume or tiered charge, a row updates the tier it matches by id, or failing that by tier number. A row that matches no tier adds a new one. If both an id and a tier number are given, they must point at the same tier.

**Billing period.** Setting a billing period on a charge turns off **Billing period on order** for that order.

**Cancelled orders.** A cancelled order can be changed only while its cancellation is still pending, and even then its effective end date cannot be changed.

**Booking notes.** A note given in the file is recorded on the booking the change produces. An empty cell records none.

### Accepted values

Fields with a fixed list of values accept only the values below. Matching ignores case and spaces, so *Sales Order* is read as *SalesOrder*.

| Field                    | Level                          | Accepted values                                                                                    |
| ------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------- |
| **Status**               | Order (Import only)            | Draft, Active                                                                                      |
| **Order type**           | Order (Import only)            | Subscription, SalesOrder                                                                           |
| **Subscription type**    | Order                          | Termed, Evergreen                                                                                  |
| **Payment method**       | Order                          | Invoice, Stripe, GoCardless                                                                        |
| **Billing period**       | Order and Order Product Charge | Monthly, Quarterly, Annual, EndOfTerm, Biannual                                                    |
| **Charge model**         | Order Product Charge           | Flat, Quantity, Volume, Tiered, Rated                                                              |
| **Charge type**          | Order Product Charge           | Measured, Usage, Recurring, OneOff                                                                 |
| **Start on**, **End on** | Order Product Charge           | AlignToSubscription, SpecificDate, Milestone                                                       |
| **Price period**         | Order Product Charge           | Monthly, Quarterly, Annual                                                                         |
| **Usage rating**         | Order Product Charge           | Sum, Max, Average                                                                                  |
| **Billing day**          | Order Product Charge           | None, FirstDayOfMonth, LastDayOfMonth, FromOrder, FromCharge, FromAccount, SpecificDay, DaysOffset |
| **Billing timing**       | Order Product Charge           | InAdvance, InArrears                                                                               |
| **Period alignment**     | Order Product Charge           | None, AlignToOrder, AlignToCharge, AlignToMonth, AlignToCalendarQuarter, AlignToDate               |
| **Price base**           | Order Product Charge detail    | Flat, PerUnit                                                                                      |
| **Booking change type**  | Order (Change only)            | Upsell, Downsell, Renewal, None, PriceAdjustment                                                   |

***

## 6. Products

### Import

Import creates new products with their charge plans, charges and prices.

| Level             | Fields                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Product**       | **Name** and **Product Type** (both required; Simple, MultipleCharges, MultipleChargePlans or Full), product category, activation date, end of sales, end of renewal, end of life, framework product, external ids                                                                                                                                                                                                   |
| **Charge Plan**   | **Charge plan name** (required when the level is used), effective start, end of sales, effective end                                                                                                                                                                                                                                                                                                                 |
| **Charge**        | **Name** (required when the level is used), end of sales, model, type, price period, usage rating, measurements rule, billing day, specific billing day, offset billing days, billing period, billing period alignment, billing timing, default quantity, invoice lines per tier, tax included, unit of measure, tax template, revenue recognition rule, revenue accounts, recognised revenue template, external ids |
| **ChargeDetails** | **Tier** (required when the level is used), description, from and to quantity, price, price base, currency code, tier decimal precision, and whether the last tier is infinite                                                                                                                                                                                                                                       |

A product with more than one charge plan needs a name for each plan. Within a charge, each currency can have each tier only once. When a charge is priced in more than one currency, every price detail needs its currency code.

### Update

Update changes products that already exist, and only what already exists: it never adds a charge plan, a charge or a price detail. The product is identified by number, name or id; charge plans and charges by number or id; price details by id. A reference that matches nothing is refused with an error saying which record was not found.

All product, charge plan and charge fields offered by Import can be updated. Dates cannot be earlier than 1 January 1950. This includes a charge's end of sales, and the date is checked before anything is written, so one row with an earlier date stops the whole batch. Clearing the end of sales column, as described in section 4, removes the date again. Price details on rated charges are ignored. Products shared from another legal entity cannot be changed from a file.

### Upsert

Upsert updates a product's charge plans, charges and prices, and **creates the ones it cannot find**. At product level it offers only the product reference and its name. Below that:

| A row that…                                                | Does                                               |
| ---------------------------------------------------------- | -------------------------------------------------- |
| References an existing charge plan, charge or price detail | Updates it                                         |
| Gives no charge plan reference                             | Creates a new charge plan, which then needs a name |
| Gives no charge reference                                  | Creates a new charge, which then needs a name      |
| Gives a price detail without an id                         | Adds a new price detail                            |
| References something that does not exist                   | Is refused                                         |

A new charge plan created without any charge rows gets a default charge. A row with no charge plan data at all is refused. The upserted product is validated in full, as it would be when saved in Younium.

> **Note on Update versus Upsert:** Both start from an existing product. Update is the safe choice for correcting values, because a mistyped reference fails rather than creating something. Upsert is the choice for extending a product, such as adding a charge plan or a currency, and creates whatever the file does not reference.

### Accepted values

Fields with a fixed list of values accept only the values below. Matching ignores case and spaces, so *Multiple Charges* is read as *MultipleCharges*.

| Field                        | Level                       | Accepted values                                                                                    |
| ---------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
| **Product Type**             | Product (Import and Update) | Simple, MultipleCharges, MultipleChargePlans, Full                                                 |
| **Model**                    | Charge                      | Flat, Quantity, Volume, Tiered, Rated                                                              |
| **Type**                     | Charge                      | Measured, Usage, Recurring, OneOff                                                                 |
| **Price period**             | Charge                      | Monthly, Quarterly, Annual                                                                         |
| **Usage rating**             | Charge                      | Sum, Max, Average                                                                                  |
| **Measurements rule**        | Charge                      | LatestDate, SumLatestDate                                                                          |
| **Billing day**              | Charge                      | None, FirstDayOfMonth, LastDayOfMonth, FromOrder, FromCharge, FromAccount, SpecificDay, DaysOffset |
| **Billing period**           | Charge                      | Monthly, Quarterly, Annual, EndOfTerm, Biannual                                                    |
| **Billing period alignment** | Charge                      | None, AlignToOrder, AlignToCharge, AlignToMonth, AlignToCalendarQuarter, AlignToDate               |
| **Billing Timing**           | Charge                      | InAdvance, InArrears                                                                               |
| **Price base**               | ChargeDetails               | Flat, PerUnit                                                                                      |

***

## 7. Accounts

### Import

Import creates new accounts. Each account is one row, or several rows with the same account key.

| Area                         | Fields                                                                                                                                                                                                                                              |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account                      | **Name** (required), account type (Customer, Reseller, Subsidiary, Prospect or Other), parent account, currency, description, site, inactive, year founded, employees, organisation number, tax registration number, references                     |
| Invoicing                    | Invoice email, invoice email Cc, reminder email, invoice delivery method, payment term, tax template, invoice batch group, invoice setting group, invoice template, disable invoice reminders, attach UBL to invoice, attach ZUGFeRD XML to invoice |
| E-invoicing                  | E-invoice address, e-invoice address scheme, e-invoice operator                                                                                                                                                                                     |
| Accounting                   | Accounts receivable, unbilled accounts receivable, external ERP and CRM ids                                                                                                                                                                         |
| Invoice and delivery address | Name, description, street, street 2, city, state, county, zip and country                                                                                                                                                                           |

An account without a currency gets the legal entity's base currency. Giving a parent account makes the account a subsidiary unless another type is given, and a subsidiary must have a parent that is not itself a subsidiary. Any address value requires that address's country, and the country must be active. Every Cc address must be a valid email address. Address fields cannot be cleared.

Importing accounts requires two permissions: **Import Account in Data Management** and **Create accounts**.

### Accepted values

Fields with a fixed list of values accept only the values below. Matching ignores case and spaces, so *Electronic Invoice* is read as *ElectronicInvoice*.

| Field                       | Accepted values                                                            |
| --------------------------- | -------------------------------------------------------------------------- |
| **Account type**            | Customer, Reseller, Subsidiary, Prospect, Other                            |
| **Invoice delivery method** | Email, Print, ElectronicInvoice, ExternalPrint, AutomaticElectronicRouting |

***

## 8. Mapping Templates

A mapping template saves everything needed to run the same kind of file again: the entity and operation, which column maps to which field, and the date format and decimal separator. Templates belong to the legal entity, so a template saved by one user is available to everyone who uses the tool there.

Each template needs a name, and two templates cannot share the same name. Templates can be updated, deleted and downloaded. Younium provides two to start from, **Standard Order Template** and **Standard Product Template**, both for Import.

The date format and decimal separator a template saves are the ones described in [Values in the File](#4-values-in-the-file).


---

# 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/data-management-tool.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.
