Subscriptions
Overview
Subscriptions run sold subscriptions and licences along their lifecycle — from signing through renewals to expiry. A perpetual licence rides along in the same list as the term “perpetual”.
They are the third source of recurring revenue alongside contracts and retainers, and like those they feed billing.
Core tasks
Sign a subscription. Customer, scope and term.
Run the lifecycle. Start a trial, activate, renew, change plan, pause and resume, suspend, cancel, let expire — the status catalogue lives in the subscription settings. A trial grants access without revenue; with automatic renewal it becomes a paid licence at the end. A pause blocks access, billing rests and the term is extended by the pause.
Late payment. From the configured dunning level a subscription becomes past due; after the grace period the daily run suspends it. A payment reactivates it.
Issue keys. Generate key issues a unique key with the prefix from the settings. With the release set, the customer sees licence and key in the customer portal — every access is logged.
Bill usage. Per feature a price for the quantity above the limit can be set; reported usage above it is charged with the next billing.
Reconcile Shopware. Fetching from the Shopware account never writes silently into the inventory: every difference appears in the subscription settings as a proposal to apply or ignore.
Reconcile with an external license server. If your software checks keys against its own license server (Keygen, Cryptlex or your own service), Octibiz reads its activations — Octibiz itself runs no activation server. The reconciliation matches by license key and stores on the license the number and state of activations with a timestamp; the detail shows them as Activations (license server), e.g. “7 / 5 · active · more than licensed”. The run report names over-activations (more activations than seats), keys the server lists as revoked or expired while the license runs, keys without a license in Octibiz and running licenses the server does not know (state unknown there — only with a complete list). The reconciliation does not change seats or license status — the decision stays with you. The run starts daily at 03:30 and immediately via Reconcile license server in the subscription settings.
See the revenue. The revenue view is its own permission: managing subscriptions does not automatically show what they bring in. Above the list you see MRR, net revenue retention and churn, below them the revenue per product and per variant: for each variant the running MRR, the number of subscriptions, the change within the review window and what churned through cancellation or expiry. When a subscription switches variants, this counts as an outflow from the old variant and an inflow to the new one; subscriptions without a variant are listed as Base variant.
Spot churn risk and upsell chances. The card Churn risk & upsell on the subscription shows a level per direction (none, low, medium, high) and the signals behind it: a scheduled cancellation, overdue payment, suspended or paused, an end without renewal within the next 60 days, a downgrade in the last six months and low usage of a quota point to a risk; a quota at 80 % or above, a trial ending soon and a monthly subscription running for at least six months (offer an annual term) point to an upsell chance. AI assessment lets the AI weight these signals and phrase a short recommendation — it invents nothing; with the AI switched off, the assessment by rules remains. The list marks subscriptions from level medium with a hint and filters by churn risk or upsell chance under Hint (state of the nightly run). When a level rises to high, the automation trigger Churn risk or upsell chance high (LicenseInsightRaised) fires once — for example for a task for the account manager. Permission: products.revenue.view. The values above are defaults: under Subscription settings → Churn risk & upsell you set when a subscription gets a hint — End of term without renewal (default 60 days), Quota near the limit from (80 %), Low usage below (25 %), Low usage counts from a term of (30 days — before that little usage raises nothing), Trial ends within (14 days), Offer an annual term after (6 months) and Downgrade counts for (180 days). A change applies at once to the card on the subscription and from the next nightly run to the list and the trigger.
Run the lifecycle now. Every night at 02:00 the system renews due subscriptions, sends reminders, finalises cancellations, expires what has run out, suspends after the grace period, ends trials and pauses and rates churn risk and upsell chance. Run lifecycle now in the subscription settings brings this run forward — right next to the policies (grace period, reminder, trial) it applies — and then shows per step how many subscriptions were affected. Permission: products.license.lifecycle.
Fields in detail
| Field | Required | Values / format | What it does |
|---|---|---|---|
Customer customerId | yes | an existing customer | Who holds the licence. |
Article productId | yes | an existing article | What is licensed. |
Variant variantId or variantUlid | no | a variant of the article | Which version — edition, tier. |
Licence key licenseKey | no | text | The key the customer uses. Left empty the licence has no key until Generate key issues one. |
Replace existing key replaceKey | no | yes/no | Only with Generate key: without this confirmation an existing key stays — a new one invalidates the old. |
Show key in portal keyVisibleInPortal | no | yes/no | Whether the customer sees the key in the portal. Only takes effect with the portal permission "Licences" on the access. |
Seats seats | no | number, greater than 0 | For how many users or devices the licence applies. |
Term term | no | monthly, yearly, perpetual | How long it lasts. Perpetual does not expire and is not renewed. |
Starts on startsAt | no | date | From when it applies. |
Auto-renew autoRenew | no | yes/no | Whether it renews at the end. On means a new period arises and with it an invoice, without anyone acting — the reason the notice period beside it matters. |
Cancel at cancelAt | no | date | When the licence should end. |
Immediate immediate | no | yes/no | Whether cancellation takes effect at once instead of at period end. Immediate means access ends now — with everything that implies for the customer. |
Brand brandId | no | one of your brands | Which brand the licence is kept under. |
Trial length trialDays | no | days | Only when starting a trial; empty takes the default from the settings. |
Pause until pauseUntil | no | date | Only when pausing; empty means an open-ended pause until resumed. |
Feature featureKey | no | key of a feature | For usage reports and overage price: which feature is meant. |
Usage usedAmount | no | number, 0 or more | The current level in the running period. Only the increase above the limit is billed — reporting the same level again charges nothing twice. |
Overage price overageUnitPriceAmount | no | amount per unit | What each unit above the limit costs. Empty turns overage billing off. |
Interface and automation only
| Field | Values / format | What it does |
|---|---|---|
currentVersionId | identifier of a version | Which program version the licence covers. |
sourceQuoteId | identifier of a quote | Which accepted quote the licence came from. |
Settings & permissions
- Module
module.licensing. products.license.view,products.license.create,products.license.lifecyclefor
the lifecycle, products.revenue.view for the revenue view, licensing.config.manage for catalogue, rules, Shopware and license server reconciliation, products.license_key.manage to generate keys, products.license_usage.report for usage reports.
- Subscription rules in the subscription settings: grace period, dunning level for "past due",
reminder before renewal (goes to the account manager), default trial and key prefix.
- Churn risk & upsell in the subscription settings: the seven thresholds of the hints (see above).
Both sections can only be changed by users allowed to manage system settings (platform.settings.manage).
- External license server: integration of type
license_server(Settings → Integrations, can be
switched off via active) with base_url, optional activations_path (default /activations), items_path (data), the field paths field_license_key, field_activations, field_status, field_last_seen (dot notation, e.g. attributes.key), paging pagination (page, link, none) with page_param/per_page_param/per_page; the access token as token (stored encrypted), header via auth_header/auth_prefix (default Authorization: Bearer). API POST /api/v1/licensing/license-server-sync; the activation fields of the license (activationCount, activationStatus, activationsCheckedAt) are read-only.
- Recurring revenue runs through billing.
FAQ & troubleshooting
A subscription keeps being billed. Check its status and the plan in billing.
I see no revenue. Then products.revenue.view is missing — deliberate, not a display fault.
A subscription cannot be renewed. Then products.license.lifecycle is missing.
Subscription or contract? A subscription entitles to use a product and carries MRR/ARR; a contract commits to work — retainer, maintenance, hosting — and runs quotas. Anyone consuming hours or quotas needs the contract.