Stripe Billing Integration

Monetize from Day One

Most directory builders leave billing as an afterthought — “we’ll figure out payments later.” AI Magic Directory ships with Stripe fully integrated so you can start collecting revenue the day you launch.

Three Billing Models, One Platform

Every directory operator has a different pricing strategy. AI Magic Directory supports all three out of the box:

Subscription Plans Fixed monthly billing for predictable revenue. Providers pay a flat fee regardless of lead volume. This is ideal for high-value directories where providers expect unlimited access.

Metered (Pay-Per-Lead) Billing Usage-based pricing where providers pay per lead delivered. A background worker batches unreported leads every 5 minutes and reports them to Stripe as metered usage. Revenue scales linearly with the value you deliver.

Free Tier Every directory needs a funnel entry point. The free tier gives providers limited access (e.g., 5 leads/month, no featured badge) — enough to demonstrate value, not enough to satisfy demand. When they hit the ceiling, the upgrade path is one click away.

Stripe Checkout Integration

Provider signup flows through Stripe Checkout — a PCI-compliant, hosted payment page that handles credit cards, debit cards, and local payment methods. No payment form to build, no PCI audit to maintain. Checkout creates a Stripe customer, attaches the subscription, and redirects the provider back to their dashboard.

Self-Serve Billing Management

Providers manage their own billing through Stripe Customer Portal — update payment methods, view invoices, change plans, or cancel. This eliminates billing support tickets and gives providers full control over their account.

Automated Usage Reporting

For metered billing, a dedicated background worker runs every 5 minutes:

1. Queries payments_usage for unreported leads
2. Groups leads by organization
3. Reports usage to Stripe via usage_records.create
4. Marks leads as reported to prevent double-counting

The worker uses p-retry with exponential backoff (3 attempts) to handle transient Stripe API failures gracefully. It caches subscription item IDs to minimize API calls.

Webhook Lifecycle Management

AI Magic Directory handles every Stripe webhook event that matters:

• checkout.session.completed — Activates the subscription, stores customer ID
• customer.subscription.updated — Syncs plan changes, period dates
• customer.subscription.deleted — Handles cancellations gracefully
• invoice.payment_succeeded — Confirms payment, updates billing status
• charge.failed — Flags failed payments, triggers notifications

Every webhook event is logged to the audit table with the full event diff, creating a complete billing history.

Revenue Visibility

The admin dashboard shows billing metrics in real time:

• Active subscriptions by plan tier
• Metered usage (leads delivered per organization)
• Revenue by directory
• Failed payment flags

The ROI Calculation

If you charge $49/month per listing and acquire 100 paying providers, that’s $4,900/month in recurring revenue. With metered billing at $2/lead, 100 providers averaging 50 leads/month generates $10,000/month. The billing infrastructure is already built — your only job is acquiring listings.