Skip to main content
Subscriptions represent an ongoing payment relationship with your customer. Flowglad provides a robust subscription model with carefully considered defaults to handle common billing scenarios effectively.

What is a Subscription?

A Subscription in Flowglad tracks the details of a recurring charge for a customer, including what products or services they’re paying for, how often, and their current status. Key concepts:
  • Customers are always on a subscription, even if they aren’t paying: when a customer is created, they are subscribed to the default plan for their pricing model. If they purchase a subscription product while they are currently subscribed to your pricing model’s free plan, their current subscription will change to be attached to the new price.
  • One Current Subscription per Customer (Default): By default, a customer can only have one active subscription at a time (see “Current vs Non-Current Subscriptions” below). This encourages simpler billing management. If you need customers to have multiple simultaneous subscriptions, you can enable the allow_multiple_subscriptions_per_customer setting at the organization level in your dashboard settings page.
  • Billing Cycle Anchor Date: The billingCycleAnchorDate (set from the startDate on creation) determines the day of the month billing occurs. If this date doesn’t exist in a given month (e.g., the 31st in February), billing occurs on the last day of that month.
  • Billing Periods: Defined by the startDate, interval (e.g., Month, Year), and intervalCount. Flowglad automatically calculates the currentBillingPeriodStart and currentBillingPeriodEnd for each cycle.

Subscription Structure

Each Subscription record has one or more SubscriptionItem records.
  • Subscription Record: Holds the core details like the customer (customerId), overall status, billing cycle information (interval, intervalCount, billingCycleAnchorDate), trial period (trialEnd), and potentially default/backup payment methods. It also has a primary priceId which often corresponds to the initial item purchased. But note: the SubscriptionItems define the actual billing components.
  • SubscriptionItem Record: Represents a specific product or service line item within the subscription. Each item has its own priceId, quantity, and unitPrice. This allows for subscriptions with multiple components, potentially added or changed over time. The sum of active subscription items determines the amount billed each period (for non-usage-based items).

Current vs Non-Current Subscriptions

Depending on its status, a subscription can either be current or not. A current subscription will grant feature access and usage credits. A non-current subscription will not. Current subscriptions have one of the following statuses:
  • "active"
  • "past_due"
  • "trialing"
  • "cancellation_scheduled"
  • "unpaid"
Subscriptions in all other statuses will be inactive.

Creating a Subscription

There are two primary ways to create a subscription:

1. Via Checkout Session

Customers can initiate subscriptions themselves by completing a checkout session for a product with a subscription type price.
  • How: This can be done through hosted product/price purchase pages or programmatically using the useBilling() hook’s createCheckoutSession method.
  • Use Case: Standard customer sign-ups and purchases where the customer interacts directly with a checkout flow initiated from within the product
  • Payment Method: Checkout Sessions typically require collecting payment details (unless a trial is offered).
Learn more about setting up checkouts in the Checkout Sessions documentation.

2. Via API

You can programmatically create subscriptions using the API endpoint
  • How: Requires providing customerId, priceId, startDate, interval, and intervalCount.
  • Use Case: Ideal for scenarios where you create subscriptions automatically based on actions within your application, such as user sign-up, plan changes initiated within your UI, or migrations.
  • Payment Method: Creating subscriptions via the API does not require a defaultPaymentMethodId or backupPaymentMethodId. This is useful for starting customers on free trials without asking for card details upfront. The subscription status will initially be Incomplete if autoStart is false and there’s no trial or payment method. It becomes Trialing if a trialEnd date is provided, or Active if autoStart is true and a default payment method exists for the customer or is provided.

Subscription Lifecycle & Billing

Subscriptions transition through various statuses and billing cycles over their lifetime.

Statuses

A subscription can be in one of several states (SubscriptionStatus):
  • Trialing: Active during a free trial period. Considered a “current” subscription.
  • Active: The standard state for a paying, up-to-date subscription. Considered “current”.
  • PastDue: Payment failed, but Flowglad may retry. Considered “current”.
  • Unpaid: Payment failed after retries; requires manual intervention or updated payment method. Considered “current”.
  • Incomplete: Created but needs setup (e.g., payment method added) before becoming active. Not “current”.
  • IncompleteExpired: A related Checkout Session expired before completion. Not “current”.
  • CancellationScheduled: Will be canceled at a future date (usually the end of the current billing period). Considered “current” until the cancellation date.
  • Canceled: The subscription has ended and is no longer active. Not “current”.
You can check if a subscription is in any of the “current” states (Active, PastDue, Trialing, CancellationScheduled, Unpaid) using helper functions or by checking the status directly.

Billing Periods & Transitions

At the end of each currentBillingPeriodEnd, a transition occurs:
  1. A new billing period is calculated based on the anchor date, interval, and interval count.
  2. For upcoming charges, a BillingRun is generated.

Charging Behavior

  • runBillingAtPeriodStart: This boolean field on the Subscription determines when the charge for a billing period is attempted.
    • Default for subscription Price Type: true. Charges are typically attempted at the start of the billing period (e.g., paying for the upcoming month).
    • Default for usage Price Type: false. Charges are attempted at the end of the billing period after usage for that period has been recorded.
  • Overrides: This default behavior can be overridden when creating or updating the subscription if needed.

Canceling a Subscription

Flowglad offers flexibility in how subscriptions can be canceled.

Cancellation Options

  • Immediately: The subscription is canceled right away. Proration logic may apply depending on your settings (though explicit proration controls are still evolving).
  • At End of Current Billing Period: The subscription remains active until the currentBillingPeriodEnd, at which point it transitions to Canceled. The status becomes CancellationScheduled until then.
  • At a Future Date (Coming Soon): Functionality to cancel on a specific arbitrary date in the future is planned.

Methods for Cancellation

  1. Flowglad Dashboard: Manually cancel subscriptions directly within the Flowglad UI.
  2. API: Programmatically cancel subscriptions using the API endpoint or SDK methods (client, server).
  3. Customer Self-Service: Allow customers to manage their own subscriptions.
    • Hosted Billing Portal: (available for livemode customers only) A no-code option accessible via a unique URL for your organization. The billingPortalUrl is returned in customer billing details from useBilling or the get billing details API. It can also be found in the customer details page in your Flowglad dashboard.
    • Headless Implementation: Use the useBilling() hook’s cancelSubscription function (ensure it’s used within a <FlowgladProvider> context) to build a completely custom cancellation UI.

Uncanceling a Subscription

If a subscription has been scheduled for cancellation (status cancellation_scheduled), you can reverse the cancellation before it takes effect. This restores the subscription to its previous state (either active or trialing) and ensures billing will continue as normal.

When Uncancel is Available

Uncancel is available for subscriptions that have a scheduled cancellation (status cancellation_scheduled). This typically happens when you cancel a subscription with the “At End of Current Billing Period” option. Once a subscription is immediately canceled (status canceled), it cannot be uncanceled. A new subscription would need to be created. For paid subscriptions, a valid payment method must exist for the subscription. For free subscriptions, no payment method is required.

Methods for Uncanceling

  • React SDK: Use the uncancelSubscription method from the useBilling() hook for client-side implementation
  • Server SDK: Use the uncancelSubscription method from FlowgladServer for server-side implementation
  • API: Make a POST request to /api/v1/subscriptions/{id}/uncancel
See the SDK documentation for detailed code examples.

Adjusting a Subscription

Flowglad supports upgrading and downgrading subscriptions mid-billing cycle with automatic proration handling. This allows customers to change their plan at any time without waiting for the next billing period.

What is a Subscription Adjustment?

A subscription adjustment changes the products or services a customer is subscribed to. This can be:
  • Upgrade: Moving to a higher-priced plan (e.g., from Basic to Pro)
  • Downgrade: Moving to a lower-priced plan (e.g., from Pro to Basic)
  • Lateral change: Switching to a different plan at the same price point

Adjustment Timing

When an adjustment occurs depends on the timing parameter:
  • Auto (default): Flowglad automatically determines the best timing by comparing the total monetary value of subscription items:
    • Upgrades (new total > current total) apply immediately with proration (customer gets new features right away)
    • Downgrades (new total < current total) apply at the end of the current billing period (customer keeps current plan until they’ve used what they paid for)
    • Same-price changes (new total = current total) apply immediately (no financial impact)
    The total is calculated as unitPrice × quantity summed across all subscription items.
  • Immediately: The adjustment takes effect right away. For upgrades, the customer is charged the prorated difference for the remainder of the billing period. For downgrades, the plan changes immediately but no refund is issued.
  • At End of Current Billing Period: The adjustment is scheduled for the end of the billing period. This is only valid for downgrades (changes with zero or negative net charge).

Proration

Proration ensures fair billing when plans change mid-cycle. Flowglad uses a “fair value” calculation:
  1. Calculate the value of the old plan for the time already used
  2. Calculate the value of the new plan for the remaining time in the billing period
  3. Determine the total fair value and compare against what has already been paid
  4. Charge only the difference (for upgrades)
Example: A customer on a $100/month plan upgrades to a $200/month plan halfway through the billing period:
  • Old plan value (first half): $50
  • New plan value (second half): $100
  • Total fair value: $150
  • Already paid: $100
  • Proration charge: $50
Downgrades do not issue refunds. When using auto timing, downgrades are scheduled for the end of the billing period so the customer continues to receive the value of their current plan.
You can disable proration by setting prorate: false when adjusting. This applies the plan change immediately but delays the pricing change until the next billing period. This effectively gives the customer the upgraded features for free until the period ends.
The prorate option only applies to immediately and auto timing. When using at_end_of_period, there is no proration since the change takes effect at the start of the next billing cycle.

Methods for Adjusting

  • React SDK: Use the adjustSubscription method from the useBilling() hook for client-side implementation
  • Server SDK: Use the adjustSubscription method from FlowgladServer for server-side implementation

Restrictions

Subscription adjustments have the following restrictions:
  • The subscription must be in an active state (not canceled, incomplete_expired, etc.)
  • The subscription must be a renewing subscription (not a one-time purchase)
  • The subscription cannot be a free plan (use createSubscription to upgrade from free)
  • The subscription cannot have the doNotCharge flag set
  • A valid payment method is required for proration charges (upgrades with prorate: true)
  • The new price must belong to the same pricing model as the subscription
  • Only recurring (subscription-type) prices can be used
  • For downgrades with resource features (e.g., team seats), claimed resources must fit within the new capacity—excess claims must be released before the adjustment can proceed
Resource claims (like team seats) persist across subscription adjustments. When upgrading, claims are preserved and new capacity is immediately available. When downgrading, Flowglad validates that active claims don’t exceed the new capacity. See Resources for detailed examples.
For subscriptions on a free trial without a payment method attached, proration upgrades will fail because there is no way to charge for the prorated amount. To upgrade a trialing subscription without a payment method, either:
  1. Collect a payment method first using a checkout session
  2. Use prorate: false to skip the immediate charge (customer gets features now, pays at next billing period)

Usage-Based Pricing and Adjustments

Subscription adjustments only affect recurring (subscription-type) prices. Usage-based pricing is not prorated during adjustments.
  • Usage charges continue to accumulate throughout the billing period regardless of any subscription adjustments
  • Usage is billed at the end of the billing period based on actual consumption
  • If you adjust a subscription mid-period, the customer will still be charged for all usage accrued during that period
To include usage-based pricing in a subscription, add usage prices as separate subscription items when creating the subscription. These items are billed based on metered usage rather than the adjustment proration logic.