Add Real Subscriptions to an AI Prototype
A prototype that only demos checkout needs sign-in, a webhook that updates your database once, and a failed-payment state a person can see.
By Muhammad Saif and Aashan Khan · Techtribe co-founders
The prototype has a pricing page and a button. The button creates a Stripe session, or it pretends to. The browser lands on a thank-you page. In the database, the account is still on a free flag you set by hand, or there is no account, only the browser. The founder can demo the click. A customer cannot be expired, refunded, or distinguished from a second customer. You do not have subscriptions. You have a tour of a checkout.
This note is how that tour becomes a ledger: someone signs in, a payment event updates your database once, and a failed payment later is a state you can see and act on. If you already have the endpoint and it is simply not being called, you want the debugging article, Stripe webhook not triggering. Do not read that one as a substitute for a data model. An endpoint that fires into a table with no unique payment id will create duplicate customers the moment Stripe retries, which is what Stripe does.
The success page is not the payment
Stripe, or whichever processor you chose, is the system that knows a card was charged. Your app is the system that knows what that charge unlocked. Those stay separate on purpose. The browser is the least reliable messenger you have. A tab can close. A user can refresh the thank-you page. A malicious user can open the thank-you page without paying, if the page is only a route. Entitlement that depends on the route is entitlement anyone can grant themselves.
The event from the processor to your server is the payment. Your server verifies the signature. It writes a row keyed by the event or the subscription id. It writes the same row again if the event is delivered again, and the result is still one subscription, not two. Then it unlocks the feature for that account. The thank-you page may poll that row. It may not be the reason the row exists.
If you do not have a server, you do not have this feature yet. A client-side call with a secret is not a server. The secret is now in the bundle. Rotate it before you do anything else. The Bolt, v0, and Replit articles are full of this class of prototype: Bolt, v0, Replit. Billing is often the moment those apps have to leave the preview, because a webhook needs a stable URL and a database you can query when a customer writes to you angry.
Sign-in before the price
A subscription belongs to an account. An account is a login you can reset, not an email typed into Stripe and forgotten. Build the sign-in first, or admit the first paid version is a single known customer you invoice by hand. Hand invoicing is a legitimate two-week decision. Pretend self-serve is how you get a checkout with no user.
The account stores the processor's customer id. You do not ask the user to remember it. You do not create a new processor customer every time they click upgrade. One account, one processor customer, many events. If the prototype created a new customer per click, the cleanup is part of the scope: decide which id is real, and stop minting them.
A second user is the test. They sign up. They pay. They see the paid feature. They do not see the first user's rows. Payment does not fix a missing tenant boundary. It funds one. If account B can read account A's data, do not turn on billing to "see if the business works." You will have paying users inside a leak. The verdict on whether that leak is a repair or a rewrite is when to repair a vibe-coded app.
The three states that have to be real
Active. The latest event says the subscription is paid, and your row agrees. The feature flag for that account is on. You can answer a support email from the row without opening the processor first. You will still open the processor when they disagree. Agreement is the goal, not a vibe.
Past due or failed. The card fails on a renewal. The product does not keep the paid feature forever, and it does not lock the user out with no sentence. A state, a date, and a sentence: update the card, here is the link, here is when access will stop. The first version can use the processor's hosted link rather than a card form you build. Building a card form is how you take on a compliance surface you do not need. Hosted checkout and a hosted update link are the default. A custom card UI is a different project. Decline it until the ledger is boring.
Canceled. The user, or you, ends it. Access stops at the time you decided, end of period or immediate, and the row says which. A user who canceled and still has the feature is a bug. A user who still pays and lost the feature is a louder bug. Both are tests. Write them down before launch. Run them with test clocks or test cards, not with a teammate's real card and a refund you do by hand while apologizing.
There is no fourth state called "the demo button was green." Delete that path or gate it behind an internal flag. A green button in production is a comped account you forgot.
What is inside the production package, and what is a sequel
A real first subscription is a fixed build: auth, your cloud, your repo, and the connections the ledger needs. For this problem those are often the processor and the email tool and nothing else. Leave the rest unconnected if you do not have it. The build includes the failed-payment state, the unique event write, and a plain way to see who is active. It does not include every future change to what you charge. The surrounding product, accounts and a paid boundary, is an LLM-powered SaaS MVP. Book the call and we will say whether you are this shape or a smaller repair.
A short build is one flow. Use it when the "subscription" is a single test customer and a checkout you want honest, and the rest of the product is one AI feature. Do not use it to imply a portal, tax, and three plans. If your prototype already sketched five billing ideas, the sketch is not a commitment. Bring the one plan you can explain. We will refuse the other four until the ledger is real.
Tax, several plans with different entitlements, a full customer portal, prorations you have not defined, and dunning copy your lawyer has not read are a sequel. We can name them on the call. We will not bury them in "billing hooks" and discover them in week five. Coupons are the usual ambush. One coupon for a design partner is a row you can set by hand. A campaign tool is not.
Usage-based billing is a different product from a seat price. Metering, idempotent usage reports, and an invoice the customer can predict. If that is what you sell, say so on the call. A flat monthly price should not be estimated with a usage platform because it sounded more like a startup.
Webhooks, retries, and the row
Verify the signature with the raw body. Parse only after the verify. Store the event id. If you have seen it, return success and do nothing. Stripe retries because your server was slow, not because it wants a second subscription. A handler that creates a user on every retry will create a family of users before lunch.
Return quickly. Work that sends email and unlocks features can happen after you have recorded the event. A timeout looks like a failure to the processor, which retries, which meets your unique key and stops. That is the design. A handler that calls a model before it returns will time out, and you will debug a ghost. The model is not part of the payment path. If payment unlocks a model feature, the unlock is a flag the feature reads. The feature does not live inside the webhook.
Point the webhook at the production URL and, separately, at staging. Staging that shares the production endpoint is how a test card changes a real customer. Use a signing secret per endpoint. Write the secrets into the host, not into the repo. If a secret was ever in the client or the git history, roll it.
The debugging article covers the case where none of this runs because the endpoint is wrong, the secret does not match, or the event type was not selected. Use it for that narrow pain. Use this article to notice you never had a row to update. Both can be true. Fix the delivery, then fix the meaning of the delivery. A delivered event that updates nothing is a log line, not a subscription.
Failed payments are a screen, not an email you meant to write
Decide the grace period in days, as a number, before the build. "A little while" becomes a fight during the first failure. On the day the number hits, the flag flips and the sentence shows. The email, if you send one, is one template, sent by a system you can search. "We thought the processor would email them" is not a template. Check what the processor sends. Add the one message it does not send, if you need it. Do not add a drip sequence. A drip is a marketing integration. It can wait until a real customer has failed once and you know what they needed to hear.
A founder should be able to comp an account without editing the database by hand, even if the admin screen is plain. Plain admin is in the production package. A comp that is a SQL update at midnight will be wrong, and it will disagree with the next webhook. The webhook should not clobber a comp you intended. Write that rule down. It is one of the few business rules in this feature, and it is the one that will page you.
Refunds are a similar rule. A refund in the processor dashboard that does not reach your row is the silent-money bug again. Handle the refund event, or check the processor when support asks, and then handle the event so you stop checking by hand. Partial refunds can be out of scope. Full refunds that must remove access cannot.
What the AI in the prototype must not do
The model does not decide the price. The price is a price id in the processor, mapped to a plan you named. A prompt that "figures out what to charge" will figure out something you cannot explain on an invoice. The add AI note says the same about business rules. Billing is the rule to keep out of the prompt first.
The model does not grant the entitlement because the user sounded paid. Entitlement is the row. The feature reads the row. If the feature is a document chat or an agent, it still reads the row before it spends tokens. A failed payment that keeps calling the model is a donation. Token cost is how that donation grows. Check the flag before the call.
The model does not answer "am I subscribed" from memory. That question is a database read. If you want a support draft that looks up the subscription, that is the one lookup in an AI support agent allowed to do three things. It is not a reason to let the billing webhook ask a model what the event meant.
A cutover from demo checkout
Freeze the demo path. Pick the price id. Have one internal user pay with a test card and one real card you intend to refund. Confirm one row, one customer id, access on, refund or cancel, access off. Then let a stranger pay. Do not open the pricing page to the public while the webhook still points at a laptop.
If strangers have already paid into the demo, reconcile before you invite more. A list from the processor, a list from your table, the difference written down. Comps and duplicates resolved. Then the new handler owns the future events. Leaving the old thank-you page live will keep minting the wrong kind of customer.
What to bring
The pricing page. The processor account, or a willingness to create one in your name rather than ours. The event types you think you care about, which for a first subscription are the ones that mark paid, failed, and canceled. The grace period as a number. Whether you have one plan or several. If you have several and cannot say what each unlocks, you have one plan and a menu you have not designed. Bring the one.
If a webhook exists, bring a failed delivery id and read the other article first so the call is not spent on a typo in the URL. If no webhook exists, say that. It changes the work from a repair to a ledger.
If this is your app, send the repo.
A 30-minute scope call. We read what is live, name what is dangerous, and quote a fixed scope.
How Techtribe adds a real subscription
We put sign-in and a processor customer together, verify the webhook, and write one row per subscription that retries cannot duplicate. Active, failed, and canceled are states the product reads. The thank-you page does not grant access. The model does not set what the customer pays. Tax, a portal, and a pile of plans stay out until you ask for them as their own scope.
A single existing endpoint can be a repair. A first real paid path, with auth and the failed-payment state, is a fixed build. Ongoing plan changes are a team that stays. We say which on the call. If the endpoint merely never fires, start with Stripe webhook not triggering. The service page is SaaS development.
The scope call is 30 minutes with a founder. Bring the pricing page and say whether anyone real has already paid. That is enough to tell a tour of checkout from a ledger.
Questions
What is missing when a prototype only demos checkout?
A real sign-in, a webhook your server verifies, a row in your database that matches the payment, and a state for a card that fails later. A success page the browser shows after a redirect is not any of those.
We already have a webhook and it never fires. Is this the same problem?
No. If an endpoint exists and Stripe is not calling it, start with the webhook debugging note. This article is for a prototype where paid is a screen, and the ledger was never built.
Can the first build include a full billing portal?
No. Sign-in plus a reliable first payment is already the flow. Tax, several plans, a customer portal, and dunning emails are a later conversation. Bring the pricing page to the call and we will say what the first ledger actually is.
How do we know this is a repair or a new ledger?
Book the scope call. If an endpoint exists and only the delivery is broken, it is a repair. If paid is still a thank-you page, it is a ledger: auth, a webhook that updates your database, and a failed-payment state. Several plans and a portal are not that ledger.