TenantSubscription

Represents a subscription plan and billing arrangement for a tenant workspace in a multi-tenant SaaS platform. This entity manages the commercial relationship between the platform and tenant, tracking subscription tiers, billing cycles, payment status, usage quotas, and plan changes. It enables subscription lifecycle management including trials, upgrades, downgrades, cancellations, and renewals. The entity supports multiple pricing models (per-user, per-feature, usage-based, flat-rate), billing frequencies (monthly, annual, custom), and payment methods. It tracks subscription status, billing period boundaries, upcoming renewals, payment method details, and discount codes while enforcing plan-based feature access and usage limits defined in TenantSettings. The entity serves as the foundation for monetization, revenue recognition, and commercial operations in B2B SaaS platforms, enabling flexible pricing strategies and subscription management.

25 properties

Schema

Properties

Property	Type	Mode	Description	Required
tenant	Tenant	stored	Reference to the Tenant that holds this subscription	Required
plan	SubscriptionPlan	stored	Subscription plan tier that defines features, limits, and pricing for this subscription	Required
status	string	stored	Current status of the subscription Values: `trial, active, past-due, cancelled, suspended, expired` Example: `"active"`	Required
billingCycle	string	stored	Billing frequency for this subscription Values: `monthly, quarterly, annual, biennial, custom` Example: `"annual"`	Required
price	MonetaryAmount	stored	Subscription price per billing cycle (combines amount and currency)	Required
startedAt	datetime	stored	Date/time when the subscription started Example: `"2024-01-01T00:00:00Z"`	Required
trialEndsAt	datetime	stored	Date/time when the trial period ends (null if not a trial) Example: `"2024-01-15T23:59:59Z"`	Optional
currentPeriodStart	datetime	stored	Start date/time of the current billing period Example: `"2024-11-01T00:00:00Z"`	Required
currentPeriodEnd	datetime	stored	End date/time of the current billing period Example: `"2024-12-01T00:00:00Z"`	Required
renewsAt	datetime	stored	Date/time when the subscription renews Example: `"2024-12-01T00:00:00Z"`	Optional
cancelledAt	datetime	stored	Date/time when the subscription was cancelled (null if not cancelled)	Optional
cancelAtPeriodEnd	boolean	stored	Whether to cancel the subscription at the end of the current billing period	Optional
autoRenew	boolean	stored	Whether the subscription automatically renews Example: `true`	Required
quantity	number	stored	Quantity or number of units (e.g., number of seats/users for per-user pricing) Example: `25`	Optional
paymentMethod	PaymentMethod	stored	Payment method used for billing this subscription	Optional
billingContact	Person	stored	Reference to the Person responsible for billing	Optional
discountCode	string	stored	Applied discount or promo code Example: `"LAUNCH2024"`	Optional
discountPercentage	number	stored	Discount percentage applied to the subscription Example: `20`	Optional
notes	string	stored	Internal notes about this subscription	Optional
metadata	json	stored	Additional subscription metadata (e.g., external payment provider IDs, custom fields)	Optional
isTrial	boolean	calculated	Whether this subscription is currently in trial period	Optional
isActive	boolean	calculated	Whether this subscription is currently active and in good standing	Optional
isPastDue	boolean	calculated	Whether this subscription has overdue payment	Optional
daysUntilRenewal	number	calculated	Number of days until the subscription renews	Optional
daysInTrial	number	calculated	Number of days remaining in trial period (null if not in trial)	Optional

Examples

Example 1

{
  "@type": "TenantSubscription",
  "tenant": {
    "@type": "Tenant",
    "slug": "acme-corp",
    "name": "ACME Corporation"
  },
  "plan": {
    "@type": "SubscriptionPlan",
    "name": "enterprise",
    "label": "Enterprise Plan"
  },
  "status": "active",
  "billingCycle": "annual",
  "price": {
    "@type": "MonetaryAmount",
    "amount": 11999.99,
    "currency": {
      "@type": "Currency",
      "code": "USD"
    }
  },
  "startedAt": "2024-01-01T00:00:00Z",
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2025-01-01T00:00:00Z",
  "renewsAt": "2025-01-01T00:00:00Z",
  "autoRenew": true,
  "quantity": 100,
  "paymentMethod": {
    "@type": "PaymentMethod",
    "type": "credit-card",
    "last4": "4242",
    "brand": "Visa"
  },
  "billingContact": {
    "@type": "Person",
    "givenName": "John",
    "familyName": "Doe"
  }
}

Example 2

{
  "@type": "TenantSubscription",
  "tenant": {
    "@type": "Tenant",
    "slug": "techstart",
    "name": "TechStart Inc"
  },
  "plan": {
    "@type": "SubscriptionPlan",
    "name": "starter",
    "label": "Starter Plan"
  },
  "status": "trial",
  "billingCycle": "monthly",
  "price": {
    "@type": "MonetaryAmount",
    "amount": 49.99,
    "currency": {
      "@type": "Currency",
      "code": "USD"
    }
  },
  "startedAt": "2024-11-15T10:00:00Z",
  "trialEndsAt": "2024-11-29T23:59:59Z",
  "currentPeriodStart": "2024-11-15T10:00:00Z",
  "currentPeriodEnd": "2024-11-29T23:59:59Z",
  "autoRenew": false,
  "quantity": 5
}

Example 3

{
  "@type": "TenantSubscription",
  "tenant": {
    "@type": "Tenant",
    "slug": "small-biz",
    "name": "Small Business Co"
  },
  "plan": {
    "@type": "SubscriptionPlan",
    "name": "professional",
    "label": "Professional Plan"
  },
  "status": "past-due",
  "billingCycle": "monthly",
  "price": {
    "@type": "MonetaryAmount",
    "amount": 199.99,
    "currency": {
      "@type": "Currency",
      "code": "EUR"
    }
  },
  "startedAt": "2024-06-01T00:00:00Z",
  "currentPeriodStart": "2024-11-01T00:00:00Z",
  "currentPeriodEnd": "2024-12-01T00:00:00Z",
  "renewsAt": "2024-12-01T00:00:00Z",
  "autoRenew": true,
  "quantity": 15,
  "paymentMethod": {
    "@type": "PaymentMethod",
    "type": "credit-card",
    "last4": "1234",
    "brand": "Mastercard"
  }
}

Example 4

{
  "@type": "TenantSubscription",
  "tenant": {
    "@type": "Tenant",
    "slug": "consulting-partners",
    "name": "Consulting Partners LLC"
  },
  "plan": {
    "@type": "SubscriptionPlan",
    "name": "professional",
    "label": "Professional Plan"
  },
  "status": "cancelled",
  "billingCycle": "annual",
  "price": {
    "@type": "MonetaryAmount",
    "amount": 1999.99,
    "currency": {
      "@type": "Currency",
      "code": "USD"
    }
  },
  "startedAt": "2023-01-01T00:00:00Z",
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2025-01-01T00:00:00Z",
  "cancelledAt": "2024-10-15T14:30:00Z",
  "cancelAtPeriodEnd": true,
  "autoRenew": false,
  "quantity": 50,
  "paymentMethod": {
    "@type": "PaymentMethod",
    "type": "invoice"
  }
}