Subscription Contracts
Platform contracts only. No backend subscription engine.
ADR: ADR-023
Related: pricing-catalog.md, license-entitlement-contracts.md, payment-contracts.md
Contract version: subscription.v1
1. Ownership
| Concern |
Owner |
| Subscription commercial lifecycle |
Core Platform |
| Pricing binding |
Pricing Catalog refs |
| License issuance |
Core (license contracts) |
| Payment collection / PSP capture |
Payment (when activated) |
| Accounting AR / contract |
Accounting (opaque refs) |
Payment’s reserved payment.future.subscriptions is a billing shell, not ownership of platform Subscription aggregates.
2. Contracts
2.1 SubscriptionPlan
| Field |
Type |
Meaning |
plan_code |
string |
Stable code |
display_name |
string |
|
bundle_code |
string |
Business bundle definition |
bundle_version_code |
string |
Pinned commercial version |
default_pricing_item_code |
string |
Primary Pricing Catalog ref |
status |
enum |
draft | active | retired |
2.2 Subscription
| Field |
Type |
Meaning |
subscription_id |
uuid |
Logical id |
tenant_id |
uuid |
|
plan_code |
string |
|
status |
SubscriptionStatus |
|
period |
SubscriptionPeriod |
Current period |
renewal_policy |
RenewalPolicy |
|
cancellation_policy |
CancellationPolicy |
|
grace_period |
GracePeriod |
|
pricing_item_code |
string |
Bound list price |
started_at / ended_at |
datetime? |
|
ext |
object |
Additive |
2.3 SubscriptionItem
| Field |
Type |
Meaning |
subscription_id |
uuid |
|
item_code |
string |
Line identity |
kind |
enum |
bundle | addon | usage |
pricing_item_code |
string |
|
quantity |
int |
Default 1 |
service_identifier |
string? |
When item maps to a service |
2.4 SubscriptionLicense
| Field |
Type |
Meaning |
license_id |
uuid |
|
subscription_id |
uuid |
|
tenant_id |
uuid |
|
bundle_code |
string |
|
status |
enum |
requested | active | suspended | revoked | expired |
entitlement_grant_refs[] |
string[] |
Opaque refs to entitlement grants |
valid_from / valid_to |
datetime? |
|
2.5 SubscriptionStatus
requested | trialing | active | past_due | grace | cancelled | expired | suspended
2.6 SubscriptionPeriod
| Field |
Meaning |
period_start |
Inclusive |
period_end |
Exclusive or inclusive per future policy doc |
billing_anchor |
Day/time anchor |
2.7 RenewalPolicy
| Field |
Meaning |
mode |
auto | manual | none |
notice_days |
Pre-renewal notice |
2.8 CancellationPolicy
| Field |
Meaning |
mode |
end_of_period | immediate | admin_only |
refund_policy_ref |
Opaque; Payment refunds are separate (14.6+ not in this wave) |
2.9 GracePeriod
| Field |
Meaning |
days |
Length after past_due before suspend |
entitlements_during_grace |
full | read_only | none |
3. Invariants
- Creating a Subscription MUST NOT by itself mutate Payment or Accounting databases — only emit activation/request events (see activation flow).
- License is derived from an accepted Subscription; entitlements are derived from License.
- Amounts come from Pricing Catalog (or enterprise quote process), not from bundle JSON.
