orion/app/modules/billing/docs/data-model.md

Billing Data Model

Entity Relationship Overview

┌───────────────────┐
│ SubscriptionTier  │
└────────┬──────────┘
         │ 1:N
         ▼
┌───────────────────┐     ┌──────────────────────┐
│ TierFeatureLimit  │     │ MerchantSubscription │
│ (feature limits)  │     │ (per merchant+plat)  │
└───────────────────┘     └──────────┬───────────┘
                                     │
                          ┌──────────┼──────────────┐
                          ▼          ▼              ▼
                   ┌────────────┐ ┌──────────┐ ┌─────────────┐
                   │ BillingHist│ │StoreAddOn│ │FeatureOverride│
                   └────────────┘ └──────────┘ └─────────────┘
                                       │
                                       ▼
                                 ┌────────────┐
                                 │AddOnProduct│
                                 └────────────┘

┌──────────────────────┐
│StripeWebhookEvent    │ (idempotency tracking)
└──────────────────────┘

Core Entities

SubscriptionTier

Defines available subscription plans with pricing and Stripe integration.

Column	Type	Description
id	Integer	Primary key
code	String	Unique tier code (essential, professional, business, enterprise)
name	String	Display name
price_monthly_cents	Integer	Monthly price in cents
price_annual_cents	Integer	Annual price in cents (optional)
stripe_product_id	String	Stripe product ID
stripe_price_monthly_id	String	Stripe monthly price ID
stripe_price_annual_id	String	Stripe annual price ID
display_order	Integer	Sort order on pricing pages
is_active	Boolean	Available for subscription
is_public	Boolean	Visible to stores

TierFeatureLimit

Per-tier feature limits — each row links a tier to a feature code with a limit value.

Column	Type	Description
id	Integer	Primary key
tier_id	Integer	FK to SubscriptionTier
feature_code	String	Feature identifier (e.g., max_products)
limit_value	Integer	Numeric limit (NULL = unlimited)
enabled	Boolean	Whether feature is enabled for this tier

MerchantSubscription

Per-merchant+platform subscription state. Subscriptions are merchant-level, not store-level.

Column	Type	Description
id	Integer	Primary key
merchant_id	Integer	FK to Merchant
platform_id	Integer	FK to Platform
tier_id	Integer	FK to SubscriptionTier
tier_code	String	Tier code (denormalized for convenience)
status	SubscriptionStatus	trial, active, past_due, cancelled, expired
stripe_customer_id	String	Stripe customer ID
stripe_subscription_id	String	Stripe subscription ID
trial_ends_at	DateTime	Trial expiry
period_start	DateTime	Current billing period start
period_end	DateTime	Current billing period end

MerchantFeatureOverride

Per-merchant exceptions to tier defaults (e.g., enterprise custom limits).

Column	Type	Description
id	Integer	Primary key
merchant_id	Integer	FK to Merchant
feature_code	String	Feature identifier
limit_value	Integer	Override limit (NULL = unlimited)

Add-on Entities

AddOnProduct

Purchasable add-on items (domains, SSL, email packages).

Column	Type	Description
id	Integer	Primary key
code	String	Unique add-on code
name	String	Display name
category	AddOnCategory	domain, ssl, email
price_cents	Integer	Price in cents
billing_period	BillingPeriod	monthly or yearly

StoreAddOn

Add-ons purchased by individual stores.

Column	Type	Description
id	Integer	Primary key
store_id	Integer	FK to Store
addon_product_id	Integer	FK to AddOnProduct
config	JSON	Configuration (e.g., domain name)
stripe_subscription_item_id	String	Stripe subscription item ID
status	String	active, cancelled, pending_setup

Supporting Entities

BillingHistory

Invoice and payment history records.

StripeWebhookEvent

Idempotency tracking for Stripe webhook events. Prevents duplicate event processing.

Key Relationships

• A SubscriptionTier has many TierFeatureLimits (one per feature)
• A Merchant has one MerchantSubscription per Platform
• A MerchantSubscription references one SubscriptionTier
• A Merchant can have many MerchantFeatureOverrides (per-feature)
• A Store can purchase many StoreAddOns
• Feature limits are resolved: MerchantFeatureOverride > TierFeatureLimit > default