Self-service checkout
How somebody becomes a customer without anybody at Vitna doing anything, and what the box needs configured before they can.
Two doors, and they are deliberately separate. The first opens an org and costs nothing. The second sells the plan that raises what that org may enter. An instance can have the first without the second, which is what a developer machine and CI both are.
The fee shape
| Plan | Stored ID | Workloads | Monthly | Annual |
|---|---|---|---|---|
| Free | free | 1 | $0, no expiry | $0 |
| Builder | builder | 3 | $29 a month | $290 a year |
| Pro | deploy | 5 | $79 a month | $790 a year |
| Team | team | 25 | $299 a month | $2,990 a year |
| Enterprise | agreement | Contracted | Custom | Annual contract |
The first workload is free indefinitely rather than for a trial period, because the first payment's job is commitment rather than revenue. A membership is free and always has been: an org may admit as many accounts as it likes. What is metered per plan is active workloads alongside hosted API and compute quotas (pages, rendered browser pages, Browser CDP sessions, research jobs, Search, and Unblocker, defined in platform/billing/plans.mjs). Note that deploy is kept as the stored plan id for Pro for backward compatibility with existing billing rows.
The fee is charged per plan and never as a share of what anything routes. That is a commitment recorded in VERTICALS.md rather than a price point: a fee that moved with the recommendation would give every brief an incentive problem.
Workloads or volumes above Team (25 active workloads) are not sold self-serve; they are refused with a path to commercial contracting for an agreed volume and SLA.
Opening an org
A signed-in account with no membership sees a form rather than the command it used to be told to go and ask somebody to run. Submitting it writes one org and one membership, and makes that account the owner.
The limit is one org per account, and it is a partial unique index on aperture.org.opened_by_user_id rather than a check in application code, so two browser tabs cannot both pass it. Somebody willing to hold several GitHub accounts can hold several free orgs, and no rule here changes that.
Orgs an operator created carry a null in that column. They are outside the index and outside the allowance entirely: an org that arrived by agreement is on the terms of that agreement. Such an org is made with org:create, which has no flag that could set the column (see access commands):
npm run org:create -- --id acme --name "Acme Ltd"A self-service org that later signs an agreement is moved onto agreement terms with org:agree, which keeps its opener and records the date and a reference beside it. The register meters an org only where it has an opener and no recorded agreement, so the moved org is unmetered from that date:
npm run org:agree -- --org acme --note "Invoice INV-2026-014"/console/billing shows an org on agreement terms of either kind without a plan, an allowance count or a checkout, and says the register does not meter it, with the date and note where they were recorded. /console/checkout refuses a checkout for such an org. A moved org that still holds Deploy keeps its owner's button to the processor's page, because org:agree cancels nothing.
Joining an org that already exists is still a command. No endpoint can add an account to an org that has members. That is npm run org:member:add, run by a person at a prompt, exactly as before.
What grants an entitlement
One thing only: a webhook event whose signature this instance verified against STRIPE_WEBHOOK_SECRET.
The browser coming back from a payment page grants nothing. The success URL is a link anybody can visit, so /console/billing?paid=1 says a payment page was finished and then reads the record to say what the record currently holds. For a few seconds after paying that is usually still the old plan, and the page says so rather than congratulating anybody.
billing.subscription_state is append-only. The current state of an org is its newest row ordered by the processor's own event_created_at, never by arrival: a retried failure and a fresh cancellation can arrive in either order, and ordering by receipt would let a stale status overwrite a current one.
A past_due subscription still carries its allowance. unpaid does not. The line is drawn where the processor stops retrying rather than where a card first fails.
Nothing is ever taken away. An org whose plan lapses keeps every workload it entered; what it loses is the ability to enter another.
What the box needs
Environment variables in /etc/vitna/env.site, two written by the provision script and the Stripe/signup credentials set by hand:
| Variable | What | Written by |
|---|---|---|
DATABASE_SIGNUP_URL | The vitna_signup role | provision-checkout.sh |
DATABASE_BILLING_URL | The vitna_billing role | provision-checkout.sh |
STRIPE_SECRET_KEY | The processor's API key | By hand |
STRIPE_WEBHOOK_SECRET | The endpoint's signing secret | By hand |
STRIPE_PRICE_BUILDER | Stripe price id for builder ($29/mo) | By hand |
STRIPE_PRICE_DEPLOY | Stripe price id for Pro / deploy ($79/mo; fallback alias STRIPE_PRICE_PRO) | By hand |
STRIPE_PRICE_TEAM | Stripe price id for team ($299/mo) | By hand |
STRIPE_PRICE_BUILDER_ANNUAL | Optional annual Stripe price id for builder ($290/yr) | By hand |
STRIPE_PRICE_DEPLOY_ANNUAL | Optional annual Stripe price id for Pro / deploy ($790/yr; fallback STRIPE_PRICE_PRO_ANNUAL) | By hand |
STRIPE_PRICE_TEAM_ANNUAL | Optional annual Stripe price id for team ($2,990/yr) | By hand |
VITNA_WEB_SIGNUP_ENABLED | Set "true" once live signup is armed | By hand |
VITNA_WEB_SIGNUP_SECRET | Optional shared secret / bot check key for web signup | By hand |
Note that platform/billing/stripe-api.mjs checks that all three paid tier prices (builder, deploy, team) are configured distinctly before checkout starts, and refusePriceDisagreement validates both monthly ($29, $79, $299) and annual ($290, $790, $2,990) Stripe session totals against platform/billing/plans.mjs before redirecting. After deploying /etc/vitna/env.site, run a pre-flight check against GET /api/stripe (confirming configured: true and all paid tier price mappings) and POST /api/v1/keys/verify on a provisioned test key before setting VITNA_WEB_SIGNUP_ENABLED=true.
Run the provisioning before the migration deploys:
bash /home/ubuntu/vitna-web/deploy/provision-checkout.shIt creates the two roles with generated passwords and appends their connection strings. Re-running is safe and is the expected shape: the first run creates the roles and stops, and the run after the deploy proves the grants.
A migration that reaches a box where the roles do not exist fails, and that failure is safe rather than silent. The post-receive hook aborts before the restart and the previous build keeps serving.
The webhook endpoint
POST /api/stripe, configured at the processor as a webhook destination.
Four event types are acted on:
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deletedThe first binds an org to an account at the processor and grants nothing; the three subscription events carry the entitlement. Any other event type is recorded as received and ignored, which is a 200: the processor sends what the account is configured to send, and refusing an event type nobody uses would put a permanent red mark on the dashboard for no reason.
The processor account is shared, and that shapes the endpoint
Vitna and Convexity bill under one processor account on purpose. A webhook destination is a property of the account rather than of a product, so every destination receives every event it subscribed to, for every customer on the account. Convexity's subscription events arrive at vitna.ai/api/stripe, and Vitna's arrive at Convexity's destination.
A subscription is this product's when it carries `vitna_org` in its metadata, and it is nobody else's business when it does not. The key is namespaced rather than a bare org for exactly that reason: org is the obvious name, which is why the other product might use it, and two products silently claiming each other's subscriptions is the worst outcome available here. Every checkout this site opens writes vitna_org onto both the session and the subscription, so every renewal, failure and cancellation carries it for as long as the subscription lives.
A foreign event is ignored, never refused, and the status code is the whole point. A refusal is a 400, which tells the processor to retry, and a retry of somebody else's subscription can never succeed. It would redeliver on backoff indefinitely, fill the journal with a word that means "look at me", and a destination that fails for long enough is disabled at the processor, which would take the real events down with the foreign ones. So a foreign event is answered 200, recorded once with outcome ignored, and logged as stripe: foreign.
A run of stripe: foreign is the other product being used. It is not a problem and needs nothing done about it.
Signature failures are never told what was wrong. The response says the request was not signed by this instance's processor. The specific sentence, and whether it was the timestamp or the digest, is in the journal.
The edge blocks some clients before the app sees them
The site is behind Cloudflare, which refuses a request from a user agent it reads as a bot with a 403 and an HTML body carrying error code: 1010. That answer never reaches this application, so nothing about it appears in the journal.
Checked on 2026-08-31, posting the same body three ways:
| User agent | Answer |
|---|---|
Stripe/1.0 (+https://stripe.com/docs/webhooks) | 400, reached the app |
| absent | 400, reached the app |
Python-urllib/3.12 | 403, blocked at the edge |
The processor's own agent gets through, which is the case that matters. The one to know about is the third: a hand-rolled probe in Python looks like a blocked bot, answers 403, and reads exactly like a broken endpoint. Send probes with curl, or post to http://127.0.0.1:3200/api/stripe on the box to bypass the edge entirely.
The two secrets are checked in opposite directions
STRIPE_SECRET_KEY opens a payment page. STRIPE_WEBHOOK_SECRET verifies what comes back. An instance holding the first and not the second can send somebody to pay and can never learn that they did, so check both are set before turning the endpoint on at the processor.
An instance holding neither refuses both routes with a 503 and renders neither button, which is the intended state of anything that is not production.
A published price that the processor would not charge
The figure on the page lives in platform/billing/plans.mjs and the price id lives in an environment file, which makes them two claims about one number kept in two places.
The checkout route asks the processor what it would charge, compares it with the published figure, and refuses to redirect anybody when the two disagree. It logs checkout: price disagreement at error level. That line means every visitor to the plan page is reading a figure this site will not honour, so it is worth waking somebody for.
Reading it back
journalctl -u vitna-web -g 'signup:'
journalctl -u vitna-web -g 'checkout:'
journalctl -u vitna-web -g 'stripe:'An abandoned checkout is a row in billing.checkout with no subscription state after it, which is a question somebody can answer rather than an event that left no trace.
stripe: foreign is the other product on the shared account and needs nothing. stripe: refused is the one word here that means something is wrong and somebody should look.
