Offerings & Checkout

This guide covers reading offerings in a page, formatting prices, taking payment, one-tap upsells, and declarative failure recovery. Full signatures are in the components reference and hooks reference.

A design axiom first: Appfunnel does not manage currency. The payment provider resolves the visitor’s price; the SDK receives one { amount, currency } per offering and only displays it, formatted in the active locale. There’s no FX and no currency picker on our side.

Reading an offering

useOffering(slot) takes a slot id from funnel.ts offerings and returns a display-ready Offering, or undefined if the slot is unassigned or not found. useOfferings() returns all offerings in order.

import { useOffering, useOfferings } from '@appfunnel-dev/sdk'
 
const offering = useOffering('plan') // Offering | undefined
const all = useOfferings() // Offering[]

import { definePage, useOffering, Checkout } from '@appfunnel-dev/sdk'
 
export default definePage(function Paywall() {
	const offering = useOffering('plan')
 
	if (!offering) {
		return <p>Assign an offering to the "plan" slot to turn on checkout.</p>
	}
 
	return (
		<section>
			<h1 className="text-3xl font-bold">{offering.name}</h1>
			<p className="mt-2 text-xl font-semibold">
				{offering.price.formatted}
				{offering.period !== 'one-time' ? `/${offering.period}` : ''}
			</p>
			<Checkout offering="plan" className="mt-6" />
		</section>
	)
})

The Offering shape

Offering is display-ready — prices are already formatted in the active locale.

Money is { amount, minor, currency, formatted } — amount is major units (79), minor is minor units (7900), and formatted is the locale-formatted string you render.

The one-time hazard

period for a one-time offering is the literal string 'one-time'. So the naive template pattern:

{
	offering.price.formatted
}
{
	offering.period ? `/${offering.period}` : ''
}

renders $49/one-time — because 'one-time' is a truthy string. Guard on the value, not on existence:

{
	offering.price.formatted
}
{
	offering.period !== 'one-time' ? `/${offering.period}` : ''
}

Checkout

Three components take money, and the one you reach for answers where the payment happens:

import { Checkout, CheckoutButton, UpsellButton } from '@appfunnel-dev/sdk'
 
<Checkout offering="plan" />                                  // payment renders right here
<CheckoutButton offering="plan">Get my plan</CheckoutButton>  // a button opens it
<UpsellButton offering="addon">Add it</UpsellButton>          // one tap, card already saved

Each takes the offering slot id, and that’s the only required prop. The SDK handles the purchase analytics (checkout.start, purchase.complete) and advances the funnel after the charge; the card entry and the charge itself run through the store the funnel is published to.

<Checkout> — payment on the page

<Checkout> mounts the payment where you put the tag. There is no button to tap first and no label to write, so it takes no children.

<Checkout offering="plan" className="mt-6" />

By default it renders the best complete way to pay for the store this funnel sells through — every visitor who reaches it can finish, whatever wallets they do or don’t have set up.

<CheckoutButton> — payment behind a tap

Same purchase, opened from a button. Default label: “Continue”. Pass asChild with exactly one element to use your own button instead:

<CheckoutButton offering="plan" asChild>
	<button className="rounded-lg bg-black px-6 py-3 text-white">
		Start my trial
	</button>
</CheckoutButton>

By default the payment opens in the funnel’s own sheet — the visitor never leaves the page.

<UpsellButton> — one tap, no card re-entry

<UpsellButton> charges the payment method the visitor already saved, off-session. Nothing opens: one tap and it’s bought. It’s the post-purchase upsell primitive, for pages declared type: 'upsell'. Default label: “Add to my plan”.

<UpsellButton offering="addon">Add annual coaching</UpsellButton>

If that charge fails, it recovers on-session: the funnel’s sheet asks for a payment method and charges once more, in place, without losing the visitor’s position in the sequence. That’s on by default — write recover={false} to opt out and just report the failure through onError / the checkout.failed event.

Every option, and what happens if you don’t set it

Only offering is required. Write nothing else and you get a complete, working checkout — this is what each option does when left alone.

Refining what the visitor sees — payment

payment picks the payment UI. It’s on all three components and means the same thing on each; it defaults to auto.

The wallet button and the wallet row are not the same thing. wallets — and auto on a phone — gives you Stripe’s own black Apple Pay button: one tap, authorize, done. card lists “Apple Pay” as a row the visitor selects before pressing your pay button. Same payment method, more steps between the visitor and the purchase.

Leading with the wallet never traps anyone. A “Pay another way” control sits under the button and reveals the card form in place — the wallet button stays where it is — and a visitor with no wallet enrolled goes straight to the card form without seeing it at all.

Styling the SDK’s buttons

Two buttons are the SDK’s own rather than the provider’s — the pay button and “Pay another way” — and both ship styled, in your brand colour, with nothing to configure.

Out of the box the pay button is a solid near-black bar at the size and weight a paywall CTA wants, and “Pay another way” is a quiet control beneath it. Write nothing and the checkout looks finished — there’s no setup step here.

When you do want them in your own brand, pass classNames and write Tailwind exactly as you would anywhere else:

<Checkout
	offering="plan"
	classNames={{
		submit: 'w-full rounded-xl bg-emerald-600 py-4 text-lg font-bold text-white',
		payAnotherWay: 'mt-3 w-full rounded-xl bg-neutral-100 py-3 font-semibold',
	}}
/>

Your classes win outright. The defaults are written at zero specificity, so a single Tailwind class beats them — no !important, no fighting inline styles, and no need to know which stylesheet loaded first. The same is true of a plain CSS rule on [data-checkout-submit] or [data-checkout-another-way] if you’d rather keep it in a stylesheet.

The provider’s own card fields are a different question — they render inside its frame, where no class of yours reaches. Theme those with appearance.

Wallet-first paywall. wallets is the one setting that can show a visitor a UI they can’t use — someone with no wallet enrolled has nothing to tap — so give them a second way through:

<section>
	<Checkout offering="plan" payment="wallets" />
	<CheckoutButton offering="plan" payment="card" className="mt-3 underline">
		Pay with a card instead
	</CheckoutButton>
</section>

Let the provider run the whole purchase. payment="full" hands over the entire moment — the provider draws its own order summary and its own pay button, and you draw nothing:

<Checkout offering="plan" payment="full" />

How the methods are listed — methods

Wherever the SDK draws the payment UI itself — payment="card", and payment="auto" where it resolves to the list — methods shapes that list. It works the same on <Checkout> and <CheckoutButton>, including the payment a button opens in the sheet.

By default the methods are an accordion with the first one open. A collapsed list only earns its extra tap when there’s a real choice to make — and where card is the only method, which is common now that wallets lead as their own button, collapsing gives the visitor a row reading “Card” they must press to reach fields they already knew were coming.

<Checkout offering="plan" />                                            // first method open
<Checkout offering="plan" methods={{ collapsed: true }} />              // all closed, visitor picks
<Checkout offering="plan" methods={{ layout: 'tabs' }} />               // methods across the top
<Checkout offering="plan" methods={{ order: ['apple_pay', 'card'] }} /> // lead with Apple Pay

Wallet-only checkout. payAnotherWay: false gives a visitor with Apple Pay that button and nothing else — no card form to drop into:

<Checkout offering="plan" methods={{ payAnotherWay: false }} />

It doesn’t strand anyone who has no wallet: with no wallet to show, there’s no wallet button to stand alone, and they get the card form exactly as they would otherwise. The setting only decides what someone who has a wallet is offered beside it. Be deliberate about it though — a visitor whose card fails inside the wallet sheet has nowhere else to go on that screen.

Below a wallet button, the revealed list leads with card unless you set order yourself — the wallets are already offered above, and opening one as the first row would show its mandate text instead of the card fields the visitor just asked for.

Refining where it opens — opens

opens is on the two button components (<Checkout> has nowhere else to open — it is the payment). It defaults to sheet.

The in-app-browser escape hatch. Paid social sends traffic through the in-app browsers Meta and TikTok open, and overlays can fail silently in them. opens="redirect" gives up the overlay for a full-page hand-off that always works:

<CheckoutButton offering="plan" opens="redirect">
	Continue to payment
</CheckoutButton>

The return trip is handled for you — see Redirect-return settlement.

On <UpsellButton>, payment and opens describe the recovery — the only thing an upsell ever presents. payment="wallets" re-collects with a wallet button instead of a card form; opens="redirect" recovers on the provider’s page instead of in the funnel’s sheet.

Merchant of record — managed

managed puts Stripe on the hook as merchant of record for that one charge: Stripe owns the tax, the fraud checks and the disputes. It’s decided per checkout, so a funnel can sell one offering managed and another not.

<Checkout offering="plan" managed />

Under managed the provider collects the card in its own frame, so payment narrows to auto and full — asking for card or wallets alongside it is a compile error rather than something you find out at publish. Your Stripe account also has to be onboarded to managed payments; the charge is refused if it isn’t.

Custom CTAs — useCheckout

Reach for asChild first — it gives your own element the click handler and keeps every default. When you need more than a trigger (your own loading and error states, a charge fired from something that isn’t a button), useCheckout(options) is the headless hook underneath all three components.

import { useCheckout } from '@appfunnel-dev/sdk'
 
function BuyButton() {
	const checkout = useCheckout({ intent: 'purchase' })
	return (
		<button
			onClick={() => checkout.open('plan', 'sheet')}
			disabled={checkout.isLoading}
		>
			{checkout.isLoading ? 'Processing…' : 'Buy now'}
		</button>
	)
}

useCheckout returns { open, status, error, isLoading, reset, ... }. status moves through 'idle' → 'loading' → 'requires_action' → 'success' | 'error'. The options — intent, kind, managed, advanceOnSuccess, onSuccess, onError, onFailed — are the same ones the components accept. advanceOnSuccess defaults to true, so a successful charge advances the funnel automatically.

open’s first argument is the offering slot id. open('plan', 'sheet') opens the funnel’s sheet; open('plan') with no second argument charges off-session, which is what an upsell does.

Declarative failure recovery

Instead of writing branching error logic, map failure categories to recovery routes declaratively. <Checkout> accepts an onFailed map:

<Checkout
	offering="plan"
	onFailed={{
		prepaid_card: { go: 'real-card' }, // route to a page
		insufficient_funds: { modal: DownsellModal }, // show a modal
		default: { modal: TryAgainModal }, // catch-all
	}}
/>

Each entry is a FailureRoute, one of:

• { go: pageKey } — navigate to a page.
• { modal: name | Component } — show a modal. It receives FailureModalProps — { error, product?, go(pageKey), retry() } — because modals mount outside the nav context, those closures are how a recovery modal navigates or retries.
• { fallback: 'sheet' } — ask for a payment method again in the funnel’s sheet, and retry once.
• (error) => void — a callback for full control.

The category keys you can map: card_declined, insufficient_funds, expired_card, prepaid_card, authentication_required, requires_payment_method, processing_error, canceled, already_purchased, unknown, plus the synthetic default. canceled only routes when you map it explicitly, and so does already_purchased — left alone, the visitor already owns it and the flow advances without charging again.

onFailed runs after onError, so you can log in onError and recover in onFailed.

Redirect-return settlement

With opens="redirect" (or opens="popup") the visitor leaves to pay and comes back. When they return, the purchase is verified and resolves into the normal success or failure path automatically — you don’t place or configure anything for it.

Testing with test-mode stores

Test and Live are separate environments in the catalog: an offering binds a Live price and a Test price independently. When you run a funnel in test mode, useOffering resolves the Test binding, and checkout uses the test store — so you can complete a full purchase with test cards without real charges. An offering with no Test binding can’t be QA’d in test mode; the catalog warns you when a Test price is missing. See Offerings & Catalog for binding prices per environment.