Appearance
Legal Documents
TiruPay provides a built-in system for managing legal documents such as Terms of Service, Privacy Policies, or Data Processing Agreements. Documents are versioned, can be published on a scheduled date, and can require explicit customer acceptance before a purchase completes or an existing subscription renews.
Selling downloadable content?
If you want to sell content like manuals or e-books rather than enforce legal compliance, see Article Documents instead - a simpler, unrelated concept with no acceptance workflow.
Concepts
Document
A Document is the top-level container for a legal text. It groups all versions of that text under a single identity with a fixed type (e.g. TOS) and name. Documents belong to a service or are global (superadmin-owned, no service_id).
Services cannot create global documents. Only superadmins can create documents without a service_id.
Scopes
Every document has a set of scope links that define which articles, article categories, or balance types it applies to. Scopes are a property of the document itself - all versions of a document share the same scope. A scope link targets exactly one of:
| Target | Meaning |
|---|---|
global_ = true | Applies to all customers of the service (or all services for global documents) |
article_id | Applies to subscriptions and purchases of a specific article |
article_category_id | Applies to subscriptions and purchases of any article in the category |
balance_type_id | Applies to balances of a specific balance type |
A document can have multiple scope links - for example, a document that covers two specific articles would have one link per article. global_ cannot be combined with other scopes (it already covers everything). Global documents (service_id = null) may only use global_ scope.
Scopes can be set when creating the document or updated at any time via PATCH /admin/documents/{document_id}.
DocumentVersion
A DocumentVersion holds the actual content - a reference to a File and metadata describing the change. Multiple versions of the same document can exist simultaneously (e.g. different locales or drafts for future publication). At most one version per (document_id, locale) combination can be PUBLISHED at any time.
Status Lifecycle
text
DRAFT → FINALIZED → PUBLISHED → ARCHIVED| Status | Description |
|---|---|
DRAFT | Being worked on. Can be edited and updated freely. |
FINALIZED | Notification emails have been sent (triggered by notification_date). No further edits allowed. Customers can already read and accept this version. |
PUBLISHED | Live and enforced. The previously published version of the same (document_id, locale) is automatically archived. |
ARCHIVED | Superseded by a newer version. Still readable for audit purposes. |
Key Fields
| Field | Description |
|---|---|
version | Human-readable version label (e.g. "2.0", "2026-01-01") |
locale | Language of this version (e.g. "de", "en") |
required | If true, customers must accept this version before completing a first purchase in the document's scope |
reaccept_on_purchase | If true, every purchase in the document's scope requires re-acceptance, even if the customer already accepted this version before. Does not affect pending-acceptance warnings shown outside of a purchase - see Mandatory Re-acceptance on Purchase. |
enforcement_mode | What happens to existing customers when this version is published (see Enforcement Modes) |
notification_date | When notification emails are sent and the version transitions to FINALIZED. Must be before publishing_date. Not allowed for SILENT enforcement mode. |
publishing_date | When the version goes live automatically via cron job |
previous_version_id | Automatically set to the currently published version of the same (document_id, locale) at creation time |
change_summary | Human-readable description of what changed in this version |
checkout_consent_text | Optional text shown to the customer at checkout when this document version requires explicit consent (e.g. for withdrawal right or terms acceptance). The frontend renders this text and passes the result back to TiruPay for permanent storage on the consent record. |
DocumentAcceptance
A DocumentAcceptance records that a specific customer has accepted a specific document version, including the timestamp and which user acted on the customer's behalf. Acceptances are permanent - they are never deleted.
Normally at most one record exists per (customer_id, document_version_id) combination, and accepting a version a second time returns the existing record without error. The exception is versions with reaccept_on_purchase = true: a new record is created on every purchase that requires re-acceptance, so multiple records for the same customer and version can exist over time.
Only PUBLISHED and FINALIZED versions can be accepted - customers can review and accept a finalized version before it officially takes effect.
Enforcement Modes
enforcement_mode on a DocumentVersion controls what TiruPay does to existing customers who have previously accepted an older version of the same document.
| Mode | Notification | Effect on existing customers |
|---|---|---|
SILENT | None | No action. Existing customers are not notified and face no consequences. Use for editorial changes that do not affect customers. |
SOFT | Yes (via notification_date) | Customers are informed but face no consequences if they do not re-accept. |
HARD | Yes (via notification_date) | Customers must re-accept. At the next subscription renewal or PAYG billing run, those who have not accepted face cancellation or a balance freeze. |
When enforcement applies
Enforcement only applies to customers who have already accepted a previous version of the same document. First-time customers are only subject to the required flag on the version.
HARD mode and subscription cancellation
When a subscription is due for renewal, TiruPay checks whether any HARD-mode document in the subscription's scope has a new version the customer has not yet accepted. If so, the subscription is cancelled instead of renewed. The cancellation follows the normal flow (respects min_term_periods, sends cancellation email).
HARD mode and balance freezing
When a PAYG balance is due for billing, TiruPay checks whether any HARD-mode document in the balance's scope has a new version the customer has not yet accepted. If so, the balance is frozen with system reason DOCUMENT_ACCEPTANCE_REQUIRED instead of being billed. Once the customer accepts all pending versions, the freeze is automatically lifted and billing resumes at the next billing run.
Scope-based enforcement
Enforcement is always scope-aware. A HARD-mode document scoped to a specific article only affects customers with an active subscription for that article - not all customers of the service.
Publishing Flow
Immediate vs. Scheduled
A version can be published in two ways:
- Immediately via
POST /admin/documents/{document_id}/versions/{version_id}/publish - Scheduled by setting a
publishing_date- the version staysDRAFT(orFINALIZED) until the daily cron job activates it
With Advance Notification
To notify customers before a version goes live, finalize it first:
- Immediately via
POST /admin/documents/{document_id}/versions/{version_id}/finalize- transitionsDRAFT→FINALIZEDand sends notification emails right away. Not allowed forSILENTenforcement mode. - Scheduled by setting a
notification_date- the cron job finalizes and sends emails automatically at that date.
Once finalized, the version can be published immediately via the publish endpoint or will be picked up by the cron job on its publishing_date.
If both notification_date and publishing_date are set:
- At
notification_date- the cron job transitions the version toFINALIZEDand sendsDOCUMENT_VERSION_NOTIFICATIONemails to all affected existing customers. Customers can already read and accept the new version at this point. - At
publishing_date- a second cron job transitions the version toPUBLISHEDand archives the previous published version.
Archiving
When a version is published, all other PUBLISHED versions of the same (document_id, locale) combination are automatically archived. There is always at most one PUBLISHED version per locale per document.
No Duplicate Scheduling
Two versions of the same (document_id, locale) combination cannot share the same publishing_date. Attempting to schedule a second version for the same day raises a conflict error.
Notification Emails
When a version reaches its notification_date, TiruPay sends a DOCUMENT_VERSION_NOTIFICATION email to all customers who:
- Have previously accepted an older version of the same document, and
- Are currently active in the document's scope:
global_scope: all customers of the document's servicearticle_idscope: customers with an active subscription for that article or any of its extensionsarticle_category_idscope: customers with an active subscription for any article in the categorybalance_type_idscope: customers with an active balance of that type
Customers who have never accepted any version are not notified.
The email template can be customized per service via the email settings.
Acceptance Flow
First Purchase (required = true)
When a customer attempts to complete a purchase, TiruPay checks whether any PUBLISHED version with required = true in the document's scope has not yet been accepted. If so, order finalization returns a 403 error:
json
{
"code": "document_acceptance_required",
"pending_version_ids": ["ver_abc", "ver_def"]
}The frontend should present the pending documents, collect acceptance, and retry finalization.
Recording an Acceptance
http
POST /user/documents/customers/{customer_id}/acceptancesjson
{
"document_version_id": "ver_abc"
}Only PUBLISHED and FINALIZED versions can be accepted. The call is idempotent.
Querying Pending Acceptances
http
GET /user/documents/customers/{customer_id}/pendingReturns all versions the customer has not yet accepted, filtered to the provided purchase context:
| Query parameter | Description |
|---|---|
article_ids | Article IDs in the current purchase |
article_extension_ids | Article extension IDs in the current purchase (resolved to their parent article for scope matching) |
balance_type_ids | Balance type IDs in the current context |
required_only | If true, only return versions with required = true |
purchase_context | If true, versions with reaccept_on_purchase = true are always returned regardless of prior acceptance. See Mandatory Re-acceptance on Purchase. |
Mandatory Re-acceptance on Purchase
By default, a customer who already accepted a document version is never asked again. Setting reaccept_on_purchase = true on a version changes this for purchases only: the version is treated as pending on every purchase in its scope, even if the customer accepted it before.
This only takes effect when the query is explicitly scoped to a purchase, i.e. when calling GET .../pending with purchase_context = true, or during order finalization (which always checks with purchase context). Calls without purchase_context - such as a general "pending documents" overview outside of checkout - are unaffected, so a reaccept_on_purchase version the customer already accepted does not appear as a standing warning.
Use case
Use reaccept_on_purchase for documents that must be reconfirmed on every transaction (e.g. a cancellation policy acknowledgement), without nagging the customer about it between purchases.
Access Control
Documents and Scopes
| Role | Create | Read | Update / Set scopes | Publish |
|---|---|---|---|---|
| User | - | PUBLISHED + FINALIZED + ARCHIVED | - | - |
| Service | - | Own service + global | - | - |
| Admin | Own service | Own service + global | Own service | Own service |
| Superadmin | All (incl. global) | All | All | All |
Services cannot manage documents
Document management is an admin responsibility. Service accounts have read-only access to ensure legal documents are reviewed before publication.
Acceptances
| Role | Record acceptance | View acceptances |
|---|---|---|
| User | Own customers | Own customers |
| Service | Own service customers | Own service customers |
| Admin | Own service customers | Own service customers |
| Superadmin | All | All |
Edge Cases
Acceptance after archiving
Archived versions can no longer be accepted. Customers attempting to accept an archived version should be shown the current published version instead.
Multiple locales
Each (document_id, locale) combination is managed independently. German and English versions of the same document can have different publishing dates without conflict.
SILENT versions
SILENT-mode versions cannot have a notification_date. They transition directly from DRAFT to PUBLISHED without any intermediate FINALIZED state or email.
Relationships
- Files - Each document version references a file containing the actual legal text.
- Orders & Order Lifecycle - Order finalization checks for required pending acceptances and blocks until they are provided.
- Subscriptions - Subscription renewal checks for pending
HARD-mode document acceptances. - Service Balances - PAYG billing checks for pending
HARD-mode document acceptances. - Email - Notification emails are sent via the
DOCUMENT_VERSION_NOTIFICATIONemail type. - Background Jobs - Scheduling, finalization, and publication are handled by daily cron jobs.
- Article Documents - A related but distinct concept for selling downloadable content, without the acceptance/enforcement workflow.