# How to store terms of service acceptance

> A complete Postgres schema for storing terms of service acceptance, with the insert and the re-acceptance query. Then what that table cannot show anyone else.

Source: https://esigncomply.com/learn/store-tos-acceptance

Learn · storing 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_acceptances · 1 row

One row of the terms_acceptances table, with its columns

| 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_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`

```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](https://esigncomply.com/docs/guides/reacceptance)

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.

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

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

### 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](https://www.govinfo.gov/content/pkg/USCOURTS-cand-3_24-cv-08167/pdf/USCOURTS-cand-3_24-cv-08167-0.pdf) 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](https://esigncomply.com/why/immutable-record).

## 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 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](https://esigncomply.com/why/third-party-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. **Add the two columns**

   `record_id` names the sealed record. `receipt` is a compact token signed by Esign Comply with ES256 that names the record hash.

2. **Register each version through the API**

   Send 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. **Let the browser report the ceremony**

   Your 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. **Confirm on your server, then write the row**

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

[Server confirmation in full](https://esigncomply.com/docs/guides/server-confirmation) · [Read the quickstart](https://esigncomply.com/docs/quickstart)

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

```ts
// 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](https://esigncomply.com/learn/clickwrap-vs-browsewrap)

### The record

Who keeps the evidence, and how hashing, chaining, signing and an outside timestamp make it tamper-evident.

[Why a third party keeps the record](https://esigncomply.com/why/third-party-record)

[How the record stays tamper-evident](https://esigncomply.com/why/immutable-record)

### 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](https://esigncomply.com/product/prompt-generator)

## Keep reading

- Article

  **[7 things your AI coding tool gets wrong about e-signatures](https://esigncomply.com/learn/vibe-coded-esignature-mistakes)**

  Pre-checked boxes, notices that name nothing, links to terms that change, and four more. Each one as code, with the fix.

  Read it

- Article

  **[Clickwrap vs browsewrap vs sign-in wrap](https://esigncomply.com/learn/clickwrap-vs-browsewrap)**

  The three patterns with a code example of each, how courts have treated them, and which one to build.

  Read it

- Checklist

  **[ESIGN Act and UETA checklist for developers](https://esigncomply.com/compliance/esign-act-checklist)**

  Each U.S. requirement with its source, the implementation task, and the rule or SDK step that covers it.

  Read it

- Checklist

  **[eIDAS checklist for developers](https://esigncomply.com/compliance/eidas-checklist)**

  Simple 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 guide](https://esigncomply.com/docs/guides/reacceptance)

### 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](https://esigncomply.com/why/third-party-record)

## Keep your acceptances table. Add a record you can't edit.

[Get started](https://esigncomply.com/signup) · [Documentation](https://esigncomply.com/docs)

Free plan: 10 live signatures a month and a full test mode. No card required.

---

Every page on esigncomply.com has a Markdown version at the same URL plus `.md` (the home page is `https://esigncomply.com/index.md`). https://esigncomply.com/llms.txt lists them.
