@startsimpli/billing

@startsimpli/billing

Universal billing integration for StartSimpli Next.js apps. Products and pricing are configured in Django admin — frontend components auto-fetch and render.

Backend Setup

The billing backend lives in start-simpli-api/apps/billing/. Models, admin, and API are already configured.

Key Endpoints

Endpoint	Method	Auth	Description
/api/v1/billing/products/	GET	Public	List public products with offers
/api/v1/billing/products/{slug}/	GET	Public	Get product by slug
/api/v1/billing/offer-checkout/	POST	Required	Create checkout session
/api/v1/billing/offer-portal/	POST	Required	Create portal session
/api/v1/billing/subscription/current/	GET	Required	Get current user's subscription

Admin Workflow

• Add a BillingProviderCredential (Stripe secret key + webhook secret)
• Create a BillingProduct (slug = identifier used by frontend)
• Add ProductOffer inlines (pricing tiers)
• Use "Sync to provider" admin action to push to Stripe

Frontend Setup

Installation

In your Next.js app's package.json:

{
  "dependencies": {
    "@startsimpli/billing": "workspace:*"
  }
}

Add transpilePackages: ['@startsimpli/billing'] to next.config.js.

Usage

import { BillingProvider, PricingPage, useCheckout, ManageSubscription } from '@startsimpli/billing'

// Wrap your app (or a subtree) with BillingProvider
<BillingProvider apiBaseUrl="/api/v1" authToken={accessToken}>
  <PricingPage productId="raise-simpli" onSelectOffer={handleSelect} />
</BillingProvider>

// Checkout hook
const { checkout, loading } = useCheckout()
await checkout({ offerId, successUrl, cancelUrl })

// Subscription management
<ManageSubscription returnUrl="/settings" buttonText="Manage Billing" />

Components

Component	Props	Description
BillingProvider	apiBaseUrl, authToken	Context provider — required wrapper
PricingPage	productId, onSelectOffer?	Full pricing display with offer cards
PricingSection	productId, onSelectOffer?	Pricing section component
PricingDetailPage	productId, onSelectOffer?	Detailed pricing page
UpgradeModal	productId, open, onClose, onSelectOffer?	Modal pricing overlay
ManageSubscription	returnUrl, buttonText?	Portal redirect button
SubscriptionManager	productId?	Full subscription management interface

Hooks

Hook	Returns	Description
useProduct(slug)	{ product, loading, error }	Fetch product + offers
useCheckout()	{ checkout, subscribeFree, loading, error }	Create checkout session or free subscription
usePortal()	{ openPortal, loading, error }	Open customer portal
useSubscription()	{ subscription, loading, error, refetch }	Get current user's subscription

Architecture

• Provider-agnostic: BaseBillingProvider → StripeBillingProvider (extensible to Paddle, etc.)
• BillingProviderFactory: Resolves credentials per-team with global fallback
• BillingService: Orchestrates sync, checkout, and portal operations
• ProductOffer: Supports flat, per_seat, tiered, volume, and usage pricing models

Integration with @startsimpli/auth

The billing package integrates seamlessly with @startsimpli/auth:

import { BillingProvider } from '@startsimpli/billing'
import { useAuth } from '@startsimpli/auth'

function App() {
  const { tokens } = useAuth()

  return (
    <BillingProvider
      apiBaseUrl={process.env.NEXT_PUBLIC_API_URL + '/api/v1'}
      authToken={tokens?.access}
    >
      {/* Your app */}
    </BillingProvider>
  )
}

Environment Variables

NEXT_PUBLIC_API_URL=https://api.startsimpli.com

Backend requires:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Tests

# Frontend tests (39 tests)
cd packages/billing
npm test

# Backend tests (184 tests)
cd start-simpli-api
docker-compose -f docker-compose.local.yml exec -T django pytest apps/billing/tests/ -v

Development

# Type checking
npm run type-check

# Watch mode for tests
npm run test:watch

# Coverage report
npm run test:coverage