Appearance
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, orCOMPLETED
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:
| Kind | Description |
|---|---|
FEATURES | Replaces the full set of features granted by the article or extension |
PAYG_PLAN | Binds, rebinds, or removes the article's PAYG plan binding |
BALANCE_TOPUP | Adds, changes, or removes a balance top-up for one balance type |
DOCUMENT_LINK | Links 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.
Consent
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
| Policy | Effect on existing subscribers |
|---|---|
NO_IMPACT | Only new subscribers get the new state. Existing subscriptions keep renewing with the old state indefinitely. |
AUTO_APPLY | The 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_REJECT | Same 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_CANCEL | Customers must accept. If no response by the effective date, their subscription is cancelled at the end of the current period. |
CONSENT_REQUIRED_KEEP | Customers 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.
4. Customer submits consent
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:
- 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. - 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_APPLYrenewals pick up this new state immediately. - Subscriptions are processed according to the group's policy:
NO_IMPACT- locked state already set in step 1; no further actionAUTO_APPLY- the locked state is updated to match the new article state; renewals pick up the changeAUTO_APPLY_CANCEL_ON_REJECT- subscriptions withPENDINGorACCEPTEDconsents get the new locked state;REJECTEDsubscriptions are cancelled at end of current periodCONSENT_REQUIRED_CANCEL- subscriptions withPENDINGorREJECTEDconsents are cancelled at end of current period;ACCEPTEDsubscriptions get the new locked stateCONSENT_REQUIRED_KEEP- subscriptions withPENDINGorREJECTEDconsents keep the old locked state (no action);ACCEPTEDsubscriptions get the new locked state
- 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_codeis 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
DRAFTstatus. valid_frommust be beforevalid_until.cancellation_effective_atmust not be beforevalid_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_untilwindow. Country-specific rights take precedence over wildcard rights. - The selected subscriptions (or all affected ones if
subscription_idsis omitted) are cancelled withcancellation_effective_atset to the right'scancellation_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
| Endpoint | Description |
|---|---|
GET /article-changes/groups/{group_id}/termination-rights | List 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.