Amend, renew and supersede
What this page is — the ways a sealed document is changed, extended, replaced, withdrawn or forced through its lifecycle, and the rules that gate each one.
What it is for — so a change to an agreement produces a record of the change, instead of a quietly edited file.
The problem it solves — changing a signed agreement by editing the file leaves no record of what changed, when, or who agreed.
Route: /org/papers/documents/<document> · Permissions: Create documents from a type.
to amend, renew or add an addendum; Force transitions / re-open (audited). to supersede, revoke or
override.
1. What it is
The question a dispute turns on is usually "what was agreed, and when did it change?". A sealed document that could be edited could not answer it. So Papers never edits one — it creates or records something new.
| Action | Produces | The original | Use when |
|---|---|---|---|
| Amendment | A new linked draft | Untouched | Terms change by consent |
| Renewal | A new linked draft | Untouched | The period is extended |
| Addendum | A new linked draft | Untouched | Terms are added, not changed |
| Supersede | No new document — links an existing replacement | State → superseded | A different document takes over entirely |
| Revoke | Nothing | State → revoked | It is withdrawn, with no replacement |
| Override | Nothing | Forced to any state | The lifecycle is stuck — the exception |
And one thing that does not exist: deleting a document. The Delete drafts permission appears in the role editor, but documents cannot currently be deleted — revoke a finalized document, or rename a draft clearly.
2. Why you would use it
- The history stays true. The original remains the record of what was agreed at the time; the amendment records what changed and when.
- The family is navigable. Parent and children show the relationship, the knowledge graph links them, and Cross-document consistency can check an amendment against its parent.
- Verification stays honest. A revoked document's code still resolves — and says revoked, which is what a recipient holding a copy needs to know.
- Integrations hear about it. A new child fires
paper.createdwithoriginandparent_document_id; a revocation firespaper.revoked. - Override is owned. Forcing a state needs a reason and lands in the audit trail, so a workaround is a decision somebody owns.
3. Step by step
Amendment, renewal or addendum
- Amend ▾ → choose Amendment, Renewal or Addendum.
- Keep or edit the suggested title.
- Create Draft, then Open it from the toast.
- Change what is changing, and take the draft through its own lifecycle.
Supersede — Supersede → pick the replacing document from the list (shown as number — title (state)) → confirm.
Revoke — Revoke → enter the reason → confirm.
Override — Override → pick the target state → enter the reason → confirm.
A renewal can also be created from the Obligations page with Renew — but see §5, because that path follows different rules.
4. Field reference
Amendment, renewal, addendum
| Rule | Refusal |
|---|---|
| A title is required | title is required |
| The relation must be one of the three | relation_type must be amendment, renewal or addendum |
| The parent's type must allow amendment — off by default | this document type does not allow amendments — enable 'Allows amendment' on the type first |
What the new draft carries
| Copied from the parent | Not copied |
|---|---|
| Every field value | Number, seal, verification code |
| Confidentiality and owner | Versions and signatures |
| A link to the parent, with the relation | Obligations |
| — | Validity dates (the Obligations Renew rolls them forward; Amend ▾ does not) |
Supersede
| Rule | Refusal |
|---|---|
| Needs Force transitions / re-open (audited).; not offered on a draft or an already-superseded document | — |
| A replacing document must be chosen | superseded_by_document_id does not resolve to a visible document |
| Not itself | a document cannot supersede itself |
| Not under legal hold | document is under legal hold and cannot be superseded |
Revoke
| Rule | Refusal |
|---|---|
| Needs Force transitions / re-open (audited).; not offered on a draft or an already-revoked document | — |
| A reason is required | reason is required to revoke a document |
| Not under legal hold | document is under legal hold and cannot be revoked |
The public verify page reflects a revocation immediately.
Override
| Rule | |
|---|---|
| Permission | Force transitions / re-open (audited). — Force transitions / re-open (audited) |
| Reason | Mandatory |
| Recorded | As a state transition with the reason, in the audit trail |
When a document is waiting in an approval state, ordinary transitions are refused with "this document is waiting on an approval decision (…). Approve, reject or return it from the Approvals Inbox … An administrator can force the state with an override and a reason." That is the situation override exists for.
5. Two renewals, two rule sets
| Amend ▾ → Renewal (workspace) | Renew (Obligations page) | |
|---|---|---|
| Permission | Create documents from a type. | Manage obligations and reminders. |
| Requires Allows amendment | Yes | No |
| Validity | Not set | Rolled forward by the original's term |
| Knowledge-graph edge | Created | Not created until a graph rebuild |
paper.created webhook | Fired | Not fired |
Prefer the workspace path when a type forbids amendment on purpose — the Obligations path will not stop you.
6. Worked example
An operations manager has three changes to make on a signed facilities contract.
The price is changing. Amend ▾ → Amendment: refused, this document type does not allow amendments. The type owner turns on Allows amendment on Facilities Contract and publishes. They retry; "Facilities Contract — Northwind — Amendment 1" opens as a draft with every value copied. They change the monthly fee, submit, and it goes through approval, finalize and signature on its own.
A second site is being added. Amend ▾ → Addendum — the terms are additions, not changes.
Last year's contract was replaced by this one. On last year's document, Supersede → pick
FAC/2026/00007 — Facilities Contract — Northwind (executed) → confirm. Its state becomes superseded.
A duplicate was issued in error. Revoke with reason "Duplicate of FAC/2026/00007 issued in error". Anyone who received a copy and checks the verification code now sees revoked. The duplicate cannot be deleted, but it can no longer be mistaken for a live agreement.
7. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
| Allows amendment is on for types that get amended | Behaviour settings | Amend ▾ is refused — it defaults off |
| The role holds Create documents from a type. | Role editor | No Amend ▾ |
| The role holds Force transitions / re-open (audited). for the few who need it | Role editor | No Supersede, Revoke or Override |
| Legal holds are released when appropriate | Retention and holds | Supersede, revoke and finalize are refused |
| Validity dates are set on amendments where they matter | The draft | Renewals from Amend ▾ never reach Expiring documents |
8. Downstream
| After… | Then |
|---|---|
| An amendment is created | It appears in the list as a draft, linked to its parent |
| An amendment is finalized | The parent is not superseded automatically — supersede it if the amendment replaces it |
| Supersede (list) | The document stays in the list as a record; filter by state to hide it |
| Revoke | Verification says revoked; paper.revoked fires; every share link stops working and reports the document as revoked |
| Supersede | Share links keep working — superseding does not withdraw the old copy. Revoke the links, or the document, if it must stop circulating |
| Override | Transitions resume from the forced state |
9. Don't confuse this with…
| Versions | Snapshots of the same document. These are new documents or state changes |
| Revoking a share link | Withdraws one link. Revoking the document marks it withdrawn everywhere |
| Cross-document consistency | Checks an amendment against its parent for conflicts |
| Deleting | Not available for documents |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| …does not allow amendments… | Allows amendment is off on the type — it defaults off |
| Renew worked from Obligations but Amend ▾ was refused | The two paths follow different rules — Renew does not check the switch |
| Supersede or Revoke is missing | Your role lacks Force transitions / re-open (audited)., or the document is a draft |
| reason is required to revoke a document | Enter a reason |
| …under legal hold… | Release the hold first |
| A renewal has no validity date | Created from Amend ▾, which does not roll dates forward |
| The parent was not superseded when the amendment executed | By design — supersede it deliberately |
| I cannot delete a document created in error | Documents cannot currently be deleted. Revoke it, or rename a draft clearly |