> 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/orders.md). # Orders *** ## 1. Overview An order is the commercial record of what a customer has agreed to buy. Younium uses one order model for two quite different things: **subscriptions**, which are recurring agreements that change over their lifetime, and **sales orders**, which are one-time purchases that may involve delivery and payment before they are complete. Both carry an account, a currency, products and charges, optional discounts and milestones, and a status showing where they have reached. Orders are **versioned**. When an agreement changes materially, Younium does not overwrite it — it creates a new version under the same order number and keeps the previous one. That is what lets you see what a customer was sold last year, bill correctly for a period that spans an amendment, and undo a change that should not have been made. This article covers what both order types share, and the sales order lifecycle in full. Recurring terms, renewal, cancellation and reactivation belong to subscriptions and are covered in [Subscriptions](/platform/subscriptions.md). *** ## 2. Core Concepts ### Order An order holds the commercial terms agreed with one account. Alongside its products and charges it carries the header below, plus any custom fields you have configured for orders, and the commercial metrics Younium maintains from it (CMRR, ACV, TCV, EMRR and one-time fees). | Field | Description | | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Order number** | Stable across every version of the order. A draft shows **Draft** until it is activated | | **Version** | Increments with each change. The first activated version is 1 | | **Last version** | Marks the current version. Exactly one version of an order number carries it | | **Order type** | Subscription or sales order | | **Status** | Where the order has reached (see below) | | **Account** | The customer the order belongs to | | **Invoice account** | The account invoiced, when it differs from the customer | | **Order date** | When the order was placed | | **Effective start date** / **Effective end date** | The period the order covers | | **Description**, **Remarks** | Free text on the order | | **Your reference**, **Our reference**, **Buyer reference**, **Your order number** | References carried onto the invoice | | **Currency** | The currency the order is priced in | | **Invoice currency** | The currency to invoice in, when it differs from the order currency | | **Payment term** | Drives the due date on invoices raised from the order | | **Payment method** | **Invoice**, **Stripe** or **GoCardless**, where that integration is active | | **Invoice template** | The template used for invoices from this order | | **Invoice batch group**, **Use Account invoice batch group** | Which batch group the order's invoices join | | **Invoice separate** | Invoices this order on its own rather than combined with others for the account | | **Disable invoicing** | Stops the order being invoiced at all | | **Accounts receivable** | Overrides the account's receivable account, where enabled | | **External ERP Id** / **External CRM Id** | Identifiers used when matching the order to a record in a connected system | ### Order type | Order type | Purpose | | ---------------- | ------------------------------------------------------------------------------------------------------------------- | | **Subscription** | A recurring agreement, with terms, renewal and amendment over time. See [Subscriptions](/platform/subscriptions.md) | | **Sales order** | A one-time purchase, which may involve delivery and progresses towards paid | The type is chosen when the order is created and shapes everything that follows — which statuses apply, whether renewal is possible, and how the order is invoiced. ### Order status Status is where the order has reached. The two order types use different sets, and the overlap is small. | Status | Applies to | Meaning | | ----------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | **Draft** | Subscription | Saved but not yet activated. No order number, no invoicing, no events | | **Order draft** | Sales order | Saved but not yet activated | | **Active** | Subscription | Live | | **Order** | Sales order | Activated and confirmed, not yet fully delivered or paid | | **Partially delivered** | Sales order | Some stock lines delivered | | **Delivered** | Sales order | Every stock line delivered | | **Invoiced** | Sales order | Everything invoiced and delivered, nothing yet paid | | **Partially paid** | Sales order | Part of the invoiced amount settled | | **Paid** | Sales order | Settled in full | | **Cancelled** | Both | Cancelled. A subscription may still be running until its end date passes — see [Subscriptions](/platform/subscriptions.md) | | **Deleted** | Both | Removed from normal use, retained for history | > **Note on which statuses count as open:** Lists of a customer's subscriptions treat both **Active** and **Cancelled** as open, because a cancelled subscription is often still running. Lists that combine subscriptions and sales orders also count sales orders in **Order**, **Partially delivered** and **Delivered** as open, since none of those is finished. ### Versions and change orders A material change to an activated order produces a **change order**: a new version under the same order number, with the version number increased by one, and the previous version no longer marked as the current one. Nothing is overwritten. On a subscription, **Effective change date** is required and sets when the new version's terms take effect. It must fall inside the period the previous version covers. Sales orders use the **Order date** instead. A version whose effective change date is still in the future is a **pending change order**: the amendment is agreed and recorded, but has not taken effect yet. ### Editing previous versions A previous version is history. It can still be annotated, but its terms, pricing and invoicing cannot be changed, and only the current version accepts those edits. | Where | On a previous version | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Order information, edited in Younium | Text fields and custom fields save. Any other change, such as payment term, payment method, notice period, batch group, invoice template or disabling invoicing, is refused with a message naming the fields, and nothing is saved | | Charges, edited in Younium | Only **Name**, **Remarks**, the external ERP and CRM identifiers and tier descriptions save. Other changes in the same edit are ignored, and the result shows what was actually stored. Custom fields save as normal | | Data Management Tool order Edit | The same rule applies to the order, its products, charges and tier details. A row that changes anything other than text is refused with an error naming the fields | | Subscriptions API update | A previous version, or a deleted subscription, cannot be updated. The request is refused with a message that the subscription could not be found or is not the latest version | > **Note on sales orders:** The Subscriptions API update is not restricted by order type, so a sales order can still be updated through it. ### Milestones An order can carry **milestones** — named points that charges can be tied to, so a charge starts or ends when the milestone is reached rather than on a fixed date. The order tracks how many milestones it has and how many are still open. *** ## 3. Creating and Activating Orders An order starts as a draft. A draft is saved under the order number **Draft**, is not invoiced, and raises no events, so you can build one up over several sittings without it affecting anything. Saving a draft again updates it in place. **Activation** turns a draft into a live order: Younium allocates a real order number, sets the version to 1, marks it as the current version, calculates the order's commercial metrics, records the booking, and publishes the activation event. A subscription becomes **Active**; a sales order becomes **Order**. Saving an order that already has a real order number is a change, not a new order, and produces a new version instead. Before an order is saved, Younium normalises a few things so the result can be billed: one-off charges are set to bill in advance, and subscription charge dates are aligned to the order where alignment is configured. A new order is rejected if any charge's **Invoiced to** date falls before that charge's effective start date, since this could otherwise lead to the charge being invoiced incorrectly, or twice, for the same period. The rule applies equally to an order created directly, through the API, or by import, and mirrors the rule that already governs changing **Invoiced to** on a charge that exists — see Invoicing, Payments and Metrics. ### Settings These defaults are applied to new orders and can be overridden on the order itself. | Setting | Description | Default | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | **Default Order type** | Order type proposed for a new order | Tenant-configured | | **Default payment term** | Payment term applied to new orders | Tenant-configured | | **Default payment method** | **Invoice**, **Stripe** or **GoCardless**. The provider options require that integration to be active | **Invoice** | | **Default Effective Start Date** | How the start date is proposed | Tenant-configured | | **Default Invoice Batch Group** | Batch group new orders join | Tenant-configured | | **Invoice template** | Invoice template applied to new orders | Tenant-configured | | **Sales order confirmation template** / **Subscription order confirmation template** | Order confirmation documents per type | Tenant-configured | | **Sales order packing slip template** / **Subscription order packing slip template** | Packing slip documents per type | Tenant-configured | | **Invoice Separate** | Whether new orders are invoiced on their own | Tenant-configured | | **Use Account Invoice Batch Group** | Whether new orders take the account's batch group | Tenant-configured | | **Invoice charges separately** | Whether each charge is invoiced on its own line item run | Tenant-configured | | **Enable order discount** | Enables discounts applied to the whole order | Tenant-configured | | **Set billing period on order** / **Default billing period** | Allows a billing period on the order rather than per charge, and the default | Tenant-configured | | **Enable Split Order** | Allows part of a subscription to be moved onto a new subscription of its own — see [Subscriptions](/platform/subscriptions.md) | Tenant-configured | | **Enable specific effective end date** | Allows a charge to end on a date of its own | Tenant-configured | | **Specific date first invoice** | Allows the first invoice to fall on a chosen date | Tenant-configured | | **Enable Mass Update Charges** | Enables updating charge fields across many orders at once | Tenant-configured | | **Use account receivable on order** | Allows the order to override the account's receivable account | Tenant-configured | | **Use invoice currency code on order** | Allows an invoice currency separate from the order currency | Tenant-configured | | **Default Initial Term**, **Default Renewal Term**, **Default Notice Period**, **Default Auto renewal**, **Default Term Type** | Subscription term defaults — see [Subscriptions](/platform/subscriptions.md) | Tenant-configured | *** ## 4. Changing an Order A change order copies the structure of the order as you have edited it, compares it against the current version, and records what changed on each charge — new, cancelled, credited, or arising from the change itself. It then creates the new version, recalculates the order's metrics, regenerates order-based revenue schedules, and records a booking so the change appears in your revenue reporting. Almost every field on a charge is part of that comparison — price, dates, billing and revenue settings, remarks, custom fields, and its **External ERP Id** and **External CRM Id** among them. Editing any one of these on its own is enough to give the charge a new version; a charge left genuinely identical to the previous version is carried forward unchanged rather than duplicated. Each change carries a **reason**, which is what distinguishes an ordinary amendment from a cancellation or a reactivation: | Reason | Used when | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **Milestone** | A milestone on the order has been reached | | **Split order** | Part of the subscription is moved onto a new subscription of its own — see [Subscriptions](/platform/subscriptions.md) | | **Change quote** | A CPQ change quote is converted | | **Cancel order product** | A product is removed from the order | | **Reactivate** | A cancelled subscription is brought back | | **Adjust end date** | A cancellation that shortens the end date rather than ending the agreement | A change is refused when the previous version is deleted or still a draft, when the effective change date falls outside the previous version's period, or when the order is cancelled and its cancellation has already taken effect — reactivation being the exception. An order cannot be changed while an open CPQ quote is amending it, because the quote would be working from terms that had moved underneath it. > **Note on cancellation:** Cancelling is itself a change order. It produces a new version in **Cancelled** status rather than editing the current one, which is why a cancellation appears in the order's version history like any other amendment. See [Subscriptions](/platform/subscriptions.md) for what cancellation does to charges and dates. ### Booking classifications A booking also carries a **classification**, separate from the reason above: a grouping used when reviewing or charting booking activity, such as new customer, expansion, contraction, customer churn, no change, split order, or reactivation. Younium assigns one of these automatically from the nature of the change, and you can add classifications of your own to tag bookings by hand alongside them. | Setting | Description | | ---------------------------- | -------------------------------------------------------------------------------- | | **Name** | Required | | **Description** | Free text | | **Chart color** | Hex colour code (e.g. `#ffffff`) used when the classification appears in a chart | | **Is system classification** | Read-only. Ticked for the classifications Younium assigns automatically | A classification Younium assigns automatically cannot be deleted, and nor can one already in use on a booking — Younium refuses the request rather than leaving a booking without a classification. ### Associated charges Not everything an order bills for comes from the product catalogue. An **associated charge** is a one-off amount put straight onto an existing order — a setup fee, a piece of hardware, a day of consultancy — with a title, a description, a date and a price of its own, and no product or charge plan behind it. Adding one does not create a new version of the order. The charge appears as a line on the order, and the amount is booked so that reporting picks it up. A later version of the order carries its associated charges forward with the rest of the agreement. An associated charge is always a one-off at a flat price in the order's currency, billed in advance from its own date. It has no quantity and does not recur, it needs a title, and its date cannot fall before the order's start date. **What it needs in order to be booked correctly.** Each associated charge carries a revenue recognition rule, a deferred revenue account, a recognised revenue account, a tax template, and whether tax is included in the price. Rather than choosing those every time, an administrator can set up an **associated charge template** and pick it instead: | Setting | What it decides | | --------------------------------------------- | ------------------------------------------------------- | | **Name** | What the template is called when you choose it | | **Revenue rule** | The revenue recognition rule the charge is booked under | | **Deferred revenue** / **Recognized revenue** | The accounts revenue posts to | | **Tax template** | How the charge is taxed | | **Tax included** | Whether the price already contains tax | > **Note on order-based revenue recognition:** An associated charge cannot use a rule that recognises revenue from the order. Younium refuses the charge and says so, so pick an invoice-based rule — see [Revenue Recognition](/platform/revenue-recognition.md). **Discounts.** An order discount that applies to every charge reaches an associated charge automatically, as long as the charge's date falls inside the discount's period. A discount aimed at specific charges does not. **What it does to the numbers.** The amount goes into the order's total contract value and its one-time fees, and leaves the recurring figures — contracted monthly revenue, annual contract value — untouched. The booking is recorded against the order with **Associated charge** as its reason, dated to the charge unless your booking rule books on the activation date instead. Changing the price books the difference; removing the charge books it back out. **Invoicing and removal.** An associated charge is invoiced like any other one-off, from its date. Once it has been invoiced it can no longer be removed — unless that invoice was cancelled, in which case it can. Removing one that has not been invoiced also takes it out of any invoice forecast it had reached. In [Insights](/platform/reporting-analytics.md), associated charges are grouped under the name **Associated charges** rather than under a catalogue product, since they have none. ### Adjusting many orders at once A single amendment is made on the order. A change that has to reach hundreds of subscriptions — an annual price increase, a re-rating of one product across the customer base, a correction to a field set wrongly at migration — is made instead by **adjusting orders**, which selects the charges to change by criteria and then applies one described change to all of them. Every adjustment is a change order per order, not a bulk overwrite. Each affected order gets a new version, its metrics are recalculated, and its booking is recorded, exactly as an amendment made by hand would. That is what makes an adjustment safe to run against live contracts, and also what makes it something to prepare rather than improvise. **Selecting what to adjust.** The selection is made against charges, not orders: conditions are set on order product charge fields and combined with logic of your own, so an adjustment can be aimed at one product on one price plan in one currency. Younium resolves the selection to the charges that match and the orders that hold them, and works only on the current version of each — an adjustment never reaches a superseded version. Within a selected order, a charge is adjusted only if it is still running on the effective date. A charge qualifies when its effective end date has not passed, when the subscription is evergreen and so has no end date, or when the charge ends on a milestone that has not yet been set. Charges that have already ended are left alone even when they match the criteria. **When the change takes effect.** The effective date is chosen once for the run, and how Younium resolves it per order depends on the option: | Option | The effective date becomes | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Next billing period** | The point each charge has been invoiced to, so the change lands at the start of the next period rather than reopening one already billed | | **Next renewal date** | The day after the order's effective end date. It does not apply to evergreen subscriptions, which have no renewal date | | **Specific date** | The date you give, applied to every order in the run | | **Custom field** | The value of a date custom field on each order, so different orders can take different dates from data already held against them | > **Note on the custom field option:** Younium reads the field per order and stops on the first order where it is empty or cannot be read as a date, naming that order. Because the run has to succeed as a whole, a single order with a blank field prevents the whole adjustment — populate the field across the selection before running. **What can be changed.** An adjustment changes price, or fields, or both. The price side offers five options, and which units apply to each differs: | Adjustment | By percentage | By amount | Replaced with an amount | | --------------------------- | ------------- | --------- | ----------------------- | | **None** | — | — | — | | **Price** | Yes | Yes | Yes | | **List price** | Yes | Yes | Yes | | **Discount** | — | — | — | | **List price and discount** | Yes | Yes | Yes | A percentage is applied to each charge's own current amount, so one run can raise a mixed book by the same proportion. An amount is added to the current amount. A replacement sets the amount outright, which is why a percentage cannot replace anything — there is no such thing as replacing a price with a percentage. **Discount** is the exception in the table: it always replaces the discount percentage with the one you give, rather than changing it by a percentage or an amount. **List price and discount** applies both in one pass — the list price moves, and the discount percentage is replaced. > **Note on adjusting price without list price:** Price and list price are not independent. Younium holds a list price, a discount and a final price, and recalculates the other two whenever one of them moves. Raising the **Price** alone therefore does not leave the discount where it was: with a list price of 300 and no discount, raising the price by 100 gives a final price of 400 and a discount of −100, because the price now exceeds the list price. Where the intention is a genuine price rise rather than a negative discount, adjust the **List price** — or both. **Fields.** Alongside or instead of a price change, an adjustment can set fields on the orders and charges it selects. | Level | Fields an adjustment can set | | -------------------- | -------------------------------------------------------------------------------------------- | | Order | Remarks, custom fields | | Order product charge | Billing period, period alignment, alignment date, effective end date, remarks, custom fields | **Booking notes.** A run carries a note that is recorded against the bookings it produces. This is the only durable record of why a bulk change was made — an indexation reference, a contract clause, a ticket number — so it is worth writing for the person who reads the booking a year later. Younium also stamps each adjusted charge with the date it was last adjusted. **Saving an adjustment.** A configured adjustment can be saved under a name and run again later, which is how a recurring exercise such as an annual indexation stays consistent between years. Names must be unique, and a saved adjustment can be deleted when it is no longer used. **When something fails.** Younium reports progress as the run proceeds and logs failures against the order that caused them. An adjustment applies only where it completes without error, so the way to recover is to correct what the log names and run the adjustment again over the orders that did not take it. *** ## 5. The Sales Order Lifecycle A sales order moves from draft, through confirmation and delivery, to invoiced and paid. Younium advances the status as the underlying work completes, rather than asking you to set it. ### Draft and confirmation A sales order draft sits in **Order draft** under the order number **Draft**. Activating it assigns the real number and moves it to **Order**. A confirmed sales order can be invoiced while it is the current version and at least one charge has not been invoiced yet. Orders that are cancelled, deleted, still drafts, fully invoiced or paid cannot be invoiced further. ### Delivery Charges on **stock** products track delivery. Recording delivered quantities moves the order forward: | Condition | Status | | ---------------------------------- | ----------------------- | | Some stock lines still undelivered | **Partially delivered** | | Every stock line delivered | **Delivered** | A sales order with no stock products has nothing to deliver and moves straight from confirmation to invoicing. > **Note on what counts as an undelivered stock line:** Only a stock line still awaiting delivery holds the order back. A line that was cancelled, credited, or never actually part of the confirmed order does not — it cannot be delivered, so Younium treats it as already settled rather than leaving the order in **Order** or **Partially delivered** indefinitely. The same rule decides when stock delivery is complete under **Invoicing and payment**, below. ### Invoicing and payment Once every charge has been invoiced and any stock delivery is complete, the status follows what has been paid: | Payment state | Status | | --------------- | ------------------ | | Nothing settled | **Invoiced** | | Part settled | **Partially paid** | | Settled in full | **Paid** | Posting a payment batch recalculates this from the settled and invoiced totals across every version of the order. The status is left alone while draft invoices still exist or charges remain uninvoiced, so a part-finished billing run cannot move an order to **Paid** prematurely. Status can also be set by hand where you need to override what Younium has worked out, but the progression above is what normally drives it. ### Cancellation A sales order is cancelled the same way as a subscription, with a preview of the effect before you confirm it. What a cancelled sales order can still be invoiced for differs from a cancelled subscription: a cancelled sales order is closed to further invoicing, whereas a cancelled subscription may still have charges to bill for the period before it ends. *** ## 6. Subscription Orders in Brief Subscription orders use **Draft**, **Active**, **Cancelled** and **Deleted**. They never enter the delivery or payment statuses, because a subscription is billed continuously rather than delivered once and settled. | Topic | Where to find it | | --------------------------------------------------------------- | ------------------------------------------- | | Termed and evergreen agreements, renewal and auto-renewal | [Subscriptions](/platform/subscriptions.md) | | Cancellation, prolonging a cancelled subscription, reactivation | [Subscriptions](/platform/subscriptions.md) | | The events a subscription raises | [Subscriptions](/platform/subscriptions.md) | *** ## 7. Reverting, Deleting, and What You Can Do to an Order ### Revert **Revert** undoes the most recent version of a subscription, removing it and making the previous version current again. It is the way to back out an amendment that should not have been made, rather than amending again to compensate. It is available on a subscription's latest version, from version 2 onwards, while the subscription is **Active** or **Cancelled**. Younium refuses it when the version has invoices that are not cancelled, when the order has been split, or when order-based revenue for the version falls in a closed accounting period or has already been recognised — in each case reverting would contradict something already accounted for. Sales orders cannot be reverted. ### Delete Deleting an order moves it to **Deleted** and hides it from normal use rather than removing it, so history and reporting stay intact. Whether an order can be deleted depends on what depends on it. Younium refuses to delete an order that has open invoices, meaning any invoice raised for one of its charges that has not been cancelled. It applies wherever the deletion is made from, including the API, and nothing is deleted when the request is refused. An order whose invoices have all been cancelled can be deleted. Draft orders have no invoices and can always be deleted. ### Available actions For any order, Younium works out which of these apply: delete, invoice, revert, change, reactivate, and reactivate directly to the previous state. This is why an action you expect may not be offered on a particular order — the conditions above decide it. *** ## 8. Invoicing, Payments, and Metrics Whether an order can be invoiced depends on its type, its status, whether it is the current version, its charge dates, and whether draft invoices already exist for those charges. Each charge records how far it has been invoiced in its **Invoiced to** date, which can never be earlier than the charge's effective start date — whether the charge is new or already exists. Changing it by hand is also refused while draft invoice lines exist for the charge, so the two cannot disagree. Once a charge has invoices that are posted or settled, **Invoiced to** can only move forward from there: a new value must fall on or after the day following the last invoiced period, so an edit can never reopen a period the customer has already been billed for. If Younium cannot establish where that period ends, it refuses any new date rather than risk billing the customer twice; clearing the date is always allowed. > **Note on Invoiced to:** The last invoiced day counts as billed in full, so a value that falls anywhere within that day is still treated as reopening it — the earliest accepted date is the following day. The order's **payment term** sets the due date on invoices raised from it. Posting payments can move a sales order towards **Partially paid** or **Paid**; see [Payments](/platform/payments.md). The order's commercial metrics are recalculated whenever it is created, changed, renewed or cancelled, so reporting reflects the current agreement rather than the one originally sold. *** ## 9. Events Younium publishes events as orders reach these points, for webhooks and integrations to act on. | Order type | Event | Raised when | | ------------ | ----------------------- | ------------------------------------------------------------------ | | Subscription | `SubscriptionActivated` | A subscription is activated | | Subscription | `SubscriptionChanged` | A new version is saved and is not a cancellation | | Subscription | `SubscriptionCancelled` | A new version is saved in **Cancelled** status | | Subscription | `SubscriptionRenewed` | A renewal completes | | Subscription | `SubscriptionUpdated` | The current version is updated without a new version being created | | Subscription | `SubscriptionReverted` | A version is reverted | | Subscription | `SubscriptionDeleted` | A subscription is deleted | | Sales order | `SalesOrderActivated` | A sales order is activated | | Sales order | `SalesOrderUpdated` | A sales order is updated | | Sales order | `SalesOrderDeleted` | A sales order is deleted | Activation and change also refresh the invoice forecast. --- # 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/orders.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.