> 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/subscriptions.md). # Subscriptions *** ## 1. Overview A subscription is a recurring agreement with a customer: what they have, on what terms, for how long, and what they are billed for it. In Younium a subscription is an [order](/platform/orders.md) of type Subscription, which means it inherits the order model's versioning — every amendment is recorded as a new version rather than overwriting what came before. That matters more for subscriptions than for anything else in Younium, because a subscription is expected to change. Customers upgrade mid-term, add users, renew on new terms, and cancel with notice. The version history is what lets you bill a period that spans an amendment correctly, show a customer what they agreed to and when, and report on how recurring revenue moved rather than only where it stands. Subscriptions connect to [accounts](/platform/accounts-contacts.md) for who is billed, to [billing](/platform/billing.md) for the invoices their charges produce, and to [payments](/platform/payments.md) for how those invoices are settled. Many begin life as a won CPQ quote. Changes, renewals and cancellations all run through the order layer described in [Orders](/platform/orders.md). *** ## 2. Core Concepts ### Subscription type The subscription type decides whether the agreement has an end date, and therefore whether it can be renewed. | Subscription type | Meaning | | ----------------- | ------------------------------------------------------------------------------------------ | | **Termed** | The subscription runs to a defined end date. Renewal extends that date by the renewal term | | **Evergreen** | The subscription runs without an end date until it is cancelled | > **Note on renewal:** Only **termed** subscriptions renew, and only while they are **Active**. An evergreen subscription has no end date to extend, so renewal does not apply to it — it simply continues until cancelled. ### Terms and renewal | Field | Role | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Initial term (months)** | The length of the first contract period | | **Renewal term (months)** | The length applied at each renewal. After a renewal, this holds the term for the *next* one | | **Auto-renewal** | When on, Younium renews the subscription itself rather than waiting for someone to do it | | **Notice period (months)** / **Notice period date** | How much notice is required to cancel, and the date by which it must be given. The date moves forward on renewal | | **Last renewal** | When the subscription last renewed | ### Dates | Field | Role | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Effective start date** | When the subscription begins | | **Effective end date** | When it ends. Empty on an evergreen subscription until it is cancelled | | **Effective change date** | Required on every amendment. Sets when the new version's terms take effect, and must fall inside the previous version's period | | **Effective cancellation date** | Recorded when the subscription is cancelled | The day after the effective end date is when a termed subscription would next renew. An evergreen subscription has no such date. ### Status Subscriptions use four of the order statuses. The delivery and payment statuses belong to sales orders and never apply here. | Status | Meaning | | ------------- | -------------------------------------------------------------------------------------------------- | | **Draft** | Saved but not activated. Held under the order number **Draft**, not invoiced, and raises no events | | **Active** | Live | | **Cancelled** | Cancellation recorded. The subscription may still be running — see below | | **Deleted** | Removed from normal use, retained for history | > **Note on a cancelled subscription that is still running:** Cancelling records the decision; it does not stop the subscription that day. While the effective end date is today or later, the cancellation is **pending** and the subscription is still live: it appears in lists of open subscriptions, and charges that fall before the end date are still billed. Only once the end date passes is the subscription finished. This is why a customer who cancelled last week may still receive an invoice. ### Versions Each material change to an active subscription creates a new version under the same order number, with the previous version retained. Renewals and some in-place adjustments update the current version instead of creating a new one — the distinction matters for reporting, and is what separates the **Changed** and **Updated** events described below. A previous version keeps its terms: only text fields and custom fields can still be edited on it, and the API cannot update it. See [Orders](/platform/orders.md#editing-previous-versions). ### Charges and alignment A subscription's charges can be aligned to the subscription itself, so that their start or end follows the agreement rather than a fixed date. On a termed subscription, recurring charges aligned to the end date are extended when the subscription renews. One-off charges are not: they have a single billing event and are not renewed. *** ## 3. From Draft to Active A subscription draft carries the order number **Draft**. Saving it does not assign a real number, does not make it billable, and raises no activation event, so you can prepare an agreement without it affecting anything. **Activation** makes it live. Younium assigns the real order number, sets the version to 1, calculates the subscription's commercial metrics, records the booking, refreshes the invoice forecast, and publishes `SubscriptionActivated`. The status becomes **Active**. > **Note on quotes:** Converting a won CPQ quote can create and activate the subscription in one step. The subscription type, terms, auto-renewal and dates come from the quote unless they are overridden during conversion. ### Settings These defaults apply to new subscriptions and can be overridden on the subscription itself. | Setting | Description | Default | | -------------------------------------------- | ------------------------------------------------- | ----------------- | | **Default Term Type** | **Termed** or **Evergreen** for new subscriptions | Tenant-configured | | **Default Initial Term** | Initial term in months | Tenant-configured | | **Default Renewal Term** | Renewal term in months | Tenant-configured | | **Default Auto renewal** | Whether new subscriptions renew automatically | Tenant-configured | | **Default Notice Period** | Notice period in months | Tenant-configured | | **Default Effective Start Date** | How the start date is proposed | Tenant-configured | | **Subscription order confirmation template** | Document template for subscription confirmations | Tenant-configured | Further order-level defaults — payment term, payment method, invoice template, batch group — are shared with sales orders and listed in [Orders](/platform/orders.md). *** ## 4. Renewal Renewal extends a termed subscription by its renewal term. Younium requires the subscription to be **Active**, to be termed with an end date, and to have a renewal term greater than zero. On renewal, Younium: * Extends the **Effective end date** by the renewal term, keeping it aligned to the original start date so renewals do not drift. * Records the renewal date as the day after the previous end date, so there is no gap and no overlap. * Moves the **Notice period date** forward, where one is set. * Extends recurring charges aligned to the subscription end date, leaving one-off and cancelled charges alone. * Extends order-level discounts aligned to the order, so a negotiated discount is not silently lost at renewal. * Stores the renewal term supplied for the *next* renewal, recalculates the subscription's contract value, regenerates order-based revenue schedules, and records a renewal booking. * Publishes `SubscriptionRenewed` and refreshes the invoice forecast. A renewal updates the current version rather than creating a new one. ### Automatic renewal When **Auto-renewal** is on, Younium renews the subscription without anyone acting. It considers current-version subscriptions that are **Active**, termed, with a renewal term greater than zero, and renews one once its notice period date or effective end date has passed. A subscription with an **open CPQ quote** amending it is skipped, because renewing it would move the terms the quote is being built against. If an automatic renewal fails, it is recorded against that subscription and the others in the run continue. Manual renewal applies exactly the same rules, so a subscription renewed by hand and one renewed automatically end up in the same state. *** ## 5. Changes, Cancellation, Prolonging and Reactivation ### Changing a subscription Editing an active subscription — its products, charges, dates, discounts or custom fields — produces a new version. **Effective change date** is required, and Younium compares the new charges against the current ones to work out what changed: which are new, which are cancelled, which need crediting, and which arise from the change itself. Bookings and order-based revenue schedules are generated for the new version. Saving publishes `SubscriptionChanged`, unless the new version is a cancellation, in which case it publishes `SubscriptionCancelled` instead. A subscription cannot be changed while an open CPQ quote is amending it. ### Cancellation Cancelling creates a new version in **Cancelled** status. Younium sets the effective end date, records the cancellation date, sets the effective change date to the day after the end, clears the notice period, and marks the products cancelled. How far each charge is billed depends on the **cancel mode** you choose: | Cancel mode | Charges end | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **On order cancellation date** | On the subscription's cancellation date | | **On charges invoice-to dates** | Where each charge has already been invoiced to, so nothing is billed beyond what the customer has been charged for | | **On charges effective end dates** | On each charge's own end date. Evergreen charges fall back to their invoiced-to date | | **On custom dates** | On dates you supply per charge | Only **On order cancellation date** needs the subscription's own end date to be given directly. The other three modes work it out from where each charge ends, so the order's end date always lines up with what the charges are actually billed to. **On custom dates** needs an end date for every charge being cancelled — leave one out and Younium refuses the cancellation, naming the charge that is missing its date. Cancellation is previewed before it is confirmed, so you can see what each mode would do before committing to it. Shortening the end date to a point before the current one is treated as an end-date adjustment rather than a cancellation, since the agreement continues — just for less time. ### Prolonging a cancelled subscription A cancelled subscription whose end date has not yet passed can be **prolonged**: the end date moves later, and selected charges can move with it. This is how you retain a customer who has given notice but agreed to stay. Prolonging updates the current version in place rather than creating a new one, recalculates the metrics and bookings, and publishes `SubscriptionUpdated`. ### Reactivation Where the reactivate feature is enabled, a cancelled subscription that is the current version can be brought back. Younium creates a change order with the reason **Reactivate**, and the subscription follows the normal change and activation path from there. Where the version immediately before the cancellation was **Active**, a **simple reactivation** is available, which returns the subscription to that state directly. *** ## 6. Splitting a Subscription Splitting moves selected products off a subscription onto a **new subscription of their own**, starting on a date you choose. Because the new subscription is independent of the original, each can then be billed, renewed, amended and cancelled on its own — without having to cancel and re-sell what the customer already has. Only subscriptions can be split, and the feature has to be enabled with **Enable Split Order**. ### What happens on each side Splitting produces two orders in one step, and links them so the history stays traceable. **On the original subscription**, Younium creates a new version with the change reason **Split order**. The products you selected are marked cancelled on it, and their charges end the day before the new subscription starts, so the original stops billing for them exactly where the new one takes over. **The new subscription** is created active, with its own order number, carrying the selected products. Younium adjusts them to fit their new start date: * Charges that had already ended before the split date are dropped — there is nothing left to bill. * Charges that started before the split date are moved to start on it, and aligned to the new subscription. * How far each charge has been invoiced is cleared, so the new subscription bills from its own start rather than repeating what the original already invoiced. * Charges tied to a milestone that has a date become fixed-date charges instead, since the milestone belongs to the original agreement. * Discounts carry across, but only those that still apply to a charge on the new subscription. * Milestones that no longer have a charge referring to them are dropped. Both subscriptions record the split in their history — the original noting which order it split to, the new one noting where it came from — and the products stay linked across the two. ### Choosing the date The new subscription's start date has to fall inside a window Younium works out from what has already happened to the charges, and it shows you that window before you commit. | Bound | Set by | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Earliest | The subscription's own start date, and never before what has already been invoiced on the products being moved. A credited period can push this later | | Latest | The end dates of the charges being moved. A charge with a fixed end date, or one ending on a milestone with no date set, constrains how late the split can be | A date outside that window is refused, with the allowed range given. ### Restrictions Splitting is refused when: * The order is a sales order. Only subscriptions can be split. * **Enable Split Order** is off. * An **open CPQ quote** is amending the subscription — the quote would be working from terms that had moved underneath it. A subscription that has been split cannot be **reverted** afterwards, because the new subscription exists independently and reverting would leave it stranded. *** ## 7. Reverting a Change **Revert** removes the latest version and makes the previous one current again — the way to back out an amendment that should not have been made, rather than amending again to compensate. Younium refuses it when the version has invoices that are not cancelled, when the subscription 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. Revert publishes `SubscriptionReverted` and refreshes the invoice forecast. *** ## 8. Events Younium publishes these as a subscription reaches each point, for webhooks and integrations to act on. | Event | Raised when | | ----------------------- | -------------------------------------------------------------------------------------------- | | `SubscriptionActivated` | A subscription is activated | | `SubscriptionChanged` | A new version is saved and is not a cancellation | | `SubscriptionCancelled` | A new version is saved in **Cancelled** status | | `SubscriptionRenewed` | A renewal completes, whether manual or automatic | | `SubscriptionUpdated` | The current version is updated without a new version being created — prolonging, for example | | `SubscriptionReverted` | A version is reverted | | `SubscriptionDeleted` | A subscription is deleted | > **Note on Changed versus Updated:** **Changed** means a new version exists, so the agreement itself is different. **Updated** means the current version was modified without a new one being created. An integration that tracks contract history should act on **Changed**; one that only needs current state can act on either. Activation and change also refresh the invoice forecast. *** ## 9. Invoicing and Payment A subscription can be invoiced while it is the current version and is not a draft or deleted — including while it is **Cancelled**, because a cancelled subscription that is still running has charges left to bill. What is actually billed is decided per charge: a charge is excluded once it is fully invoiced, or where cancellation has ended it. The subscription's **payment term** sets the due date on its invoices. Its **payment method** may be **Invoice**, **Stripe** or **GoCardless** where that integration is active; see [Payments](/platform/payments.md). --- # 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/subscriptions.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.