Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.billingos.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Import

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

​
Usage

function UpgradeButton({ priceId }: { priceId: string }) {
  const { openCheckout, isLoading, error } = useCheckout();

  const handleClick = async () => {
    const result = await openCheckout({
      priceId,
      customer: { email: "user@example.com" },
    });

    if (result.success) {
      toast.success("Payment successful!");
    }
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? "Processing..." : "Upgrade"}
    </button>
  );
}

​
Return value

PropertyTypeDescription
openCheckout(options) => Promise<CheckoutResult>Opens the checkout flow
closeCheckout() => voidCloses the checkout
isLoadingbooleanWhether checkout is in progress
errorError | nullLast error, if any

​
Checkout options

OptionTypeRequiredDescription
priceIdstringYesThe price to charge
customer{ email?, name?, taxId? }NoPrefill customer info
couponCodestringNoDiscount code
existingSubscriptionIdstringNoFor upgrades/downgrades
metadataRecord<string, string>NoCustom data
adaptivePricingbooleanNoEnable localized pricing

​
Checkout result

interface CheckoutResult {
  success: boolean
  subscription?: Subscription
  error?: Error
}

​
Imperative API

You can also open checkout programmatically from anywhere — even outside React: 
// Via the global window object
window.billingOS?.checkout.open({
  priceId: "price_pro_monthly",
  onSuccess: (subscription) => {
    console.log("Subscribed!", subscription);
  },
  onError: (error) => {
    console.error("Checkout failed:", error);
  },
});
Or using the exported function: 
import { openCheckout } from "@billingos/sdk";

await openCheckout({
  priceId: "price_pro_monthly",
  sessionToken: "bos_session_test_...",
});

​
Example: Custom upgrade flow

function PlanCard({ plan }) {
  const { openCheckout, isLoading } = useCheckout();

  return (
    <div className="border rounded p-6">
      <h3>{plan.name}</h3>
      <p>${plan.price}/mo</p>
      <button
        onClick={() => openCheckout({ priceId: plan.priceId })}
        disabled={isLoading}
      >
        {plan.isCurrentPlan ? "Current" : "Choose Plan"}
      </button>
    </div>
  );
}