Skip to content

Scheduled Article Changes ​

Articles can be updated at any time - their features, PAYG plan binding, balance top-ups, and document links can all change. Updating an article directly only affects new purchases - existing subscriptions keep renewing with whatever they already had.

Scheduled Article Changes let you plan and control how such changes roll out to existing subscribers instead - define effective dates, choose a policy, collect customer consent where required, and let TiruPay apply everything automatically. This mirrors Scheduled Price Changes, applied to features, PAYG plans, balance top-ups, and document links instead of price.

Compliance Reminder

Depending on the country, changes to what a subscription includes may need to be communicated to customers in advance and may require explicit active customer confirmation before taking effect.

This information is provided for general guidance only and does not constitute legal advice.

For legal requirements and timelines, always review the applicable local laws and regulations.

Concepts ​

Article change group ​

A group bundles one or more scheduled article changes behind a single consent event. It has:

  • an effective date for new customers - when new subscribers start getting the new state
  • an effective date (optional) - when the change takes effect for existing subscribers. Must be on or after the new-customer date. If omitted, defaults to the new-customer date.
  • a policy - what happens to existing subscribers
  • a service scope - groups always belong to one service
  • a status - DRAFT, PUBLISHED, CANCELLED, or COMPLETED

Groups start in DRAFT status. They must be explicitly published before consents are created and customers are notified.

Scheduled article change ​

One entry per changed item inside a group. Each entry targets exactly one article or article extension, and exactly one of the following kinds of change:

KindDescription
FEATURESReplaces the full set of features granted by the article or extension
PAYG_PLANBinds, rebinds, or removes the article's PAYG plan binding
BALANCE_TOPUPAdds, changes, or removes a balance top-up for one balance type
DOCUMENT_LINKLinks or unlinks an article document

At the time of creation, the current (old) state of the target is automatically snapshotted. A single article can have multiple open changes at once, as long as they don't target the same kind (and, for BALANCE_TOPUP, the same balance type; for DOCUMENT_LINK, the same document) - for example, a features change and a PAYG plan change on the same article can be scheduled independently, or even bundled into the same group.

One consent record per group per customer. It is created automatically when a group is published (depending on policy) and tracks whether the customer has accepted or rejected the change. A customer affected by several changes in the same group still only gets one consent for the whole group.

When someone else pays for a subscription (see Paying Customer), the paying customer gets the consent and answers it. One consent covers all affected subscriptions a customer pays for, including their own. The customer who receives the features still gets the new features and documents once the paying customer accepts.

Special termination right ​

A special termination right can be attached to a group while it is in DRAFT status, exactly like for price changes. It grants affected customers the right to cancel their subscription at a specific date during a defined window.

A right can be scoped to a specific country or apply to all customers of the group (wildcard). At most one right per (group, country) combination is allowed.

See Special Termination Rights for details.

Policies ​

PolicyEffect on existing subscribers
NO_IMPACTOnly new subscribers get the new state. Existing subscriptions keep renewing with the old state indefinitely.
AUTO_APPLYThe new state takes effect automatically on the next renewal after the effective date. No customer action required (subject to local law).
AUTO_APPLY_CANCEL_ON_REJECTSame as AUTO_APPLY if the customer does not respond - the new state takes effect automatically. If the customer explicitly rejects, their subscription is cancelled at the end of the current period instead.
CONSENT_REQUIRED_CANCELCustomers must accept. If no response by the effective date, their subscription is cancelled at the end of the current period.
CONSENT_REQUIRED_KEEPCustomers must accept. If no response by the effective date, they keep the old state.

New subscribers

New subscribers are handled based on two dates:

  • After effective_date_new_customers: The subscriber already gets the new state from the start. No consent needed.
  • Before effective_date_new_customers: The subscriber is treated like an existing customer - they receive a consent record and notification, just like all other subscribers.

This two-date model ensures that new customers are always informed early enough about upcoming changes (as may be legally required), while customers who subscribe after the new-customer date already get the new state from the start.

Direct feature, PAYG, and top-up changes vs. policy-driven changes

Updating an article's features, PAYG plan binding, or balance top-ups directly (outside of the Article Change process) only affects new purchases and new orders immediately - it does not directly update existing subscriptions. The actual update for existing subscribers happens exclusively through the policy logic in step 5 of the lifecycle.

We strongly recommend using the NO_IMPACT policy instead of direct article updates for any planned change that should reach existing subscribers in a controlled way.

Document links are not protected by this system

Linking or unlinking an article document directly (outside of the Article Change process) is not protected the way features, PAYG plan binding, and balance top-ups are. A directly created link is granted to existing subscribers on their next renewal without any consent check.

Always link or unlink documents for existing subscribers through a DOCUMENT_LINK change in an Article Change group instead of the regular document-link endpoints, if the change should be subject to a policy or consent.

Lifecycle ​

1. Create a group (DRAFT) ​

POST /article-changes/groups?service_id={id}

json
{
  "name": "Add usage analytics feature",
  "effective_date_new_customers": "2026-04-01T00:00:00Z",
  "effective_date": "2026-06-01T00:00:00Z",
  "policy": "CONSENT_REQUIRED_CANCEL",
  "changes": [
    {
      "article_id": "art_123",
      "change_kind": "FEATURES",
      "new_feature_links": [
        { "feature_id": "feat_analytics", "value_bool": true }
      ]
    }
  ]
}

The group is created in DRAFT status. No consents are created yet and no customers are notified.

While in DRAFT, you can:

  • Update the group via PATCH /article-changes/groups/{group_id}
  • Add or remove special termination rights (see below)

2. Publish the group ​

POST /article-changes/groups/{group_id}/publish

Publishing transitions the group from DRAFT to PUBLISHED. TiruPay will:

  • Find all affected subscriptions that reference any of the changed articles or extensions (including paused and cancelled subscriptions, to ensure legal notification obligations are met)
  • Create one consent (status PENDING) per affected customer - the paying customer, if someone else pays

For AUTO_APPLY, consents are created with status AUTO_APPLIED for documentation purposes. For NO_IMPACT, no consents are created.

For AUTO_APPLY_CANCEL_ON_REJECT, consents are created with status PENDING - unlike plain AUTO_APPLY - because the customer retains a real option to reject and trigger a cancellation instead of the automatic update.

WARNING

Once published, the group and its changes can no longer be edited. Special termination rights also cannot be added or removed after publishing.

3. Notify customers ​

After publishing, customers with PENDING consents are notified by email with a link to the consent form.

POST /article-changes/customers/{customer_id}/consent

json
{
  "article_change_group_id": "grp_789",
  "accepted": true
}

If accepted: true:

  • The consent status becomes ACCEPTED
  • Nothing changes yet - the new state takes effect on the next renewal after the effective date

If accepted: false:

  • The consent status becomes REJECTED
  • For CONSENT_REQUIRED_KEEP: the old state is preserved; the subscription continues unchanged
  • For CONSENT_REQUIRED_CANCEL: the subscription will be cancelled at the end of the current billing period on the effective date (same as if the customer never responded)
  • For AUTO_APPLY_CANCEL_ON_REJECT: the subscription will be cancelled at the end of the current billing period on the effective date - unlike a non-response, which lets the new state apply automatically

In both cases, consent is only recorded at this step. The actual update (or cancellation) happens exclusively during step 5.

Submitting a consent after the effective date has passed returns an error.

5. Effective date processing ​

Scheduled background processing handles all groups whose effective date has passed.

For each due group:

  1. Subscriptions are locked (only for NO_IMPACT) - the current (old) feature set, PAYG plan, or balance top-up amount is written to the subscription before the article itself is updated. This locked state is used on every future renewal for that subscription, indefinitely, until the customer explicitly accepts a subsequent article change.
  2. The article is updated - features, PAYG plan binding, balance top-up, or document link is changed to the new state, unconditionally. New subscribers and AUTO_APPLY renewals pick up this new state immediately.
  3. Subscriptions are processed according to the group's policy:
    • NO_IMPACT - locked state already set in step 1; no further action
    • AUTO_APPLY - the locked state is updated to match the new article state; renewals pick up the change
    • AUTO_APPLY_CANCEL_ON_REJECT - subscriptions with PENDING or ACCEPTED consents get the new locked state; REJECTED subscriptions are cancelled at end of current period
    • CONSENT_REQUIRED_CANCEL - subscriptions with PENDING or REJECTED consents are cancelled at end of current period; ACCEPTED subscriptions get the new locked state
    • CONSENT_REQUIRED_KEEP - subscriptions with PENDING or REJECTED consents keep the old locked state (no action); ACCEPTED subscriptions get the new locked state
  4. Group status is set to COMPLETED

Document links work a little differently

For DOCUMENT_LINK changes, there is no separate "locked state" field on the subscription - document access is tracked the same way as for any other purchase, through a document grant. Whether a customer's grant is created or withheld for a newly linked document still follows the same policy/consent outcome described above.

Special Termination Rights ​

In some jurisdictions, a change to what a subscription includes grants customers the right to cancel their subscription under special terms - typically effective at the change date or immediately, without waiting for the normal cancellation deadline. This works exactly like Special Termination Rights for price changes.

Creating a right ​

POST /article-changes/groups/{group_id}/termination-rights

json
{
  "country_code": "DE",
  "valid_from": "2026-03-01T00:00:00Z",
  "valid_until": "2026-05-31T23:59:59Z",
  "cancellation_effective_at": "2026-06-01T00:00:00Z"
}
  • country_code is optional. If omitted, the right applies to all customers of this group regardless of country.
  • At most one right per (group, country) combination is allowed, including the wildcard (at most one per group with country_code = null).
  • Rights can only be created while the group is in DRAFT status.
  • valid_from must be before valid_until.
  • cancellation_effective_at must not be before valid_from.

Exercising a right ​

POST /article-changes/customers/{customer_id}/exercise-termination

json
{
  "article_change_group_id": "grp_789",
  "subscription_ids": ["sub_abc", "sub_def"]
}

subscription_ids is optional. If omitted, all affected subscriptions are cancelled. If provided, only the listed subscriptions are cancelled - all IDs must be affected by the group, otherwise the request fails.

When exercised:

  • TiruPay checks whether a matching right exists for the customer's country and whether the current date is within the valid_from/valid_until window. Country-specific rights take precedence over wildcard rights.
  • The selected subscriptions (or all affected ones if subscription_ids is omitted) are cancelled with cancellation_effective_at set to the right's cancellation_effective_at.
  • If a subscription was already cancelled (e.g. via a normal cancellation), its effective date is moved earlier if the right's date is sooner.
  • The customer's consent record is set to REJECTED.

Managing rights ​

EndpointDescription
GET /article-changes/groups/{group_id}/termination-rightsList all rights for a group
GET /article-changes/termination-rights/{right_id}Get a single right
DELETE /article-changes/termination-rights/{right_id}Delete a right (only on DRAFT groups)

Edge Cases ​

Bundled changes ​

A group can bundle changes for multiple different articles or extensions, not just multiple kinds of change on the same one. If one customer has a subscription affected by several of the bundled changes (for example, a features change and a PAYG plan change on the same article), they get one consent for the whole group - accepting it applies all of those changes at once.

A customer only sees the changes that actually apply to their own subscriptions - both in the consent notification email and in the changes field returned by GET /article-changes/customers/{customer_id}/pending. If a group also changes a different article the customer doesn't have, that change is left out for them.

Paused subscriptions ​

PAUSED subscriptions (payment charged back) still receive consent records when an article change group is published. This ensures legal notification obligations are met regardless of the subscription's current payment state. The customer can accept or reject the change while paused.

If a CONSENT_REQUIRED_CANCEL consent is pending, or an AUTO_APPLY_CANCEL_ON_REJECT consent has been rejected, and the subscription is paused, cancellation is still applied when the effective date is reached.

Paying customer changes ​

If a new paying customer takes over a subscription while a group is still open, they get their own consent and notification. The previous paying customer's answer no longer applies to that subscription.

Only one active change per (target, kind) ​

Creating a group fails if another active group (in DRAFT or PUBLISHED status) already contains a scheduled article change of the same kind for the same article or extension (and, for BALANCE_TOPUP, the same balance type; for DOCUMENT_LINK, the same document). This also applies within a single request. Changes of a different kind on the same article don't conflict with each other.

Cancelling a group ​

POST /article-changes/groups/{group_id}/cancel

  • Sets the group status to CANCELLED
  • The article remains unchanged (nothing was applied yet)

INFO

The group as well as all consents are kept for audit purposes

Good to know ​

Querying Pending Consents

Use GET /article-changes/customers/{customer_id}/pending to retrieve all open consent requests for a customer. Each entry includes affected_subscriptions - the specific subscriptions that customer pays for and that the change affects. This is useful for building consent UIs, reminder emails, and selective termination flows.

Cancelling a Group is Permanent

Once a group is cancelled, it cannot be reactivated. All consents are kept for audit purposes, but nothing will be changed. You'll need to create a new group if you want to reschedule.

Consent Window

Customers can only submit consent while the group is published and the effective date has not yet passed.

Relationships ​

  • Articles - Article changes target an article's features or balance top-ups, an extension, or the article's PAYG plan binding.
  • Subscriptions - Affected subscriptions may be cancelled or kept at their old state based on policy and consent. New state takes effect on the next renewal.
  • Pay-As-You-Go (PAYG) - Article changes can rebind or remove an article's PAYG plan binding.
  • Article Documents - Article changes can link or unlink documents from an article.
  • Scheduled Price Changes - The sibling feature for price, sharing the same policy and consent model.
  • Paying Customer - The paying customer answers consents for the subscriptions they pay for.
  • Services - Each article change group is scoped to a service.