Skip to main content

​
Overview

Checkout sessions allow you to launch hosted Flowglad checkout pages to complete customer transactions.

​
Checkout Session Types

Flowglad offers three distinct types of checkout sessions, each tailored to different scenarios:
  • Product checkout: A “product” checkout session is the most straightforward and you can create it with createCheckoutSession in both client and server side. The customer will checkout according to the standard terms defined on your product and price records. Customers can initiate these sessions directly by visiting a product or price purchase page. You specify either the priceId or the priceSlug of the product (both single_payment and subscription are valid priceType’s), and provide the successUrl, cancelUrl, quantity, and optionally outputMetadata and outputName. See checkoutSession.ts for more information on the parameters.
  • Add Payment Method: The “Add Payment Method” checkout session provides a flow for customers to securely save a payment method to their Flowglad profile. You can create this type of checkout with createAddPaymentMethodCheckoutSession in both client and server side. Upon successful completion, the payment method is stored. Optionally, if a targetSubscriptionId is provided when creating the session, the newly added payment method will automatically become the default payment method for that specific subscription. See checkoutSession.ts for more information on the parameters.
  • Activate Subscription: You use this when a subscription already exists, but the customer still needs to provide payment details and formally start billing. It will prompt the customer to add or confirm a payment method, pay any outstanding invoices tied to the subscription, and transition the subscription from a pending/credit state to “active,” establishing the billing cycle anchor. See checkoutSession.ts for more information on the parameters.

​
Customer Association

When creating checkout sessions from the SDK, the authenticated customer’s ID will be linked automatically to the checkout sesion. Associating a checkout session with an existing customer record ensures that all billing activities are correctly attributed and avoids potential data discrepancies or the creation of duplicate customer profiles. To create anonymous checkout sessions, you can call the create checkout session API directly with anonymous field set to true.

​
What you can do

  • Create product checkout sessions.
  • Securely save a payment method to a customer’s Flowglad profile, optionally making it the default payment method for subscriptions.
  • …and more!

​
Example: Launch a product checkout

  • Client
  • Server
'use client'

import { useBilling } from '@flowglad/nextjs'

export function PurchaseButton({ priceId }: { priceId: string }) {
  const { createCheckoutSession, loaded, errors } = useBilling()

  if (!loaded) {
    return <button disabled>Loading checkout…</button>
  }

  if (errors) {
    return <p>Unable to load checkout right now.</p>
  }

  const handlePurchase = async () => {
    await createCheckoutSession({
      priceId,
      successUrl: `${window.location.origin}/billing/success`,
      cancelUrl: `${window.location.origin}/billing/cancel`,
      autoRedirect: true,
    })
  }

  return <button onClick={handlePurchase}>Buy now</button>
}

​
Example: Collect a payment method

  • Client
  • Server
'use client'

import { useBilling } from '@flowglad/nextjs'

export function SavePaymentMethodButton() {
  const { createAddPaymentMethodCheckoutSession, loaded, errors } = useBilling()

  if (!loaded) {
    return <button disabled>Loading billing…</button>
  }

  if (errors) {
    return <p>Unable to load billing right now.</p>
  }

  const handleSave = async () => {
    await createAddPaymentMethodCheckoutSession({
      successUrl: `${window.location.origin}/billing/payment-method/success`,
      cancelUrl: `${window.location.origin}/billing/payment-method/cancel`,
      autoRedirect: true,
    })
  }

  return <button onClick={handleSave}>Save payment method</button>
}