Subscription Statuses
Every subscription moves through a defined set of statuses over its lifetime:Plans
A plan is the template that defines what you charge and how often. Create a plan once and attach as many subscriptions to it as you need.id that you pass when enrolling a customer.
Creating a Subscription
Enrolling a customer is a Cardholder Initiated Transaction (CIT), and a CIT may require 3D Secure. Pass the card one of two ways:card.nonceData/card.cardData— Therius runs the CIT + first charge here. Simple, but this CIT cannot do a 3D Secure challenge, so a 3DS-required card fails.card.tokenData— a card that already completed its CIT (with 3DS) via/payment/authorizationor/payment/purchase. Therius records the mandate and, for cycle 1, either charges an MIT or — if you passfirstPaymentId(the payment id from that CIT) — links the payment you already made. This is the reliable path for 3DS cards. See the endpoint reference.
id, its initial status (trialing if the plan has a trial, otherwise pending until the first payment clears), the current period start and end dates, and the first invoice object.
However you supply the card — SDK nonce, raw
cardData, or a vt_... token — card scheme rules require the customer to be actively present and consenting when their card is first saved for recurring charges. If you use an SDK nonce it must be fresh; you cannot reuse a nonce from a previous session.Lifecycle Management
After a subscription is active, use the following endpoints to manage it. All endpoints acceptPOST and require your API key.
Pause
POST /subscription/{id}/pauseSuspends renewals immediately. No charges are attempted while the subscription is paused. The billing date is recalculated when you resume.Resume
POST /subscription/{id}/resumeRestores a paused subscription (recalculates the next billing date) or re-charges a suspended subscription immediately to bring it back to active.Cancel
POST /subscription/{id}/cancelPermanently cancels the subscription. Therius fires the subscription.cancelled webhook event. Cancelled subscriptions cannot be reactivated.Change Plan
POST /subscription/{id}/change-planMigrates the subscriber to a different plan. Pass "applyAt": "now" for a prorated immediate switch, or "applyAt": "next_billing" to change at the end of the current period.Update Payment Method
POST /subscription/{id}/payment-methodReplaces the stored card and its mandate. Changing the card is a CIT and may need 3D Secure — either record a card you already CIT’d elsewhere (card.tokenData, no charge, no 3DS here), or run a zero-value CIT here (card.nonceData / card.cardData). Only the CIT-mode path can reactivate a suspended subscription. See the endpoint reference.Retry Payment
POST /subscription/{id}/retry-paymentQueues an immediate dunning attempt for a past_due subscription without waiting for the next scheduled retry.Move Billing Day
POST /subscription/{id}/update-billing-daySets the day-of-month on which renewals are charged. Accepts values 1–28.Usage-based and hybrid billing
On top of a plan’s flatamount, you can charge for metered consumption — a hybrid of a fixed base fee and a variable usage fee. There are three pieces:
1. Meters. A meter is a named counter scoped to your merchant account, e.g. api_requests or data_stored_gb. Each meter has an aggregation mode that decides how a period’s events collapse into one billable quantity:
2. Per-plan pricing. Each meter is priced on a plan with a scheme:
per_unit— a flat price per unit.volume— every unit is priced at the rate of the single bracket the total quantity falls into.graduated— each bracket prices only the units that fall within its own range.
includedUnits allowance is subtracted before pricing each period.
Meters and their per-plan pricing are managed in the Dashboard under Subscriptions → Usage Meters. There is no API for meter or price configuration.
POST /subscription/usage for each usage event:
Idempotency-Key header if your reporting job might retry — a duplicate (meterCode, Idempotency-Key) returns the original event. An optional occurredAt sets which billing period the event counts toward (it defaults to now).
At each renewal Therius aggregates the period’s events, applies the pricing, and adds the result to the invoice. A hybrid invoice carries a lines array — one line for the base fee plus one per metered add-on — and the invoice amount is their sum. See View Invoices.
Dunning
When a scheduled renewal fails — for example due to insufficient funds or an expired card — Therius automatically moves the subscription topast_due and begins the dunning sequence. Retries are spaced according to card scheme retry caps and your merchant configuration.
Once all retries are exhausted, the subscription moves to suspended and Therius fires a subscription.suspended webhook. See the webhook events catalog for every subscription event you can subscribe to. To reactivate a suspended subscription, the customer must provide a new payment method:
active.
This reactivation path runs its own CIT and cannot complete a 3D Secure challenge. If
the new card requires 3DS, run a 3DS-capable CIT + recovery charge yourself via
/payment/purchase, then record the resulting token with card.tokenData — see the
Update Card on File reference.Parent / Child Subscriptions
You can link subscriptions together by passingparentSubscriptionId when creating a child. This is useful for add-ons, seat expansions, or any billing model where multiple line items should share a lifecycle.
propagateLifecycle: true to cascade status changes — pause, resume, and cancel — from the parent subscription to all its children automatically. When propagateLifecycle is false (the default), each subscription manages its lifecycle independently.