Skip to content
BuildBase

Payments end to end

Every payment flow of @buildbase/sdk in one running example app: plans, credits, usage, sales, disputes and payouts, paid with Stripe test cards.

The Kiln Market example app, built on @buildbase/sdk, runs every payment flow BuildBase offers with real Stripe test-mode money. It has two halves:

  • Kiln Studio, where the app sells its own plans to its users (the Billing module): trials, upgrades, seats, add-ons, credits, usage and failed payments.
  • Kiln Market, where the app's users sell to each other (Commerce): items, carts, coupons, subscriptions, disputes and payouts.

Each flow below starts on a page of the app, pays on Stripe's hosted Checkout page with a Stripe test card, and names the SDK hooks and components it uses and the docs page that explains it.

Note

About the example. Every screenshot is from the Kiln Market example app running against a Staging environment with Stripe test keys. An automated harness repeats each flow below and checks it in the app, on BuildBase and in Stripe.

Before you start

  • A BuildBase app with the SDK installed (installation).
  • Stripe connected in a Staging environment with test keys (connect Stripe), so nothing real is charged.
  • For the selling half, Stripe Connect on in test mode (zero to first sale).

Test cards used

CardWhat it does
4242 4242 4242 4242Pays
4000 0000 0000 0002Declined
4000 0027 6000 3184Asks for 3-D Secure
4000 0000 0000 0259Pays, then opens a dispute
pm_card_chargeCustomerFailAttaches, then fails the next renewal (dunning)

Stripe lists every test card in its testing docs.

Billing: the app sells its own plan

The studio has two plans, Basic and Pro, monthly and yearly, in one published pricing group.

Pricing page and checkout

The pricing page renders the published plans with the PricingPage render prop and starts a subscription with useCreateCheckoutSession. The buyer pays on Stripe's hosted page.

Kiln Studio plans: Studio Basic at $15.00 a month with a 7-day free trial and Studio Pro at $40.00, a Monthly and Yearly toggle, a promotion code field and a Subscribe button on each plan

The same pricing page at 360 pixels wide, plans stacked

Docs: pricing page, in-app payment.

Paywall and entitlements

Before a plan, WhenNotEntitled shows an upgrade card in place of the feature. Once the studio is on Pro, WhenEntitled opens the Glaze Lab.

The Glaze Lab before Pro: The Glaze Lab comes with Kiln Studio Pro, and an Upgrade to Pro link

The Glaze Lab open on Pro, with a glaze recipe and the kilns in use

Docs: entitlements.

Trial, then the first charge

A trial with a card shows as trialing with the days left (useSubscription). When the trial ends Stripe charges the card and the subscription turns active; useInvoices lists the paid invoice with its hosted receipt and PDF.

Your plan: Studio Basic, status trialing, Trial: 7 days left, with Change plan, Cancel at period end and Billing portal buttons

Your plan: Studio Basic, active, and Invoices and receipts with a $15.00 paid invoice, its View and PDF links

Docs: first subscription.

Upgrade, interval change, downgrade, cancel

useUpdateSubscription moves Basic to Pro now with a prorated invoice, monthly to yearly, and Pro back to Basic at the renewal. Cancelling keeps the plan until the period ends, and the studio can resume before then.

Your plan ends at the end of this period: Studio Basic yearly, ends then, cancelled, with a Resume button and the invoices from the upgrade and interval change

Docs: managing subscriptions.

Usage, overage and quotas

Each firing is recorded with useRecordUsage. Past the 10 included, the overage goes on the next invoice. A capped quota refuses the next use with QUOTA_EXHAUSTED, and WhenQuotaExhausted says so.

Usage: kiln firings 15 of 10 used, 5 over, billed on the next invoice; gallery photos 5 of 5, the sixth refused with 402 QUOTA_EXHAUSTED

Docs: quotas.

Seats and add-ons

Members past the included seat are billed as seats (useSeatStatus). At the kiln limit WhenLimitReached offers an extra kiln add-on (useWorkspaceAddOns, usePurchaseAddOn), which raises the limit.

Seats: 3 members, 1 included, 2 billed, at most 3

Docs: seats, add-ons.

Credits

The studio buys a credit pack with a promotion code (usePurchaseCredits), spends credits (useConsumeCredits), holds some for a long job and settles what it used (useReserveCredits). Past the balance the platform refuses, and at zero WhenCreditsExhausted shows.

Firing credits at zero: You are out of credits, a promotion code field, a 100 credit pack for $5.00, and Fire a kiln load, Hold for a glaze test, Settle for half and Release

The credits page at 360 pixels wide

Docs: credit packages, promotion codes.

Declined card, 3-D Secure and a promotion code

A declined card stays on Stripe's page and nothing is subscribed. The 3-D Secure card asks for the challenge, and once it is completed the subscription starts; a promotion code takes half off.

Stripe's hosted page for Studio Pro with the KILN50 code taking $20.00 off, and the declined card's message under the card number

Docs: promotion codes.

Failed payment and dunning

When a renewal fails, the subscription goes past due and the studio shows an update-card banner (dunningState). A new card pays the open invoice and the banner goes.

Your last payment failed. Update your card to keep your studio plan, above Studio Pro with status past_due and an open invoice

Docs: failed payments.

Customer portal and tax

useBillingPortal opens Stripe's customer portal for the studio. With Stripe Tax on, checkout asks for a billing address and a tax ID and Stripe works out the tax.

Stripe's customer portal: the current subscription with seats and the extra kiln, payment methods, billing information and invoice history

Docs: customer billing settings, tax.

Bank debits

Paying by bank debit (ACH), where the payment succeeds or fails days later, is pending: the example's run for it is written and runs once bank debits are on in the Stripe test account it uses.

Selling: the app's users sell

Potters sell firings, glazes and kiln slots, and buyers shop, fill a cart and pay.

A seller, a person or a workspace

A seller onboards with Stripe, and SellerHome shows what is left to do. A workspace can sell too: its sales are paid to the workspace's own Stripe account, and SellerSales with a workspaceId subject lists them.

Selling: Mara Clayworks, Active, Can sell and Can get paid, with payouts, account details, documents and co-seller invitations

Your studio selling as Mara Okafor's Workspace: a $36.00 paid sale in Sales

Docs: selling, zero to first sale: marketplace, zero to first sale: storefront.

Buying: checkout, carts and coupons

A buyer pays for an item on Stripe's hosted page and lands on the paid order. A cart holds several items, from one seller or several, and a coupon takes its discount off before payment.

Stripe's hosted page for Wheel throwing basics at $45.00 in a Stripe sandbox

Back in the shop after paying: the order Wheel throwing basics, $45.00, paid, and what the buyer got

A cart of four items with a coupon field, Total $197.00 and Check out, and the files and licence key the buyer got earlier

A cart with a coupon applied: $5.00 off, $35.00 to pay

Docs: items, orders, bundles, coupons.

Subscriptions to a seller, and prices in parts

A buyer can subscribe to a seller's item: with an intro price, a set number of payments, or tiers to move between, and several billed together. An item can also be paid in parts: a deposit now and the balance later.

My account, Subscriptions: an intro price for the first 2 payments, payment 2 of 3, a tier that moves to Member at the renewal, and two items billed together

A seller's sale paid in parts: payment 1 of 2, a $30.00 deposit, paid; payment 2 of 2, $70.00, with Ask for the balance

Docs: item types, options.

Dispute fees, disputes and payouts

Before a seller can sell, they accept the terms for dispute fees with DebitTermsConsent. When a buyer disputes and the seller loses, the sale is reversed and Stripe's dispute fee is taken; when the seller wins, nothing is taken. Payouts reach the seller's bank and are reconciled.

Account debit terms: if you lose a dispute, the app passes Stripe's dispute fee on to you, with an Accept button for the current version

Account debit terms: You accepted version v-mw8yaox93n8 on Nov 9, 2026

The buyer disputed this payment and the bank sided with the buyer: $42.45 taken back from the payout and Stripe's $15.00 dispute fee debited

The same lost dispute at 360 pixels wide

Payouts and balance: total balance $640.26, $20.00 available, and a $25.00 payout to a Stripe test bank, paid

Docs: account debit terms, revenue and health.

Co-sellers

ItemCoSellers and CoSellerInvitations let one seller offer another a share of an item's sales. In the marketplace shape a split sale pays each seller their share by a transfer of their own, and refunds and a lost dispute take back from each in proportion. A split subscription pays each seller per invoice, and a price in parts per part. The storefront shape, and a split subscription or price in parts in a cart, are refused with split_not_supported.

Docs: co-seller screens.