Kernlift

Sell products and plans

Your products appear on the storefront with a price; buying one issues a licence the buyer activates with a GitHub username.

You define what the store sells in the admin console. A product is what a buyer gets a licence for. A plan is one price for a product in one locale. Checkout always charges the price saved on the plan.

Before you begin

  • An admin account with products.read and products.write. The built-in Commerce Manager role holds them.
  • A connected payment provider to take real payments. See Connect a payment provider.

Start from the seeded catalogue

A freshly migrated database has no products, so the storefront is empty. Seed the catalogue this store ships with (the Kernlift Premium membership and the business templates) and edit it from there:

pnpm db:seed-storefront

The command only inserts what is missing, so running it again changes nothing and does not overwrite copy or prices you edited. The seeded prices are examples. Set your own on each plan as described below. The catalogue is defined in scripts/db/storefront-catalog.ts. Replace it when you sell your own products.

Create a product

Open the form

Go to Commerce → Products (/admin/products) and click New product.

Describe the product

  • Key: a stable identifier in lowercase letters, digits, hyphens or underscores, such as cms. It cannot be changed later.
  • Kind: Foundation is the membership (it comes with the base repository and unlocks member prices); Template is a business template sold on its own. Module and Bundle remain for catalogues that sell that way.
  • Status: Active lists the product on the storefront; Hidden and Retired do not.
  • Delivery repository (owner/name): the private GitHub repository a buyer is invited to when they activate the purchase, for example kernlift/image-studio. A product without one is shown as not open yet and cannot be bought.
  • Requires (comma separated keys) and All-access bundle (entitles every active product): leave empty and unticked for a membership or a template.
  • Name, Tagline and Description for each locale.

Save

Click Save product. The page opens the product so you can add plans.

Add a plan

Each plan is one price in one locale, so a product sold in English and Chinese has one plan row per locale.

A business template has two plans per locale: <key>-lifetime is the list price anyone can pay, and <key>-member is the member price. A plan whose key ends in -member can only be checked out by an account that holds the membership; the server refuses it otherwise.

Start a plan

On the product page, in the Plans card, click + Plan key. To edit an existing plan, click its button, shown as plan key · locale.

Set the price

  • Plan key (for example pro_monthly) and Locale. Neither can change after saving.
  • Price (cents) and Currency, for example 4900 and usd.
  • Interval: Monthly, Yearly, Lifetime or One-time, shown next to the price.
  • Checkout mode: payment for a one-time charge, subscription for a recurring one. Stripe creates subscriptions with a monthly cycle.
  • Included credits: credits granted once when an order for this plan is paid. See Charge usage with credits.
  • Plan status: active can be bought; deferred cannot.

Fill in the card copy

Fill in Name, Description, CTA label and CTA href, and optionally AI limit label. In Features (one per line, prefix - to mark not included), write one feature per line.

Save

Click Save plan. The page shows Plan saved. and checkout uses the new price immediately. Repeat for each locale.

Where products are shown

Only products with Status Active are listed. /pricing shows the membership as one card and the templates with both prices. A visitor who is a member is offered the member plan; everyone else the list plan. A product without an active plan above zero in the visitor's locale shows Not priced yet.

Understand what a purchase grants

When the provider confirms the payment, the buyer receives:

  • An invoice on /app/billing, and a subscription for subscription plans.
  • The plan's Included credits, once per order.
  • A licence for the plan's product on /app/licences (Purchased templates).

The licence is not the code yet. The buyer enters their GitHub username on that page and clicks Activate; the store then invites that account to the product's delivery repository with read access. The username is fixed by the first activation, and an invitation GitHub expired after 7 days can be sent again from the same page.

Activation counts as delivery: an order whose licence has been activated can no longer be refunded, while an order that was never activated can be, and a full refund revokes its licence. Revoking an activated licence on Commerce → Licences removes the account from the repository.

Invitations are sent with a GitHub token you store once under GitHub delivery on Commerce → Products. It needs admin access to every delivery repository. Without it, activation tells the buyer delivery is not configured and records nothing.

To give someone a licence without a purchase, use Grant licence on Commerce → Licences (/admin/licences, needs licences.write). An account cannot buy a product it already holds.

Add a buy button to your own page

The pricing cards post to the checkout API, and you can do the same from any signed-in page. Send the plan's own price, currency and mode. A request with any other value is rejected.

src/components/billing/buy-button.tsx
const response = await fetch("/api/billing/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    planKey: "growth",
    checkoutMode: "subscription",
    amountCents: 9900,
    currency: "usd",
    locale: "en",
  }),
});
const result = await response.json();

if (response.status === 409 && result.message) {
  // result.status is unknown_plan, plan_inactive, amount_mismatch,
  // product_mismatch, membership_required or already_owned
  throw new Error(result.message);
}
if (result.checkoutUrl) window.location.assign(result.checkoutUrl);

On success the API returns 201 with a checkoutUrl on the provider's site. After paying, the buyer returns to your Success URL with billing_order_id, billing_status and provider in the query string. Do not treat those parameters as proof of payment. Read the order status.

Verify

Open /pricing in each locale and check that it shows the plan's price. Buy it with a test card, then confirm the order is paid on Commerce → Orders and the licence appears on the buyer's /app/licences, where it can be activated. pnpm validate:github-delivery checks the member price, activation, the refund rule and revocation; pnpm validate:billing checks that settlement grants plan credits once.

Troubleshooting

A product does not appear on the storefront

The product's Status is not Active. Set it to Active and click Save product.

The card says Not priced yet

The product has no active plan with a price above zero in that locale. Add or edit the plan for that locale.

Checkout returns 409 with amount_mismatch

The request sent an amount, currency or mode that differs from the plan. Send the plan's values unchanged. Editing a plan in the admin console changes the expected amount immediately.

Checkout returns 409 with membership_required

The request named a member-price plan (<key>-member) and the account does not hold the membership. The buyer either becomes a member first or buys the template with its list plan.

Checkout returns 409 with already_owned

The account already holds an active licence for that product. Send the buyer to /app/licences to activate it.

Activation says delivery is not configured

The product has no Delivery repository, or no GitHub token is stored. Set both on Commerce → Products, then use Check the stored token to confirm GitHub accepts it.

Reference

Next steps