Samir Boulahtit
9d8d5e7138
- 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>
412 lines
15 KiB
Python
412 lines
15 KiB
Python
# app/services/stripe_webhook_handler.py
|
|
"""
|
|
Stripe webhook event handler.
|
|
|
|
Processes webhook events from Stripe:
|
|
- Subscription lifecycle events
|
|
- Invoice and payment events
|
|
- Checkout session completion
|
|
"""
|
|
|
|
import logging
|
|
from datetime import datetime, timezone
|
|
|
|
import stripe
|
|
from sqlalchemy.orm import Session
|
|
|
|
from models.database.subscription import (
|
|
BillingHistory,
|
|
StripeWebhookEvent,
|
|
SubscriptionStatus,
|
|
SubscriptionTier,
|
|
VendorSubscription,
|
|
)
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
class StripeWebhookHandler:
|
|
"""Handler for Stripe webhook events."""
|
|
|
|
def __init__(self):
|
|
self.handlers = {
|
|
"checkout.session.completed": self._handle_checkout_completed,
|
|
"customer.subscription.created": self._handle_subscription_created,
|
|
"customer.subscription.updated": self._handle_subscription_updated,
|
|
"customer.subscription.deleted": self._handle_subscription_deleted,
|
|
"invoice.paid": self._handle_invoice_paid,
|
|
"invoice.payment_failed": self._handle_payment_failed,
|
|
"invoice.finalized": self._handle_invoice_finalized,
|
|
}
|
|
|
|
def handle_event(self, db: Session, event: stripe.Event) -> dict:
|
|
"""
|
|
Process a Stripe webhook event.
|
|
|
|
Args:
|
|
db: Database session
|
|
event: Stripe Event object
|
|
|
|
Returns:
|
|
Dict with processing result
|
|
"""
|
|
event_id = event.id
|
|
event_type = event.type
|
|
|
|
# Check for duplicate processing (idempotency)
|
|
existing = (
|
|
db.query(StripeWebhookEvent)
|
|
.filter(StripeWebhookEvent.event_id == event_id)
|
|
.first()
|
|
)
|
|
|
|
if existing:
|
|
if existing.status == "processed":
|
|
logger.info(f"Skipping duplicate event {event_id}")
|
|
return {"status": "skipped", "reason": "duplicate"}
|
|
elif existing.status == "failed":
|
|
logger.info(f"Retrying previously failed event {event_id}")
|
|
else:
|
|
# Record the event
|
|
webhook_event = StripeWebhookEvent(
|
|
event_id=event_id,
|
|
event_type=event_type,
|
|
status="pending",
|
|
)
|
|
db.add(webhook_event)
|
|
db.flush()
|
|
existing = webhook_event
|
|
|
|
# Process the event
|
|
handler = self.handlers.get(event_type)
|
|
if not handler:
|
|
logger.debug(f"No handler for event type {event_type}")
|
|
existing.status = "processed"
|
|
existing.processed_at = datetime.now(timezone.utc)
|
|
db.commit() # noqa: SVC-006 - Webhook handler controls its own transaction
|
|
return {"status": "ignored", "reason": f"no handler for {event_type}"}
|
|
|
|
try:
|
|
result = handler(db, event)
|
|
existing.status = "processed"
|
|
existing.processed_at = datetime.now(timezone.utc)
|
|
db.commit() # noqa: SVC-006 - Webhook handler controls its own transaction
|
|
logger.info(f"Successfully processed event {event_id} ({event_type})")
|
|
return {"status": "processed", "result": result}
|
|
|
|
except Exception as e:
|
|
logger.error(f"Error processing event {event_id}: {e}")
|
|
existing.status = "failed"
|
|
existing.error_message = str(e)
|
|
db.commit() # noqa: SVC-006 - Webhook handler controls its own transaction
|
|
raise
|
|
|
|
# =========================================================================
|
|
# Event Handlers
|
|
# =========================================================================
|
|
|
|
def _handle_checkout_completed(
|
|
self, db: Session, event: stripe.Event
|
|
) -> dict:
|
|
"""Handle checkout.session.completed event."""
|
|
session = event.data.object
|
|
vendor_id = session.metadata.get("vendor_id")
|
|
|
|
if not vendor_id:
|
|
logger.warning(f"Checkout session {session.id} missing vendor_id")
|
|
return {"action": "skipped", "reason": "no vendor_id"}
|
|
|
|
vendor_id = int(vendor_id)
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.vendor_id == vendor_id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for vendor {vendor_id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Update subscription with Stripe IDs
|
|
subscription.stripe_customer_id = session.customer
|
|
subscription.stripe_subscription_id = session.subscription
|
|
subscription.status = SubscriptionStatus.ACTIVE
|
|
|
|
# Get subscription details to set period dates
|
|
if session.subscription:
|
|
stripe_sub = stripe.Subscription.retrieve(session.subscription)
|
|
subscription.period_start = datetime.fromtimestamp(
|
|
stripe_sub.current_period_start, tz=timezone.utc
|
|
)
|
|
subscription.period_end = datetime.fromtimestamp(
|
|
stripe_sub.current_period_end, tz=timezone.utc
|
|
)
|
|
|
|
if stripe_sub.trial_end:
|
|
subscription.trial_ends_at = datetime.fromtimestamp(
|
|
stripe_sub.trial_end, tz=timezone.utc
|
|
)
|
|
|
|
logger.info(f"Checkout completed for vendor {vendor_id}")
|
|
return {"action": "activated", "vendor_id": vendor_id}
|
|
|
|
def _handle_subscription_created(
|
|
self, db: Session, event: stripe.Event
|
|
) -> dict:
|
|
"""Handle customer.subscription.created event."""
|
|
stripe_sub = event.data.object
|
|
customer_id = stripe_sub.customer
|
|
|
|
# Find subscription by customer ID
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_customer_id == customer_id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for customer {customer_id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Update subscription
|
|
subscription.stripe_subscription_id = stripe_sub.id
|
|
subscription.status = self._map_stripe_status(stripe_sub.status)
|
|
subscription.period_start = datetime.fromtimestamp(
|
|
stripe_sub.current_period_start, tz=timezone.utc
|
|
)
|
|
subscription.period_end = datetime.fromtimestamp(
|
|
stripe_sub.current_period_end, tz=timezone.utc
|
|
)
|
|
|
|
logger.info(f"Subscription created for vendor {subscription.vendor_id}")
|
|
return {"action": "created", "vendor_id": subscription.vendor_id}
|
|
|
|
def _handle_subscription_updated(
|
|
self, db: Session, event: stripe.Event
|
|
) -> dict:
|
|
"""Handle customer.subscription.updated event."""
|
|
stripe_sub = event.data.object
|
|
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_subscription_id == stripe_sub.id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for {stripe_sub.id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Update status and period
|
|
subscription.status = self._map_stripe_status(stripe_sub.status)
|
|
subscription.period_start = datetime.fromtimestamp(
|
|
stripe_sub.current_period_start, tz=timezone.utc
|
|
)
|
|
subscription.period_end = datetime.fromtimestamp(
|
|
stripe_sub.current_period_end, tz=timezone.utc
|
|
)
|
|
|
|
# Handle cancellation
|
|
if stripe_sub.cancel_at_period_end:
|
|
subscription.cancelled_at = datetime.now(timezone.utc)
|
|
subscription.cancellation_reason = stripe_sub.metadata.get(
|
|
"cancellation_reason", "user_request"
|
|
)
|
|
elif subscription.cancelled_at and not stripe_sub.cancel_at_period_end:
|
|
# Subscription reactivated
|
|
subscription.cancelled_at = None
|
|
subscription.cancellation_reason = None
|
|
|
|
# Check for tier change via price
|
|
if stripe_sub.items.data:
|
|
new_price_id = stripe_sub.items.data[0].price.id
|
|
if subscription.stripe_price_id != new_price_id:
|
|
# Price changed, look up new tier
|
|
tier = (
|
|
db.query(SubscriptionTier)
|
|
.filter(SubscriptionTier.stripe_price_monthly_id == new_price_id)
|
|
.first()
|
|
)
|
|
if tier:
|
|
subscription.tier = tier.code
|
|
logger.info(
|
|
f"Tier changed to {tier.code} for vendor {subscription.vendor_id}"
|
|
)
|
|
subscription.stripe_price_id = new_price_id
|
|
|
|
logger.info(f"Subscription updated for vendor {subscription.vendor_id}")
|
|
return {"action": "updated", "vendor_id": subscription.vendor_id}
|
|
|
|
def _handle_subscription_deleted(
|
|
self, db: Session, event: stripe.Event
|
|
) -> dict:
|
|
"""Handle customer.subscription.deleted event."""
|
|
stripe_sub = event.data.object
|
|
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_subscription_id == stripe_sub.id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for {stripe_sub.id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
subscription.status = SubscriptionStatus.CANCELLED
|
|
subscription.cancelled_at = datetime.now(timezone.utc)
|
|
|
|
logger.info(f"Subscription deleted for vendor {subscription.vendor_id}")
|
|
return {"action": "cancelled", "vendor_id": subscription.vendor_id}
|
|
|
|
def _handle_invoice_paid(self, db: Session, event: stripe.Event) -> dict:
|
|
"""Handle invoice.paid event."""
|
|
invoice = event.data.object
|
|
customer_id = invoice.customer
|
|
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_customer_id == customer_id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for customer {customer_id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Record billing history
|
|
billing_record = BillingHistory(
|
|
vendor_id=subscription.vendor_id,
|
|
stripe_invoice_id=invoice.id,
|
|
stripe_payment_intent_id=invoice.payment_intent,
|
|
invoice_number=invoice.number,
|
|
invoice_date=datetime.fromtimestamp(invoice.created, tz=timezone.utc),
|
|
subtotal_cents=invoice.subtotal,
|
|
tax_cents=invoice.tax or 0,
|
|
total_cents=invoice.total,
|
|
amount_paid_cents=invoice.amount_paid,
|
|
currency=invoice.currency.upper(),
|
|
status="paid",
|
|
invoice_pdf_url=invoice.invoice_pdf,
|
|
hosted_invoice_url=invoice.hosted_invoice_url,
|
|
)
|
|
db.add(billing_record)
|
|
|
|
# Reset payment retry count on successful payment
|
|
subscription.payment_retry_count = 0
|
|
subscription.last_payment_error = None
|
|
|
|
# Reset period counters if this is a new billing cycle
|
|
if subscription.status == SubscriptionStatus.ACTIVE:
|
|
subscription.orders_this_period = 0
|
|
subscription.orders_limit_reached_at = None
|
|
|
|
logger.info(f"Invoice paid for vendor {subscription.vendor_id}")
|
|
return {
|
|
"action": "recorded",
|
|
"vendor_id": subscription.vendor_id,
|
|
"invoice_id": invoice.id,
|
|
}
|
|
|
|
def _handle_payment_failed(self, db: Session, event: stripe.Event) -> dict:
|
|
"""Handle invoice.payment_failed event."""
|
|
invoice = event.data.object
|
|
customer_id = invoice.customer
|
|
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_customer_id == customer_id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
logger.warning(f"No subscription found for customer {customer_id}")
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Update subscription status
|
|
subscription.status = SubscriptionStatus.PAST_DUE
|
|
subscription.payment_retry_count = (subscription.payment_retry_count or 0) + 1
|
|
|
|
# Store error message
|
|
if invoice.last_payment_error:
|
|
subscription.last_payment_error = invoice.last_payment_error.get("message")
|
|
|
|
logger.warning(
|
|
f"Payment failed for vendor {subscription.vendor_id} "
|
|
f"(retry #{subscription.payment_retry_count})"
|
|
)
|
|
return {
|
|
"action": "marked_past_due",
|
|
"vendor_id": subscription.vendor_id,
|
|
"retry_count": subscription.payment_retry_count,
|
|
}
|
|
|
|
def _handle_invoice_finalized(
|
|
self, db: Session, event: stripe.Event
|
|
) -> dict:
|
|
"""Handle invoice.finalized event."""
|
|
invoice = event.data.object
|
|
customer_id = invoice.customer
|
|
|
|
subscription = (
|
|
db.query(VendorSubscription)
|
|
.filter(VendorSubscription.stripe_customer_id == customer_id)
|
|
.first()
|
|
)
|
|
|
|
if not subscription:
|
|
return {"action": "skipped", "reason": "no subscription"}
|
|
|
|
# Check if we already have this invoice
|
|
existing = (
|
|
db.query(BillingHistory)
|
|
.filter(BillingHistory.stripe_invoice_id == invoice.id)
|
|
.first()
|
|
)
|
|
|
|
if existing:
|
|
return {"action": "skipped", "reason": "already recorded"}
|
|
|
|
# Record as pending invoice
|
|
billing_record = BillingHistory(
|
|
vendor_id=subscription.vendor_id,
|
|
stripe_invoice_id=invoice.id,
|
|
invoice_number=invoice.number,
|
|
invoice_date=datetime.fromtimestamp(invoice.created, tz=timezone.utc),
|
|
due_date=datetime.fromtimestamp(invoice.due_date, tz=timezone.utc)
|
|
if invoice.due_date
|
|
else None,
|
|
subtotal_cents=invoice.subtotal,
|
|
tax_cents=invoice.tax or 0,
|
|
total_cents=invoice.total,
|
|
amount_paid_cents=0,
|
|
currency=invoice.currency.upper(),
|
|
status="open",
|
|
invoice_pdf_url=invoice.invoice_pdf,
|
|
hosted_invoice_url=invoice.hosted_invoice_url,
|
|
)
|
|
db.add(billing_record)
|
|
|
|
return {"action": "recorded_pending", "vendor_id": subscription.vendor_id}
|
|
|
|
# =========================================================================
|
|
# Helpers
|
|
# =========================================================================
|
|
|
|
def _map_stripe_status(self, stripe_status: str) -> SubscriptionStatus:
|
|
"""Map Stripe subscription status to internal status."""
|
|
status_map = {
|
|
"active": SubscriptionStatus.ACTIVE,
|
|
"trialing": SubscriptionStatus.TRIAL,
|
|
"past_due": SubscriptionStatus.PAST_DUE,
|
|
"canceled": SubscriptionStatus.CANCELLED,
|
|
"unpaid": SubscriptionStatus.PAST_DUE,
|
|
"incomplete": SubscriptionStatus.TRIAL, # Treat as trial until complete
|
|
"incomplete_expired": SubscriptionStatus.EXPIRED,
|
|
}
|
|
return status_map.get(stripe_status, SubscriptionStatus.EXPIRED)
|
|
|
|
|
|
# Create handler instance
|
|
stripe_webhook_handler = StripeWebhookHandler()
|