CheckoutModal

Import

import { CheckoutModal } from "@billingos/sdk";

Basic usage

const [open, setOpen] = useState(false);

<CheckoutModal
  open={open}
  onOpenChange={setOpen}
  priceId="price_pro_monthly"
  onSuccess={(subscription) => {
    console.log("Paid!", subscription);
    setOpen(false);
  }}
/>

The checkout modal renders in a secure iframe. Card data never touches your servers — it goes directly to Stripe.

Props

boolean

required

Whether the modal is visible.

(open: boolean) => void

required

Called when the modal should open or close.

string

required

The price ID to charge.

(subscription: any) => void

required

Called after a successful payment.

object

Prefill customer information to skip the email step.

Show child attributes

string

Customer email

string

Customer name

string

Tax ID

string

Apply a discount code automatically.

boolean

Require billing address during checkout.

string

Override the default currency.

string

Pass an existing subscription ID for upgrades/downgrades. The checkout will show proration details.

Record<string, string>

Custom key-value pairs attached to the subscription.

boolean

Enable localized pricing based on the customer’s location.

string

Locale for the checkout UI.

(error: Error) => void

Called if the payment fails.

() => void

Called if the user closes the modal without completing payment.

boolean

default:"false"

Enable debug logging for development.

The checkout modal runs in a secure iframe. Card details are handled entirely by Stripe — your app never processes or stores payment information. This means you’re PCI-compliant by default.

Examples

Upgrade with proration

<CheckoutModal
  open={open}
  onOpenChange={setOpen}
  priceId="price_enterprise_monthly"
  existingSubscriptionId={currentSubscription.id}
  onSuccess={(sub) => {
    toast.success("Upgraded!");
    queryClient.invalidateQueries({ queryKey: ["subscriptions"] });
  }}
/>

With customer prefill and coupon

<CheckoutModal
  open={open}
  onOpenChange={setOpen}
  priceId="price_pro_yearly"
  customer={{
    email: user.email,
    name: user.name,
  }}
  couponCode="LAUNCH20"
  onSuccess={handleSuccess}
  onError={(err) => toast.error(err.message)}
/>

Adaptive pricing

<CheckoutModal
  open={open}
  onOpenChange={setOpen}
  priceId="price_pro_monthly"
  adaptivePricing={true}
  onSuccess={handleSuccess}
/>

Getting Started

Components

Hooks

Advanced

Import

Basic usage

Props

Examples

Upgrade with proration

With customer prefill and coupon

Adaptive pricing

​Import

​Basic usage

​Props

​Examples

​Upgrade with proration

​With customer prefill and coupon

​Adaptive pricing

Import

Basic usage

Props

Examples

Upgrade with proration

With customer prefill and coupon

Adaptive pricing