Checkout

Nozle supports hosted and embedded Stripe payment results. The flow:

Customer selects a plan in your application
The React SDK calls your authenticated merchant callback with { planCode, returnUrl }
Your backend derives the customer, validates the plan and return origin, and calls Nozle with sk_
Nozle keeps the current plan active and computes the exact invoice or proration
If money remains due, Nozle returns a hosted Stripe URL or embedded client secret
Customer completes payment with Stripe
Stripe sends signed payment events to Nozle
Nozle applies the paid plan change only after verified success

Plan checkout is payment-gated: a paid plan change is not applied until Stripe confirms payment through the webhook. If prepaid credits reduce the exact amount due to zero, Nozle applies the change transactionally and returns type: "completed" without creating a Stripe session.

Required Stripe webhook setup

When you connect a Stripe account, Nozle registers a Stripe webhook endpoint for that account and stores Stripe’s webhook signing secret. Your Stripe account must allow webhook endpoint creation. The webhook target is derived from your public Nozle API URL:

{NOZLE_PUBLIC_API_URL}/webhooks/stripe/{organization_id}?code={stripe_provider_code}

Stripe events used by checkout:

payment_intent.succeeded
payment_intent.payment_failed
payment_intent.canceled

Without this webhook, Stripe may collect payment but Nozle will not reliably update invoice or subscription state.

API shape

Plan checkout:

{
  "customer_id": "customer_123",
  "plan_code": "growth",
  "return_url": "https://app.example.com/settings/billing"
}

Free plans and paid upgrades fully funded by prepaid credits return a completed response instead. Downgrades and other cycle-end transitions return a scheduled response from the same /checkout endpoint; browser sessions never call /billing/upgrade or /subscriptions/change.

Response

{
  "type": "stripe",
  "client_secret": "cs_...",
  "clientSecret": "cs_...",
  "invoice_id": "invoice_uuid",
  "amount_cents": 19900,
  "currency": "USD"
}

The browser calls your authenticated merchant backend, which derives the Nozle customer and starts checkout with a restricted sk_. A Nozle publishable key is valid only for the plan catalog. If you mount embedded Stripe checkout yourself, your app also needs the Stripe publishable key for the same Stripe account connected in Nozle. Credit-funded completion response:

{
  "type": "completed",
  "status": "succeeded",
  "payment_source": "credits",
  "plan_code": "growth",
  "amount_cents": 0,
  "currency": "USD"
}

Scheduled transition response:

{
  "type": "scheduled",
  "status": "pending",
  "subscription_id": "subscription_uuid",
  "plan_code": "starter"
}

React implementation

Option A — CheckoutButton (simplest)

<CheckoutButton
  planCode="growth"
  returnUrl="https://app.example.com/settings/billing"
  label="Subscribe to Growth"
  onStripeClientSecret={setClientSecret}
/>

Option B — Custom flow with `useCheckoutSession`

const { fetchClientSecret, isLoading } = useCheckoutSession();

const handleCheckout = async () => {
  const clientSecret = await fetchClientSecret(
    'growth',
    'https://app.example.com/settings/billing',
  );
  // Pass the cs_... secret to <Checkout>
};

Option C — Embedded Stripe Checkout

<Checkout
  clientSecret={secret}
  publishableKey={import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY}
  onComplete={() => router.refresh()}
/>

Server-side plan changes

For B2B scenarios where payment is already handled outside embedded checkout:

const result = await nozle.subscribe('customer_123', 'growth');
// { subscription_id: 'sub_...', status: 'active' }

subscribe() requires a secret key (sk_). Embedded checkout should be used when Nozle needs to collect payment before activating a paid plan.

Mixed Entity plan checkout

Seat-based products can sell different Entity plans in one invoice and one payment. Your backend first creates or reuses active placeholder Entities, then calls the bulk Entity checkout endpoint with the selected plan for each placeholder.

Customer workspace
├── seat_pro_001 -> Pro monthly
├── seat_pro_002 -> Pro monthly
└── seat_max_001 -> Max monthly
           │
           └── one Nozle invoice -> one Stripe checkout

Keep the secret key in your backend. The browser should send only merchant-facing intent, such as { proSeats: 2, maxSeats: 1 }; your backend derives the customer, creates stable Entity IDs, validates the return origin, and calls Nozle. Use billing_time: "anniversary" when the first successful purchase should establish the customer’s renewal day. Later Entity purchases align to that day and use Nozle’s invoice proration. See Entity Subscriptions for the complete request and response.

Getting Started

Billing

Product Credits

Margin Intelligence

Entitlements

Required Stripe webhook setup

API shape

Response

React implementation

Option A — CheckoutButton (simplest)

Option B — Custom flow with `useCheckoutSession`

Option C — Embedded Stripe Checkout

Server-side plan changes

Mixed Entity plan checkout

​Required Stripe webhook setup

​API shape

​Response

​React implementation

​Option A — CheckoutButton (simplest)

​Option B — Custom flow with useCheckoutSession

​Option C — Embedded Stripe Checkout

​Server-side plan changes

​Mixed Entity plan checkout

Required Stripe webhook setup

API shape

Response

React implementation

Option A — CheckoutButton (simplest)

Option B — Custom flow with `useCheckoutSession`

Option C — Embedded Stripe Checkout

Server-side plan changes

Mixed Entity plan checkout