Subscriptions¶
BadgerCommerce provides subscription management for recurring payments, integrated with Stripe's subscription billing system.
Key Features¶
Subscription Management¶
- Stripe Integration: Full integration with Stripe Subscriptions API
- Local Data Storage: Subscriptions and invoices stored locally for fast access
- Status Tracking: Active, trialing, past_due, canceled, paused states
- Billing Period Tracking: Current period start/end, trial end dates
- Payment Method Display: Shows card brand and last 4 digits
Invoice Management¶
- Automatic Invoice Storage: Invoices synced from Stripe
- Payment Tracking: Paid status, payment dates, amounts
- PDF Access: Direct links to Stripe-hosted invoice PDFs
- Line Item Details: Full breakdown of invoice line items
Gift Aid Integration¶
- Eligibility Tracking: Subscriptions can be marked Gift Aid eligible
- Donation Creation: Automatic donation records for paid invoices
- HMRC Reporting: Gift Aid donations flow into standard reporting
- Regular giving needs both decorators: a recurring donation is a product with
subscriptionProductanddonationProduct, plus thedonationFormExtensionfor the Gift Aid tick. A monthly payment is claimed only when all three hold: the invoice is for a subscription, its product is a donation (InvoiceServiceImpl.createDonationForInvoicecreates no donation otherwise), and the donor has Gift Aid on file: the subscription was flagged Gift Aid eligible (ticked at checkout, or a declaration already on their account) or a declaration matches their name and address. WithsubscriptionProductalone the gift still recurs but records no donations. The first payment is the checkout order's donation; the subscription starts on a trial, so its first invoice is £0 and is skipped. Set the product'squantityTypetoFIXEDso the storefront shows each tier's price rather than "Give any amount". - Plan: Gift Aid on recurring donations needs the
regularGivingcapability (Charity plan or Enterprise). Without it the subscription still runs, unflagged. See Subscription Entitlements.
Subscription prices¶
Each subscription SKU (a variant, or a product without variants, of a product with the
subscriptionProduct type) is billed at a Stripe recurring price. Shop owners manage those prices
in Badger, from the product's page or Catalogue > Subscription prices, or through the
manageSubscriptionPrices MCP tool. They never open the Stripe dashboard or copy a price ID.
SubscriptionPriceService (common/.../subscription/price/) owns all of it. The design follows
Badger Sett's plan prices.
Stripe is the record of prices. Badger keeps no copy. A SKU is linked to its price by the
stripe-subscription-price-key attribute, which only the service writes: the admin edit forms
don't show it and carry it over unchanged when they save. Prices Badger makes carry metadata:
badger_site, badger_product_sku, badger_variant_sku, and badger_supersedes (the price this
one replaced). Every call uses the site's own Stripe account (its Connect account, or legacy
keys) in its current test or live mode, through StripePaymentService.constructRequestOptions.
Creating a price makes one Stripe product per Badger product the first time it's needed. Badger
chooses that product's id (bdgr_<siteId>_<productSku>), so it is found again rather than
duplicated, on any account and in either mode. The price is in the shop's currency
(siteCurrencyCode), and the SKU's own selling price is set to the amount. The two must match:
the first payment is the checkout order, taken at the selling price, and renewals are taken at the
Stripe price. For a "give any amount" product the selling price is the per-unit price (usually £1)
and Stripe bills it times the quantity. A price can be monthly, every 3 or 6 months, or yearly
(the MCP tool also accepts weekly). Create and change pass an idempotency key to Stripe, so a
resubmitted form doesn't make a second price.
Changing a price can't edit it, because Stripe prices are immutable. Badger makes a new price at
the new amount with the same currency and interval, points every SKU that used the old price at
it, sets their selling price, and archives the old price. Archiving only stops new subscriptions:
Stripe keeps renewing existing ones at an archived price. The old price id is kept on the SKU
(stripe-subscription-previous-price-keys), so subscriptions still on it resolve to the right SKU,
and so to its product and Gift Aid.
Existing subscribers stay on what they pay, unless the admin says otherwise. This is the
default, as in Badger Sett: someone agreed to £10 a month and keeps paying £10. Only new
subscribers pay the new amount. The alternative is move at next renewal: each subscription
still billing (active, trialing, past due, unpaid or paused) has its item switched to the new
price with no proration. The payment already taken covers the current period, and the next
renewal is at the new amount. Badger doesn't email anyone about it and Stripe doesn't either, so
the admin is told to tell subscribers first. In the admin, moving needs the word move typed,
and the server re-checks it. A subscription that can't be moved stays on the old price and is
counted in the result. Moves happen during the request, which is fine for a shop's supporter
base but not for tens of thousands of subscriptions.
Linking an existing price to a SKU is how a price made in the Stripe dashboard is imported. It must be active, recurring, have a fixed amount and be in the shop's currency. Badger tags it with its metadata so it manages it from then on. A price tagged for another Badger shop is refused.
Archiving is refused while a SKU uses the price. In the admin it needs archive typed.
Sync ("Check with Stripe") compares every subscription SKU with Stripe and reports:
| Issue | Meaning | Sync fixes it? |
|---|---|---|
| No price | A subscription SKU has no price, so it can't be bought as a subscription | No: set one |
| Missing | The linked price isn't on this account in this mode, e.g. a test-mode price after going live | Yes: recreated at the SKU's selling price and the recorded interval |
| Archived | The linked price is archived, so new subscriptions to it fail | Yes: recreated at the same amount and interval |
| Not recurring | The linked price is one-off or has no fixed amount | No |
| Currency mismatch | The linked price isn't in the shop's currency | No |
| Amount mismatch | The selling price differs from what Stripe renews at | No: change the price or the selling price |
| Made outside Badger | The linked price has no Badger metadata | Yes: tagged |
| Unused | An active price Badger made for this shop that no SKU uses | No: archive it if unwanted |
It also lists active prices made outside Badger that no SKU uses, so they can be linked. Going live is the main case for sync: the test-mode prices don't exist in live mode, and one sync recreates them all.
Regular giving with Gift Aid needs nothing extra. A monthly-giving product has both
subscriptionProduct and donationProduct (see above), and prices are made for its variants in
the same way. Changing a price leaves each subscription's Gift Aid flag alone, and moved
subscriptions keep theirs.
Failed Payments & Dunning¶
When a recurring payment fails, Stripe owns the retry schedule and the eventual cancel decision (via its Smart Retries / dunning settings on the connected account). Badger's role is to send a branded chaser email to the customer with a link to update their payment method — one email per real Stripe attempt.
How it works¶
- The
invoice.payment_failedwebhook drives everything. On each failed attempt Badger sends exactly one chaser, so the cadence matches Stripe's actual retry schedule rather than a fixed local timer. - Copy follows Stripe's timeline: if the invoice has a
next_payment_attempt, the email says "we'll automatically try again on {date}"; if there's no further attempt, it's the final notice (the subscription will lapse unless the card is updated). - De-duplication: chasers are keyed off Stripe's
attempt_count, so a re-delivered webhook never sends a second email for the same attempt. - Recovery:
invoice.payment_succeededsettles that invoice's dunning state toRECOVERED— no cross-invoice side effects. That includes an invoice alreadyGIVEN_UPthat the customer pays afterwards (for example through the update-payment link). - Reconciliation sweep: a daily job re-checks only invoices currently
IN_DUNNINGagainst Stripe (the source of truth) as a safety net for missed webhooks. It re-drives a chaser if Stripe attempted again (a no-op otherwise thanks to the dedup), settles paid/voided invoices toRECOVEREDand invoices Stripe has marked uncollectible toGIVEN_UP. A failure on one invoice is isolated and never aborts the run. - Cancelled subscriptions: no chaser is sent for a cancelled subscription; its in-dunning invoice is settled to
GIVEN_UP. Stripe stops collecting a subscription's open invoices when it is cancelled.
Dunning state lives on the Invoice (see the Invoice data model below), giving a per-invoice lifecycle: NONE → IN_DUNNING → RECOVERED (or GIVEN_UP when Stripe stops retrying).
Delivery and addressing¶
-
Queued send: the chaser is published as an
EmailJobonto the email-jobs queue rather than sent inline from the webhook handler, so the webhook acknowledges quickly and the send happens out of band. The worker rebuilds the email model at send time viaEmailJobModelReconstructor(EmailModelSpec.Kind.SUBSCRIPTION, carrying the subscription and invoice ids). Invoice dunning state is persisted before the job is published, so the worker readsnextAttemptAtback off the invoice.Retry and parking
A failed send is retried a few times by the email-jobs listener and, if it still fails, parked on
email-jobs-dead-queuerather than dropped — see Transactional Email. Nothing consumes that queue yet, so a parked chaser means a customer was not chased and nobody is told automatically.- Tenant resolution: every subscription webhook handler (
customer.subscription.created/updated/deleted, andinvoice.created/payment_succeeded/payment_failed) resolves the owning site throughSubscriptionInvoiceSiteResolver. It prefers the Stripemetadata.siteId, is scoped to the connected account, and refuses to guess when the result is ambiguous rather than falling back to the first site. This matters on multi-tenant accounts, where a wrong guess would send a chaser branded as the wrong shop. Until October 2026 the subscription andinvoice.createdhandlers still guessed. On DMRT, whose Stripe account also backs teamshop, renewals of subscriptions made before Badger stampedsiteIdwere recorded as new teamshop subscriptions. Those older subscriptions now resolve only once a site already holds them locally, so stampsiteIdonto them in Stripe. - Secure update link: the "update your payment method" link carries a short-lived signed token (
SubscriptionUpdateLinkTokenService— per-site HMAC, 14-day TTL, signing key auto-provisioned in configuration) which authorises the request and identifies the order and subscription. Links minted before this change passed the order'sconfirmationCodeinstead;SecureSubscriptionPaymentControllerstill honours those as a legacy fallback. Once authorised the customer is redirected into a Stripe Billing Portal session, so card capture stays PCI-safe with Stripe.
- Tenant resolution: every subscription webhook handler (
Operator setup¶
Because Badger is the customer-facing voice on failed payments, disable Stripe's own failed-payment customer emails on each connected account (Stripe → Settings → Subscriptions and emails) to avoid duplicate messaging.
Configuration keys (category subscription-dunning):
| Key | Purpose |
|---|---|
subscriptionDunningEnabled |
Master on/off for chaser emails (per site) |
subscriptionDunningFromAddress / subscriptionDunningFromName |
From address / display name. Blank address = the shop's own sender (orderConfirmationFromAddress); blank name = the site name |
subscriptionDunningSubjectPattern |
Email subject ({0} = site name) |
subscriptionDunningEmailTemplate |
Template name (default subscriptionPaymentFailed) |
Global keys (System → Global Configuration):
| Key | Purpose |
|---|---|
subscription-dunning-slack-channel |
Slack channel notified each time a chaser goes out for a live-mode invoice (default #badger-prod; blank disables) |
subscription-dunning-slack-test-channel |
Same, for Stripe test-mode invoices (default #badger-stripe-test; blank disables) |
The Slack notice names the site, the order (by id, never the customer's name or email), amount due, Stripe attempt number and next retry date, and flags the final chaser. It's posted when the chaser is queued, so a send that later fails and is parked on email-jobs-dead-queue still shows up in Slack as sent. The Slack post is best-effort, so if it fails the chaser still goes out.
The email template is subscriptionPaymentFailed (with a -text plain-text variant) under commerce-core/.../templates/shop/email/.
Billing Schedule¶
By default a subscription's recurring charge is anchored to the moment the subscriber signed up —
join on the 20th and you are billed on the 20th thereafter. The first payment is taken at checkout
and the subscription is created with a trial end one interval later, so no proration is involved.
The worker (SubscriptionProcessingEventListener) saves the local subscription record as soon as
Stripe has created it, carrying the checkout card as its default payment method, and links any of
its invoices that were saved first (InvoiceService.linkUnlinkedInvoices). It doesn't wait for the
customer.subscription.created webhook, which a connected account's endpoint may not send; when
the webhook does arrive it updates the same record.
Setting subscriptionBillingDayOfMonth (1-28) moves every new monthly subscription onto a common
billing day instead, which is what you want when subscribers need to be settled together — for
example a monthly draw or dispatch that requires everyone's payment to have cleared first.
- 0 (default) keeps the existing behaviour, so enabling it is a per-site decision.
- Only monthly prices are affected. A day-of-month anchor is meaningless for weekly prices and would arbitrarily shift a yearly one.
- Days are capped at 28, since later days do not exist in every month.
- New subscribers get a slightly longer first period rather than being charged twice within days of joining: the first charge is the first occurrence of the billing day on or after the signup-anchored date. Their checkout payment already covers that period, so there is nothing to prorate or refund.
- Existing subscriptions are not rescheduled. The setting applies as subscriptions are created.
The date arithmetic lives in SubscriptionBillingDateCalculator.
Lifecycle Notifications¶
Cancellation, a subscription being set to end, and quantity changes notify people automatically. They are detected centrally, so they fire however the change was made: customer self-service, an admin edit, MCP, or the Stripe dashboard and billing portal.
Who the subscriber's emails go to. Every email to a subscriber (these, the failed-payment
chaser and the refused-card email) goes to the customer's current address, not the one typed on
the sign-up order, so correcting a mistyped address on the customer's Contact details card (or the
customer changing it in their account) reaches every later email. In order: the customer's contact
email, their sign-in email, then the sign-up order's email (a guest subscription with no customer
record). SubscriptionRecipients decides this.
Cancellation¶
When a subscription's status transitions to canceled, SubscriptionCancelledEvent is published and
SubscriptionCancellationEmailListener sends:
- a cancellation confirmation to the subscriber, with a resubscribe link or contact address;
- a reverse-fulfilment notification to the product's fulfiller, telling them to stop fulfilling.
Because the trigger is the status transition rather than the cancellation request, a subscription
set to cancel at period end sends this email at the period boundary, when fulfilment should actually
stop, and its date line reads "Ended on" that day (Stripe's canceledAt is when the cancellation was
asked for). Cancellations Stripe makes itself after exhausted payment retries notify the same way.
Set to end, and carrying on again¶
A subscription cancelled at the end of its period stays live until then, so the subscriber is told
straight away as well. When cancelAtPeriodEnd changes on a live subscription,
SubscriptionEndingChangedEvent is published and SubscriptionEndingEmailListener emails the
subscriber (only the subscriber: the fulfiller carries on until it ends):
- Your subscription will end (
subscriptionEnding) when it is set to end, with the end date, the reassurance that they won't be charged again, and a link to the subscription in their account where they can keep it; - Your subscription will continue (
subscriptionContinuing) when that is undone, with the next payment date.
A subscription cancelled at period end therefore gets two emails: "will end" when it's cancelled and "has been cancelled" when it ends.
The cancel and resume actions record the change locally before Stripe's webhook arrives, and the
webhook records it too. Both go through SubscriptionRepository.setCancelAtPeriodEndIfChanged, one
atomic update that reports whether it changed the stored value, and only the one that changed it
publishes, so each change is emailed once whichever lands first. Nothing is sent once the subscription
has ended (Stripe may clear the flag as it does), and an immediate cancellation never sets the flag.
Quantity change¶
When the quantity on a subscription changes, SubscriptionQuantityChangedEvent is published and
SubscriptionQuantityChangedEmailListener sends:
- a confirmation to the subscriber recording the old and new quantity, so an unintended change is
visible to them (suppressible per-site via
subscriptionQuantityChangeCustomerEnabled); - a fulfilment notification to the product's fulfiller with the new quantity to send from the next delivery onwards.
Without this a subscriber dropping from three units to one would keep receiving three — nothing else in the pipeline announces the change.
Only a genuine change publishes. Stripe emits customer.subscription.updated on renewals, payment
method updates and metadata edits too, and those leave the quantity alone.
Fulfiller routing¶
Both listeners route to the fulfiller the same way: Product.fulfilmentMethod names a site config
key whose value is the fulfiller's email address — the convention used by EmailFulfilmentProcessor.
If the product has no fulfilment method, or the key has no address configured, the fulfiller email is
skipped and the customer email still goes out.
Subscription info¶
The Subscription Info extension (subscriptionInfoExtension, product only, bannerSection by
default) shows live figures for a subscription product: memberships, limited places, or a lottery
sold as numbers (a "200 Club", where each unit of quantity is one number).
- How many are taken: the summed quantity of the product's paid-up subscriptions (
activeandtrialing; checkout takes the first payment and uses a trial to anchor billing). Past due, unpaid, paused and cancelled subscriptions don't count, so leavers and failed payments drop out on their own. With How many there are set (e.g. 200) it reads "137 of 200" with a bar. - Recurring total (off by default, so a member count never publishes the takings; meant for a lottery's prize fund): taken × the product price × Share of the total shown (%) (default 100; 50 for a prize fund that is half the takings). It uses the product's current price, so it is only right for a single-price product, not one with price tiers as variants.
- Breakdown: optional parts of the total as
label:percent, e.g.1st prize:50, 2nd prize:30, 3rd prize:20, each with its current value rounded down to the penny.
The headings (Count heading, Total heading, Breakdown heading) are the shop's own words, e.g. Numbers / This month's prize fund / Prizes this month; left blank they fall back to generic defaults. The figures are worked out as the page renders (cached for five minutes per product), so nobody updates them by hand.
Multi-Tenancy¶
The subscription system is fully multi-tenant:
Per-Site Isolation¶
- Each site has its own Stripe account (via Stripe Connect)
- Subscriptions are scoped to
siteId - Invoices are scoped to
siteId - Sync runs independently per site
Sync Process¶
- Manual Trigger: Admin users can trigger sync from
/admin/subscriptionsor/admin/shopSettings/payment - Per-Site API Calls: Uses each site's Stripe credentials via
constructRequestOptions(siteContext) - Incremental Sync: Tracks last sync timestamp per site in configuration
- Tenant Isolation: All created records tagged with correct
siteId - Duplicate Protection: Concurrent sync requests for the same site are blocked
Owner Resolution¶
When syncing subscriptions, the system resolves the Badger user (owner) via:
1. Subscription Metadata: Check for userId or orderId in Stripe metadata
2. Order Lookup: If orderId found, lookup order to get owner
3. Customer Charges: Query Stripe for customer's charges, extract order metadata from charge metadata
Technical Implementation¶
Data Models¶
Subscription (common/.../subscription/Subscription.java)
- siteId: Tenant identifier
- provider: Payment provider (STRIPE)
- externalId: Stripe subscription ID (sub_xxx)
- externalCustomerId: Stripe customer ID (cus_xxx)
- owner: Badger user ID
- orderId/orderNumber: Original order reference
- productSkuId: Badger parent product SKU ID
- skuId: Badger variant SKU ID (for linking back to product catalogue)
- status: Subscription state
- amountInPence, currency, interval, intervalCount: Billing details. amountInPence is the per-unit price; getTotalAmountInPence() (unit × quantity) is what is charged per period
- currentPeriodStart, currentPeriodEnd, trialEnd: Dates
- giftAidEligible: For charitable donations
- created: Uses Stripe's created timestamp (not local creation time)
Invoice (common/.../subscription/Invoice.java)
- siteId: Tenant identifier
- subscriptionId: Link to local Subscription record
- externalId: Stripe invoice ID (in_xxx)
- status: draft, open, paid, void, uncollectible
- total, amountPaid, amountDue: Amounts in pence
- paidAt: when Stripe took the payment (status_transitions.paid_at), not when the webhook was processed. The renewal's Gift Aid donation is dated from it, so a delayed or replayed event can't move it into another tax period
- lineItems: Embedded line item details
- giftAidEligible, donationId: Gift Aid tracking
- dunningState: NONE, IN_DUNNING, RECOVERED, or GIVEN_UP (see Failed Payments & Dunning)
- lastDunnedAttemptCount, lastDunnedAt, nextAttemptAt, dunningEmailsSent: chaser tracking, driven by Stripe's attempt_count / next_payment_attempt
Services¶
SubscriptionService (common/.../subscription/SubscriptionService.java)
- CRUD operations for subscriptions
- createFromStripeSubscription(): Create from Stripe webhook/sync
- resolveOwnerFromStripeCustomer(): Multi-step owner resolution
- calculateMRR(): Monthly recurring revenue calculation
InvoiceService (common/.../subscription/InvoiceService.java)
- CRUD operations for invoices
- createFromStripeInvoice(): Create from Stripe webhook/sync
- createDonationIfEligible(): Gift Aid donation creation
SubscriptionSyncService (commerce-core/.../subscription/SubscriptionSyncService.java)
- syncSite(): Sync single site's subscriptions and invoices
- syncAllSites(): Iterate all sites and sync each
Stripe Integration¶
Metadata on Subscription Creation
When creating a Stripe subscription, the following metadata is attached:
- orderId: Badger order ID
- orderNumber: Human-readable order number
- userId: Badger user ID
- siteId: Site identifier
- productSkuId: Parent product SKU ID
- skuId: Variant SKU ID (or parent SKU if no variant)
This enables owner and product resolution during sync for subscriptions created through the platform.
Product Resolution¶
When syncing subscriptions, the system resolves the Badger product via:
1. Metadata: Check for skuId and productSkuId in Stripe subscription metadata
2. Price Key Lookup: If metadata is missing, search for products with stripe-subscription-price-key attribute matching the subscription's priceId, then for one whose stripe-subscription-previous-price-keys lists it (a subscriber who stayed on a price that has since been changed)
The stripe-subscription-price-key attribute is on either:
- Non-variant products: the product itself. Adding the product to the basket copies it onto the line item, the same as a variant's attributes.
- Variant products: the specific variant
Set it through Subscription prices, not by hand. The examples below show what is stored.
Example (variant product):
{
"skuId": "subscription",
"productName": "Monthly Subscription",
"variants": [
{
"skuId": "subscription-10",
"attributes": {
"stripe-subscription-price-key": "price_1JvWB9CujlwdofGIIzJJDSqO"
}
}
]
}
Example (non-variant product):
{
"skuId": "single-subscription",
"productName": "Standard Subscription",
"attributes": {
"stripe-subscription-price-key": "price_1XyZ123AbCdEfGhIjKlMnOpQ"
}
}
Admin Interface¶
Subscription List (/admin/subscriptions)¶
- Filterable by status (All, Active, Trialing, Past Due, Canceled)
- Filterable by subscription product; the product list comes from the catalogue, so a product with no subscribers yet still appears (with a count of zero). Status and product filters combine.
- Shows: Status, Product, Amount, Interval, Customer link, Created, Period End
- Pagination support
- Click-through to subscription detail
Subscription Detail (/admin/subscriptions/view/{id})¶
- Customer Section: Name, email, phone with link to user profile
- Subscription Details: Product, amount, interval, quantity, Gift Aid status
- Billing Period: Current period dates, trial end, created date
- Payment & Reference: Payment method, original order link, Stripe IDs
- Invoices Table: All invoices, newest first, with status, amounts, PDF links
Subscription prices (/admin/catalogue/subscriptions)¶
- List: every recurring price in the Stripe account, with the options using it, live subscribers, and whether it was replaced or made outside Badger; above it, any subscription option with no price, with a Set a price button
- Price page: the options using it, Change price (new amount, and whether existing subscribers stay or move), link it to another option, remove it from one, archive it
- Check with Stripe (
/sync): the drift report above, with Fix automatically for the fixable rows and a Link picker for prices made outside Badger - Product and variant pages: a Subscription prices card above the tabs, one row per option, showing what it renews at, with Change price or Set a price inline. It opens by itself when something needs attention.
Customer Account (/account/subscription?id={id})¶
Customers see their subscription details and a Payment History of its invoices, newest first, ending with the checkout payment that covered the first period (the £0 invoice Stripe raises when the subscription starts is left out). Stripe reports a subscription bought at checkout as trialing until its first renewal, because the checkout already paid for that period; the account pages show it as Active (Subscription.displayStatus()), with its next payment date. The card shown is the subscription's default payment method, or the checkout payment's card, which is what renewals are charged to. The amount shown everywhere (account, admin, MCP, emails) is what the subscriber pays per billing period: the per-unit price times the quantity.
Changing the amount is offered only on an active or trialing subscription to a "give any amount" SKU (Product.isOpenAmount(); a variant's own quantityType wins). The subscriber enters it in pounds (e.g. 3 or 3.50, minimum 1). Fixed-price subscriptions (boxes, tiers, memberships) can't be repriced by the subscriber, and the server refuses it whatever is posted. Such a subscription is billed as the SKU's per-unit price (usually £1) times a quantity, so SubscriptionService.updateSubscriptionAmount sets the quantity: £3 at £1 a unit is quantity 3. The amount must be a whole number of units, otherwise the shopper is asked for a multiple of the unit price. If the subscription was on another price (an ad-hoc price made by the old amount change), it is moved back onto the SKU's current subscription price at the same time. There is no proration: the new amount applies from the next billing date. The subscriber gets the quantity-change confirmation, worded as amounts ("£10.00 → £3.00"), not units.
There is no plan switching: subscribers who want a different product or tier cancel and subscribe again.
Cancelling. A live subscription is cancelled at the end of its period, and the subscriber can undo that until then. A subscription in arrears (past_due, unpaid or incomplete: Subscription.isInArrears()) is cancelled now instead, whoever cancels it (subscriber, admin or MCP), so Stripe stops retrying the failed renewal and the customer isn't charged for it again. Subscribers in arrears see Update payment method and Cancel now on their subscription page, with a note that the last payment didn't go through; before, they saw no actions at all. In the admin, the cancel action on such a subscription reads Cancel now.
User Profile Integration¶
- User profile page shows subscriptions section
- Active subscription count and monthly value widgets
- Table of all user's subscriptions with view links
Integration Points¶
The subscription system integrates with: - Order System: Links subscriptions to original orders - User System: Links subscriptions to user profiles - Gift Aid/Donations: Creates donation records for eligible invoices - Stripe Webhooks: Receives subscription and invoice events - Admin Dashboard: MRR statistics and reporting
Key Classes¶
| Class | Location | Purpose |
|---|---|---|
Subscription |
common | Subscription entity |
Invoice |
common | Invoice entity |
SubscriptionService |
common | Business logic |
InvoiceService |
common | Invoice business logic |
SubscriptionSyncService |
commerce-core | Sync orchestration |
SubscriptionCancellationEmailListener |
commerce-core | Cancellation emails (customer + fulfiller) |
SubscriptionQuantityChangedEmailListener |
commerce-core | Quantity change emails (customer + fulfiller) |
SubscriptionEndingEmailListener |
commerce-core | "Will end" and "will continue" emails (customer) |
SavedCardRestrictionService |
commerce-core | Puts back or removes a saved card the subscription's product refuses (Ways of paying a product refuses) |
CustomerUpdatedHandler |
worker | customer.updated webhook: checks a changed default card |
SubscriptionAdminController |
web-admin | Admin UI controller |
SubscriptionInfoExtension |
commerce-core | Live count of paid-up units, recurring total and its breakdown on a product page |
StripePaymentService |
common | Stripe API operations |
SubscriptionPriceService |
common | Stripe recurring prices: create, change, link, archive, sync |
StripePriceGateway |
common | The Stripe calls behind SubscriptionPriceService |
SubscriptionPriceAdminController |
web-admin | Subscription prices screens |
SubscriptionPricePanels |
web-admin | The product page's Subscription prices card |
SubscriptionPriceTools |
ai | subscriptionPrices / manageSubscriptionPrices MCP tools |
SubscriptionUpdateLinkTokenService |
common | Signs/verifies the dunning update-payment link token |
SubscriptionInvoiceSiteResolver |
worker | Resolves the owning site for a subscription or invoice webhook |
SecureSubscriptionPaymentController |
web-mvc | Account-free card update entry point from the chaser email |
Configuration¶
Lifecycle notification emails are configured per-site under the subscription-emails category —
from address, from name, subject, template and BCC for each of the four emails, plus
subscriptionQuantityChangeCustomerEnabled to suppress the customer-facing quantity change
confirmation. The "will end" and "will continue" emails have their own subject and template
(subscriptionEndingCustomer*, subscriptionContinuingCustomer*) and use the cancellation customer
email's from address, from name and BCC, as does the card refused email
(subscriptionCardRefusedCustomer*, see Ways of paying a product refuses). Every subscription email, including the failed-payment chaser, is sent from the shop's own
address (orderConfirmationFromAddress, the sender set in Email branding) unless its own from
address is set; none of them sends from a Badger address.
Sync timestamp stored per-site in configuration:
- Key: subscriptionSync.lastRunTimestamp
- Category: sync
- Not editable/visible in admin UI