SkinbaseNova/docs/academy-billing-production.md

Academy Billing Production Rollout

Last updated: 2026-05-19

This note covers the remaining non-code steps required to move Academy Stripe billing from implemented-in-app to production-ready.

Readiness Check

Run the local readiness command before enabling the rollout flag:

php artisan academy:billing-health
php artisan academy:billing-health --json
php artisan academy:billing-health --strict

What it checks:

• Stripe publishable key, secret key, and webhook secret are configured and not placeholder values
• Academy billing price IDs are present for all configured plans
• Cashier webhook and Academy billing routes are registered
• Billing tables and Cashier user columns exist locally
• Moderation Academy billing overview route is available

--strict exits non-zero when blocking issues are found, which makes it suitable for CI or pre-deploy checks.

Environment Variables

The following values must be set with real production values before enabling Academy billing:

SKINBASE_ACADEMY_ENABLED=true
ACADEMY_BILLING_ENABLED=true
ACADEMY_STRIPE_SUBSCRIPTION_NAME=academy

STRIPE_KEY=pk_live_...
STRIPE_SECRET=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
CASHIER_CURRENCY=eur
CASHIER_CURRENCY_LOCALE=sl_SI

ACADEMY_CREATOR_MONTHLY_PRICE_ID=price_...
ACADEMY_PRO_MONTHLY_PRICE_ID=price_...

Do not enable ACADEMY_BILLING_ENABLED=true until the webhook endpoint and Billing Portal are configured in Stripe.

Stripe Dashboard Steps

Create these products:

• Skinbase Academy Creator
• Skinbase Academy Pro

Create these recurring prices:

• creator_monthly
• pro_monthly

Configure the production webhook endpoint:

• URL: https://skinbase.org/stripe/webhook
• Signing secret: copy into STRIPE_WEBHOOK_SECRET

Recommended subscribed events:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• customer.updated
• customer.deleted
• payment_method.automatically_updated
• invoice.payment_succeeded
• invoice.payment_failed
• invoice.payment_action_required

Configure Stripe Billing Portal:

• Allow payment method updates
• Allow plan changes
• Allow cancellation
• Allow invoice history access

Deployment Sequence

1. Deploy code and migrations.
2. Populate production env with live Stripe values and production price IDs.
3. Run php artisan academy:billing-health --strict on the target environment.
4. Confirm the webhook endpoint is reachable and signature verification is active.
5. Test a full Stripe test-mode or low-risk live transaction.
6. Verify the subscription appears in local Cashier tables and Academy access updates from synced state.
7. Verify /moderation/academy/billing shows the expected audit event and subscription counts.
8. Enable ACADEMY_BILLING_ENABLED=true only after the prior checks pass.

Smoke Test Checklist

After rollout:

• Guest can view Academy pricing
• Guest cannot start checkout
• Verified user can start checkout
• Success page does not grant access by itself
• Webhook sync creates or updates the local subscription rows
• Creator plan unlocks creator content but not pro content
• Pro plan unlocks creator and pro content
• Billing Portal opens and returns to /academy/billing
• Canceling a subscription keeps access during grace period and removes it after end

Operational Note

The moderation billing overview at /moderation/academy/billing is visibility-only. It is not a manual entitlement system and should not be used to bypass Stripe billing state.