Appearance
Subscriptions
A Subscription is the authoritative record for a recurring relationship between a customer and a service. It owns all subscription state - billing period, cancellation, plan changes. Orders linked to a subscription are pure payment receipts.
How Subscriptions Are Created
A subscription is created automatically from a customer's first order for a subscription article. TiruPay reads the order's positions to determine the article, interval, and extensions, then creates the subscription record and links the order to it via subscription_id.
Timing follows the same rule as feature activation:
- On order completion (the default) - the subscription is created once the first payment succeeds.
- At order finalization, if the service's payment method configuration has
activate_features_on = pending- the subscription is created immediately, before payment is confirmed, same as features.started_atreflects this earlier moment, not the later payment confirmation.
The subscription is never created manually - it always originates from an order, whether or not that order has been paid yet.
Free Tier
A subscription on a Free Tier has is_free_tier = true and no term: interval and current_period_end are null, it is never renewed, and cancelling it ends it immediately.
Trial
A subscription started with a Trial has is_trial: true until the Trial ends. Its first period ends with the Trial (current_period_end equals trial_ends_at, both null for a Trial without end), it is not invoiced and not renewed.
Fields
| Field | Description |
|---|---|
article_id | The subscription article currently active |
is_free_tier | true if the subscription runs on a Free Tier |
status | Current lifecycle status (see below) |
interval | Billing interval - snapshotted from the article at creation time. null for a Free Tier |
min_term_periods | Minimum number of billing periods before cancellation takes effect. null = no minimum term |
started_at | When the subscription started - order completion, the earlier pending-time activation (see above), or the most recent upgrade |
current_period_start | Start of the current billing period |
current_period_end | End of the current billing period - next renewal date. null for a Free Tier |
cancelled_at | When the customer requested cancellation |
cancellation_effective_at | When the cancellation actually takes effect (respects min_term_periods) |
user_cancellation_reason | Optional reason the customer gave when cancelling: too_expensive, too_complex, missing_features, not_using_it, switching_provider, technical_issues or other |
internal_cancellation_reason | Optional reason set when an admin, a service or TiruPay itself cancelled: price_change, article_change, payment_failure, fraud, terms_violation, article_unavailable, trial_ended or other |
cancelled_by_user_id | Account that cancelled the subscription - decides who may reactivate it |
coupon_id | Coupon applied to the renewals. Removed once it is expired or used up, e.g. a one-time coupon after the order it discounted |
payment_method_id | Payment method used for recurring charges |
payment_partner | Payment partner used for renewals (e.g. mollie, stripe). Together with payment_method_id, this identifies the mandate to charge at renewal. |
locked_article_price | Net article price charged on renewal instead of the article's current price - see Manually Overwritten Prices |
extensions | Active extensions booked on the subscription, each with its own quantity (e.g. 5 units of the same add-on) and locked_price (net, per unit) |
pending_change | Scheduled plan change (at most one at a time), which may also carry a deferred coupon change - see Downgrade |
is_trial | true while the subscription is in a Trial |
trial_started_at | When the Trial started. Stays set after the Trial ended |
trial_ends_at | When the Trial ends. null during a Trial without end |
trial_end_action | What happens when the Trial ends: convert (paid plan), fallback (Free Tier) or expire (nothing follows) |
Fields shown to a User are a reduced set: payment_method_id, payment_partner, coupon_id, min_term_periods, locked_article_price, extensions, created_at, and updated_at are not included.
Statuses
| Status | Description |
|---|---|
ACTIVE | Running normally. Features are active, renewals will occur. |
CANCELLED | Customer requested cancellation. Features remain active until cancellation_effective_at. |
PAUSED | An order was revoked - payment was charged back, or an order (first payment or renewal) went unpaid past its due date. Features are deactivated. Resumes on successful re-payment. Admin can also pause manually. |
EXPIRED | Natural end after cancellation_effective_at passed. Features are deactivated. Set by a daily job. |
TERMINATED | Forcefully ended by an admin or due to non-payment after a paused period. Features are deactivated immediately. No renewal. |
Status Transitions
plain
ACTIVE ──→ CANCELLED ──→ ACTIVE (reactivate, while still in future)
│ │
│ └──→ EXPIRED (once cancellation_effective_at passes, via daily job)
│
├──→ PAUSED (order revoked - chargeback or unpaid past due date - or manual admin action)
│ │
│ ├──→ ACTIVE / CANCELLED (unpause, after successful re-payment)
│ └──→ TERMINATED (next renewal attempt while still paused)
│
└──→ TERMINATED (admin terminate)Renewal
Renewals are triggered by a daily job that finds all subscriptions whose current_period_end ≤ now.
For each due subscription:
- The period is advanced:
current_period_startandcurrent_period_endare updated - Any pending plan change is applied if its
effective_at ≤ now - A new order is created directly in
PENDINGstatus - Payment is triggered via the stored mandate
- On successful payment (webhook): features are activated for the new period and deactivated for the previous period
The new current_period_end normally falls on the same day-of-month as started_at. If a given month is too short to contain that day (e.g. a subscription started on the 31st and the next period is February), the date is capped to that month's last day. Once a long-enough month comes around again, renewals return to the original day-of-month instead of staying capped forever - so 31 Jan → 28 Feb → 31 Mar, not 31 Jan → 28 Feb → 28 Mar.
PAUSED subscriptions
If a subscription is still PAUSED when the next renewal is due, it is terminated immediately. No new order is created and no refund is issued - features were already deactivated when the pause began.
Mandate Resolution at Renewal
When a renewal is triggered, TiruPay resolves the mandate to charge as follows:
- If
payment_partneris set on the subscription, it is used directly together withpayment_method_idto look up the mandate. - If
payment_partneris not set, TiruPay uses the partner of the subscription's most recent payment.
To ensure clean renewal behavior, payment_partner should always be set. It is populated automatically when the first subscription payment completes, and can be updated via PATCH /subscriptions/{id}/mandate.
Renewal Pricing
If an active scheduled price change exists for the article and its effective_date for existing customers has not yet passed, the old price is used. This ensures customers are not charged the new price before their consent window has elapsed.
See Scheduled Price Changes for details. See Manually Overwritten Prices if the order that created the subscription had a manually set price.
Manually Overwritten Prices
The price locked on a subscription (locked_article_price, and locked_price per extension) does not have to match the article's own price. It is taken directly from the order position that created the subscription: if a service or admin set a custom unit_price on that position instead of leaving it to the article's/extension's own pricing, that exact price becomes the subscription's price for every future renewal.
Not protected against upgrades, downgrades, or being moved onto shared pricing
A manually overwritten price survives plain renewals and a NO_IMPACT price change (or a CONSENT_REQUIRED_KEEP change the customer never responds to) - those are designed to leave an existing price alone. It is still discarded by:
- Upgrade or downgrade - the new article's price is always resolved fresh; any previous overwrite does not carry over.
AUTO_APPLY/AUTO_APPLY_CANCEL_ON_REJECT- these move every affected subscription onto the new shared price, custom-priced ones included.- An accepted price change consent (
CONSENT_REQUIRED_KEEPorCONSENT_REQUIRED_CANCEL) - accepting always moves the subscription onto the new price, overwriting whatever was locked before.
Give permanently custom-priced customers their own article
If a customer needs a price that must never change - not even across an AUTO_APPLY price change or an upgrade - don't rely on an overwritten order price alone. Create a dedicated copy of the article (and any extensions) just for that customer and set their price there. Price changes and upgrades/downgrades are always resolved per-article, so a customer on their own private copy is never touched by a change aimed at everyone else on the shared one.
Cancellation
Cancellation is a soft operation - features stay active until cancellation_effective_at.
What happens:
cancelled_atis set to nowcancellation_effective_atis set to the later of: the end of the current billing period, or the end of the minimum term- Status is set to
CANCELLED(only if currentlyACTIVE-PAUSEDkeeps its status) - A daily job deactivates all features once
cancellation_effective_athas passed
Minimum term
If the article has min_term_periods = 3 (monthly) and the customer cancels after 1 month, cancellation_effective_at is set to started_at + 3 months, not current_period_end.
System-initiated cancellation
If the article or extension a subscription is on stops being available in the customer's country - because the article availability for it was removed, or the customer's country changed to one without one - TiruPay automatically cancels the subscription the same way, respecting min_term_periods and the current billing period, and sets internal_cancellation_reason to article_unavailable. Renewals never fail silently because of this.
Reactivation
A cancelled subscription can be reactivated via POST /subscriptions/{id}/reactivate as long as cancellation_effective_at is still in the future. An Admin can reactivate any subscription; a User or Service account only one it cancelled itself.
cancelled_at, cancellation_effective_at, user_cancellation_reason, internal_cancellation_reason, and cancelled_by_user_id are all cleared. Status returns to ACTIVE.
A cancelled Trial that continues as a paid plan gets no consent request for a price change. If a price change for its plan was published while it was cancelled, reactivating it fails with 409, so it can't continue at the old price. The customer starts a new subscription instead.
Price changes after reactivation
If the subscription was cancelled because the customer did not accept a scheduled price change (CONSENT_REQUIRED_CANCEL policy), or explicitly rejected one (AUTO_APPLY_CANCEL_ON_REJECT policy), reactivating it does not restore consent. The next renewal will use the current article price - which may already reflect the price increase. Make sure the customer is aware of the price before reactivating.
Reactivating a subscription cancelled for missing availability
If a subscription was cancelled because its article or extension has no availability for the customer's country, reactivating it will not fix that - the next renewal attempt will fail again unless an availability is added back first, or the customer's country is changed to one that has one.
Upgrade or Downgrade
Both are requested the same way, through POST /subscriptions/{id}/change - TiruPay determines which one actually happens.
json
{
"new_article_id": "art_123",
"new_extensions": [{ "extension_id": "ext_456", "quantity": 5 }],
"coupon_code": "SAVE20"
}new_extensionsis the full desired set of extensions and their quantities, not just what's changing - anything already booked but left out of the list is removed.coupon_codeis optional. If given, it becomes the subscription's new recurring coupon (replacing any existing one). If omitted, the subscription's existing recurring coupon - if it still has one - carries over unchanged.
Direction: Upgrade vs. Downgrade
Direction is decided by comparing final prices, not raw article prices: the subscription's current final price (after whatever coupon currently applies) against the new plan's final price (after whichever coupon will apply going forward - the newly supplied one, or the existing one carrying over unchanged).
- Equal or higher final price → upgrade. Applied immediately.
- Strictly lower final price → downgrade. Scheduled for the next renewal - or later, if the minimum term hasn't elapsed yet.
During a Trial every change is applied immediately like an upgrade and ends the Trial. Nothing is refunded, since nothing was paid.
Because the final price decides direction, a coupon can flip it: an article that's nominally more expensive can still end up cheaper overall, and be scheduled as a downgrade instead of charged immediately, if a big enough coupon is attached at the same time.
Example
A subscription is on a 10.00 €/month plan with no coupon. Switching to a 20.00 €/month plan together with a coupon EVERY75 (75% off) brings the final price to 5.00 €/month - lower than the current 10.00 €. Even though 20.00 € alone looks like an upgrade, this is scheduled as a downgrade for the next renewal, with the coupon applied at the same time.
Upgrade
What happens, immediately:
- A pro-rata refund for the unused portion of the current period is credited to the customer's Credit Balance
- The subscription's
article_id,interval,min_term_periods, extensions, and (if supplied) coupon are updated started_atandcurrent_period_start/endare reset to now- A new order is created for the new plan and charged immediately
- Features from the old plan are deactivated; features from the new plan are activated
- A scheduled downgrade, including its coupon, is dropped. A scheduled paying customer change stays
Pro-rata calculation
The refund amount is (remaining_days / total_days) × net_amount, credited to the Credit Balance - not to the original payment method.
Downgrade
What happens at the next renewal:
- The pending change is applied: article, extensions,
min_term_periodsare updated - A coupon supplied with the downgrade is applied at this point too, not before - so the coupon and the price change land together
started_atis reset to the renewal date- The new billing cycle begins with the downgraded plan's pricing
At most one pending change can exist per subscription.
Previewing a Change
POST /subscriptions/{id}/change/preview reports what an upgrade, downgrade, and/or coupon change would do, without applying anything. It takes the same body as POST /subscriptions/{id}/change; omit new_article_id to preview a coupon-only change instead - equivalent to previewing switching the recurring coupon.
| Field | Description |
|---|---|
possible | Whether the change can actually be applied |
is_upgrade | true/false for a plan change, null for a coupon-only preview |
effective_at | When the change would take effect |
current_price / new_price | Final price before and after, including whichever coupon applies on each side |
current_price_gross / new_price_gross | current_price / new_price converted to gross using the current / new article's tax rate for the customer's country; falls back to the net price itself (0% rate) when no rate can be resolved |
coupon | Details of the coupon that would apply, if any |
pro_rata_refund | For an immediate upgrade only: the pro-rata credit for the unused portion of the current period, in the same units as new_price_gross. null for a downgrade or a coupon-only preview. Subtract it from new_price_gross to get the amount actually charged now |
pro_rata_refund_net | pro_rata_refund without taxes. Subtract it from new_price to get the net amount charged now |
issues | Every reason the change isn't possible, when possible is false - e.g. the new article isn't available in the customer's country, or the coupon doesn't apply |
Unlike the endpoints it previews, issues collects every problem at once rather than stopping at the first one.
Coupon-only preview is Admin/Service only
A User can preview a plan change, optionally together with a coupon. Previewing a coupon-only change (no new_article_id) is only available to Admin/Service, matching the restriction on the switch/remove endpoint below.
Switching or Removing the Recurring Coupon
PUT /subscriptions/{id}/coupon changes or removes a subscription's recurring coupon on its own, without touching the article or extensions. Unlike an upgrade or downgrade, it never prorates or charges immediately - the new coupon (or its removal) simply takes effect at the next renewal.
Send {"coupon_code": "SAVE20"} to switch to a new recurring coupon, or {"coupon_code": null} (or omit it) to remove the current one.
Admin/Service only
Only an Admin or Service account can switch or remove a subscription's coupon this way - not a User.
Conflicts with a pending downgrade
If a downgrade is already scheduled with its own coupon change attached, this endpoint is rejected until that pending change is resolved - applied at the next renewal, or cancelled - since a subscription can only have one coupon change queued at a time.
Switching the Payment Method
A customer can switch the payment partner and method used for renewals via PATCH /subscriptions/{id}/mandate. This updates payment_partner and payment_method_id on the subscription.
Requirements:
- A VALID or PENDING mandate for the new partner and payment method combination must already exist in TiruPay. Use
POST /payment/mandates/checkoutto create one first if needed. - The mandate must belong to the subscription's paying customer. To hand the payments over to another customer, schedule a new paying customer instead.
- The existing mandate is not affected - it remains in place and can be reused or revoked separately.
Expiry
Natural end of a cancelled subscription once cancellation_effective_at has passed. Triggered by a daily job.
What happens:
- Status is set to
EXPIRED - All features are deactivated
Termination
Forceful end initiated by an admin or triggered automatically when a PAUSED subscription misses its next renewal. No waiting for cancellation_effective_at. Only an admin can terminate a subscription directly - a service account cannot.
What happens:
- Status is set to
TERMINATED cancellation_effective_atis set to now- All features are deactivated immediately
- If
refund: true(admin only): a pro-rata refund for the unused period is credited to the Credit Balance and the last order is markedREFUNDED
Pause / Unpause
Pause is triggered automatically when a payment on a subscription order is charged back. Admins can also pause manually.
On pause:
- Status →
PAUSED - All features are deactivated immediately
On unpause (after successful re-payment or admin action):
- Status returns to
ACTIVEorCANCELLED(whichever it was before the pause) - Features are reactivated if the current period is still running
Trial
A subscription in a Trial has two endpoints of its own, for a Service or Admin account:
| Endpoint | What it does |
|---|---|
PATCH /subscriptions/{id}/trial | Moves the end of the Trial: {"trial_ends_at": "<datetime>"} in the future, or null for a Trial without end. The customer is reminded again before the new end. |
POST /subscriptions/{id}/end-trial | Ends the Trial now. What follows is the same as at its regular end: the first paid period is charged, or the subscription ends and the Free Tier takes over. A cancelled Trial simply ends. |
Both answer 409 Conflict for a subscription that is not in a running Trial.
Whether a customer can start a Trial of an article tells GET /customers/{id}/trial-eligibility?article_id=...: eligible, and otherwise a reason - not_offered, fallback_unavailable (the Free Tier the Trial moves to is not offered in the customer's country), has_paid_subscription or already_used.
Relationships
- Orders - Every subscription is linked to one or more orders via
subscription_id - Paying Customer - Another customer can pay the subscription
- Articles - The subscription's article and extensions define what features and pricing apply
- Payments - Renewals are charged via a stored mandate
- Scheduled Price Changes - Active price changes affect renewal pricing
- Coupons - A recurring coupon is applied on every renewal if still valid
- Balances - Pro-rata refunds on upgrades and terminations are credited here
- Free Tier - Subscriptions without a term; upgrade, downgrade and fallback after cancellation
- Trial - A free first phase of a subscription