Introduction
When you decide to build out a proper set of frequently asked questions, the first option that comes to mind is usually a dedicated FAQ SaaS — a cloud service you pay for monthly. It ships with an admin screen and can be live in a few days, so there are good reasons to pick one.
The trouble starts when you embed it into an EC site. Fonts and buttons don't quite match the rest of the site, the search box behaves differently from on-site search, and every sister site you launch adds another subscription.
This article covers why we built the FAQ into the site itself rather than leaning on an external SaaS for an apparel and gear EC site, and what the resulting design looks like. It organizes 100-plus questions into about ten categories and handles search, admin editing, and multi-site rollout on our own. Rather than walking through implementation details, it focuses on the decisions that led to this shape.
Three Reasons We Built It Into the Site
The Look and the Search Behave Like the Rest of the Site
A SaaS FAQ always reads as "the one part running on a different service." Font weights differ, button corners are rounded differently, and the search box works nothing like on-site search. Each mismatch is small on its own, but stack them up and users start to feel the site is hard to search.
Build it into the site and the FAQ screens are assembled from the same components as the product pages. Search sits on the same mechanism too, so users look things up the same way they browse products. That consistency was the single biggest reason we went in-house.
Adding Sites Barely Adds Cost
Most FAQ SaaS products charge by inquiry volume or page views. We were running several sister EC sites and wanted the same FAQ foundation on all of them. If every site means another subscription, fixed costs grow as the business grows.
Owning the mechanism means a system built once can simply be dropped onto another site. The only thing that increases is hosting, not a bill that scales with the number of sites. Over a few years, that gap gets large.
The FAQ Itself Becomes an Entry Point from Search
An FAQ reduces inquiries, but it also draws traffic from search engines. The words users type when they're genuinely stuck are sitting right there as question text.
Hand it to a SaaS and you lose control over URL structure and structured data (extra information that tells search engines what a page means), which limits your SEO options. Keep it on your own site and you design the category URLs and heading structure yourself, growing the FAQ pages into an acquisition channel.
Live in a few days, but the look doesn't match the site, search behaves differently, and cost stacks up as sites are added
Assembled from the same components as product pages, search feels unified, and rolling out to more sites stays cheap
Speed of setup on one side, long-term freedom and cost on the other — that comparison is what the in-house decision comes down to.
The Full Picture — Storage, Delivery, and Search
FAQ Content Lives in Per-Category Files
The FAQ itself is managed as JSON files (readable data files listing field names and values) split by category. One file per unit: "Shipping & Delivery," "Returns & Exchanges," "Account Registration." Developers handle these in Git (a system that manages files while recording their change history), so every edit leaves a record of when, who, and what.
Display Data Is Served from a Fast Store
Files are great for management, but reading and parsing them every time a user opens a page is inefficient. So production display is served from Vercel KV (a store built for fast reads and writes), with the file contents synced into it. Neither ease of management nor display speed has to be given up.
A Separate Search Index Spans All 100-Plus Questions
Opening categories one at a time to find an answer among 100-plus questions isn't realistic. We built a separate search index (the data equivalent of the index at the back of a book) covering every category, narrowing candidates on the fly as the user types. Users search by words alone, without thinking about categories.
~10 categories, 100+ questions, managed with change history
Data used for production display
For searching across categories
Category pages, collapsible answers, and a path to the contact form
In diagram form: keep the source data in one place, then distribute it to two destinations — one for display, one for search.
Staff Can Fix Things Fast, Developers Still Keep Control
Two Editing Entry Points
FAQ operations often stall on a clash between "staff want to fix it the moment they notice" and "developers want the data properly managed." In this design, staff edit FAQs directly through an admin screen they log into with a one-time password, while developers work with the same data as files. The two are connected by a sync mechanism, so whichever entry point is used, the data converges into one.
Sister Sites Get the Same Setup As-Is
The same mechanism runs on the sister EC sites. The data structure, the admin screen, and the search are shared, so nothing has to be rebuilt per site. Launching a new site means preparing that site's FAQ data and syncing it. Getting the foundation right once is what makes these moments cheap.
What Building It In-House Left Us With
A look that matches the rest of the site, search that behaves consistently, easy rollout to more sites, and an FAQ that earns search traffic as content. In-house puts all of these — the things a SaaS makes hard — under your own control at once.
Summary
The reasons for building the FAQ in-house come down to four: consistency of look and search, cost, multi-site rollout, and value as content that earns search traffic. None of it is flashy, but this kind of foundation keeps paying off for both inquiry reduction and acquisition.
An AI agent (AI-assisted development) helped with much of the design and implementation here, and it confirmed something useful: even without an engineering background, deciding what to combine and how is enough to get this built.
Each part is covered in the three articles below.
FAQ Data Management and Search Index with JSON + KV
How the data is held in per-category files, and how the index behind cross-category search is built.
Admin-UI Editing with Git-Based Sync
Staff edit in the admin screen, developers manage files — how sync keeps both paths working together.
Connecting FAQ to the Contact Flow to Reduce CS Load
The flow design that places FAQ search ahead of the contact form to encourage self-service.