Skip to content

Article Documents ​

TiruPay lets you sell downloadable content - manuals, e-books, license certificates, anything delivered as a file - by attaching it to an article. Purchasing the article unlocks the document for the customer (permanently by default, or for a configurable number of days), similar to how a purchase grants features or tops up a balance.

Example

You sell a "Pro Plan" subscription and want to include a PDF user manual. You create an Article Document "User Manual", upload the PDF as its first version, and link it to the "Pro Plan" article. Every customer who buys the Pro Plan is granted access to that manual, by default for as long as they want to keep it - see Subscriptions and Renewals for how access evolves for subscribers specifically, and ArticleDocument for making access time-limited instead.

Not the same as Legal Documents

Article Documents are unrelated to Legal Documents. Legal Documents (Terms of Service, Privacy Policy, ...) require customer acceptance and are enforced during checkout. Article Documents are simply unlocked as a consequence of a purchase - there is no acceptance step, no enforcement, and no scheduled publishing.

Concepts ​

ArticleDocument ​

An ArticleDocument is the top-level container for a piece of purchasable content (e.g. "User Manual"). It belongs to exactly one service and groups all versions of that content under a single identity.

FieldTypeRequiredDescription
namestringyesDisplay name of the document
descriptionstringnoDescription of the document
service_idstringyesThe service this document belongs to
grant_validity_daysinteger | nullnoIf set, a grant for this document expires this many days after it was granted. null (default) means permanent access. Only applies to one-time purchases - grants created from a subscription's order are never time-limited this way, since a subscription's access already has its own lifecycle (see Subscriptions and Renewals).
replace_on_new_versionbooleannoIf true, a subscription that picks up a newer version (see Subscriptions and Renewals) loses its grant for the previous version instead of keeping both. Default false. Never applies to one-time purchases.

Unlike Legal Documents, an ArticleDocument always belongs to exactly one service - there is no global/service-agnostic variant, since it can only ever be unlocked through a service-scoped article.

ArticleDocumentVersion ​

An ArticleDocumentVersion holds the actual content - a reference to a File. Creating a new version automatically makes it the current version and demotes the previous one.

FieldTypeDescription
versionstringHuman-readable version label (e.g. "1.0", "2026-01")
file_idstringThe uploaded file containing the document content
is_currentbooleanWhether this is the version new purchases unlock. Exactly one version per document can be current at a time.
previous_version_idstring | nullAutomatically set to the version being replaced, making the history traceable

Customers keep the version they were granted

is_current only decides which version new purchases unlock. Uploading version 2.0 does not retroactively change what customers who bought while version 1.0 was current can access - their grant already points at version 1.0 specifically.

There is no draft/publish workflow - a version becomes current the moment it is created. If you need to prepare content ahead of time without unlocking it yet, don't create the version until you're ready to go live.

An ArticleDocumentLink connects an ArticleDocument to exactly one article or article extension, unlocking the document's current version whenever that article or extension is purchased.

FieldTypeDescription
article_idstring | nullThe article that unlocks this document. Mutually exclusive with article_extension_id.
article_extension_idstring | nullThe extension that unlocks this document. Mutually exclusive with article_id.

Multiple links per document

A single ArticleDocument can be linked to several articles - for example, a manual that ships with both the "Pro Plan" and a one-time "Setup" article.

The linked article or extension must belong to the same service as the ArticleDocument. Linking across services is rejected.

CustomerDocumentGrant ​

A CustomerDocumentGrant records that a customer has unlocked a specific ArticleDocumentVersion through a purchase. It always pins the exact version available at purchase time, so later version changes never affect a customer retroactively. Access is permanent by default; if the document's grant_validity_days is set, the grant instead expires after that many days.

FieldTypeDescription
customer_idstringThe customer who holds the grant
article_document_version_idstringThe specific version this grant unlocks
order_idstring | nullThe order that created this grant
granted_atdatetimeWhen access was granted
expires_atdatetime | nullWhen access ends, if the document has grant_validity_days set. null means permanent.

Each (customer_id, article_document_version_id) combination is unique - purchasing the same article twice does not create a duplicate grant.

Granting and Revoking ​

Document grants follow the exact same lifecycle timing as feature activation:

  • On order completion - a grant is created for the current version of every document linked (directly or via an extension) to a purchased article.
  • At order finalization, if the service's ServicePaymentMethodConfig has activate_features_on = pending - the grant is created immediately, before payment is confirmed, same as features.
  • On revoke or refund - TiruPay re-evaluates, for every document the order unlocks, whether the customer has any other still-valid order (any status except revoked, refunded, withdrawn, or cancelled) that also unlocks the same document. Access is only actually withdrawn if none remains.
  • On reactivating a revoked order (e.g. an overdue invoice finally gets paid) - TiruPay restores the exact grant that was withdrawn, pinned to the version the customer originally held. It does not re-grant the now-current version, even if a newer one was published while the order was revoked. If the order never had a grant in the first place (possible for a subscription renewal that failed payment before completion, depending on activate_features_on), the current version is granted fresh instead.
  • On subscription pause, unpause, or expiry - handled separately from the order-level cases above; see Subscriptions and Renewals below.

Multiple articles unlocking the same document

If two different articles both link to the same ArticleDocument, only one CustomerDocumentGrant row exists per customer - the grant is idempotent, keyed by (customer_id, article_document_version_id). Buying article B while already holding a grant from article A is a no-op; it does not create a second grant. Refunding the order for article A does not remove access as long as article B is still validly owned - TiruPay checks the customer's full order history for the document, not just the order being refunded.

Subscriptions and Renewals ​

A one-time purchase pins the document version available at purchase time forever - see Customers keep the version they were granted above. A subscription is different: as long as it keeps renewing, it should keep picking up newer versions too, so a customer paying annually isn't stuck waiting up to a year for content published mid-subscription.

Accumulating vs. replacing versions

By default, a subscription that picks up a newer version keeps the older one's grant too - the customer ends up holding every version they were ever entitled to. If the document has replace_on_new_version set, picking up a newer version instead withdraws the grant for whichever version the customer previously held, so a subscription always holds at most one version of that document. This only applies to grants created via a subscription's orders - a one-time purchase's grant is never replaced this way, even if the same document is also unlocked by a subscription of the same customer that replaces versions: the previous grant is only withdrawn if no other still-valid order (of any kind) also justifies it.

A grant is tied to the order that first created it, not the subscription

The grant's order_id points at whichever order actually created it - typically the customer's first purchase, or whichever order the sync job used the day it granted a newer version. Later renewal orders that don't create a new grant (because one already exists) never take ownership of it. This is why ending access has to key off the subscription, not off which order the grant happens to point at (see below).

Unlike a one-time purchase, document access from a subscription is tied to the subscription staying alive:

  • Pausing (e.g. an unpaid renewal) withdraws every document grant unlocked by any of the subscription's orders, the same way features and PAYG access are deactivated.
  • Unpausing restores exactly the grants that were withdrawn on pause, and additionally grants whichever document (or newer version) was published while paused and is now current - the customer doesn't miss out on updates just because of a pause, but only once the subscription is actually paid up again. Restoration only happens if the subscription's current period is still paid for, matching the existing feature-reactivation condition. A grant whose expires_at had already passed while paused is not restored.
  • Expiring (reached once a customer's own cancellation has run its course) withdraws document access permanently, at the same point features and PAYG access are deactivated. A subscription that has expired no longer qualifies for the daily sync either.

Independent purchases of the same document are unaffected

Just like the order-level revoke/refund path, pausing or expiring a subscription only withdraws a document grant if none of the customer's other still-valid orders also unlocks it. If the same document is also unlocked by an unrelated, still-valid one-time purchase or subscription, access survives the subscription ending.

If you need access to survive a pause/unpause cycle exactly as it was, this is handled automatically. If you need access to persist after the subscription is gone entirely (e.g. a one-time perk that should outlive cancellation), don't unlock it via a subscription article - link the document to a separate one-time article instead.

Downloading ​

Granted documents are downloaded through the regular Files API - GET /files/{file_id}/download - using the file_id from the version. Access is enforced by the file's article_document category rule: a user may download the file only if they have access to a customer holding an active grant for that specific version.

Access Control ​

RoleCreateReadUpdate
User-Own services-
ServiceOwn serviceOwn serviceOwn service
AdminOwn serviceOwn serviceOwn service
SuperadminAllAllAll

Services can manage article documents

Unlike Legal Documents, Article Documents are a product feature rather than a compliance concern, so service accounts have full create/update access within their own service.

Grants ​

RoleView
UserOwn customers
ServiceOwn service customers
AdminOwn service customers
SuperadminAll

Relationships ​

  • Files - Each document version references a file containing the actual content. Downloads go through the standard Files API.
  • Articles & Features - Articles and extensions are the purchase trigger that unlocks a document.
  • Scheduled Article Changes - Linking or unlinking a document from an article can be rolled out to existing subscribers in a controlled way.
  • Orders & Order Lifecycle - Order completion (and revocation/refund) drives grant creation and withdrawal.
  • Payments - activate_features_on controls whether grants are created at order finalization or only after payment completes.
  • Legal Documents - A related but distinct concept for compliance documents that require customer acceptance.