Skip to main content
Version: Thelia 3

Subscriptions

Added in Thelia 3.4.

A shop can sell a product by subscription. The customer pays the first installment at the checkout, as for any order. The shop then charges each following installment on its own, to a payment method the customer stored, and keeps the calendar, the retries and the states of the subscription. The customer follows it from their account.

Each installment is an ordinary order, with its own reference, invoice, stock movement and confirmation e-mail. Orders, exports and accounting keep working without a change.

Plans​

A merchant sells a product through one or more plans. A plan holds:

FieldMeaning
TitleOne per language.
PriceOne per currency, for one installment, excluding tax. A price in the default currency is required.
PeriodWhat an installment pays for: week, month, quarter or year, times a count. Every 2 weeks is week with a count of 2.
TrialA number of days served before the first charge. 0 means no trial.
InstallmentsHow many installments are billed in all. Empty means until the customer cancels.
CommitmentHow many installments the customer owes even if they cancel. Empty means none.
PausableWhether the customer may pause the subscription.
VisibleWhether the plan is offered in the shop.

The plan is copied onto the subscription when the customer takes it: price, currency, period and commitment. Editing or deleting the plan later changes nothing for a subscription that runs.

A subscription is one sale element, a quantity and a plan.

What the customer sees in the shop​

  • A product with a visible plan offers the plans on its page. The customer picks one and adds it to the cart.
  • The customer must be signed in. A visitor who is not signed in cannot subscribe.
  • A cart that holds a plan holds nothing else, and holds one plan line only. Adding anything else is refused with a message. This is deliberate: one order takes one subscription, with the payment method its installments will be charged to.
  • A product whose price is on request offers no plan. A visitor who may not see a product, or its price, does not see its plans, or their price, either.
  • With a trial, the first order is at zero. Without one, the first installment is charged at the checkout.
  • With a trial, the cart and the payment step give the date of the first charge: the date the billing will use, if the order is paid that day.
  • Only the payment methods that can charge a stored method without the customer are offered. A shop with no such module cannot sell a subscription. See Charging a stored method off session.
  • The subscription is created when the first order turns paid.

In their account, at My subscriptions, a customer sees each subscription with its status, its next payment date and its installments, and can:

  • change the payment method, to one of the methods they stored, until the subscription is cancelled;
  • pause an active subscription, when the plan allows it, and resume it;
  • cancel.

Resuming only undoes a pause. A suspended subscription comes back when the installment it owes is paid, and a trial ends with its first charge: neither can be resumed.

Cancelling takes effect at the end of the paid period. If the plan has a commitment, the installments still owed are billed until it is reached. The subscription is served until then.

States​

StateMeaning
trialWaiting for the first charge, after the trial days.
activeRunning and paid up.
payment_failedAn installment was declined. The shop tries again.
suspendedThe retries ran out. Nothing is charged until someone acts.
pausedStopped by the customer or the merchant. Nothing is charged.
cancelledCancelled, still served until its paid period or its commitment ends.
endedOver. Final.

What moves a subscription from one state to another:

FromToWhat does it
trialactiveThe first charge is paid.
trial, activepayment_failedA charge is declined, or the bank asks the customer to confirm it.
payment_failedactiveA retry is paid.
payment_failedsuspendedThe attempts are used up.
suspendedactiveThe customer gives another method, or the shop reactivates, and the charge is paid. A new period starts on the day of the payment.
activepausedThe customer or the merchant pauses (plan must be pausable for the customer).
pausedactiveResume. The paused weeks are not charged: a new period starts at that date.
trial, active, payment_failed, suspended, pausedcancelledThe customer or the merchant cancels.
cancelledendedThe paid period or the commitment is over.
any billing stateendedEvery installment of the plan is billed.

Every change leaves a line in the history of the subscription, with who did it: the customer, an administrator, or the system (the shop itself, from the billing).

A state refuses what its table does not allow. Through the API the answer is 409.

Billing and retries​

The shop bills each subscription when its next billing date is reached. For each installment it:

  1. places the order of the installment;
  2. asks the payment module to charge the stored method, without the customer;
  3. turns the order paid and moves the next billing date forward, or records the failure.

An installment is at most one order, whatever the retries: a declined charge is tried again on the same order, never on a new one.

A declined charge, or one where the bank asks the customer to confirm the payment, counts as a failed attempt. It is tried again after a few days, up to a number of attempts. Then the subscription is suspended, the order of the installment is cancelled and its stock goes back.

SettingDefaultMeaning
subscription_retry_attempts3How many declined charges of an installment suspend the subscription.
subscription_retry_interval_days2Days between two charges of a declined installment.

Both are configuration variables, read and written with thelia:config. A value that is not a whole number of one or more falls back to the default.

When the provider cannot be reached (a timeout, an outage), nothing is declined. The charge is tried again an hour later and does not count as a failed attempt.

To get a suspended subscription going again, the customer gives another payment method, or the merchant reactivates it. The installment that is due is then charged at once, on a new order. Once it is paid, a new period starts on the day of the payment, and the next installment falls one period later, on that day of the month. The months of the suspension are not billed and place no order. The same goes for any installment paid once the period it was due for is over: the next billing date is never in the past.

A physical product takes its stock with each installment order. A virtual product takes it once, with the first order.

E-mails​

Three messages are sent, in the language the subscription was taken in:

MessageSent toWhen
subscription_payment_failedThe customerA charge is declined or needs the customer's confirmation, and the shop will try again. Not sent when the provider could not be reached.
subscription_suspendedThe customer, and the notification addresses of the shopThe retries ran out. The shop copy is addressed to the merchant.
subscription_cancelledThe customerThe customer or an administrator cancels. Not sent when the system cancels, as when the customer data is erased.

They are rendered from the active e-mail template. The default template ships all three. A shop with a template of its own adds subscription_payment_failed, subscription_suspended and subscription_cancelled as .html.twig and .txt.twig files. Until it does, the mail is logged and not sent. Billing is never affected.

All three receive the subscription (subscription_id, subscription_ref, subscription_status, customer_id), its plan as copied (product_title, quantity, unit_price, currency_code, period_unit, period_count), the label of the payment method (payment_method_label) and the dates next_billing_date, current_period_end_date and cancel_at_date, formatted Y-m-d or empty. order_id and order_ref come with them when the installment has an order. Each message adds its own:

MessageExtra variables
subscription_payment_failedinstallment_number, failure_count, failure_kind (declined or action_required), retry_date
subscription_suspendedfailure_count, recipient (customer or shop)
subscription_cancelledactor_type (customer, admin or system)

A template must handle an empty date and an absent order. See also Emails and PDF.

The scheduled task​

subscription:bill-due bills what is due. It sends one job per subscription that has something due, on the async queue. Each job locks its subscription and reads it again, so two runs at once never bill an installment twice.

The scheduler of the shop runs it every 15 minutes. Change it with THELIA_SCHEDULE_SUBSCRIPTION_BILLING (a cron expression). An empty value turns it off, for a shop that runs the command from a crontab. See Running the workers and the background jobs reference.

Without the scheduler, run it from a crontab, every few minutes:

*/5 * * * * cd /var/www/shop && php Thelia subscription:bill-due

Without a queue worker, the jobs run at once, inside the command. To see what is due without billing anything:

php Thelia subscription:bill-due --dry-run

What the merchant does in the back office​

A merchant with the admin.subscription right sees the subscriptions of the shop. The right is granted profile by profile: existing profiles do not have it until it is given.

  • List the subscriptions and filter them by state, plan, next billing date, or a search on the reference and the customer's name or e-mail. The active and payment-failed subscriptions are counted above the list.
  • Open one to read its terms, its payment method (by its label), its installments with their orders, and its history.
  • With the update right: cancel, pause (when the plan allows it), resume, or reactivate a suspended subscription or one whose payment failed. Reactivating charges the failed installment again at once; the subscription becomes active when that charge is paid.
  • Read the monthly recurring revenue on the dashboard, and the subscriptions of a customer on the customer sheet.

Plans are set up in the Subscription plans tab of the product sheet, with the product right (a plan belongs to the catalogue): title per language, price per currency (the default currency is required), period, trial, number of installments, commitment, pausable, online.

Whatever an administrator does is recorded in the history with the administrator as the actor.

API​

The customer account, the administration and the plans are exposed by the API. See Subscriptions in the endpoints reference.

Personal data​

The export of a customer carries a subscriptions section: the values of each subscription, its installments with the reference of their order, its history and the label of its payment method. Never the token.

The anonymization of a customer cancels and ends their running subscriptions, as the system, so nothing is left to bill. The orders already emitted stay as they are. A customer who has orders, which every subscriber has, cannot be deleted. See Personal data.

Known limits​

  • No proration when a plan changes.
  • No usage based tiers.
  • No deferred revenue accounting.
  • One line per subscription, and one subscription per cart, alone in it.
  • A customer who is not signed in cannot subscribe.
  • The unpaid order of an installment of a customer who is erased is left as it is.
  • No payment module of the core charges a stored method without the customer yet. A module has to implement the interface described in Charging a stored method off session.