Skip to main content
The useCheckout hook creates checkout sessions using your backend checkout route. By default it calls POST /api/priceos/v1/checkout.
Setup first: see the React integration guide.

​
Usage

const { createCheckoutSession, openCheckout } = useCheckout(options?)

​
Parameters

​
options.customerId
string
Optional fallback customerId used when openCheckout/createCheckoutSession are called without customerId in the body.

​
Returns

​
createCheckoutSession
(body) => Promise<CreateCustomerCheckoutResponse>
Creates a checkout session and returns { url }.
​
openCheckout
(body) => Promise<CreateCustomerCheckoutResponse>
Creates a checkout session, then redirects the browser to Stripe Checkout.

​
Body fields

​
productKey
string
required
Product key from your PriceOS dashboard to start checkout for.
​
stripePriceId
string
Optional Stripe price ID override. When omitted, PriceOS uses the product’s default active Stripe price.
​
successUrl
string
Optional URL to redirect to when checkout succeeds.
​
cancelUrl
string
Optional URL to redirect to when checkout is canceled.
​
customerId
string
Optional customer override. If omitted, the hook uses options.customerId or your backend identifyCustomer.
​
metadata
Record<string, string>
Optional metadata to attach to the Stripe checkout session.
​
checkoutParams
Record<string, unknown>
Optional Stripe Checkout session params to merge into the request.

​
Example

import { useCheckout } from "priceos/react";

export function UpgradeButton() {
  const { openCheckout } = useCheckout();

  async function onClick() {
    await openCheckout({
      productKey: "starter_monthly",
      successUrl: "https://app.acme.com/settings/billing?checkout=success",
      cancelUrl: "https://app.acme.com/settings/billing?checkout=canceled",
    });
  }

  return <button onClick={onClick}>Upgrade</button>;
}