Payments

Sell subscriptions and one-off products. Stripe is built in: connect it with one restricted key and Gemmein makes your Payment Links, hosts the webhook, manages subscriptions and writes receipts, so you build none of it.

Payments are processed by Stripe on your own account; Gemmein receives only the webhook events. Any provider that signs its webhooks, GoCardless, Paddle or Lemon Squeezy among them, drives access the same way through a relay.

Connect Stripe

Connect Stripe once per environment with a restricted key. Gemmein then makes your products, prices and Payment Links in your Stripe account and registers the webhook that tells it who paid.

1. Open Stripe's API keys page: Developers (bottom left) → API keys, or directly: test mode for Development, live mode for Live.
2. Choose Create restricted key. When Stripe asks how you will use the key, choose Powering an integration you built, then Choose your own below the templates. Don't pick a template: each one turns on 15 to 42 permissions, and Gemmein refuses the key. The third-party option does the same, ticking many permissions for you.
3. Turn on only these five. The filter box at the top of the key editor finds a row by name.

   Section	Row	Set to
   Core	Products	Write
   Billing	Prices	Write
   Payment Links	Payment Links	Write
   Webhook Endpoints	Webhook Endpoints	Write
   Connect	Accounts	Read

   Accounts is under Connect, not Accounts v2. It is Read only, so Gemmein knows which Stripe account the key belongs to. Then choose Create.
4. Already made a key with more? Edit it in Stripe and choose None on every section heading: each heading sets every row under it. Then turn on only the five.
5. Paste the key on that environment's Payments page. It starts rk_test_ in Development and rk_live_ in Live. Don't share your keys anywhere else: paste the restricted key only there.
6. Give each paid plan a price (an amount, a currency, and how often it bills: day, week, month or year), and each product or credit pack a one-time price: your AI writes them in gemmein/payments.json and npx gemmein sync sets them in Development, or you set them on the Payments page. Gemmein makes the Payment Link.

Changing a price, or renaming something Gemmein made in Stripe, needs the key connected. Disconnecting forgets the key: the webhook, its signing secret and every Payment Link keep working, and only making or changing things in Stripe stops. If two people save at once, the later save is refused with a reload message rather than overwriting the first.

Turning payments off stops new sales: nothing new can be bought and Gemmein turns off the Payment Links it made. Existing customers carry on as before. A renewal keeps its access, and a cancellation, a full refund of a purchase, or a renewal Stripe stops retrying takes it away. The webhook stays; a new sale that still arrives is kept on the Problems page for you to refund or grant, and is never granted on its own. Removing the webhook is a separate action, Disconnect and delete, which waits until no Gemmein link is on, no subscription can still charge, and 72 hours have passed since the last link went off. A key from a different Stripe account is refused. In Development, Start over lets you connect another Stripe account once nothing can still pay.

A payment names what was bought by the Payment Link it was made on. A payment on a link Gemmein did not make with this environment's key is kept on the Problems page for you to refund or grant, and is never granted on its own.

Protect your accounts

• Use a different email address for Stripe and for Gemmein. If one inbox is compromised, the other account stays safe.
• Make them addresses only you use, not your public name or contact address: for example, a new address kept only for this. Attackers target the addresses they can find on your site, on LinkedIn or in git commits.
• Turn on two-step sign-in for both inboxes and for Stripe. You sign in to Gemmein with a code sent to your email, so your inbox's security is your Gemmein account's security.
• Never share your keys or sign-in codes, including in screenshots. Gemmein asks for a key only in the Connect Stripe field on the Payments page.

Going live

Going live copies your plans and products into Live with their names, prices, credit allowances and packs, and what they unlock. Development's Stripe products, Payment Links and signing secret stay in Development. Connect Stripe in Live with a live-mode key and Gemmein creates them in Stripe live mode. Until then customers can't pay in Live, and Live's checkout answers payments_not_configured; you can still go live first.

Once live, Promote on the Go live page copies what Development has into Live:

• Plans, products and credit packs Live doesn't have are copied whole.
• Plan and pack definitions (credits, rollover, the welcome allowance, a pack's credits) are brought to Development's values.
• A different price is shown and never applied. Change Live's price on Live's Payments page.
• An AI tool or collection unlocked by a plan Live doesn't have is re-linked to Live's plan of the same name. If no name matches, the promote stops before anything moves and says which one.
• An AI provider key is copied only when you tick Use the same key as Development.

Each priced plan and product has a Tax category, such as Online service, Software subscription, Ebook or Audio. Gemmein sets the matching tax code on the product it makes in Stripe, which Stripe Tax and Managed Payments read. A product starts on Online service and a plan on Software subscription.

Set by your AI

In Development your AI sets how each plan and product is sold, in one file the project keeps: gemmein/payments.json. Per product: its price, the file inside the project (or the link) a buyer gets, the credits it adds and its tax category. Per plan: its price and how often it bills, the credits each period grants and what rolls over, and its tax category.

{ "plans": [
    { "name": "Free", "default": true },
    { "name": "Pro", "paid": true,
      "price": { "amountMinor": 900, "currency": "gbp", "interval": "month" },
      "credits": { "perPeriod": 500, "rollover": "none" } } ],
  "products": [
    { "name": "Field Guide", "price": { "amountMinor": 1500, "currency": "gbp" },
      "deliveryFile": "assets/field-guide.pdf", "taxCategory": "ebook" } ] }

• npx gemmein sync shows what it will change, uploads the file, and sets it in Development. With Stripe connected there, each priced item sells at once through Stripe test mode; without, it waits as not sold yet and is made the moment the key connects.
• Those rows read set by your AI on the Payments page. You can edit any of them; the next sync shows your edit and leaves it as it is, unless you run npx gemmein sync --overwrite.
• An item missing from the file stays. "remove": true on it takes it down: its Payment Link goes off, and a file stays for whoever bought it.
• A product's file is a pdf, zip, epub, audio file or image up to 100 MB, or a video (mp4, webm, mov) up to 500 MB (50 MB in Development). The buyer's g.files.link(file) plays an audio or video product in the page; other files download.
• npx gemmein payments --cloud reads back what Development sells: each price, how it is sold, its Payment Link, its file and tax category, and whether Stripe is connected.
• Live is never set by sync. Going live and promote copy Development's plans and products into Live, where Live's own key makes them.

Subscriptions

With Stripe connected and your plans priced, your app has two jobs:

// 1. Send the person to checkout. One call; Gemmein does the rest
await g.subscriptions.checkout("pro")   // redirects to Stripe; omit the arg for the paid plan

// 2. Unlock paid features by reading the managed subscription:
const sub = await g.subscriptions.mine()   // { plan, status } or null
if (sub?.plan === "pro") { /* unlock */ }

Each person has one subscription (matched case-insensitively on email). The payment itself creates it, cancellation downgrades it to your default plan, and out-of-order Stripe events resolve to the newest.

On the Payments page, choose how each plan is sold:

• Stripe. A price, with Stripe connected; Gemmein makes the Payment Link. checkout navigates to the Payment Link. Stripe's webhooks write the subscription, and its cancellations and lapses end it. A checkout paid by bank debit opens the plan once the payment clears.
• Relay. Any provider whose webhook you map (GoCardless, Lemon Squeezy, Paddle, bank transfer) grants the plan with the grant_plan relay action and ends it with revoke_plan. A relay-sold plan is active until revoke_plan; the provider's cancellation webhook is the revoke.
• Not yet.

Subscription state is written by Stripe's webhooks or by the relay you configured, never by your app. g.subscriptions.mine() answers the same { plan, status } whichever way the plan is sold.

Plan limits (note counts, seats, feature caps) are your app's logic. Gemmein tells you who is on which plan, and plan names carry no quotas. Errors worth handling on checkout: authentication_required (sign in first: a plan is tied to an account, so a plan is never bought signed out), plan_has_no_link (Stripe isn't connected here or the plan has no price yet), and 409 plan_not_sellable (the plan is sold via a relay, or not yet).

One-off purchases

Plans are for subscriptions. To sell a single thing (a beat, an ebook, a course, a licence), add products on the same page and choose how each is sold:

• Stripe. A price, with Stripe connected; Gemmein makes the Payment Link. g.payments.buy navigates to Stripe only for a product sold this way.
• Relay. Any provider whose webhook you map (GoCardless, Lemon Squeezy, Paddle, bank transfer) fulfils the product with the fulfil_product relay action. The relay binds by name: renaming or deleting it stops fulfilment until a relay with that name exists again, and the product card shows this.
• Not yet. The product is defined and its grants and credits are known, but no way of selling it is connected.

g.payments.buy on a product sold via a relay or not yet answers 409 product_not_sellable.

Buying signed out

A visitor who is not signed in can buy a product. g.payments.buy works either way, so a product's buy button needs no sign-in in front of it. Signed out, Stripe Checkout asks for the buyer's email, and the purchase is theirs the first time they sign in with that email. A product bought with an item note needs a signed-in buyer (401 authentication_required). Plans always need sign-in, because a plan is tied to an account.

The purchase email

After each paid product purchase, Stripe or relay-sold, Gemmein emails the buyer once for that payment: Your <product> is ready, from your domain's account address, with a link to your Library on your app's verified web domain. It is on by default. On this page, under Products, Email buyers when they buy turns it off and Library path sets where the link opens (/ until you set one). It is sent only from your own verified domain; until one is verified it is not sent, and Logs shows one row a day saying so. See Email.

For one product that covers many items, name the item. The item is display text on the receipt; the price is always the Payment Link's or the relay's. g.purchases.mine() returns the person's payment history from Gemmein's own record:

await g.payments.buy("premium license", { item: "beat_37" })   // redirects

const purchases = await g.purchases.mine()   // the array itself
// [{ item, amountMinor, currency, refundedMinor, status, grants, paidAt }]

To fulfil, tick the product in the collection's Unlocked by row on the Collections page. The server then refuses people who haven't bought it, with no code from you. Never grant access when the redirect comes back: redirects can be faked, and access comes from Stripe's signed webhook.

The 14-day waiver at checkout

Buyers in the UK and EU have 14 days to cancel an online purchase. For digital content, that right ends when delivery starts, but only if the buyer agreed to it before paying. One switch per environment, off by default, adds that agreement to the Stripe checkout of every one-off product: a file, a link, or access alone. Set it in gemmein/payments.json, with the link to your Terms of Service:

{ "consent": { "digitalWaiver": true, "termsUrl": "https://example.com/terms" }, "products": [ … ] }

The buyer must tick this box before paying. "the seller's terms" links to your termsUrl:

"I agree to the seller's terms, and I ask for this digital content to be delivered straight away. I understand that once delivery starts, I lose my right to cancel within 14 days."

Your AI recommends it when your Stripe account is in the UK or EU, or a price is in GBP or EUR. npx gemmein payments --cloud shows whether it is on, and when it is recommended.

Show what you sell

The products and plans on the Payments page are your app's catalog. A storefront lists them with g.payments.products() and a pricing page with g.subscriptions.plans(), in the order the page shows them. No sign-in is needed; the app key is enough. Each item's name is what buy and checkout take, and your app supplies its own words and images for each one in code, keyed by that name:

const products = await g.payments.products()
// [{ name, price: { amountMinor, currency }, delivers, credits, unlocks }]
const plans = await g.subscriptions.plans()
// [{ name, free, price: { amountMinor, currency, period }, credits, unlocks }]

Access

This is the paywall. A plan or a product unlocks a collection when you choose it by name in that collection's Unlocked by row on the Collections page. Paying for the plan opens it; cancelling, lapsing or a full refund takes it back. The server refuses everyone else, and your app writes no check at all.

// On the Payments page: a plan named "pro" with a price
// On the Collections page: "reports" → Unlocked by → tick "pro (plan)"

// Your app reads, catches entitlement_required and shows the upgrade prompt:
try {
  const { records } = await g.collection("reports").list()
} catch (err) {
  if (err.code === "entitlement_required") showUpgrade(err.requires)  // "access:pro", the plan's access key (see below)
}

Call plans and products whatever your business calls them (pro, Film X, Course: Foundations). Gemmein attaches no meaning to the names, so a new tier needs no Gemmein release. A collection can be unlocked by several plans or products at once ("anyone on pro or studio, or who bought Midnight Pack"), and any one of them opens it. A person can hold access for several reasons at once, such as a plan, a lifetime purchase and a manual grant from the dashboard, and it ends only when the last one does.

Access keys. Each plan and product carries one access key, generated from the name when it is first saved: plan "pro" → access:pro, product "Midnight Pack" → access:midnight-pack. A rename keeps the key, so nobody loses access. It is what err.requires carries (one key, a string; if several plans open the collection, it names the first one) and what g.purchases.mine() lists under grants. The dashboard shows it only as a muted hint beside the name, and nobody types it.

What your app can see. It reads a person's purchases and what each one granted (g.purchases.mine()) and their subscription (g.subscriptions.mine()). By-hand grants are not listed to the app, and a locked read succeeds. So never rebuild the paywall client-side from the lists you can see; let the server refuse, and show the upgrade prompt on entitlement_required. To give someone access, grant it on their page in the dashboard; it is never code.

Grants

Every bit of access a person holds is a grant: one access key, one reason, a start and maybe an end. Grants have seven sources in three families. The family decides who can create a grant, what ends it, and whether it counts as revenue on your dashboard.

• A grant is never edited. An extension is a new grant, so the reason on every grant stays true.
• You can end a purchase-tied grant by hand from the person's page. That stops the access and refunds nothing; money moves only in Stripe.
• A refund never changes a by-hand or relay grant, and revoking a by-hand grant never triggers a refund.
• A relay grant reads "granted by relay <name>" on the person's page.

Which grant to use:

• "Give them a free month": a trial grant with an end date.
• "Launch deal, first 50 get pro": a promotion grant.
• "Support fix, they were double-charged": a by hand grant with the reason written down.
• "They paid on my old platform": a migration grant, so the record says why.
• "They paid through GoCardless": a relay grant, written when the provider's signed webhook lands.
• "They paid": never by hand, because Stripe writes it, so revenue reflects only money that arrived.

Refunds

Gemmein takes access back only on the events that plainly mean it: a subscription cancelled or lapsed, or a one-off purchase refunded in full. A full refund revokes only the grants that payment created, so a person who also subscribes keeps their subscription's access.

Every other refund is yours to act on:

• A partial refund leaves access in place, because a small goodwill refund on a large purchase shouldn't take away what someone bought.
• A refund on a subscription invoice touches no access at all. A webhook cannot tell a goodwill refund from a "take it all back" refund.
• When someone cancels at period end and asks for their money back, they keep access until the period ends unless you act. You have two moves, both one click and both audited: cancel the subscription immediately in Stripe, which ends the access the moment the event lands, or revoke it by hand on the person's page.
• Every refund the webhook did not act on is written to your activity view.

Receipts

A receipts collection is optional. Add one only if you want purchases inside your data model, so your app can list and edit them like any other record. Gemmein's own record above stays the authoritative payment record, and your collections cannot alter it.

Receipts carry { product, item?, status, amountTotal, currency, paidAt, deliveryUrl?, deliveryFile?, paymentRef } in .data, where amountTotal is minor units exactly as Stripe reported. You fulfil orders by editing the receipt from the dashboard (status: "shipped"); your app reads it. Refunds happen in your Stripe dashboard, and charge.refunded flips the receipt's status to "refunded".

A receipt is app-owned: its top-level ownerUserId is null (the webhook wrote it), and the audienceUserId is what scopes it to the buyer.

A deleted account

A person who deletes their account and later buys again is a new customer. A payment made before the deletion grants nothing, whether it arrives from Stripe or from a relay; refund it in your payment provider. Relays tell before from after by the payment time you map as paid_at (see Relays). The rows Logs and Problems keep for these refusals never contain the person's address.

Checkout redirects

g.subscriptions.checkout() and g.payments.buy() navigate the browser to Stripe themselves and resolve with { url, ... }. await them on the click, and don't also redirect to the returned url, which navigates twice.

Free trials and changing plan

A paid plan can start with a free trial: set trial on the plan in gemmein/payments.json, or the Free trial row in the plan editor. days is 1 to 730. card is required (the default) or optional. credits is what the trial grants; without it, the plan's per-period credits are prorated to the trial's days. onPaymentFailure is keep (the default) or end. Gemmein makes a second Payment Link for the trial and sends each customer to it once. g.subscriptions.mine() answers status: "trialing" with trialEndsAt until the trial ends.

Subscribers change plan, cancel and update their card in your Stripe customer portal. Set it up once per environment:

1. In Stripe, open Settings → Billing → Customer portal and turn it on.
2. Under Subscriptions, let customers switch plans and add each plan's product. Set a trialing subscription's update to end the trial.
3. Copy the portal's login link and paste it on Payments → Customer portal link.

Your app sends a subscriber there with await g.subscriptions.manage(). Gemmein follows every change through Stripe's webhook.

What happens if…

The cases you are most likely to meet, by part of this page. Credits have their own table on Credits.

After paying, and comped plans

Connecting Stripe

Subscriptions

Free trials

Changing plan

One-off purchases

Signed-out buyers, the purchase email and deleted accounts have their own sections: Buying signed out, The purchase email and A deleted account.

Access

Limits

Gemmein does not do the following, and none of it is planned. If your business depends on one of them, use a different backend. Credit packs are products; see Credits.

• No usage quotas or record-count limits. "Ten projects on the free plan" is your app's logic. Gemmein tells you who holds what; it does not count your records.
• No seats or per-organization billing. There are no organizations, memberships, invitations or ownership transfers. One person, one identity.
• No physical goods. No shipping, addresses, delivery rates, inventory, stock reservation, variants, fulfilment, tracking or returns. Gemmein is for software and digital access.
• No multi-item carts. One product per checkout, by design. A "cart" is N checkouts, or one bundled product you price as a bundle. Don't build a cart UI that promises otherwise.
• No marketplace shapes: multiple sellers, payouts, commissions or inter-party disputes.
• No usage-based invoicing, and no tax calculation, invoicing or accounting export. Stripe handles these.
• No DRM. Gemmein controls whether a person may fetch a file. Nothing stops a legitimately downloaded file being reshared afterwards, and no backend can change that. For an external asset (a delivery link you host elsewhere), the host is responsible for everything after the link is issued.
• Chargebacks aren't handled. A dispute does not revoke access, because Gemmein doesn't receive dispute events. Handle those in Stripe and revoke by hand if you need to.