Upgrading to Subscriptions 6
This guide takes a store on an earlier Subscriptions version to 6.0.0. It covers what to check before you upgrade, how to run the update, and which behavior changes may need template or process changes. The complete list of changes is in the changelog.
Before you upgrade
- Back up the database and the
system/user/addonsandsystem/user/templatesfolders. - Upgrade CartThrob first. Subscriptions 6 requires CartThrob 10.0.1 or newer, ExpressionEngine 6.1 or newer, and PHP 8.0 or newer. The Subscriptions update refuses to run on an older CartThrob.
- Check your payment gateway. Subscriptions 6 bills only through Stripe Payments, classic Stripe and Authorize.net with CIM, plus Offline Payments for manual workflows. Subscription checkouts on any other gateway are now rejected before payment. See Eligible payment gateways.
- Check Asynchronous Order Processing. Subscription checkouts are refused while it is on. See Eligible payment gateways.
- Pause rebilling. Stop the rebill cron job or service until the update is finished and checked.
- Review custom member fields used by checkout. If your checkout posts
custom_data, CartThrob can save matching custom member fields. CartThrob 10.0.1 lets you exclude selected fields with$config['cartthrob_protected_member_fields']. This is optional; it does not change the fields explicitly mapped in CartThrob’s Members settings. See Protecting member fields from custom data.
Run the update
- Replace both bundled add-on folders,
cartthrob_subscriptionsandcartthrob_permissions_manager, insystem/user/addons/. - In the Control Panel, go to Add-ons and run the updates for CartThrob Permissions Manager and CartThrob Subscriptions.
- Open Add-ons > CartThrob Subscriptions. Check that the Subscriptions list loads and that no warning appears at the top. If you see “You haven’t configured Purchased Items for use by CartThrob”, see Purchased Items is now required for refunds.
- In CartThrob > Orders, check Subscription ID and map it if needed; keep an existing correct mapping. Confirm that Total and Payment Gateway are mapped, which cancellation and Plan-change refunds now require. See CartThrob field mappings.
- Review Utilities > Settings. See Rebill settings. Rebill Retry Interval and Rebill Action Key are new.
- Update your rebill schedule if needed (see Rebilling changes), then turn rebilling back on.
The CartThrob 10.0.1 update also changes the Subscription’s stored error_message column to nullable text. It preserves existing messages and avoids the schema-sync error that could affect a column widened by hand. You do not need to shorten gateway messages before upgrading. This is separate from the Order field mapped as Error Message.
The update adds Subscription currency and billing-anchor columns. It turns on Allow customer to modify subscription? for existing Plans and Subscriptions, so customers keep the Plan changes that 5.x allowed. It also registers the current extension hooks.
Your templates are not changed
Upgrading never changes templates already on your site. The Utilities > Installation page does not reinstall the example subscriptions template group if one already exists.
If you built your templates from the 5.x examples, compare them with the 6.0 examples in the add-on’s installer/templates/subscriptions.group folder, and copy what you need. Alternatively, rename your existing group and install the new examples alongside it. Then check each template against the tag changes below.
Template tag changes
| Tag | What changed | What to do |
|---|---|---|
update_subscription_details |
Saves only the Subscription’s name and description. A submission that includes status, interval or other billing fields is rejected as a whole. The 5.x subscription_edit example used it to change billing terms. |
Remove billing fields from these forms. Use change_plan_form for Plan changes and update_subscription_form for card changes. |
update_recurrent_billing_form |
Deprecated. The form still renders, but submitting it shows “Updating recurrent billing through this form is currently disallowed.” | Replace it with update_subscription_form. |
delete_recurrent_billing_form |
The gateway parameter is ignored and {gateway_fields} is empty. New variables explain which other Subscriptions share the card. |
Remove gateway fields. Optionally show the impact variables. |
change_plan_form |
Requires the Subscription’s Allow customer to modify subscription? to be enabled. Both difference flags default to no. Uncertain payments wait for review instead of retrying. |
Set charge_difference and refund_difference explicitly if you want to charge or refund the difference. |
update_subscription_form |
New vault_mode (new, update, choose) and shared-card variables. |
Review card-change templates. See the tag page. |
subscription_select and form options: |
Customer-selectable terms are declared through signed options: lists. Values that aren’t declared are rejected. The PHP-built end-date selectors in the 5.x examples were removed. |
Declare the choices you offer. Turn off PHP parsing on templates that no longer need it. |
subscriptions |
New {payments} variable pair for customer payment history. |
Optional. |
Signed-in Super Admins can no longer change another member’s Subscription through front-end forms just by holding an administrative role. Use Login as Member to act as the customer.
Behavior changes
Plan edits no longer change existing Subscriptions
In 5.x, each renewal merged the Plan’s current name, description, interval and trial terms over the Subscription. In 6.0, a Subscription keeps the terms it was bought with. Price was already stored on the Subscription in both versions.
If you relied on editing a Plan to change existing customers’ schedules, edit those Subscriptions individually instead. Changing a Plan’s permission list still synchronizes permissions. See Editing Plan Permissions.
Purchased Items is now required for refunds
Cancellation refunds, Plan-change credits and the Control Panel’s Last Paid Amount and Refundable Amount use the Purchased Item recorded for each payment. Without Purchased Items, those amounts are zero and no refund is issued. Refunds also need the Orders Total and Payment Gateway fields mapped. See CartThrob field mappings.
Rebilling changes
- Failed payments are retried on a schedule. A Subscription on Hold is retried once the new Rebill Retry Interval (default 24 hours) has passed. With a daily cron job, a retry can wait about 48 hours. See Scheduling with cron.
- The HTTP rebill URL needs a key. If you triggered rebilling with an HTTP request, set Rebill Action Key and add
key=to the request. Until a key is set, the URL is disabled. The command-line rebill is unchanged. - Missed renewals are not back-billed. A Subscription recovering from Hold pays one renewal, and its schedule moves to the next future date. See Recovery after missed billing dates.
- Payments that might have succeeded are held for review. A renewal with an uncertain result now waits in Payments > Needs review instead of being retried. See Payment review and recovery.
Billing dates
Last Bill Date now records actual payment history. To move a renewal, change Next Billing Date on the Edit Subscription screen. Calendar months keep the same day of the month, using the last day in shorter months. See The dates on a Subscription.
Control Panel changes
- The separate Vault screens inside Subscriptions were removed. Their old links open CartThrob’s Vaults screen.
- The pending-billing list is now the Payments > Overdue filter on the Subscriptions list.
- See Subscriptions Control Panel for the current screens.
For PHP integrations
If custom code calls Subscriptions services or hooks:
SubscriptionsService::changePlan()has new arguments and returns a result array.- Renewals no longer emit
cartthrob_subscription_rebilled. Usecartthrob_subscription_rebill_carry_forwardto carry custom fields onto renewals.
After upgrading
- Run the rebill command once by hand. This charges any renewals that came due while rebilling was paused. Then check Payments > Overdue, Payments > Needs review and Status: Hold.
- Place a test subscription purchase and a card change on your gateway’s sandbox before relying on renewals.
- Check that subscription-protected content uses
has_subscription_permission. See Billing status and access.