How to store terms of service acceptance
Store one row per user per document version, written by your server: who accepted, which document, the exact version and a hash of its text, when, from which IP and browser, the notice they saw and how they accepted. The Postgres schema, the insert and the query for who has not accepted the current version are below. Then the second half: what this table cannot show to anyone outside your company, and the two columns that fix it.
| user_id | document | version_label | content_hash | accepted_at | ip | user_agent | notice_text | button_label | method |
|---|---|---|---|---|---|---|---|---|---|
| 4f0c2c1e-7a55-4a0e… | terms-of-service | 2026-11-21 | sha256:9f2c41d0… | 2026-11-21 15:03:20+00 | 203.0.113.24 | Mozilla/5.0 (iPhone; … | By checking the box and clicking Create account, you agree to the Terms of Service… | Create account | checkbox |
The schema: a table of versions and a table of acceptances
Two tables and one view. terms_versions holds every version of every document you have published, with the full text and its SHA-256 hash. terms_acceptances holds one row for each user and version. It is written for Postgres and Supabase, and it runs as it stands.
- An exact version, not a boolean.
version_idpoints at one row that never changes.accepted = truecannot say which text the user was given. - A hash of the text shown.
content_hashis copied onto the acceptance, so the row still names the exact text if the versions table is ever touched. - The database clock.
accepted_atdefaults tonow(). The browser's time never reaches the table. - Where it came from.
ipanduser_agent, read from the request on your server. - What the user saw and did.
notice_textis the sentence beside the button,button_labelis the button, andmethodis how they accepted: checkbox, click, typed name, drawn signature or passkey. - No edits through the API. Row-level security lets a user read their own rows. Only your server role inserts, and update and delete are revoked from the public roles.
-- Every published version of every document. Rows are never edited. create table public.terms_versions ( id uuid primary key default gen_random_uuid(), document text not null, -- 'terms-of-service' version_label text not null, -- '2026-11-21' content text not null, -- the exact text users were shown content_hash text not null, -- 'sha256:' + hex digest of content effective_at timestamptz not null, created_at timestamptz not null default now(), unique (document, version_label) ); -- One row per user per version. Insert only. create table public.terms_acceptances ( id uuid primary key default gen_random_uuid(), user_id uuid not null references auth.users (id), version_id uuid not null references public.terms_versions (id), document text not null, version_label text not null, content_hash text not null, -- copied from the version on accept accepted_at timestamptz not null default now(), -- database clock ip inet, user_agent text, notice_text text not null, -- the sentence beside the button button_label text not null, -- 'Create account' method text not null check ( method in ('checkbox', 'click', 'typed', 'drawn', 'passkey') ), locale text, unique (user_id, version_id) ); create index terms_acceptances_user_idx on public.terms_acceptances (user_id, document, accepted_at desc); -- The version of each document in effect right now. create view public.current_terms_versions with (security_invoker = true) as select distinct on (document) id, document, version_label, content_hash from public.terms_versions where effective_at <= now() order by document, effective_at desc; -- Users read their own rows. Only your server role writes. alter table public.terms_acceptances enable row level security; create policy "read own acceptances" on public.terms_acceptances for select using (auth.uid() = user_id); revoke update, delete on public.terms_acceptances from anon, authenticated;
Publish a version, then record each acceptance
Publish each version once and never edit it. A changed sentence is a new version with a new label. Postgres computes the hash from the text in the same statement, so the two cannot disagree.
Run the acceptance insert from a server route, after the user ticks an unchecked box and clicks the button. The statement takes the user and the version ID and copies the document, the label and the hash from the version row itself, so the browser cannot choose them. A double click hits the unique constraint and writes nothing.
Pass the notice text and the button label from the same constants your form renders. If the sentence on the page and the sentence in the table come from two places, they drift.
-- $1 document, $2 version label, $3 text, $4 effective time insert into public.terms_versions (document, version_label, content, content_hash, effective_at) values ( $1, $2, $3, 'sha256:' || encode(sha256(convert_to($3, 'UTF8')), 'hex'), $4 ) returning id, content_hash;
-- $1 user, $2 version, $3 ip, $4 user agent, -- $5 notice text, $6 button label, $7 method, $8 locale insert into public.terms_acceptances (user_id, version_id, document, version_label, content_hash, ip, user_agent, notice_text, button_label, method, locale) select $1, v.id, v.document, v.version_label, v.content_hash, $3, $4, $5, $6, $7, $8 from public.terms_versions v where v.id = $2 on conflict (user_id, version_id) do nothing returning id, accepted_at;
Find who has not accepted the current version
The view picks the version of each document in effect now. The query returns every user with no acceptance row for it. That covers new users who have not accepted yet and existing users after you publish new terms.
To gate one signed-in user, add and u.id = $1 and show a blocking screen when a row comes back. Ask for a fresh tick on an unchecked box and a click on a confirm button. An email that says the terms changed is a notice, and the acceptance is still the user's own act on that screen.
-- Every user who has not accepted the current version of a document. select u.id as user_id, u.email, cv.document, cv.version_label from auth.users u cross join public.current_terms_versions cv where not exists ( select 1 from public.terms_acceptances a where a.user_id = u.id and a.version_id = cv.id ) order by u.email, cv.document;
What this table shows, and what it cannot show anyone else
Inside your company the table is all you need. Your app reads it to decide who sees the re-acceptance screen, and support reads it to answer a ticket. The limits appear when the reader is outside your company: a customer's lawyer, a card network, an auditor, a court.
You wrote the row
Your signup route inserted it. Nobody else saw the event happen, so the row is your own account of your own agreement. The other side has no reason to take your word for it.
You can change it
The statement below turns an acceptance of last summer's terms into an acceptance of the new ones. Afterward the row looks like any other. Revoking update from the public roles does not bind the service role, a migration or a restore from backup.
update public.terms_acceptances a set version_id = v.id, version_label = v.version_label, content_hash = v.content_hash, accepted_at = '2026-11-21 15:03:20+00' from public.terms_versions v where v.document = 'terms-of-service' and v.version_label = '2026-11-21' and a.document = 'terms-of-service' and a.user_id = '4f0c2c1e-7a55-4a0e-9d3b-2f1c8b6a7c1d'; -- UPDATE 1
The timestamp is your server's clock
now() is the time on a machine you run. Nothing outside your company saw the row exist at that moment, so nothing outside your company can say it was not written last week.
Nothing ties it to what the page displayed
notice_text holds a string your code passed in. It is not a measurement of what the browser rendered: where the notice sat, how large it was, whether the box started unchecked, or whether the link served that version's text. Courts judge the screen the user saw. In Dawson v. Target the court found no basis to conclude the plaintiff was presented with the screens in the company's declaration.
A hash column or an audit table of your own does not change any of the four. You compute the hash, you store it, and you can compute it again after an edit. See what makes a record tamper-evident.
A dispute, question by question
March 2027. A customer files a claim in court. Your terms have sent disputes to arbitration since version 2026-11-21, and your table says this customer accepted that version on 21 November 2026 at 15:03 UTC. Their lawyer asks five questions.
| The question | From your table | From the sealed record |
|---|---|---|
| Who created this entry? | Your own signup route. | Esign Comply, from events the customer's browser sent straight to it, outside your server. |
| Who could change it since? | Anyone with the service-role key, a migration or a backup restore. | Nobody at your company. The record is hash-chained into an append-only ledger and signed with keys you do not hold. |
| Whose clock is that? | Your database server's. | Esign Comply's server time on every event, and an RFC 3161 timestamp from an outside authority over the record hash. |
| What did the screen show? | The notice string your code stored. Nothing about layout, size or the state of the box. | The captured notice text, the checkbox label and the button text, the state of the box when the page loaded, whether a real user event changed it, and whether the text behind the link matched the registered version. |
| Can we check that ourselves? | They get your export and your statement that it is untouched. | They run the open-source verifier on the evidence package, offline, with no account. |
The table answers the question your app asks: has this user accepted? The dispute asks a different one: how does anyone else know? Why a third party keeps the record walks through the reasoning.
The upgrade: keep the table and add two columns
You do not replace anything above. Your app keeps reading its own table. Each row gains a record_id and a receipt from Esign Comply, which keeps the sealed record of the same acceptance outside your database.
- 01Add the two columns
record_idnames the sealed record.receiptis a compact token signed by Esign Comply with ES256 that names the record hash. - 02Register each version through the APISend the same text you store in
terms_versions. For Markdown and plain text thecontent_hashthat comes back equals yours, so the hash is the join between your table and the record. - 03Let the browser report the ceremonyYour server creates a session and hands the browser a short-lived client token. The headless SDK attaches to the checkbox and button you built and reports the notice, the tick and the click straight to Esign Comply.
complete()returns the record ID. - 04Confirm on your server, then write the rowThe record ID arrives from the browser, so treat it as a claim. Read the record with your secret key, check its status, mode, signer and document hashes against your own state, and only then insert.
accepted_atnow comes from a clock that is not yours.
- The evidence report: a PDF for one record with the document hashes, the notice, the label and button text, and the time of every event.
- The evidence package: a ZIP that anyone verifies offline with the open-source esigncomply-verify tool.
- The receipt in your own row, which ties that row to the sealed record.
alter table public.terms_acceptances add column record_id text, -- rec_Z4m8: the sealed record add column receipt text; -- the signed receipt for that record create index terms_acceptances_record_idx on public.terms_acceptances (record_id);
// When you publish a version to terms_versions, register the same text. const { data: version, error } = await esc.documents.versions.create( "doc_8Hq2", // your Terms of Service document at Esign Comply { version_label: "2026-11-21", language: "en", content: { format: "markdown", text }, }, { idempotencyKey: "tos-2026-11-21-en" }, ); if (error) throw new Error(`${error.code}: ${error.message}`); // version.content_hash equals terms_versions.content_hash for this text.
// In your form's submit handler, after the user ticked the box. const { recordId } = await ceremony.complete(); await fetch("/api/terms/accept", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ recordId }), });
// app/api/terms/accept/route.ts import { esc } from "@/lib/esigncomply"; import { supabaseAdmin } from "@/lib/supabase-admin"; // The same constants your form renders. import { BUTTON_LABEL, NOTICE_TEXT } from "@/lib/terms-notice"; const SEALED = new Set(["recorded", "timestamped", "anchored"]); const NOT_CONFIRMED = { error: "not_confirmed" }; export async function POST(request: Request) { const user = await requireUser(request); // your auth const { recordId } = await request.json(); // a claim to check const { data: record, error } = await esc.records.get(recordId); if (error) return Response.json(NOT_CONFIRMED, { status: 409 }); // What this user has to accept, from your own table. const { data: current } = await supabaseAdmin .from("current_terms_versions") .select("id, document, version_label, content_hash"); const expected = (current ?? []).map((v) => v.content_hash).sort(); const actual = record.documents.map((d) => d.content_hash).sort(); const confirmed = SEALED.has(record.status) && record.livemode === (process.env.VERCEL_ENV === "production") && record.signer.external_id === user.id && JSON.stringify(actual) === JSON.stringify(expected); if (!confirmed) return Response.json(NOT_CONFIRMED, { status: 409 }); await supabaseAdmin.from("terms_acceptances").upsert( (current ?? []).map((v) => ({ user_id: user.id, version_id: v.id, document: v.document, version_label: v.version_label, content_hash: v.content_hash, accepted_at: record.signed_at, // Esign Comply's server time notice_text: NOTICE_TEXT, button_label: BUTTON_LABEL, method: "checkbox", record_id: record.id, // rec_Z4m8 receipt: record.receipt, // signed with keys you do not hold })), { onConflict: "user_id,version_id", ignoreDuplicates: true }, ); return Response.json({ ok: true }); }
Keep your table. Store the receipt in it.
Where to go from here
The table is one part of a signing flow. These pages cover the screen in front of it and the record behind it.
The screen
What the checkbox, the notice and the button have to look like before the row you store means anything.
Clickwrap vs browsewrap vs sign-in wrapThe record
Who keeps the evidence, and how hashing, chaining, signing and an outside timestamp make it tamper-evident.
The whole flow
Generate one prompt with the rules for your flow and let your AI tool build the page. The Free plan includes 10 live signatures a month and a full test mode.
Generate a promptKeep reading
- Article7 things your AI coding tool gets wrong about e-signaturesPre-checked boxes, notices that name nothing, links to terms that change, and four more. Each one as code, with the fix.Read it
- ArticleClickwrap vs browsewrap vs sign-in wrapThe three patterns with a code example of each, how courts have treated them, and which one to build.Read it
- ChecklistESIGN Act and UETA checklist for developersEach U.S. requirement with its source, the implementation task, and the rule or SDK step that covers it.Read it
- ChecklisteIDAS checklist for developersSimple electronic signatures for EU signers, with the UK and Switzerland where their rule packs differ.Read it
Questions about storing terms acceptance
What should I store when a user accepts my terms of service?
Store one row per user per document version: the user ID, the document, the exact version ID and label, a SHA-256 hash of the text shown, the time from your database clock, the IP address and user agent your server saw, the notice text beside the button, the button label and the method, such as checkbox. Write it from your server and never update it.
Is a boolean accepted_terms column enough?
No. A boolean cannot say which version of the terms the user accepted, when, or what the screen said. Once you publish a second version you cannot tell who accepted which. Store a row that points at one immutable version with its content hash, and keep every version you have ever published.
How do I find users who have not accepted the latest terms?
Select the version of each document in effect now, cross join it with your users, and keep the pairs that have no row in the acceptances table. The query on this page does it with one view and a not exists. With Esign Comply, GET /v1/signers/{external_id}/status answers the same question per user and lists what is outstanding.
Read the re-acceptance guideShould I store the IP address and user agent with a terms acceptance?
Yes. They are part of how you tie the acceptance to a person and a device, alongside the signed-in user ID. Read them from the request on your server, not from the browser. They are personal data, so name them in your privacy notice and keep them only as long as you keep the acceptance.
Why is my own acceptances table not enough in a dispute?
Because the company relying on the table also controls it. You wrote the row, you can change it, the timestamp is your own server's clock, and nothing ties it to what the page displayed. Keep the table and add two columns, record_id and receipt, from an independent record that is sealed when the user accepts and signed with keys you do not hold.
Why a third party keeps the recordKeep your acceptances table. Add a record you can't edit.
Free plan: 10 live signatures a month and a full test mode. No card required.