Skip to main content
The stripe-subscriptions plugin adds subscription-based billing to your Ship project using Stripe. It includes a complete pricing page, Stripe Checkout integration, webhook handling, and subscription management APIs.

​
Installation

npx create-ship-app@latest install stripe-subscriptions

​
What gets installed

​
Dependencies

WorkspacePackageVersion
apps/apistripe20.3.1

​
Files

API (apps/api):
FileDescription
src/config/stripe.config.tsEnvironment config for STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET
src/services/stripe/stripe.service.tsStripe SDK wrapper — customer creation, subscription helpers, billing portal access
src/resources/subscriptions/subscription.schema.tsZod schema for subscription data
src/resources/subscriptions/endpoints/subscribe.tsCreates a Stripe Checkout session for new subscriptions
src/resources/subscriptions/endpoints/getCurrent.tsReturns the current user’s active subscription with live Stripe sync
src/resources/subscriptions/endpoints/upgrade.tsUpgrades/downgrades/cancels the current subscription
src/resources/subscriptions/endpoints/previewUpgrade.tsPreviews proration costs before upgrading
src/resources/subscriptions/endpoints/createPortalSession.tsCreates a Stripe Billing Portal session
src/resources/webhook/endpoints/stripe.tsHandles Stripe webhook events (subscription created/updated/deleted)
src/resources/users/user.stripe.extend.tsExtends the user schema with stripeId and subscription fields
Web (apps/web):
FileDescription
src/config/stripe.config.tsClient-side config for Stripe public key and price IDs
src/pages/pricing/constants.tsPlan definitions (Free, Creator, Pro) with price IDs
src/pages/pricing/index.page.tsxFull pricing page with plan selection, subscribe, upgrade, and billing portal

​
Environment variables

After installing, add the following environment variables:

​
API (apps/api)

VariableDescription
STRIPE_SECRET_KEYYour Stripe secret key from the Developers dashboard
STRIPE_WEBHOOK_SECRETWebhook signing secret from your Stripe webhook endpoint

​
Web (apps/web)

VariableDescription
NEXT_PUBLIC_STRIPE_PUBLIC_KEYYour Stripe publishable key
NEXT_PUBLIC_PRICE_CREATORStripe Price ID for the Creator plan
NEXT_PUBLIC_PRICE_PROStripe Price ID for the Pro plan

​
Stripe setup

​
1. Get API keys

Navigate to the Developers tab and select API keys.
  • Publishable key → NEXT_PUBLIC_STRIPE_PUBLIC_KEY (web)
  • Secret key → STRIPE_SECRET_KEY (api)

​
2. Create subscription products

Go to the Products tab and create your subscription products. Each product needs a recurring price. Copy the Price IDs into your web environment variables.

​
3. Set up webhooks

Create a webhook endpoint pointing to https://<your-api-url>/webhook/stripe with the following events:
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
Copy the webhook signing secret into STRIPE_WEBHOOK_SECRET.
For local development, use the Stripe CLI to forward webhook events to your localhost.

​
API endpoints

MethodPathDescription
POST/subscriptions/subscribeCreate a Checkout session for a new subscription
GET/subscriptions/currentGet the current user’s subscription (syncs with Stripe)
POST/subscriptions/upgradeChange plan or cancel subscription
GET/subscriptions/preview-upgradePreview proration costs
POST/subscriptions/create-portal-sessionOpen the Stripe Billing Portal
POST/webhook/stripeStripe webhook handler (public endpoint)