Skip to content

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, or COMPLETED

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:

TargetDescription
article_idChanges the base price of an article
article_extension_idChanges the price of an article extension
article_availability_idChanges a country-specific price
payg_plan_price_item_idChanges a PAYG price (details), or - together with payg_change_field - a per-category PAYG condition (details)
payg_plan_idChanges a PAYG plan-level condition (requires payg_change_field, details)
payg_plan_price_idChanges 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.

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 ​

PolicyEffect on existing subscribers
NO_IMPACTOnly new subscribers pay the new price. Existing subscriptions renew at the old price indefinitely.
AUTO_APPLYThe 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_REJECTSame 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_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 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.

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:

  1. Subscriptions are locked (only for NO_IMPACT) - the current article/extension price is written to locked_article_price / locked_price on 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.
  2. Article prices are updated - the article/extension/availability's price is set to new_price or new_price_gross_amount, matching whichever the change specifies (clearing the other field, possibly switching the target's mode). New subscribers and AUTO_APPLY renewals pick up this price immediately.
  3. Subscriptions are processed according to the group's policy:
    • NO_IMPACT - locked prices already set in step 1; no further action
    • AUTO_APPLY - no action needed; renewals automatically pick up the updated article price
    • AUTO_APPLY_CANCEL_ON_REJECT - subscriptions with PENDING or ACCEPTED consents renew at the new price; 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 renew at the new price (locked price cleared on consent acceptance)
    • CONSENT_REQUIRED_KEEP - subscriptions with PENDING or REJECTED consents keep the old price (no action); ACCEPTED subscriptions renew at the new price (locked price cleared on consent acceptance)
  4. 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_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 /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_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 /price-changes/groups/{group_id}/termination-rightsList 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.