> ## 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.

# useCheckout

> Programmatic checkout for custom payment flows.

## Import

```tsx theme={null}
import { useCheckout } from "@billingos/sdk";
```

## Usage

```tsx theme={null}
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

| Property        | Type                                   | Description                     |
| --------------- | -------------------------------------- | ------------------------------- |
| `openCheckout`  | `(options) => Promise<CheckoutResult>` | Opens the checkout flow         |
| `closeCheckout` | `() => void`                           | Closes the checkout             |
| `isLoading`     | `boolean`                              | Whether checkout is in progress |
| `error`         | `Error \| null`                        | Last error, if any              |

## Checkout options

| Option                   | Type                        | Required | Description              |
| ------------------------ | --------------------------- | -------- | ------------------------ |
| `priceId`                | `string`                    | Yes      | The price to charge      |
| `customer`               | `{ email?, name?, taxId? }` | No       | Prefill customer info    |
| `couponCode`             | `string`                    | No       | Discount code            |
| `existingSubscriptionId` | `string`                    | No       | For upgrades/downgrades  |
| `metadata`               | `Record<string, string>`    | No       | Custom data              |
| `adaptivePricing`        | `boolean`                   | No       | Enable localized pricing |

## Checkout result

```typescript theme={null}
interface CheckoutResult {
  success: boolean
  subscription?: Subscription
  error?: Error
}
```

## Imperative API

You can also open checkout programmatically from anywhere — even outside React:

```typescript theme={null}
// 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:

```typescript theme={null}
import { openCheckout } from "@billingos/sdk";

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

## Example: Custom upgrade flow

```tsx theme={null}
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>
  );
}
```