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

> **Note:**

- A BuildBase app with the SDK installed ([installation](/quick-start/installation)).
- Stripe connected in a Staging environment with test keys
  ([connect Stripe](/billing-setup/connect-stripe)), so nothing real is charged.
- For the selling half, Stripe Connect on in test mode
  ([zero to first sale](/billing/first-sale-marketplace)).

## Test cards used

| Card                         | What it does                                    |
| ---------------------------- | ----------------------------------------------- |
| `4242 4242 4242 4242`        | Pays                                            |
| `4000 0000 0000 0002`        | Declined                                        |
| `4000 0027 6000 3184`        | Asks for 3-D Secure                             |
| `4000 0000 0000 0259`        | Pays, then opens a dispute                      |
| `pm_card_chargeCustomerFail` | Attaches, then fails the next renewal (dunning) |

Stripe lists every test card in its
[testing docs](https://docs.stripe.com/testing).

## 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](/images/billing/end-to-end/studio-pricing.webp)

![The same pricing page at 360 pixels wide, plans stacked](/images/billing/end-to-end/studio-pricing-360.webp)

Docs: [pricing page](/billing/pricing-page), [in-app payment](/billing/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](/images/billing/end-to-end/studio-paywall.webp)

![The Glaze Lab open on Pro, with a glaze recipe and the kilns in use](/images/billing/end-to-end/studio-glaze-lab.webp)

Docs: [entitlements](/billing/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](/images/billing/end-to-end/studio-trialing.webp)

![Your plan: Studio Basic, active, and Invoices and receipts with a $15.00 paid invoice, its View and PDF links](/images/billing/end-to-end/studio-active-invoices.webp)

Docs: [first subscription](/billing-setup/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](/images/billing/end-to-end/studio-cancel-pending.webp)

Docs: [managing subscriptions](/billing/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](/images/billing/end-to-end/studio-usage.webp)

Docs: [quotas](/credits/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](/images/billing/end-to-end/studio-seats.webp)

Docs: [seats](/billing/seats), [add-ons](/billing/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](/images/billing/end-to-end/studio-credits.webp)

![The credits page at 360 pixels wide](/images/billing/end-to-end/studio-credits-360.webp)

Docs: [credit packages](/credits/credit-packages), [promotion codes](/billing/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](/images/billing/end-to-end/studio-declined.webp)

Docs: [promotion codes](/billing/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](/images/billing/end-to-end/studio-dunning.webp)

Docs: [failed payments](/billing/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](/images/billing/end-to-end/studio-portal.webp)

Docs: [customer billing settings](/billing/customer-billing-settings), [tax](/billing/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](/images/billing/end-to-end/sell-home.webp)

![Your studio selling as Mara Okafor's Workspace: a $36.00 paid sale in Sales](/images/billing/end-to-end/sell-workspace-sales.webp)

Docs: [selling](/billing/selling), [zero to first sale: marketplace](/billing/first-sale-marketplace), [zero to first sale: storefront](/billing/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](/images/billing/end-to-end/buy-stripe-checkout.webp)

![Back in the shop after paying: the order Wheel throwing basics, $45.00, paid, and what the buyer got](/images/billing/end-to-end/buy-paid.webp)

![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](/images/billing/end-to-end/buy-cart.webp)

![A cart with a coupon applied: $5.00 off, $35.00 to pay](/images/billing/end-to-end/buy-coupon.webp)

Docs: [items](/billing/items), [orders](/billing/orders), [bundles](/billing/bundles), [coupons](/billing/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](/images/billing/end-to-end/buy-subscriptions.webp)

![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](/images/billing/end-to-end/sell-deposit.webp)

Docs: [item types](/billing/item-types), [options](/billing/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](/images/billing/end-to-end/sell-debit-terms.webp)

![Account debit terms: You accepted version v-mw8yaox93n8 on Nov 9, 2026](/images/billing/end-to-end/sell-debit-terms-accepted.webp)

![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](/images/billing/end-to-end/sell-dispute-lost.webp)

![The same lost dispute at 360 pixels wide](/images/billing/end-to-end/sell-dispute-lost-360.webp)

![Payouts and balance: total balance $640.26, $20.00 available, and a $25.00 payout to a Stripe test bank, paid](/images/billing/end-to-end/sell-payouts.webp)

Docs: [account debit terms](/billing/selling#account-debit-terms), [revenue and health](/billing/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](/billing/selling#co-seller-screens).
