stripe/subscription

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Stripe static plans configuration

Define subscription plans statically with subscription.plans as an array. Each plan object requires: name (string, auto lowercased), priceId (string, Stripe price ID). Optional fields: annualDiscountPriceId (string), limits (object), freeTrial (object with days and callbacks), group (string), seatPriceId (string), prorationBehavior (string: 'create_prorations', 'always_invoice', or 'none'), lineItems (array).

Stripe dynamic plans configuration

Define subscription plans dynamically by setting subscription.plans to an async function that fetches plans from database or API and returns an array of plan objects.

Stripe subscription upgrade race condition handling

The successUrl parameter in subscription.upgrade is internally modified to handle race conditions between checkout completion and webhook processing. The plugin creates an intermediate redirect that ensures subscription status is properly updated before redirecting to the success page.

Stripe subscription list authorization

Implement authorizeReference in subscription config to control access to subscription listing. Receives { user, session, referenceId, action } where action is 'list-subscription'. Return boolean indicating if user has permission.

Stripe cancellation states

Subscriptions track multiple cancellation states: cancelAtPeriodEnd (whether subscription will/did cancel at end of billing period), cancelAt (when cancellation will take effect if scheduled), canceledAt (when cancellation was requested), endedAt (when subscription actually ended), status (changes to 'canceled' only after subscription has actually ended).

Stripe reference system

Subscriptions are associated with referenceId, defaulting to user ID. Use custom referenceId to associate subscriptions with organizations or other entities. Pass referenceId parameter to subscription methods.

Stripe team subscriptions with seats

For team/organization plans, pass seats parameter to subscription.upgrade to specify number of team members. The seats value is passed to Stripe as quantity for the subscription item.

Stripe subscriptions per reference limitation

The plugin only supports one active or trialing subscription per reference ID at a time. Multiple concurrent subscriptions for the same reference ID are not supported. When upgrading an existing subscription, must provide subscriptionId parameter.

Stripe subscription lifecycle hooks

Available subscription lifecycle callbacks in subscription config: onSubscriptionComplete (called when subscription created via checkout), onSubscriptionCreated (called when created outside checkout), onSubscriptionUpdate (called when subscription updated, receives stripeSubscription for raw Stripe fields), onSubscriptionCancel (called when canceled), onSubscriptionDeleted (called when deleted).

Stripe free trial configuration

Configure trial periods with freeTrial object containing: days (number, required), onTrialStart (function called when trial starts, receives subscription), onTrialEnd (function called when trial ends, receives { subscription } and context), onTrialExpired (function called when trial expires without conversion, receives subscription and context).

Stripe automatic trial abuse prevention

The plugin prevents users from getting multiple free trials. Once a user has used a trial (indicated by trialStart/trialEnd fields or trialing status), no new trial will be offered on any plan. Trial eligibility is determined at subscription creation time and cannot be overridden.

Stripe subscription options table

Subscription options: enabled (boolean, required), plans (StripePlan[] or async function, required if enabled), requireEmailVerification (boolean, default false), authorizeReference (function), getCheckoutSessionParams (function), onSubscriptionComplete (function), onSubscriptionCreated (function), onSubscriptionUpdate (function), onSubscriptionCancel (function), onSubscriptionDeleted (function).

Stripe plan configuration options

Plan options: name (string, required), priceId (string, required unless using lookupKey), lookupKey (string, alternative to priceId), annualDiscountPriceId (string), annualDiscountLookupKey (string), limits (object), group (string), seatPriceId (string, requires organization plugin), prorationBehavior (string: 'create_prorations', 'always_invoice', or 'none'), lineItems (array), freeTrial (object).

Stripe checkout session customization

Customize Stripe Checkout with getCheckoutSessionParams callback. Receives { user, session, plan, subscription }, request, and context. Return object with params key for Stripe parameters and options key for request options. Can set allow_promotion_codes, tax_id_collection, billing_address_collection, custom_text, metadata, idempotencyKey.

Stripe tax ID collection

To collect tax IDs in checkout, set tax_id_collection.enabled to true in getCheckoutSessionParams.

Stripe automatic tax calculation

To enable automatic tax calculation based on customer location, set automatic_tax.enabled to true in getCheckoutSessionParams. Requires tax registration setup and configuration in Stripe dashboard first.

Stripe mixed-interval subscriptions limitation

Stripe does not support mixed-interval subscriptions via Checkout Sessions. All line items in a checkout must use the same billing interval (e.g. all monthly or all yearly). If intervals differ, Stripe API will reject the request.

Stripe schedule at period end behavior

When scheduleAtPeriodEnd is true: subscription plan is not changed until billing period ends (only stripeScheduleId is stored), no redirect to Checkout or Billing Portal occurs, change is applied server-side, at period end Stripe fires customer.subscription.updated webhook which updates the subscription, if new upgrade is requested before period ends the existing pending schedule is released first.

Give your agent this brain