Billing, Licenses & Stripe Setup

Complete guide to configuring Stripe for one-time license payments. Covers account creation, API keys, product setup, webhooks, testing, and going live.

License Tiers

AI OS offers four tiers. The Free Demo and Community edition are free. Business and Enterprise licenses use Stripe Checkout for PCI-compliant one-time payment processing.

Feature	Free Demo ($0)	Community (Free)	Business ($1,997)	Enterprise ($4,997)
Hosting	Hosted preview	Self-hosted	Self-hosted	Self-hosted
Agent access	3 agents	15 agents	All 51	All 51
Departments	Preview	5	All 10	All 10
Model tiers	Scout only	Scout + Pro	All 7 tiers	All 7 tiers
SEO Agency	1 audit/mo	5 audits/mo	Unlimited	Unlimited
Gemini Omni Studio	❌	❌	✅	✅
YouTube Intelligence	❌	❌	✅	✅
Custom agents	❌	❌	✅	✅
Custom domain	❌	✅ (self-hosted)	✅	✅
SSO / SAML	❌	❌	❌	✅
Priority support	❌	Community	Priority email	Priority + Slack
Optional renewal	N/A	N/A	N/A	$997/yr (extend priority support)

Step 1 — Create a Stripe Account

1. Go to dashboard.stripe.com/register
2. Sign up with your email
3. Verify your email and complete onboarding

Step 2 — Get Your Secret Key

1. Go to dashboard.stripe.com/apikeys
2. You will see two keys:
   • Publishable key (pk_test_...) — not needed for AI OS
   • Secret key (sk_test_...) — click “Reveal test key” and copy it
3. Paste into your .env:

STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX

Step 3 — Create Products and Prices

Create one Stripe product for each paid license tier. The Free Demo and Community tiers have no Stripe product.

Business License ($1,997 one-time)

1. Go to dashboard.stripe.com/products
2. Click + Add product
3. Fill in:
   • Name: AI OS Business License
   • Description: All 51 AI agents, all 10 departments, all commercial modules, self-hosted
4. Under Price information:
   • Pricing model: Standard
   • Price: $1,997.00
   • One time
5. Click Save product
6. On the product page, copy the Price ID (starts with price_)
7. Paste into .env:

STRIPE_BUSINESS_PRICE_ID=price_XXXXXXXXXXXXXXXXXXXXXXXX

Enterprise License ($4,997 one-time)

1. Click + Add product
2. Fill in:
   • Name: AI OS Enterprise License
   • Description: Everything in Business + 1 year priority support, custom agents, target response times, self-hosted
3. Under Price information:
   • Pricing model: Standard
   • Price: $4,997.00
   • One time
4. Save, copy the Price ID, paste into .env:

STRIPE_ENTERPRISE_PRICE_ID=price_XXXXXXXXXXXXXXXXXXXXXXXX

Optional Annual Renewal Products

Step 4 — Set Up the Webhook

The webhook lets Stripe notify your server when payments succeed, annual renewals process, or customers cancel.

1. Go to dashboard.stripe.com/webhooks
2. Click + Add endpoint
3. Endpoint URL: https://yourdomain.com/api/stripe/webhook
4. Events to listen to — click “Select events” and add:
   • checkout.session.completed
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
5. Click Add endpoint
6. On the webhook page, click Reveal under “Signing secret” and copy it (whsec_...)
7. Paste into .env:

STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXX

Step 5 — Complete .env Configuration

# Stripe — One-time license payments
STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX
STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXX
STRIPE_BUSINESS_PRICE_ID=price_XXXXXXXXXXXXXXXXXXXXXXXX
STRIPE_ENTERPRISE_PRICE_ID=price_XXXXXXXXXXXXXXXXXXXXXXXX
# Optional Enterprise renewal Price ID (if configured)
# STRIPE_ENTERPRISE_RENEWAL_PRICE_ID=price_XXXXXXXXXXXXXXXXXXXXXXXX

Step 6 — Restart and Test

sudo -u aios pm2 restart ai-os --update-env

Stripe Test Cards

Card Number	Result
4242 4242 4242 4242	Successful payment
4000 0000 0000 3220	Requires 3D Secure authentication
4000 0000 0000 0002	Card declined
4000 0000 0000 9995	Insufficient funds

Use any future expiry date, any 3-digit CVC, and any billing ZIP code.

Step 7 — Go Live

1. Complete Stripe account activation (business info, bank account for payouts)
2. Toggle Test mode off in the Stripe dashboard
3. Copy the live keys (sk_live_..., whsec_...)
4. Create the same products/prices in live mode (Price IDs will be different)
5. Update your .env with all live keys
6. Update the webhook endpoint to use live mode
7. Restart: sudo -u aios pm2 restart ai-os --update-env

Checkout Flow

The license purchase flow uses Stripe Checkout for secure, PCI-compliant payment processing:

1. User clicks a pricing CTA on the landing page
2. The server creates a Stripe Checkout Session via GET /api/stripe/checkout?plan=business or ?plan=enterprise
3. User is redirected to Stripe’s hosted payment page
4. After successful one-time payment, Stripe redirects to the success URL
5. The server provisions the license, creates a session cookie, and redirects to /app

Webhook Events

Event	Action
checkout.session.completed	Activate license, create session
customer.subscription.updated	Update annual renewal status (if applicable)
customer.subscription.deleted	End annual renewal (license remains active)
invoice.payment_succeeded	Confirm annual renewal payment
invoice.payment_failed	Notify user of renewal failure

Session Management

• Cookie name: ai-os-session
• Type: HTTP-only, Secure (production), SameSite: Lax
• Expiry: 30 days
• Content: Cryptographically random token (UUID v4)
• Validation: Server-side lookup maps token → email + plan + role + expiry
• Fallback: Bearer token via Authorization header (for API clients)