Skip to content
Learn · storing acceptance

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.

public.terms_acceptances1 row
One row of the terms_acceptances table, with its columns
user_iddocumentversion_labelcontent_hashaccepted_atipuser_agentnotice_textbutton_labelmethod
4f0c2c1e-7a55-4a0e…terms-of-service2026-11-21sha256:9f2c41d0…2026-11-21 15:03:20+00203.0.113.24Mozilla/5.0 (iPhone; …By checking the box and clicking Create account, you agree to the Terms of Service…Create accountcheckbox

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_id points at one row that never changes. accepted = true cannot say which text the user was given.
  • A hash of the text shown. content_hash is copied onto the acceptance, so the row still names the exact text if the versions table is ever touched.
  • The database clock. accepted_at defaults to now(). The browser's time never reaches the table.
  • Where it came from. ip and user_agent, read from the request on your server.
  • What the user saw and did. notice_text is the sentence beside the button, button_label is the button, and method is 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.
supabase/migrations/terms_acceptances.sql
-- 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.

Publish a version
-- $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;
Record an acceptance
-- $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.

The re-acceptance flow, step by step
Who has not accepted the current version
-- 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.

01

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.

02

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.

psql
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
03

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.

04

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.

Five questions about an acceptance, answered from your own table and from a sealed record
The questionFrom your tableFrom 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.

  1. 01
    Add the two columnsrecord_id names the sealed record. receipt is a compact token signed by Esign Comply with ES256 that names the record hash.
  2. 02
    Register each version through the APISend the same text you store in terms_versions. For Markdown and plain text the content_hash that comes back equals yours, so the hash is the join between your table and the record.
  3. 03
    Let 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.
  4. 04
    Confirm 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_at now comes from a clock that is not yours.
What you can hand over afterward
  • 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.
1. Your migration
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);
2. Register each version
// 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.
3. Browser: complete the ceremony
// 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 }),
});
4. Server: confirm, then store the receipt
// 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 wrap

The 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 prompt

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 guide

Should 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 record

Keep 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.

Working with an AI tool? This page is also available as Markdown: /learn/store-tos-acceptance.md