feat: add subscription and billing system with Stripe integration

- Add database models for subscription tiers, vendor subscriptions,
  add-ons, billing history, and webhook events
- Implement BillingService for subscription operations
- Implement StripeService for Stripe API operations
- Implement StripeWebhookHandler for webhook event processing
- Add vendor billing API endpoints for subscription management
- Create vendor billing page with Alpine.js frontend
- Add limit enforcement for products and team members
- Add billing exceptions for proper error handling
- Create comprehensive unit tests (40 tests passing)
- Add subscription billing documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/api/main.py

@@ -11,7 +11,7 @@ This module provides:
 from fastapi import APIRouter
 
 from app.api.v1 import admin, shop, vendor
-from app.api.v1.shared import language
+from app.api.v1.shared import language, webhooks
 
 api_router = APIRouter()
 
@@ -42,3 +42,4 @@ api_router.include_router(shop.router, prefix="/v1/shop", tags=["shop"])
 # ============================================================================
 
 api_router.include_router(language.router, prefix="/v1", tags=["language"])
+api_router.include_router(webhooks.router, prefix="/v1", tags=["webhooks"])

app/api/v1/admin/products.py

@@ -101,6 +101,8 @@ class CopyToVendorResponse(BaseModel):
     copied: int
     skipped: int
     failed: int
+    auto_matched: int = 0
+    limit_reached: bool = False
     details: list[dict] | None = None
 
 

app/api/v1/shared/webhooks.py

@@ -1 +1,63 @@
-# External webhooks (Stripe, etc.
+# app/api/v1/shared/webhooks.py
+"""
+External webhook endpoints.
+
+Handles webhooks from:
+- Stripe (payments and subscriptions)
+"""
+
+import logging
+
+from fastapi import APIRouter, Header, Request
+from sqlalchemy.orm import Session
+
+from app.core.database import get_db
+from app.exceptions import InvalidWebhookSignatureException, WebhookMissingSignatureException
+from app.services.stripe_service import stripe_service
+from app.services.stripe_webhook_handler import stripe_webhook_handler
+
+router = APIRouter(prefix="/webhooks")
+logger = logging.getLogger(__name__)
+
+
+@router.post("/stripe")  # public - Stripe webhooks use signature verification
+async def stripe_webhook(
+    request: Request,
+    stripe_signature: str = Header(None, alias="Stripe-Signature"),
+):
+    """
+    Handle Stripe webhook events.
+
+    Stripe sends events for:
+    - Subscription lifecycle (created, updated, deleted)
+    - Invoice and payment events
+    - Checkout session completion
+
+    The endpoint verifies the webhook signature and processes events idempotently.
+    """
+    if not stripe_signature:
+        logger.warning("Stripe webhook received without signature")
+        raise WebhookMissingSignatureException()
+
+    # Get raw body for signature verification
+    payload = await request.body()
+
+    try:
+        # Verify and construct event
+        event = stripe_service.construct_event(payload, stripe_signature)
+    except ValueError as e:
+        logger.warning(f"Invalid Stripe webhook: {e}")
+        raise InvalidWebhookSignatureException(str(e))
+
+    # Process the event
+    db = next(get_db())
+    try:
+        result = stripe_webhook_handler.handle_event(db, event)
+        return {"received": True, **result}
+    except Exception as e:
+        logger.error(f"Error processing Stripe webhook: {e}")
+        # Return 200 to prevent Stripe retries for processing errors
+        # The event is marked as failed and can be retried manually
+        return {"received": True, "error": str(e)}
+    finally:
+        db.close()

app/api/v1/vendor/__init__.py

@@ -16,6 +16,7 @@ from fastapi import APIRouter
 from . import (
     analytics,
     auth,
+    billing,
     content_pages,
     customers,
     dashboard,
@@ -73,6 +74,7 @@ router.include_router(media.router, tags=["vendor-media"])
 router.include_router(notifications.router, tags=["vendor-notifications"])
 router.include_router(messages.router, tags=["vendor-messages"])
 router.include_router(analytics.router, tags=["vendor-analytics"])
+router.include_router(billing.router, tags=["vendor-billing"])
 
 # Content pages management
 router.include_router(

app/api/v1/vendor/billing.py

@@ -0,0 +1,405 @@
+# app/api/v1/vendor/billing.py
+"""
+Vendor billing and subscription management endpoints.
+
+Provides:
+- Subscription status and usage
+- Tier listing and comparison
+- Stripe checkout and portal access
+- Invoice history
+- Add-on management
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_vendor_api
+from app.core.config import settings
+from app.core.database import get_db
+from app.services.billing_service import billing_service
+from app.services.subscription_service import subscription_service
+from models.database.user import User
+
+router = APIRouter(prefix="/billing")
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Schemas
+# ============================================================================
+
+
+class SubscriptionStatusResponse(BaseModel):
+    """Current subscription status and usage."""
+
+    tier_code: str
+    tier_name: str
+    status: str
+    is_trial: bool
+    trial_ends_at: str | None = None
+    period_start: str | None = None
+    period_end: str | None = None
+    cancelled_at: str | None = None
+    cancellation_reason: str | None = None
+
+    # Usage
+    orders_this_period: int
+    orders_limit: int | None
+    orders_remaining: int | None
+    products_count: int
+    products_limit: int | None
+    products_remaining: int | None
+    team_count: int
+    team_limit: int | None
+    team_remaining: int | None
+
+    # Payment
+    has_payment_method: bool
+    last_payment_error: str | None = None
+
+    class Config:
+        from_attributes = True
+
+
+class TierResponse(BaseModel):
+    """Subscription tier information."""
+
+    code: str
+    name: str
+    description: str | None = None
+    price_monthly_cents: int
+    price_annual_cents: int | None = None
+    orders_per_month: int | None = None
+    products_limit: int | None = None
+    team_members: int | None = None
+    features: list[str] = []
+    is_current: bool = False
+    can_upgrade: bool = False
+    can_downgrade: bool = False
+
+
+class TierListResponse(BaseModel):
+    """List of available tiers."""
+
+    tiers: list[TierResponse]
+    current_tier: str
+
+
+class CheckoutRequest(BaseModel):
+    """Request to create a checkout session."""
+
+    tier_code: str
+    is_annual: bool = False
+
+
+class CheckoutResponse(BaseModel):
+    """Checkout session response."""
+
+    checkout_url: str
+    session_id: str
+
+
+class PortalResponse(BaseModel):
+    """Customer portal session response."""
+
+    portal_url: str
+
+
+class InvoiceResponse(BaseModel):
+    """Invoice information."""
+
+    id: int
+    invoice_number: str | None = None
+    invoice_date: str
+    due_date: str | None = None
+    total_cents: int
+    amount_paid_cents: int
+    currency: str
+    status: str
+    pdf_url: str | None = None
+    hosted_url: str | None = None
+
+
+class InvoiceListResponse(BaseModel):
+    """List of invoices."""
+
+    invoices: list[InvoiceResponse]
+    total: int
+
+
+class AddOnResponse(BaseModel):
+    """Add-on product information."""
+
+    id: int
+    code: str
+    name: str
+    description: str | None = None
+    category: str
+    price_cents: int
+    billing_period: str
+    quantity_unit: str | None = None
+    quantity_value: int | None = None
+
+
+class VendorAddOnResponse(BaseModel):
+    """Vendor's purchased add-on."""
+
+    id: int
+    addon_code: str
+    addon_name: str
+    status: str
+    domain_name: str | None = None
+    quantity: int
+    period_start: str | None = None
+    period_end: str | None = None
+
+
+class AddOnPurchaseRequest(BaseModel):
+    """Request to purchase an add-on."""
+
+    addon_code: str
+    domain_name: str | None = None  # For domain add-ons
+    quantity: int = 1
+
+
+class CancelRequest(BaseModel):
+    """Request to cancel subscription."""
+
+    reason: str | None = None
+    immediately: bool = False
+
+
+class CancelResponse(BaseModel):
+    """Cancellation response."""
+
+    message: str
+    effective_date: str
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@router.get("/subscription", response_model=SubscriptionStatusResponse)
+def get_subscription_status(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Get current subscription status and usage metrics."""
+    vendor_id = current_user.token_vendor_id
+
+    usage = subscription_service.get_usage_summary(db, vendor_id)
+    subscription, tier = billing_service.get_subscription_with_tier(db, vendor_id)
+
+    return SubscriptionStatusResponse(
+        tier_code=subscription.tier,
+        tier_name=tier.name if tier else subscription.tier.title(),
+        status=subscription.status.value,
+        is_trial=subscription.is_in_trial(),
+        trial_ends_at=subscription.trial_ends_at.isoformat()
+        if subscription.trial_ends_at
+        else None,
+        period_start=subscription.period_start.isoformat()
+        if subscription.period_start
+        else None,
+        period_end=subscription.period_end.isoformat()
+        if subscription.period_end
+        else None,
+        cancelled_at=subscription.cancelled_at.isoformat()
+        if subscription.cancelled_at
+        else None,
+        cancellation_reason=subscription.cancellation_reason,
+        orders_this_period=usage.orders_this_period,
+        orders_limit=usage.orders_limit,
+        orders_remaining=usage.orders_remaining,
+        products_count=usage.products_count,
+        products_limit=usage.products_limit,
+        products_remaining=usage.products_remaining,
+        team_count=usage.team_count,
+        team_limit=usage.team_limit,
+        team_remaining=usage.team_remaining,
+        has_payment_method=bool(subscription.stripe_payment_method_id),
+        last_payment_error=subscription.last_payment_error,
+    )
+
+
+@router.get("/tiers", response_model=TierListResponse)
+def get_available_tiers(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Get available subscription tiers for upgrade/downgrade."""
+    vendor_id = current_user.token_vendor_id
+    subscription = subscription_service.get_or_create_subscription(db, vendor_id)
+    current_tier = subscription.tier
+
+    tier_list, _ = billing_service.get_available_tiers(db, current_tier)
+
+    tier_responses = [TierResponse(**tier_data) for tier_data in tier_list]
+
+    return TierListResponse(tiers=tier_responses, current_tier=current_tier)
+
+
+@router.post("/checkout", response_model=CheckoutResponse)
+def create_checkout_session(
+    request: CheckoutRequest,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Create a Stripe checkout session for subscription."""
+    vendor_id = current_user.token_vendor_id
+    vendor = billing_service.get_vendor(db, vendor_id)
+
+    # Build URLs
+    base_url = f"https://{settings.platform_domain}"
+    success_url = f"{base_url}/vendor/{vendor.vendor_code}/billing?success=true"
+    cancel_url = f"{base_url}/vendor/{vendor.vendor_code}/billing?cancelled=true"
+
+    result = billing_service.create_checkout_session(
+        db=db,
+        vendor_id=vendor_id,
+        tier_code=request.tier_code,
+        is_annual=request.is_annual,
+        success_url=success_url,
+        cancel_url=cancel_url,
+    )
+    db.commit()
+
+    return CheckoutResponse(checkout_url=result["checkout_url"], session_id=result["session_id"])
+
+
+@router.post("/portal", response_model=PortalResponse)
+def create_portal_session(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Create a Stripe customer portal session."""
+    vendor_id = current_user.token_vendor_id
+    vendor = billing_service.get_vendor(db, vendor_id)
+    return_url = f"https://{settings.platform_domain}/vendor/{vendor.vendor_code}/billing"
+
+    result = billing_service.create_portal_session(db, vendor_id, return_url)
+
+    return PortalResponse(portal_url=result["portal_url"])
+
+
+@router.get("/invoices", response_model=InvoiceListResponse)
+def get_invoices(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Get invoice history."""
+    vendor_id = current_user.token_vendor_id
+
+    invoices, total = billing_service.get_invoices(db, vendor_id, skip=skip, limit=limit)
+
+    invoice_responses = [
+        InvoiceResponse(
+            id=inv.id,
+            invoice_number=inv.invoice_number,
+            invoice_date=inv.invoice_date.isoformat(),
+            due_date=inv.due_date.isoformat() if inv.due_date else None,
+            total_cents=inv.total_cents,
+            amount_paid_cents=inv.amount_paid_cents,
+            currency=inv.currency,
+            status=inv.status,
+            pdf_url=inv.invoice_pdf_url,
+            hosted_url=inv.hosted_invoice_url,
+        )
+        for inv in invoices
+    ]
+
+    return InvoiceListResponse(invoices=invoice_responses, total=total)
+
+
+@router.get("/addons", response_model=list[AddOnResponse])
+def get_available_addons(
+    category: str | None = Query(None, description="Filter by category"),
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Get available add-on products."""
+    addons = billing_service.get_available_addons(db, category=category)
+
+    return [
+        AddOnResponse(
+            id=addon.id,
+            code=addon.code,
+            name=addon.name,
+            description=addon.description,
+            category=addon.category,
+            price_cents=addon.price_cents,
+            billing_period=addon.billing_period,
+            quantity_unit=addon.quantity_unit,
+            quantity_value=addon.quantity_value,
+        )
+        for addon in addons
+    ]
+
+
+@router.get("/my-addons", response_model=list[VendorAddOnResponse])
+def get_vendor_addons(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Get vendor's purchased add-ons."""
+    vendor_id = current_user.token_vendor_id
+
+    vendor_addons = billing_service.get_vendor_addons(db, vendor_id)
+
+    return [
+        VendorAddOnResponse(
+            id=va.id,
+            addon_code=va.addon_product.code,
+            addon_name=va.addon_product.name,
+            status=va.status,
+            domain_name=va.domain_name,
+            quantity=va.quantity,
+            period_start=va.period_start.isoformat() if va.period_start else None,
+            period_end=va.period_end.isoformat() if va.period_end else None,
+        )
+        for va in vendor_addons
+    ]
+
+
+@router.post("/cancel", response_model=CancelResponse)
+def cancel_subscription(
+    request: CancelRequest,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Cancel subscription."""
+    vendor_id = current_user.token_vendor_id
+
+    result = billing_service.cancel_subscription(
+        db=db,
+        vendor_id=vendor_id,
+        reason=request.reason,
+        immediately=request.immediately,
+    )
+    db.commit()
+
+    return CancelResponse(
+        message=result["message"],
+        effective_date=result["effective_date"],
+    )
+
+
+@router.post("/reactivate")
+def reactivate_subscription(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """Reactivate a cancelled subscription."""
+    vendor_id = current_user.token_vendor_id
+
+    result = billing_service.reactivate_subscription(db, vendor_id)
+    db.commit()
+
+    return result

app/api/v1/vendor/products.py

@@ -14,6 +14,7 @@ from sqlalchemy.orm import Session
 from app.api.deps import get_current_vendor_api
 from app.core.database import get_db
 from app.services.product_service import product_service
+from app.services.subscription_service import subscription_service
 from models.database.user import User
 from models.schema.product import (
     ProductCreate,
@@ -89,6 +90,9 @@ def add_product_to_catalog(
 
     This publishes a MarketplaceProduct to the vendor's public catalog.
     """
+    # Check product limit before creating
+    subscription_service.check_product_limit(db, current_user.token_vendor_id)
+
     product = product_service.create_product(
         db=db, vendor_id=current_user.token_vendor_id, product_data=product_data
     )
@@ -157,6 +161,9 @@ def publish_from_marketplace(
 
     Shortcut endpoint for publishing directly from marketplace import.
     """
+    # Check product limit before creating
+    subscription_service.check_product_limit(db, current_user.token_vendor_id)
+
     product_data = ProductCreate(
         marketplace_product_id=marketplace_product_id, is_active=True
     )