> 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/products-pricing.md). # Products & Pricing *** ## 1. Overview Products & Pricing is where you define what you sell and what it costs, before any of it reaches a quote, an [order](/platform/orders.md) or a [subscription](/platform/subscriptions.md). It is the catalogue the rest of Younium draws on: a salesperson picks from it, billing prices from it, and revenue recognition inherits its rules from it. The catalogue has three levels. A **product** is the thing you sell. Within a product, a **charge plan** groups the charges sold together — a way of offering the same product on different commercial terms. Within a plan, each **charge** is a separately priced, separately billable component: it decides what is charged, how the price is calculated, how often it is invoiced, and which revenue and tax treatment applies. Changing the catalogue affects future sales only. When a product is sold, its charges are copied onto the order, so existing orders and subscriptions keep the terms they were sold on and are unaffected by later catalogue edits. Framework products are the one deliberate exception, described below. *** ## 2. Core Concepts ### Product A product is the top-level catalogue record. It carries a name, an automatically assigned product number, an optional image and category, a set of lifecycle dates, and any custom fields you have configured for products. | Field | Description | | ----------------------------------------- | ---------------------------------------------------------------------------------- | | **Product number** | Assigned automatically when the product is created | | **Name** | Required | | **Product Type** | How many charge plans and charges the product can hold (see below) | | **Product category** | Optional classification | | **Activation** | When the product becomes available to sell | | **End of sales** | Last date the product can be sold to a new customer | | **Active product** | Read-only. Ticked while **End of sales** is empty or still in the future | | **End of renewal** | Last date a subscription containing the product can be renewed | | **End of life** | Product retirement | | **Is framework product** | Marks the product as a framework catalogue (see below) | | **Is shared** | Makes the product available across legal entities rather than owned by one | | **Legal entity** | The legal entity that owns the product | | **External ERP Id** / **External CRM Id** | Identifiers used when the product is matched to a record in a connected ERP or CRM | The lifecycle dates are how you retire a product without disrupting customers already on it: stopping new sales, stopping renewals, and full retirement are three separate decisions with three separate dates. **Active product** is derived from **End of sales**, so it reflects sellability without anyone having to maintain a separate flag. ### Product Type The product type fixes the shape of the product — how many charge plans it can hold, and how many charges sit in each. | Product Type | Structure | | ------------------------- | -------------------------------------------------- | | **Simple** | One charge plan holding one charge | | **Multiple charges** | One charge plan holding several charges | | **Multiple charge plans** | Several charge plans, each holding one charge | | **Full** | Several charge plans, each holding several charges | ### Charge plan A charge plan groups the charges sold together under one product. It has its own name and number, a validity window, and its own custom fields. Offering a product on more than one plan lets you sell the same thing on different commercial terms without duplicating the product. | Field | Description | | --------------------------------------- | -------------------------------------- | | **Charge plan number** | Assigned automatically | | **Charge plan name** | Required | | **Effective start** / **Effective end** | The window in which the plan is valid | | **End of sales** | Stop selling this plan after this date | A new product is created with a default charge plan and a default charge if you do not supply them, so a product is never left with nothing to sell. A charge plan cannot be deleted while a quote or order that is not deleted references it. To withdraw a plan that has been sold, set its **End of sales** date instead — existing subscriptions keep the plan they were sold on. ### Charge A charge is the priced, billable component inside a charge plan. It answers four questions: what is charged, how the price is calculated, when it is invoiced, and how the resulting revenue and tax are treated. **What is charged** — the **Type**: | Type | Use | | ------------- | ------------------------------------------------------------------------------- | | **One-off** | A single billing event, such as a setup or implementation fee | | **Recurring** | A fixed periodic fee, the usual shape of a subscription line | | **Usage** | Consumption billed after the fact, from usage recorded against the subscription | | **Measured** | Billed on a measured quantity, using the **Measurements rule** below | **How the price is calculated** — the **Model**: | Model | Behaviour | | ------------ | -------------------------------------------------------------------------------------------------- | | **Flat** | A fixed price regardless of quantity. Not available for Usage or Measured charges | | **Quantity** | A single price per unit, multiplied by the quantity sold | | **Volume** | The whole quantity is priced at the rate of the single tier it falls into | | **Tiered** | Each tier is priced at its own rate, and the quantity is charged progressively across them | | **Rated** | No catalogue price. The amount comes from the rated usage itself. Available for Usage charges only | > **Note on Volume versus Tiered:** Both read the same price tiers, but they apply them differently. Given tiers of 1–100 and 101–200, a quantity of 150 priced on **Volume** is charged entirely at the 101–200 rate. The same quantity priced on **Tiered** is charged for the first 100 at the first tier's rate and the remaining 50 at the second. Tiered charges also show a blended unit price — the total divided by the quantity — rather than any single tier's rate. This is the distinction customers most often need when reconciling an invoice. > **Note on flat tiers:** When a **Tiered** charge uses a **Price base** of Flat, each tier the quantity reaches contributes its price once, rather than being multiplied by the quantity in that tier. This is how a stepped fee is modelled, as opposed to a progressive per-unit rate. **When it is invoiced, and how revenue and tax are treated:** | Field | Description | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Charge number** | Assigned automatically | | **Default quantity** | The quantity proposed when the charge is added to an order | | **Price period** | The period the catalogue price is expressed in — Monthly, Quarterly or Annual | | **Billing period** | How often the charge is invoiced | | **Billing Timing** | Whether the period is invoiced in advance or in arrears | | **Billing day**, **Specific billing day**, **Offset billing days** | Where in the period the invoice date falls | | **Billing period alignment** | What the billing period aligns to — the order, the charge, a calendar month or quarter, or a fixed date | | **Usage rating** | For Usage charges, whether the period's usage is summed, or its maximum or average taken | | **Measurements rule** | For Measured charges, whether the measurement on the latest date is used, or all measurements on that date are summed | | **Tax included** | Whether catalogue prices are inclusive of tax | | **Tax template** | The tax treatment applied to the charge | | **UOM** / **Unit of measure** | The unit quantities are expressed in | | **Invoice lines per tier** | Whether a tiered charge produces one invoice line per tier, or a single combined line | | **Revenue recognition rule** | The rule that drives [revenue recognition](/platform/revenue-recognition.md) for this charge | | **Deferred revenue account**, **Recognized revenue account**, **Contract asset account** | The accounts revenue flows through | | **Use Recognized Revenue Template** / **Recognized revenue template** | Optional template applied to recognised revenue | | **Estimated quantity** / **Estimated usage** | Forecasting inputs used before actual quantities are known | | **Features** | Reusable feature codes attached to the charge | | **External ERP Id** / **External CRM Id** | Identifiers for matching the charge in a connected ERP or CRM | ### Price details Prices are held as tiers, one set per currency. A charge priced in three currencies has three sets, and each is maintained independently — there is no automatic conversion between them. | Field | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Tier** | Tier position. Single-price charges use one tier | | **Currency** | Required. Prices are defined per currency | | **From quantity** / **To quantity** | The quantity band the tier applies to | | **Last tier is infinite** | Removes the upper bound on the final tier, so any quantity above it is priced there | | **Price** | The price in that currency | | **Price base** | Whether the tier price is a flat amount or per unit. Per unit requires the Tiered or Volume model | | **Tier decimal precision** | How many decimals the quantity boundaries may carry, from 0 (whole numbers only) to 7. The same value applies to every tier in a currency | | **Description** | Optional label for the tier | Two active tiers for the same currency and band are rejected. Removing a tier closes the gap: remaining tiers are renumbered and their quantity bands adjusted, per currency. Flat and Quantity charges hold a single tier — any tiers beyond the first are removed when the charge is saved. Rated charges hold no prices at all, and any existing prices are removed if a charge is changed to Rated. ### Tier boundaries on Tiered and Volume charges Tiers must form an unbroken ladder within each currency. The first tier starts at zero, and each later tier begins exactly one step above where the previous one ended. A gap, an overlap, or two tiers whose boundaries merely touch are all rejected — there must be no quantity that falls into two tiers or none. **Tier decimal precision** decides how large that step is. At the default precision of 0, tiers step by whole units, so a tier ending at 100 is followed by one starting at 101. At precision 2, they step by 0.01, so the next tier starts at 100.01. Fractional boundaries are accepted on every tenant, since it is the precision declared on the charge itself that decides what is allowed. **Show tier quantity precision** only decides whether the precision control is shown when a tier is edited; switching it off does not restrict which boundaries a charge can be saved with. When a charge is sold, the precision is copied onto the order or quote from the price tiers in the matching currency, and it survives change orders and conversion from quote to order unchanged — so a subscription keeps the tier granularity it was sold on. > **Note on tiers with no upper limit:** To leave the top tier open-ended, mark it **Last tier is infinite**. This is honoured as soon as it is saved, whether the charge is being priced for the first time on a new order or subscription or is changed afterwards, including a charge that has only the one tier. Setting **To quantity** to zero does not mean unbounded, and is rejected on save — the one exception being a leading tier running from zero to zero. That tier can stand alone, deliberately billing nothing at any quantity, or head a longer ladder, so that quantity zero is free and later tiers price everything above it. A charge still holding a zero upper boundary from before this rule prices and displays correctly, and continues to contribute to recurring-revenue figures, but it cannot be edited further or invoiced until the tier is corrected. ### Framework products A framework product is a catalogue of usage-based add-ons that customers draw on over the life of an agreement, rather than a product sold once at a fixed scope. It behaves differently from an ordinary product in three ways: * It must use the **Multiple charges** product type — one charge plan. * It may contain **Usage charges only**. Any other type is rejected. * New charges added to it **propagate to existing framework orders**. This is the one case where a catalogue change reaches agreements already sold, which is the point: it extends what a customer can consume without amending their subscription. Propagation reaches the current version of every order using that charge plan, and each new charge takes its dates from the order it lands on rather than from the date it was added. Because charges propagate, framework products are edited one charge at a time rather than saved as a whole. ### Product categories and features **Product categories** classify products. The category set as the default in catalogue settings cannot be deleted while products still reference it. **Product features** are reusable codes attached to charges, unique per code. Cloning a product re-links the same features rather than duplicating them. *** ## 3. Managing the Catalogue You can build a product in one action or in stages. Saving a product with its full plan, charge and price structure replaces that structure in one step: plans and charges you have removed are deleted, new ones added, and prices recalculated — and nothing is committed unless the whole product validates. Building it up piece by piece instead, adding plans, charges and prices separately, validates each part as you save it. **Cloning** an existing product copies its plans, charges, prices and custom field values under new numbers, and re-links the same product features. It is the fastest way to create a variant of something you already sell. **Previewing prices** calculates the tiers a charge would produce without saving anything, so you can check pricing before committing it to the catalogue. Two constraints apply throughout. A charge plan or charge cannot be deleted while a quote or order references it. And a framework product cannot be saved as a whole — each charge is saved individually. ### What Younium applies automatically when a charge is saved Some combinations are corrected on save rather than rejected, so a charge is always stored in a state that can be billed: | Type or Model | Applied automatically | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **One-off** | Billed in advance, aligned to the charge, with a Monthly billing period and price period — a one-off has a single billing event, so neither period is meaningful | | **Usage** | Billed in arrears | | **Rated** | Any prices on the charge are removed | | **Flat** or **Quantity** | Any tiers beyond the first are removed | A charge saved with no prices at all is given a default price tier in the base currency. ### Events Updating charges or their price details in the catalogue publishes a product-updated event, for webhooks and integrations to act on. A single save can cover charges from several products; Younium publishes one event per affected product, not one per charge. Publishing is best-effort: if a webhook cannot be delivered, the catalogue change is still saved. ### Settings Catalogue defaults are applied when a new product, charge plan or charge is created. They save repeated data entry and keep a catalogue internally consistent; each can be overridden on the individual record. | Setting | Description | Default | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | **Default category** | Product category applied to new products. Cannot be deleted while products reference it | Tenant-configured | | **Default activation date** | How the activation date is set on new products | Tenant-configured | | **Default effective start date** | Effective start date applied to new charge plans | Tenant-configured | | **Default charge type for products** | Charge type proposed for new charges | Tenant-configured | | **Default charge Model** | Pricing model proposed for new charges | Tenant-configured | | **Default price period** | Price period applied to new charges | Tenant-configured | | **Default billing period** | Billing period applied to new charges | Tenant-configured | | **Billing Timing** | In advance or in arrears, applied to new charges | Tenant-configured | | **Billing period alignment** | Period alignment applied to new charges | Tenant-configured | | **Default billing day** | Billing day applied to new charges | Tenant-configured | | **Offset billing days** | Offset applied to the billing day on new charges | Tenant-configured | | **Default tax template** | Tax template applied to new charges | Tenant-configured | | **Default tax inclusion** | Whether new charges treat prices as tax-inclusive | Tenant-configured | | **Default unit of measure** | Unit of measure applied to new charges | Tenant-configured | | **Default revenue recognition rule** | Revenue recognition rule applied to new charges | Tenant-configured | | **Default deferred revenue account**, **Default recognized revenue account**, **Default contract asset account** | Revenue accounts applied to new charges | Tenant-configured | | **Invoice lines per tier** | Whether tiered charges produce one invoice line per tier | Tenant-configured | | **Show tier quantity precision** | Shows the decimal precision controls for the From and To quantity fields on a price tier. Decimal tier boundaries are accepted regardless of this setting — it only controls whether the control is shown | Off | *** ## 4. Validation Younium rejects a charge that cannot be billed coherently, in the catalogue and again when the charge is placed on an order. Catalogue rules protect the product definition; order rules additionally check the charge against the dates of the order it is being sold on. | Rule | Why | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A charge must have a name | — | | The **Rated** model requires the **Usage** type | Rated pricing has no catalogue price to fall back on | | A **One-off** charge cannot be billed in arrears | It has only one billing event | | A **One-off** charge cannot align to a fixed date | Its period is the charge itself | | The **Flat** model cannot be used with **Usage** or **Measured** | Consumption has no fixed price | | A **Rated** charge cannot carry prices | Its amounts come from rated usage | | A framework product cannot contain a non-Usage charge | Framework products exist for consumption-based add-ons | | A Usage charge's **Price period** cannot be longer than its **Billing period** | The invoice would cover less than one priced period. A quarterly price cannot bill monthly; an annual price cannot bill monthly, quarterly or biannually. Rated charges are exempt, having no priced period | | Subscription charge dates must fall within the subscription's own dates | A charge cannot be billed outside the agreement. On termed subscriptions a charge may start the day after the end date | | A sales order charge cannot start before the order date | — | | A charge priced on a milestone must name the milestone | — | Tier boundaries on **Tiered** and **Volume** charges carry their own rules, applied wherever tiers are saved — in the catalogue, or on an order or quote that edits them: | Rule | Why | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tiers must be contiguous within a currency, with no gap, overlap, or touching boundaries | Every quantity must fall into exactly one tier | | Boundaries cannot carry more decimals than the charge's **Tier decimal precision** | The ladder would no longer step evenly | | Precision must be the same across a currency's tiers, and between 0 and 7 | — | | **To quantity** cannot be zero, other than on a leading tier running from zero to zero | Zero is ambiguous everywhere else. A leading zero-to-zero tier — alone or followed by further tiers — genuinely covers only quantity zero; use **Last tier is infinite** for an open-ended tier instead | When a charge fails validation on an order, Younium reports the charge and the reason so it can be corrected before the order is saved. *** ## 5. Product Visibility Products can be restricted so that only certain users see them. A restricted product is invisible to users without access — it does not appear in the catalogue and cannot be retrieved directly, including by its identifier through the API, which reports it as though it did not exist. Products with no restriction are visible to everyone. Use restrictions to keep products under development, or products for a specific market, out of the general catalogue. *** ## 6. Preprocessing Imported Usage A **Usage** or **Measured** charge is priced from data recorded against the subscription rather than from the catalogue, and that data usually arrives from the system that produced it. What that system exports rarely matches what Younium needs: it may key rows differently, split one billable charge across several rows, or carry rows that should not be billed at all. **Preprocessing rules** transform each incoming row before Younium matches it to a charge. A rule can rewrite a value, derive one value from others, or drop the row entirely, which means the export can be loaded as it comes rather than reshaped by hand or in the source system first. Rules are held per legal entity and apply to every import that asks for them. They are not attached to a particular file or charge, so a rule added for one feed changes the behaviour of every later import that runs with preprocessing switched on. ### What a rule contains | Setting | Description | | -------------- | -------------------------------------------------------------------- | | **Name** | What the rule is called in the list. It has no effect on evaluation | | **Rule** | The expression, in the form below | | **Applies on** | Whether the rule runs on usage imports, measurement imports, or both | The **Applies on** setting is what keeps the two data flows apart: a rule set to usage is never evaluated during a measurement import, and vice versa. A rule that should govern both is set to apply to both rather than duplicated. ### Rule form A rule takes one of three forms: | Form | Behaviour | | -------------------------------------------------------------- | ---------------------------------------------------------- | | *expression* | Evaluated against every row | | **if** *condition* **then** *expression* | The expression is evaluated only where the condition holds | | **if** *condition* **then** *expression* **else** *expression* | One expression or the other is evaluated on every row | Source columns are referenced by name in double braces — `{{FieldA}}` reads the column called *FieldA* on the row being processed. An expression either assigns to a column, which may be one the file already has or a new one, or is the word **skip**, which discards the row. ``` if {{Country}} = 'SE' then {{UsageKey}} = 'nordics' if {{Amount}} = 0 then skip {{UsageKey}} = {{Product}} + '-' + {{Region}} ``` The first rewrites a key so that rows arriving under a country-level key are matched to a single charge. The second drops rows that would bill nothing. The third builds a key that the source file does not contain by concatenating two columns it does. ### What an expression can do Comparisons use `<`, `<=`, `>=`, `<>`, `=`, `IN` and `LIKE`. Arithmetic uses `+`, `-`, `*`, `/` and `%`, and `+` also concatenates strings. `LIKE` accepts either `*` or `%` as its wildcard, at the start of a pattern, the end, or both — `'*product*'`, `'*product'` and `'product*'` are all valid. A wildcard in the middle of a pattern is not: `'te*xt'` is rejected. To match a literal `*` or `%`, enclose it in square brackets; to match a literal bracket, enclose that in brackets too, as `[[]` or `[]]`. These functions are available: | Function | What it does | | -------------------------------------- | -------------------------------------------------------------------------------------- | | `CONVERT(expression, type)` | Converts a value to a named type, as `CONVERT({{Total}}, 'System.Int32')` | | `LEN(expression)` | The length of a string | | `ISNULL(expression, replacement)` | The value, or the replacement where the value is empty | | `IIF(condition, then, else)` | One of two values, chosen by a condition | | `TRIM(expression)` | The value with leading and trailing whitespace removed, including tabs and line breaks | | `SUBSTRING(expression, start, length)` | Part of a string, from a starting position for a given length | ### How rules are applied Every rule that matches the import's type is evaluated against every row, in turn. A row survives only if no rule discards it: the first **skip** that applies drops the row, and the rules after it are not evaluated for that row. Because each rule sees the row as earlier rules left it, order matters — a rule that reads a column another rule writes must come after it. Preprocessing is off unless the import asks for it. An import run without it loads the file exactly as supplied, regardless of how many rules exist. > **Note on testing a rule before relying on it:** A rule can be tried against a sample row and the transformed result inspected, which is the practical way to develop one. An expression that cannot be evaluated fails the row rather than being ignored, so a rule with a mistake in it costs the whole import rather than passing the data through untouched. *** ## 7. Recording Usage and Measurements Through the API Usage and measurements can be recorded one entry at a time through the public API. An entry is tied to the subscription it belongs to by a charge, a product, an order and an account, and any of these can be supplied. ### Reference checks Younium always checks that the references on an entry belong together, so an entry cannot link one account's charge to another account. The check does not depend on any option in the request. | Supplied | What Younium checks | | --------------------------------------------- | ------------------------------------------------------------------------------------------------- | | A charge | The charge exists, and any product, order and account supplied are the ones the charge belongs to | | A product, no charge | The product exists, and any order and account supplied are the ones the product belongs to | | An order and an account, no charge or product | The account is the account on the order | An entry that fails any check is rejected and nothing is recorded. The response names each reference that does not align: the product, the order or the account. ### Optional data validation A request can also ask for the data itself to be validated. This is separate from the reference checks above and is off unless requested. It applies the business rules for the charge type, including the rated price rules and the credit charge rules. When data validation is requested and the references match more than one charge, the entry is rejected unless at least one of those charges matches every reference supplied. --- # 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/products-pricing.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.