Subscriptions

Recurring revenue in CPQ. A subscription carries products over time, collects metered usage against them, and is priced with its own pricing models — a separate engine from the quote pricing waterfall. It is also where the WorkSquares suite’s own plans and credit packs are authored, as ordinary catalogue data.

Core objects

• Subscriptions — recurring agreements against a customer account, with a term, a billing frequency and a renewal date.
• Subscription products — the products included in a subscription, each with a quantity, a unit price, a discount and optional start and end dates.
• Usage records — metered quantities recorded against a subscription product.
• Amendments — a record of a mid-term change, with an effective date, the before and after values and a proration method.
• Subscription pricing models & tiers — the pricing engine for recurring charges: eight model types (FLAT_RATE, PER_SEAT, TIERED_GRADUATED, TIERED_VOLUME, STAIRCASE, HYBRID, MINIMUM_COMMIT, PREPAID_CREDIT) and a ladder of tiers.

Subscriptions

A subscription is created against a customer account with a name, a start date and a billing frequency — monthly, quarterly or annual — plus an optional end date, renewal term and auto-renew flag. Products are added, edited and removed on the subscription itself. The detail page gathers the whole record in one place: details, products, usage, amendments and renewal.

A subscription can be created in any of its states — the New Subscription form’s Status field defaults to Draft — and Activate, Suspend, Reactivate and Cancel all complete, from the header buttons, the API, and a dunning step suspending or cancelling for non-payment.

Each action is checked against the subscription status catalogue, so only the moves below are allowed:

From	Can move to
Draft	Pending, Active, Cancelled
Pending	Active, Cancelled
Active	Paused, Suspended, Pending renewal, Expired, Cancelled
Paused	Active, Expired, Cancelled
Suspended	Active, Expired, Cancelled
Pending renewal	Active, Renewed, Expired, Cancelled
Renewed	Active, Pending renewal, Expired, Cancelled
Expired	— final
Cancelled	— final

Expired and Cancelled are terminal: nothing moves out of them, so cancelling is not something you undo. Suspend is the state dunning drives a delinquent account into, and Reactivate is the way back once the account is paid.

Renewal quote. A subscription can be copied onto a new draft quote for its renewal, carrying its active products with their quantities, prices and discounts. The customer is not copied across, so set the account on the quote before you work it.

Usage

Usage is recorded against a subscription product: the line it belongs to, a quantity and a usage date. The subscription’s Usage tab lists what has been recorded, newest first, with the product name resolved.

Usage is priced against an allowance. Each subscription product carries an included quantity and an overage rate: usage up to the included quantity is charged at the line’s unit price, and everything beyond it at the overage rate. Both are set when you add the product, or later on the Products tab, and both default to zero — which means no allowance and no overage, exactly what an existing line already implies. Ask for the charge with GET /api/v1/subscriptions/{uuid}/usage-charges, which returns the base charge, the usage charge, the overage and a per-usage-type breakdown.

One thing to know: usage has to be posted through the API (POST /api/v1/subscriptions/{uuid}/usage, taking product_id). The Record Usage screen sends the line under a different field name, which the endpoint does not accept, so recording from the screen is rejected.

Subscription pricing models

Pricing models are authored by administrators and are exercised independently of any one subscription. A model carries a type, a base fee, a per-unit label, a billing frequency (monthly, quarterly, semi-annual or annual), a currency and — for the tiered types — tiers with bounds and either a unit price or a flat fee.

Model	How a quantity is priced
FLAT_RATE	Base fee, plus the per-unit rate for every unit.
PER_SEAT	Base fee, plus the per-seat rate for every seat.
TIERED_GRADUATED	Base fee, plus each tier’s share of the quantity at that tier’s unit price — like tax brackets.
TIERED_VOLUME	Base fee, plus every unit at the unit price of the tier the total lands in.
STAIRCASE	Base fee, plus the flat fee of the step the quantity lands in.
HYBRID	Base fee, plus a graduated charge on the units above the model’s included units.
MINIMUM_COMMIT	The greater of the graduated charge and the minimum commitment.
PREPAID_CREDIT	The flat-rate calculation, for pricing a credit purchase.

Two things to know when you build one: the per-unit rate every model charges from is the overage rate field — the separate per-credit rate is stored but not read by the calculator — and included units are applied by HYBRID alone, so PER_SEAT charges its rate on every seat rather than only on seats beyond an allowance.

The pricing-model editor carries a calculator. Run a quantity through a saved model and it returns the total, the base fee, the per-unit charge and, for the tiered types, the tier-by-tier breakdown — the quickest way to sanity-check a graduated, volume, staircase, hybrid or minimum-commit model before you sell on it.

Amendments

An amendment records a mid-term change to a live subscription. Nine types are accepted: upgrade, downgrade, add product, remove product, quantity change, term change, price change, renewal and cancellation. Each one carries an effective date, a reason, the before and after values, a proration method (full, partial or none) and an amount.

An amendment is a record of the change, not a mechanism: it does not alter the subscription’s products, price or term. Make product changes — including price and quantity — on the subscription’s Products tab, which does save. Changes to the subscription header itself, such as its term, end date, auto-renew flag or name, cannot be made from the web app today; the edit form’s save does not reach a live endpoint.

Three things to know when you raise one:

• An amendment cannot be back-dated. Its effective date must be on or after the day it is raised.
• Amendments have no approval state. There is nothing to approve; the Approve action on the amendments list reports success without changing the record.
• Three of the web form’s types will not save. Upgrade, Downgrade, Add Product and Remove Product go through. Change Quantity, Change Price and Other are sent under names CPQ does not accept and are rejected when you save, and term change is not offered on the form at all — raise a quantity, price or term amendment through the API, under the accepted names above.

Selling the WorkSquares suite

CPQ owns the sell side of every subscription in the WorkSquares portfolio — catalogue, plans, prices, terms and amendments. Billing and the ledger consume what CPQ signs; they never author it. The suite’s own commercial catalogue is therefore an ordinary CPQ catalogue, held as data rather than code.

It is not pre-loaded. It ships as seed data an administrator loads once per company (2026-07-18_digisquares_catalog.sql), idempotent on re-run. It defines three shapes:

• Per-user plans. Jupiter Dev, Pro and Max — one-month recurring products, each carrying its own monthly AI credit allowance. The line quantity is the number of users.
• Per-company plans. WORKSQUARES Team and Business, on PER_SEAT models whose price card is quoted as a base fee covering a number of seats plus a per-extra-seat rate.
• AI credit packs. Four one-time products — 1,000, 5,000, 25,000 and 100,000 credits — priced by a PREPAID_CREDIT model, expiring twelve months after purchase, with a lower per-credit rate on the larger packs.

A second script, 2026-07-25_datasquares_catalog.sql, adds the DataSquares plan set — BI editor and viewer seats, Pipelines, Warehouse and a platform bundle.

Prices are data. A plan’s money lives on the product’s list price, its price-book entry and its pricing model; changing the price card means editing those records, never code.

What turns a sale into a live entitlement is a small amount of metadata on the product: a plan code, and for credit packs a credit amount and an expiry in months. When an order is confirmed, CPQ raises an order.activated event carrying one entitlement per line — the account, the product code, the plan code, the seat count, the credit amount and the period — so a provisioning system can grant access without knowing anything about CPQ’s schema. That is the one entitlement event CPQ emits; nothing equivalent fires from the subscription itself.

The seat count on an entitlement is the ordered quantity. The period starts at the moment the order is confirmed: a recurring line runs for the product’s subscription term, and a credit pack runs to the same day the configured number of months later, clamped to the last day of that month when the day does not exist in it — a pack bought on 29 February 2028 expires on 28 February 2029, not 1 March.

Because plan codes are catalogue data, the same mechanism works for anything else you sell as a plan: define your own plan vocabulary on your own products and the entitlement events carry it through unchanged.

Analytics

Subscriptions → Analytics totals the mrr and arr figures stored on each active subscription, alongside the active subscription count, average contract value and a renewal forecast banded by month and auto-renew flag.

Both figures are recalculated whenever a subscription’s product mix changes — adding, editing or removing a product. Each active line contributes its discounted line total, normalised to a month using the subscription’s billing frequency: a quarterly line is divided by three, an annual one by twelve, and a one-time line contributes nothing recurring at all. ARR is twelve times MRR.

Two consequences worth knowing. A subscription whose products have not been touched since it was created still reads zero — edit any line to populate it. And because the figures are stored rather than derived on read, changing a product’s price outside the Products tab will not move them until the line is saved again.

Customer self-service

The Customer Portal Android app lists a customer’s subscriptions and opens each one with its products, dates, billing terms and recent usage. It is the only channel that does — the browser storefront’s subscription screens were built but never wired into its navigation. See Portals.

What you can do

• Create subscriptions and manage the products on them.
• Record usage against a subscription product and read it back.
• Record amendments for mid-term changes.
• Copy a subscription onto a renewal quote.
• Define pricing models and tiers, and calculate a price for a quantity.

Admin-configurable

Subscription pricing models and tiers are defined by administrators: model type, base fee, per-unit label, billing frequency, currency, included units, overage rate, minimum commitment and per-credit rate. Products are marked as subscriptions in the catalogue, where their subscription pricing, billing term and subscription type are set.

Connects to

• Products & pricing — subscription products come from the same catalogue.
• Billing & payments — recurring charges are billed through billing schedules and the billing run.
• Orders & contracts — subscriptions sit alongside orders and contracts as an outcome of a won quote, and order confirmation is what emits the entitlement that provisions a plan.