Appearance
Scheduled Price Changes
TiruPay allows you to schedule price changes for articles, extensions, or country-specific availabilities. Rather than immediately affecting all new customers, a price change goes through a controlled process: define effective dates, choose a policy, collect customer consent where required, and let TiruPay apply everything automatically.
Multiple changes (e.g. a base article and its extension) can be bundled into a single price change group, so customers only ever see one consent request per bundle - not one per changed item.
Compliance Reminder
Depending on the country, price changes 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
Price change group
A group bundles one or more scheduled price changes behind a single consent event. It has:
- an effective date for new customers - when new subscribers start paying the new price
- an effective date (optional) - when the new prices take 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 price change
One entry per target inside a group. Exactly one of the following must be set:
| Target | Description |
|---|---|
article_id | Changes the base price of an article |
article_extension_id | Changes the price of an article extension |
article_availability_id | Changes a country-specific price |
payg_plan_price_item_id | Changes a PAYG price (details), or - together with payg_change_field - a per-category PAYG condition (details) |
payg_plan_id | Changes a PAYG plan-level condition (requires payg_change_field, details) |
payg_plan_price_id | Changes a PAYG country-level condition override (requires payg_change_field, details) |
At the time of creation, the old value is automatically snapshotted from the current state - old_price (or old_price_gross_amount, matching whichever mode the target currently uses) for price targets, old_unit_scale for a unit_scale condition change. Only one active scheduled price change may exist per target (and per condition field, for PAYG condition changes) across all groups.
Set the new price as either new_price (net) or new_price_gross_amount (gross) - never both. A change is free to switch a target between net and gross mode regardless of which mode it was in before. PAYG plan price targets (payg_plan_price_item_id without payg_change_field) have no gross/net duality and only accept new_price.
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 price change. When a customer accepts, all their active subscriptions affected by the group are updated at once.
When someone else pays for a subscription (see Paying Customer), the paying customer gets the consent and answers it, not the customer who receives the features. One consent covers all affected subscriptions a customer pays for, including their own. PAYG price changes always go to the customer who owns the balance, since PAYG usage is billed to them. A group that changes both subscription and PAYG prices can therefore create consents for both customers.
Special termination right
A special termination right can be attached to a group while it is in DRAFT status. 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 pay the new price. Existing subscriptions renew at the old price indefinitely. |
AUTO_APPLY | The new price 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 price 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 price. |
New subscribers
New subscribers are handled based on two dates:
- After
effective_date_new_customers: The subscriber already pays the new price 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 price changes (as may be legally required), while customers who subscribe after the new-customer date already get the new price from the start.
Direct price changes vs. policy-driven changes
While the new_price/new_price_gross_amount field of a scheduled price change defines the future price, it does not directly update existing subscriptions when the effective date arrives. Instead, the actual price update for existing subscribers happens exclusively through the policy logic in step 5 of the lifecycle. This separation ensures that the system can handle complex scenarios (like consent requirements) correctly and transparently.
Direct price changes (e.g. updating an article's price outside of the price change process) are still possible but have no effect on existing orders. We strongly recommend using the NO_IMPACT policy instead of direct price updates for any planned price changes, to ensure a clear and consistent process for both merchants and customers.
Lifecycle
1. Create a group (DRAFT)
POST /price-changes/groups?service_id={id}
json
{
"name": "Pro Plan Preiserhöhung Q2 2026",
"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", "new_price": "39.99" },
{ "article_extension_id": "ext_456", "new_price_gross_amount": "11.90" }
]
}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 /price-changes/groups/{group_id} - Add or remove special termination rights (see below)
2. Publish the group
POST /price-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 items (including paused and cancelled subscriptions, to ensure legal notification obligations are met; Trials only if they continue as a paid plan, see Trials)
- 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 price 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 /price-changes/customers/{customer_id}/consent
json
{
"price_change_group_id": "grp_789",
"accepted": true
}If accepted: true:
- The consent status becomes
ACCEPTED - No prices change yet - the new price will take effect on the next renewal after the effective date
If accepted: false:
- The consent status becomes
REJECTED - For
CONSENT_REQUIRED_KEEP: old prices are 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 price apply automatically
In both cases, consent is only recorded at this step. The actual price update (or cancellation) happens exclusively during step 5.
consented_by_user_id
The authenticated user's ID is always stored in consented_by_user_id automatically. This tracks who submitted the consent - whether it was the customer themselves or an agent acting on their behalf.
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 article/extension price is written tolocked_article_price/locked_priceon each affected subscription before article prices are updated. This price is used on every future renewal for that subscription, indefinitely, until the customer explicitly accepts a subsequent price change. - Article prices are updated - the article/extension/availability's price is set to
new_priceornew_price_gross_amount, matching whichever the change specifies (clearing the other field, possibly switching the target's mode). New subscribers andAUTO_APPLYrenewals pick up this price immediately. - Subscriptions are processed according to the group's policy:
NO_IMPACT- locked prices already set in step 1; no further actionAUTO_APPLY- no action needed; renewals automatically pick up the updated article priceAUTO_APPLY_CANCEL_ON_REJECT- subscriptions withPENDINGorACCEPTEDconsents renew at the new price;REJECTEDsubscriptions are cancelled at end of current periodCONSENT_REQUIRED_CANCEL- subscriptions withPENDINGorREJECTEDconsents are cancelled at end of current period;ACCEPTEDsubscriptions renew at the new price (locked price cleared on consent acceptance)CONSENT_REQUIRED_KEEP- subscriptions withPENDINGorREJECTEDconsents keep the old price (no action);ACCEPTEDsubscriptions renew at the new price (locked price cleared on consent acceptance)
- Group status is set to
COMPLETED
Special Termination Rights
In some jurisdictions, a price increase grants customers the right to cancel their subscription under special terms - typically effective at the price change date or immediately, without waiting for the normal cancellation deadline.
A special termination right defines the time window during which this right can be exercised and the date on which the cancellation takes effect.
Creating a right
POST /price-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 /price-changes/customers/{customer_id}/exercise-termination
json
{
"price_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 /price-changes/groups/{group_id}/termination-rights | List all rights for a group |
GET /price-changes/termination-rights/{right_id} | Get a single right |
DELETE /price-changes/termination-rights/{right_id} | Delete a right (only on DRAFT groups) |
Edge Cases
Bundled changes
If one customer has subscriptions for article A and extension B, and both are in the same group, the customer gets one consent for the whole group. Accepting it updates all affected positions across all their subscriptions at once.
Country-specific changes
For article_availability_id-based changes, only subscriptions taxed in the matching country are affected. That is the paying customer's country, unless the subscription has a country override.
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.
Paused subscriptions
PAUSED subscriptions (payment charged back) still receive consent records when a price 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 price 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.
Trials
A price change only reaches a subscription in a Trial if the Trial continues as a paid plan and is not cancelled. Such a customer gets a consent and a notification like any other subscriber, and the first paid period after the Trial is charged at the price that applies by then.
A Trial that falls back to a Free Tier or simply expires never charges anything, and neither does a cancelled Trial. These customers get no consent and no notification.
Only one active change per target
Creating a group fails if another active group (in DRAFT or PUBLISHED status) already contains a scheduled price change for the same article_id, article_extension_id, or article_availability_id. This also applies within a single request - two changes targeting the same article in one group are rejected.
For PAYG condition changes, this check also considers payg_change_field - a plan can have an active price_per_unit change and an active unit_scale change at the same time, since they're different fields, but not two active changes to the same field.
Cancelling a group
POST /price-changes/groups/{group_id}/cancel
- Sets the group status to
CANCELLED - All article prices remain unchanged (nothing was applied yet)
INFO
The group as well as all consents are kept for audit purposes
Good to know
Choosing the Right Policy
Use NO_IMPACT for soft price increases that only apply to future sign-ups. Use AUTO_APPLY when legal requirements allow automatic updates (e.g. minor adjustments within contractual terms). Use AUTO_APPLY_CANCEL_ON_REJECT when automatic updates are acceptable but customers must still retain an explicit right to object with cancellation. Use CONSENT_REQUIRED_CANCEL when you want non-responding customers to churn rather than stay at an outdated price. Use CONSENT_REQUIRED_KEEP when retention matters more than uniform pricing.
Querying Pending Consents
Use GET /price-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 price change affects. This is useful for building consent UIs, reminder emails, and selective termination flows.
Coupons and Price Changes
Coupons may not be compatible with price changes. If a coupon applies to an article or order that is being repriced, the coupon's discount amount may no longer be valid after the price change resulting in the coupon being removed from the order.
We recommend reviewing your coupon strategy when planning price changes to avoid unexpected customer experiences.
Cancelling a Group is Permanent
Once a group is cancelled, it cannot be reactivated. All consents are kept for audit purposes, but no prices 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 - Price changes target articles, extensions, or country-specific availabilities.
- Subscriptions - Affected subscriptions may be cancelled or kept at the old price based on policy and consent. New prices take effect on the next renewal.
- Customers - Each customer receives one consent per group. Country matching applies for availability-based changes.
- Paying Customer - The paying customer answers consents for the subscriptions they pay for.
- Coupons - Coupons may be invalidated if they apply to articles or orders affected by price changes.
- Taxation - Article availabilities link price changes to specific countries.
- Services - Each price change group is scoped to a service.