Checkout Addons with Stripe Billing

Learn how to create a subscription with addons using Stripe Billing.

Stripe allows us to add multiple line items to a single subscription. This is useful when you want to offer additional features or services to your customers.

This feature is not supported by default in Makerkit. However, in this guide, I will show you how to create a subscription with addons using Stripe Billing, and how to customize Makerkit to support this feature.

Let's get started!

1. Personal Account Checkout Form

File: apps/web/app/home/(user)/billing/_components/personal-account-checkout-form.tsx

Update your PersonalAccountCheckoutForm component to pass addon data to the checkout session creation process:

home/(user)/billing/_components/personal-account-checkout-form.tsx

<CheckoutForm
 // ...existing props
 onSubmit={({ planId, productId, addons }) => {
   startTransition(async () => {
     try {
       const { checkoutToken } = await createPersonalAccountCheckoutSession({
         planId,
         productId,
         addons, // Add this line
       });
       setCheckoutToken(checkoutToken);
     } catch {
       setError(true);
     }
   });
 }}
/>

This change allows the checkout form to handle addon selections and pass them to the checkout session creation process.

2. Personal Account Checkout Schema

Let's add addon support to the personal account checkout schema. The addons is an array of objects, each containing a productId and planId. By default, the addons array is empty.

Update your PersonalAccountCheckoutSchema:

home/(user)/billing/_lib/schema/personal-account-checkout.schema.ts

export const PersonalAccountCheckoutSchema = z.object({
 planId: z.string().min(1),
 productId: z.string().min(1),
 addons: z
   .array(
     z.object({
       productId: z.string().min(1),
       planId: z.string().min(1),
     }),
   )
   .default([]),
});

This schema update ensures that the addon data is properly validated before being processed.

3. User Billing Service

Update your createCheckoutSession method. This method is responsible for creating a checkout session with the billing gateway. We need to pass the addon data to the billing gateway:

home/(user)/billing/_lib/server/user-billing.service.ts

async createCheckoutSession({
 planId,
 productId,
 addons,
}: z.infer<typeof PersonalAccountCheckoutSchema>) {
 // ...existing code
 const checkoutToken = await this.billingGateway.createCheckoutSession({
   // ...existing props
   addons,
 });
 // ...rest of the method
}

This change ensures that the addon information is passed to the billing gateway when creating a checkout session.

4. Team Account Checkout Form

File: apps/web/app/home/[account]/billing/_components/team-account-checkout-form.tsx

Make similar changes to the TeamAccountCheckoutForm as we did for the personal account form.

5. Team Billing Schema

File: apps/web/app/home/[account]/billing/_lib/schema/team-billing.schema.ts

Update your TeamCheckoutSchema similar to the personal account schema.

6. Team Billing Service

File: apps/web/app/home/[account]/billing/_lib/server/team-billing.service.ts

Update the createCheckoutSession method similar to the user billing service.

7. Billing Configuration

We can now add addons to our billing configuration. Update your billing configuration file to include addons:

apps/web/config/billing.sample.config.ts

plans: [
 {
   // ...existing plan config
   addons: [
     {
       id: 'price_1J4J9zL2c7J1J4J9zL2c7J1',
       name: 'Extra Feature',
       cost: 9.99,
       type: 'flat' as const,
     },
   ],
 },
],

NB: the ID of the addon should match the planId in your Stripe account.

8. Localization

Add a new translation key for translating the term "Add-ons" in your billing locale file:

apps/web/public/locales/en/billing.json

{
 // ...existing translations
 "addons": "Add-ons"
}

9. Billing Schema

File: packages/billing/core/src/create-billing-schema.ts

The billing schema has been updated to include addons. You don't need to change this file, but be aware that the schema now supports addons.

10. Create Billing Checkout Schema

File: packages/billing/core/src/schema/create-billing-checkout.schema.ts

The checkout schema now includes addons. Again, you don't need to change this file, but your checkout process will now support addons.

11. Plan Picker Component

File: packages/billing/gateway/src/components/plan-picker.tsx

This component has been significantly updated to handle addons. It now displays addons as checkboxes and manages their state.

Here's the updated Plan Picker component:

packages/billing/gateway/src/components/plan-picker.tsx

'use client';
import { useMemo } from 'react';
import { zodResolver } from '@hookform/resolvers/zod';
import { ArrowRight, CheckCircle } from 'lucide-react';
import { useForm } from 'react-hook-form';
import { useTranslation } from 'react-i18next';
import { z } from 'zod';
import {
 BillingConfig,
 type LineItemSchema,
 getPlanIntervals,
 getPrimaryLineItem,
 getProductPlanPair,
} from '@kit/billing';
import { formatCurrency } from '@kit/shared/utils';
import { Badge } from '@kit/ui/badge';
import { Button } from '@kit/ui/button';
import { Checkbox } from '@kit/ui/checkbox';
import {
 Form,
 FormControl,
 FormField,
 FormItem,
 FormLabel,
 FormMessage,
} from '@kit/ui/form';
import { If } from '@kit/ui/if';
import { Label } from '@kit/ui/label';
import {
 RadioGroup,
 RadioGroupItem,
 RadioGroupItemLabel,
} from '@kit/ui/radio-group';
import { Separator } from '@kit/ui/separator';
import { Trans } from '@kit/ui/trans';
import { cn } from '@kit/ui/utils';
import { LineItemDetails } from './line-item-details';
const AddonSchema = z.object({
 name: z.string(),
 id: z.string(),
 productId: z.string(),
 planId: z.string(),
 cost: z.number(),
});
type OnSubmitData = {
 planId: string;
 productId: string;
 addons: z.infer<typeof AddonSchema>[];
};
export function PlanPicker(
 props: React.PropsWithChildren<{
   config: BillingConfig;
   onSubmit: (data: OnSubmitData) => void;
   canStartTrial?: boolean;
   pending?: boolean;
 }>,
) {
 const { t } = useTranslation(`billing`);
 const intervals = useMemo(
   () => getPlanIntervals(props.config),
   [props.config],
 ) as string[];
 const form = useForm({
   reValidateMode: 'onChange',
   mode: 'onChange',
   resolver: zodResolver(
     z
       .object({
         planId: z.string(),
         productId: z.string(),
         interval: z.string().optional(),
         addons: z.array(AddonSchema).optional(),
       })
       .refine(
         (data) => {
           try {
             const { product, plan } = getProductPlanPair(
               props.config,
               data.planId,
             );
             return product && plan;
           } catch {
             return false;
           }
         },
         { message: t('noPlanChosen'), path: ['planId'] },
       ),
   ),
   defaultValues: {
     interval: intervals[0],
     planId: '',
     productId: '',
     addons: [] as z.infer<typeof AddonSchema>[],
   },
 });
 const { interval: selectedInterval } = form.watch();
 const planId = form.getValues('planId');
 const { plan: selectedPlan, product: selectedProduct } = useMemo(() => {
   try {
     return getProductPlanPair(props.config, planId);
   } catch {
     return {
       plan: null,
       product: null,
     };
   }
 }, [props.config, planId]);
 const addons = form.watch('addons');
 const onAddonAdded = (data: z.infer<typeof AddonSchema>) => {
   form.setValue('addons', [...addons, data], { shouldValidate: true });
 };
 const onAddonRemoved = (id: string) => {
   form.setValue(
     'addons',
     addons.filter((item) => item.id !== id),
     { shouldValidate: true },
   );
 };
 // display the period picker if the selected plan is recurring or if no plan is selected
 const isRecurringPlan =
   selectedPlan?.paymentType === 'recurring' || !selectedPlan;
 const locale = useTranslation().i18n.language;
 return (
   <Form {...form}>
     <div
       className={
         'flex flex-col space-y-4 lg:flex-row lg:space-x-4 lg:space-y-0'
       }
     >
       <form
         className={'flex w-full max-w-xl flex-col space-y-6'}
         onSubmit={form.handleSubmit(props.onSubmit)}
       >
         <If condition={intervals.length}>
           <div
             className={cn('transition-all', {
               ['pointer-events-none opacity-50']: !isRecurringPlan,
             })}
           >
             <FormField
               name={'interval'}
               render={({ field }) => {
                 return (
                   <FormItem className={'rounded-md border p-4'}>
                     <FormLabel htmlFor={'plan-picker-id'}>
                       <Trans i18nKey={'common:billingInterval.label'} />
                     </FormLabel>
                     <FormControl id={'plan-picker-id'}>
                       <RadioGroup name={field.name} value={field.value}>
                         <div className={'flex space-x-2.5'}>
                           {intervals.map((interval) => {
                             const selected = field.value === interval;
                             return (
                               <label
                                 htmlFor={interval}
                                 key={interval}
                                 className={cn(
                                   'flex items-center space-x-2 rounded-md border border-transparent px-4 py-2 transition-colors',
                                   {
                                     ['border-primary']: selected,
                                     ['hover:border-primary']: !selected,
                                   },
                                 )}
                               >
                                 <RadioGroupItem
                                   id={interval}
                                   value={interval}
                                   onClick={() => {
                                     form.setValue('interval', interval, {
                                       shouldValidate: true,
                                     });
                                     form.setValue('addons', [], {
                                       shouldValidate: true,
                                     });
                                     if (selectedProduct) {
                                       const plan = selectedProduct.plans.find(
                                         (item) => item.interval === interval,
                                       );
                                       form.setValue(
                                         'planId',
                                         plan?.id ?? '',
                                         {
                                           shouldValidate: true,
                                           shouldDirty: true,
                                           shouldTouch: true,
                                         },
                                       );
                                     }
                                   }}
                                 />
                                 <span
                                   className={cn('text-sm', {
                                     ['cursor-pointer']: !selected,
                                   })}
                                 >
                                   <Trans
                                     i18nKey={`billing:billingInterval.${interval}`}
                                   />
                                 </span>
                               </label>
                             );
                           })}
                         </div>
                       </RadioGroup>
                     </FormControl>
                     <FormMessage />
                   </FormItem>
                 );
               }}
             />
           </div>
         </If>
         <FormField
           name={'planId'}
           render={({ field }) => (
             <FormItem>
               <FormLabel>
                 <Trans i18nKey={'common:planPickerLabel'} />
               </FormLabel>
               <FormControl>
                 <RadioGroup value={field.value} name={field.name}>
                   {props.config.products.map((product) => {
                     const plan = product.plans.find((item) => {
                       if (item.paymentType === 'one-time') {
                         return true;
                       }
                       return item.interval === selectedInterval;
                     });
                     if (!plan || plan.custom) {
                       return null;
                     }
                     const planId = plan.id;
                     const selected = field.value === planId;
                     const primaryLineItem = getPrimaryLineItem(
                       props.config,
                       planId,
                     );
                     if (!primaryLineItem) {
                       throw new Error(`Base line item was not found`);
                     }
                     return (
                       <RadioGroupItemLabel
                         selected={selected}
                         key={primaryLineItem.id}
                       >
                         <RadioGroupItem
                           data-test-plan={plan.id}
                           key={plan.id + selected}
                           id={plan.id}
                           value={plan.id}
                           onClick={() => {
                             if (selected) {
                               return;
                             }
                             form.setValue('planId', planId, {
                               shouldValidate: true,
                             });
                             form.setValue('productId', product.id, {
                               shouldValidate: true,
                             });
                             form.setValue('addons', [], {
                               shouldValidate: true,
                             });
                           }}
                         />
                         <div
                           className={
                             'flex w-full flex-col content-center space-y-2 lg:flex-row lg:items-center lg:justify-between lg:space-y-0'
                           }
                         >
                           <Label
                             htmlFor={plan.id}
                             className={
                               'flex flex-col justify-center space-y-2'
                             }
                           >
                             <div className={'flex items-center space-x-2.5'}>
                               <span className="font-semibold">
                                 <Trans
                                   i18nKey={`billing:plans.${product.id}.name`}
                                   defaults={product.name}
                                 />
                               </span>
                               <If
                                 condition={
                                   plan.trialDays && props.canStartTrial
                                 }
                               >
                                 <div>
                                   <Badge
                                     className={'px-1 py-0.5 text-xs'}
                                     variant={'success'}
                                   >
                                     <Trans
                                       i18nKey={`billing:trialPeriod`}
                                       values={{
                                         period: plan.trialDays,
                                       }}
                                     />
                                   </Badge>
                                 </div>
                               </If>
                             </div>
                             <span className={'text-muted-foreground'}>
                               <Trans
                                 i18nKey={`billing:plans.${product.id}.description`}
                                 defaults={product.description}
                               />
                             </span>
                           </Label>
                           <div
                             className={
                               'flex flex-col space-y-2 lg:flex-row lg:items-center lg:space-x-4 lg:space-y-0 lg:text-right'
                             }
                           >
                             <div>
                               <Price key={plan.id}>
                                 <span>
                                   {formatCurrency({
                                     currencyCode:
                                       product.currency.toLowerCase(),
                                     value: primaryLineItem.cost,
                                     locale,
                                   })}
                                 </span>
                               </Price>
                               <div>
                                 <span className={'text-muted-foreground'}>
                                   <If
                                     condition={
                                       plan.paymentType === 'recurring'
                                     }
                                     fallback={
                                       <Trans i18nKey={`billing:lifetime`} />
                                     }
                                   >
                                     <Trans
                                       i18nKey={`billing:perPeriod`}
                                       values={{
                                         period: selectedInterval,
                                       }}
                                     />
                                   </If>
                                 </span>
                               </div>
                             </div>
                           </div>
                         </div>
                       </RadioGroupItemLabel>
                     );
                   })}
                 </RadioGroup>
               </FormControl>
               <FormMessage />
             </FormItem>
           )}
         />
         <If condition={selectedPlan?.addons}>
           <div className={'flex flex-col space-y-2.5'}>
             <span className={'text-sm font-medium'}>Addons</span>
             <div className={'flex flex-col space-y-2'}>
               {selectedPlan?.addons?.map((addon) => {
                 return (
                   <div
                     className={'flex items-center space-x-2 text-sm'}
                     key={addon.id}
                   >
                     <Checkbox
                       value={addon.id}
                       onCheckedChange={() => {
                         if (addons.some((item) => item.id === addon.id)) {
                           onAddonRemoved(addon.id);
                         } else {
                           onAddonAdded({
                             productId: selectedProduct.id,
                             planId: selectedPlan.id,
                             id: addon.id,
                             name: addon.name,
                             cost: addon.cost,
                           });
                         }
                       }}
                     />
                     <span>{addon.name}</span>
                   </div>
                 );
               })}
             </div>
           </div>
         </If>
         <div>
           <Button
             data-test="checkout-submit-button"
             disabled={props.pending ?? !form.formState.isValid}
           >
             {props.pending ? (
               t('redirectingToPayment')
             ) : (
               <>
                 <If
                   condition={selectedPlan?.trialDays && props.canStartTrial}
                   fallback={t(`proceedToPayment`)}
                 >
                   <span>{t(`startTrial`)}</span>
                 </If>
                 <ArrowRight className={'ml-2 h-4 w-4'} />
               </>
             )}
           </Button>
         </div>
       </form>
       {selectedPlan && selectedInterval && selectedProduct ? (
         <PlanDetails
           selectedInterval={selectedInterval}
           selectedPlan={selectedPlan}
           selectedProduct={selectedProduct}
           addons={addons}
         />
       ) : null}
     </div>
   </Form>
 );
}
function PlanDetails({
 selectedProduct,
 selectedInterval,
 selectedPlan,
 addons = [],
}: {
 selectedProduct: {
   id: string;
   name: string;
   description: string;
   currency: string;
   features: string[];
 };
 selectedInterval: string;
 selectedPlan: {
   lineItems: z.infer<typeof LineItemSchema>[];
   paymentType: string;
 };
 addons: z.infer<typeof AddonSchema>[];
}) {
 const isRecurring = selectedPlan.paymentType === 'recurring';
 const { i18n } = useTranslation(`billing`);
 // trick to force animation on re-render
 const key = Math.random();
 return (
   <div
     key={key}
     className={
       'fade-in animate-in zoom-in-95 flex w-full flex-col space-y-4 py-2 lg:px-8'
     }
   >
     <div className={'flex flex-col space-y-0.5'}>
       <span className={'text-sm font-medium'}>
         <b>
           <Trans
             i18nKey={`billing:plans.${selectedProduct.id}.name`}
             defaults={selectedProduct.name}
           />
         </b>{' '}
         <If condition={isRecurring}>
           / <Trans i18nKey={`billing:billingInterval.${selectedInterval}`} />
         </If>
       </span>
       <p>
         <span className={'text-muted-foreground text-sm'}>
           <Trans
             i18nKey={`billing:plans.${selectedProduct.id}.description`}
             defaults={selectedProduct.description}
           />
         </span>
       </p>
     </div>
     <If condition={selectedPlan.lineItems.length > 0}>
       <Separator />
       <div className={'flex flex-col space-y-2'}>
         <span className={'text-sm font-semibold'}>
           <Trans i18nKey={'billing:detailsLabel'} />
         </span>
         <LineItemDetails
           lineItems={selectedPlan.lineItems ?? []}
           selectedInterval={isRecurring ? selectedInterval : undefined}
           currency={selectedProduct.currency}
         />
       </div>
     </If>
     <Separator />
     <div className={'flex flex-col space-y-2'}>
       <span className={'text-sm font-semibold'}>
         <Trans i18nKey={'billing:featuresLabel'} />
       </span>
       {selectedProduct.features.map((item) => {
         return (
           <div key={item} className={'flex items-center space-x-1 text-sm'}>
             <CheckCircle className={'h-4 text-green-500'} />
             <span className={'text-secondary-foreground'}>
               <Trans i18nKey={item} defaults={item} />
             </span>
           </div>
         );
       })}
     </div>
     <If condition={addons.length > 0}>
       <div className={'flex flex-col space-y-2'}>
         <span className={'text-sm font-semibold'}>
           <Trans i18nKey={'billing:addons'} />
         </span>
         {addons.map((addon) => {
           return (
             <div
               key={addon.id}
               className={'flex items-center space-x-1 text-sm'}
             >
               <CheckCircle className={'h-4 text-green-500'} />
               <span className={'text-secondary-foreground'}>
                 <Trans i18nKey={addon.name} defaults={addon.name} />
               </span>
               <span>-</span>
               <span className={'text-xs font-semibold'}>
                 {formatCurrency({
                   currencyCode: selectedProduct.currency.toLowerCase(),
                   value: addon.cost,
                   locale: i18n.language,
                 })}
               </span>
             </div>
           );
         })}
       </div>
     </If>
   </div>
 );
}
function Price(props: React.PropsWithChildren) {
 return (
   <span
     className={
       'animate-in slide-in-from-left-4 fade-in text-xl font-semibold tracking-tight duration-500'
     }
   >
     {props.children}
   </span>
 );
}

12. Stripe Checkout Creation

File: packages/billing/stripe/src/services/create-stripe-checkout.ts

The Stripe checkout creation process now includes addons:

if (params.addons.length > 0) {
  lineItems.push(
    ...params.addons.map((addon) => ({
      price: addon.planId,
      quantity: 1,
    })),
  );
}

This change ensures that selected addons are included in the Stripe checkout session.

Conclusion

These changes introduce a flexible addon system to Makerkit. By implementing these updates, you'll be able to offer additional features or services alongside your main subscription plans.

Remember, while adding addons to the checkout process is now straightforward, managing them post-purchase (like allowing users to add or remove addons from an active subscription) will require additional custom development. Consider your specific use case and user needs when implementing this feature.