vitna.ai/docs/operations/checkout Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/operations/checkout
> Raw Markdown: https://vitna.ai/docs/operations/checkout.md
> Corpus index: https://vitna.ai/llms.txt

# 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](../cli/access.md)):

```bash
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:

```bash
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
bash /home/ubuntu/vitna-web/deploy/provision-checkout.sh
```

It 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.deleted
```

The 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

```bash
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.
Human Machine Shift+M