Skip to content

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 subscriptionProduct and donationProduct, plus the donationFormExtension for 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.createDonationForInvoice creates 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. With subscriptionProduct alone 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's quantityType to FIXED so the storefront shows each tier's price rather than "Give any amount".
  • Plan: Gift Aid on recurring donations needs the regularGiving capability (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_failed webhook 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_succeeded settles that invoice's dunning state to RECOVERED — no cross-invoice side effects. That includes an invoice already GIVEN_UP that the customer pays afterwards (for example through the update-payment link).
  • Reconciliation sweep: a daily job re-checks only invoices currently IN_DUNNING against 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 to RECOVERED and invoices Stripe has marked uncollectible to GIVEN_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 EmailJob onto 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 via EmailJobModelReconstructor (EmailModelSpec.Kind.SUBSCRIPTION, carrying the subscription and invoice ids). Invoice dunning state is persisted before the job is published, so the worker reads nextAttemptAt back 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-queue rather 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, and invoice.created/payment_succeeded/payment_failed) resolves the owning site through SubscriptionInvoiceSiteResolver. It prefers the Stripe metadata.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 and invoice.created handlers still guessed. On DMRT, whose Stripe account also backs teamshop, renewals of subscriptions made before Badger stamped siteId were recorded as new teamshop subscriptions. Those older subscriptions now resolve only once a site already holds them locally, so stamp siteId onto 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's confirmationCode instead; SecureSubscriptionPaymentController still 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.

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 (active and trialing; 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

  1. Manual Trigger: Admin users can trigger sync from /admin/subscriptions or /admin/shopSettings/payment
  2. Per-Site API Calls: Uses each site's Stripe credentials via constructRequestOptions(siteContext)
  3. Incremental Sync: Tracks last sync timestamp per site in configuration
  4. Tenant Isolation: All created records tagged with correct siteId
  5. 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