BillWise

Framework-agnostic SaaS billing toolkit — Stripe integration, tier management, and usage tracking.

Built by Hidden Leaf Networks.

Installation

pip install billwise

# With Stripe integration
pip install billwise[stripe]

Quick Start

from billwise import TierManager, UsageTracker
from billwise.tiers import create_tier_config

# Define your tiers
config = create_tier_config({
    "free": {
        "is_free": True,
        "features": {"messages": 50, "documents": 5, "tokens": 50000},
    },
    "pro": {
        "price_id": "price_xxx",
        "features": {"messages": 500, "documents": 50, "tokens": 500000},
    },
    "enterprise": {
        "price_id": "price_yyy",
        "features": {"messages": -1, "documents": -1, "tokens": -1},
    },
})

tiers = TierManager(config)
tracker = UsageTracker(tiers)

# Check limits
result = tracker.check_limit("user_123", "free", "messages")
# {'allowed': True, 'limit': 50, 'used': 0, 'remaining': 50, 'unlimited': False}

# Track usage
tracker.increment("user_123", "free", "messages", amount=1)

# Get summary
summary = tracker.get_summary("user_123", "free")

Stripe Integration

from billwise.stripe_billing import StripeBilling

billing = StripeBilling(
    api_key="sk_...",
    webhook_secret="whsec_...",
    tier_manager=tiers,
    success_url="https://app.example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
    cancel_url="https://app.example.com/billing",
)

# Create checkout session
session = billing.create_checkout_session(
    user_id="user_123",
    tier_name="pro",
    email="user@example.com",
)
# {'checkout_url': 'https://checkout.stripe.com/...', 'session_id': 'cs_...'}

# Customer portal
portal = billing.create_portal_session(user_id="user_123")
# {'portal_url': 'https://billing.stripe.com/...'}

# Webhook handler (in your web framework)
result = billing.handle_webhook(request.body, request.headers["Stripe-Signature"])

Framework-Agnostic

BillWise uses Protocol-based storage backends. Implement two protocols to connect to any database:

from billwise.usage import UsageStore
from billwise.stripe_billing import SubscriptionStore

class MyUsageStore:
    def get_record(self, user_id, period_start):
        # Query your database
        ...
    def save_record(self, record):
        # Persist to your database
        ...

class MySubscriptionStore:
    def get_by_user(self, user_id): ...
    def get_by_stripe_customer(self, customer_id): ...
    def get_by_stripe_subscription(self, subscription_id): ...
    def save(self, subscription): ...

In-memory stores are included for testing.

Features

• Tier management — Define tiers with feature limits, compare tiers, look up by Stripe price ID
• Usage tracking — Increment counters, check limits, generate summaries
• Stripe integration — Checkout sessions, customer portal, webhook handling
• Event hooks — Register callbacks for checkout, subscription updates, cancellations
• Framework-agnostic — Protocol-based storage, works with any ORM or database

License

MIT License — see LICENSE for details.

---

Built with intention by Hidden Leaf Networks — an applied AI studio.