Stripe Subscriptions Plugin

Accept payments and manage subscriptions with Stripe. Includes webhook processing, subscription sync, event logging, and an admin dashboard with tabbed UI.

Overview

The Stripe plugin provides a complete subscription management system for SonicJS, built for Cloudflare Workers (no Stripe SDK required — uses fetch API directly).

Installation

The Stripe plugin is a core plugin and can be installed from the admin plugins page at /admin/plugins.

1. Navigate to Admin > Plugins
2. Find "Stripe Subscriptions" and click Install
3. Go to Admin > Plugins > Stripe > Settings to configure your API keys

Configuration

Navigate to /admin/plugins/stripe/settings to configure the plugin. You'll need two keys from your Stripe Dashboard:

Setting Up Webhooks

1. Go to Stripe Dashboard > Developers > Webhooks
2. Click Add endpoint
3. Set the URL to https://your-domain.com/api/stripe/webhook
4. Select these events:
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • checkout.session.completed
   • invoice.payment_succeeded
   • invoice.payment_failed
5. Copy the Signing secret and paste it into the plugin settings

Local Development

Use the Stripe CLI to forward webhooks locally:

stripe listen --forward-to localhost:8787/api/stripe/webhook

The CLI prints a whsec_... signing secret to use during development.

Admin Dashboard

The Stripe admin UI at /admin/plugins/stripe has three tabbed pages:

Subscriptions Tab

Displays all subscriptions stored in D1 with:

• Status badges (active, canceled, past_due, trialing)
• Customer email (joined from users table)
• Stripe subscription and customer IDs
• Period dates and cancel-at-period-end status
• Pagination and status filtering
• Stats cards showing totals by status

Events Tab

Displays the webhook event log at /admin/plugins/stripe/events with:

• Stats cards (total, processed, failed, ignored)
• Filter by event type and status
• Event details: timestamp, type, object ID, Stripe event ID
• Error details shown on hover for failed events
• Pagination

Settings Tab

Configure API keys, webhook secret, and checkout URLs.

Subscription Sync

Click the Sync from Stripe button on the Subscriptions tab to pull all existing subscriptions from the Stripe API into D1.

The sync:

• Fetches all subscriptions from GET /v1/subscriptions (auto-paginates)
• Upserts each subscription into the subscriptions table by stripe_subscription_id
• Links subscriptions to SonicJS users via sonicjs_user_id metadata or customer ID lookup
• Reports total synced and any errors

This is useful when connecting Stripe to an existing account with pre-existing subscriptions.

Webhook Events

The plugin automatically logs every webhook event to the stripe_events table:

Events are logged with three statuses:

• processed — Successfully handled (subscription created/updated/deleted, payment succeeded/failed)
• failed — Handler threw an error (logged for debugging)
• ignored — Unhandled event type (logged for visibility)

API Reference

All API routes are prefixed with /api/stripe.

Public Endpoints

Authenticated Endpoints

Admin Endpoints

Query Parameters

GET /api/stripe/subscriptions:

GET /api/stripe/events:

Checkout Integration

To create a checkout session from your frontend:

const response = await fetch('/api/stripe/create-checkout-session', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    priceId: 'price_...' // Optional - uses default from settings
  })
})

const { url } = await response.json()
window.location.href = url // Redirect to Stripe Checkout

The plugin automatically:

• Finds or creates a Stripe customer for the logged-in user
• Attaches sonicjs_user_id metadata for webhook linking
• Redirects to Stripe Checkout with the configured success/cancel URLs