Skip to content

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:

TargetMeaning
global_ = trueApplies to all customers of the service (or all services for global documents)
article_idApplies to subscriptions and purchases of a specific article
article_category_idApplies to subscriptions and purchases of any article in the category
balance_type_idApplies 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
StatusDescription
DRAFTBeing worked on. Can be edited and updated freely.
FINALIZEDNotification emails have been sent (triggered by notification_date). No further edits allowed. Customers can already read and accept this version.
PUBLISHEDLive and enforced. The previously published version of the same (document_id, locale) is automatically archived.
ARCHIVEDSuperseded by a newer version. Still readable for audit purposes.

Key Fields ​

FieldDescription
versionHuman-readable version label (e.g. "2.0", "2026-01-01")
localeLanguage of this version (e.g. "de", "en")
requiredIf true, customers must accept this version before completing a first purchase in the document's scope
reaccept_on_purchaseIf 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_modeWhat happens to existing customers when this version is published (see Enforcement Modes)
notification_dateWhen notification emails are sent and the version transitions to FINALIZED. Must be before publishing_date. Not allowed for SILENT enforcement mode.
publishing_dateWhen the version goes live automatically via cron job
previous_version_idAutomatically set to the currently published version of the same (document_id, locale) at creation time
change_summaryHuman-readable description of what changed in this version
checkout_consent_textOptional 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.

ModeNotificationEffect on existing customers
SILENTNoneNo action. Existing customers are not notified and face no consequences. Use for editorial changes that do not affect customers.
SOFTYes (via notification_date)Customers are informed but face no consequences if they do not re-accept.
HARDYes (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 stays DRAFT (or FINALIZED) 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 - transitions DRAFT → FINALIZED and sends notification emails right away. Not allowed for SILENT enforcement 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:

  1. At notification_date - the cron job transitions the version to FINALIZED and sends DOCUMENT_VERSION_NOTIFICATION emails to all affected existing customers. Customers can already read and accept the new version at this point.
  2. At publishing_date - a second cron job transitions the version to PUBLISHED and 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:

  1. Have previously accepted an older version of the same document, and
  2. Are currently active in the document's scope:
    • global_ scope: all customers of the document's service
    • article_id scope: customers with an active subscription for that article or any of its extensions
    • article_category_id scope: customers with an active subscription for any article in the category
    • balance_type_id scope: 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}/acceptances
json
{
  "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}/pending

Returns all versions the customer has not yet accepted, filtered to the provided purchase context:

Query parameterDescription
article_idsArticle IDs in the current purchase
article_extension_idsArticle extension IDs in the current purchase (resolved to their parent article for scope matching)
balance_type_idsBalance type IDs in the current context
required_onlyIf true, only return versions with required = true
purchase_contextIf 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 ​

RoleCreateReadUpdate / Set scopesPublish
User-PUBLISHED + FINALIZED + ARCHIVED--
Service-Own service + global--
AdminOwn serviceOwn service + globalOwn serviceOwn service
SuperadminAll (incl. global)AllAllAll

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 ​

RoleRecord acceptanceView acceptances
UserOwn customersOwn customers
ServiceOwn service customersOwn service customers
AdminOwn service customersOwn service customers
SuperadminAllAll

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_NOTIFICATION email 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.