Broadleaf Microservices
  • v1.0.0-latest-prod

Change Auto-Renewal Intention

Changing the auto-renewal status of a subscription allows a customer or an administrator to toggle whether their subscription will automatically renew at the end of its current term. Depending on the subscription’s setup, this could be the end of the month or the end of a multi-year contract.

Definitions

  • Auto Renewal

    • If a subscription has terms (i.e. it has a contract), then Auto Renewal refers to the renewal of terms (e.g., the renewal of a 1-year contract).

      • When Auto Renewal is turned off, the subscription is scheduled to cancel on the end-of-terms date.

      • When Auto Renewal is turned on, the scheduled cancellation is removed.

    • If a subscription does not have terms, then Auto Renewal refers to renewing access for each period.

      • When Auto Renewal is turned off, the subscription is scheduled to cancel at the end of the current period.

      • When Auto Renewal is turned on, the scheduled cancellation is removed.

Auto Renewal Domain

Product Domain

Key Term Fields:

  • Product#terms - Represents the available terms for the Product.

    • ProductTerm#durationType (YEARS, MONTHS, etc.) and ProductTerm#durationLength define the length of the terms.

      • If terms are present for the customer’s selections on the product, these values are stored at CartItem#termDurationType and CartItem#termDurationLength.

Key Auto Renewal Fields:

  • Product#autoRenewalEnabled - Serves as the default value for all term options.

  • Product#allowAutoRenewalModification - Serves as the default value for all term options.

  • ProductTerm#endOfTermStrategy (CANCEL vs AUTO_RENEW) - For each term, provides the ability to override the default intention to auto renew or not.

  • ProductTerm#allowAutoRenewalModification - For each term, provides the ability to override the default ability to modify auto-renewal.

autoRenewalEnabled & allowAutoRenewalModification Resolution & Cart Storage

DefaultCartItemCatalogInformationService#isAutoRenewalEnabled and DefaultCartItemCatalogInformationService#allowAutoRenewalModification are responsible for enforcing whether the product defaults or overrides from the selected terms are used. Note: of course, terms are not required, so those overrides may not play a role.

If a value cannot be resolved from either the product or selected terms, then the following system properties are consulted to find a default value:

  • broadleaf.cartoperation.service.subscription-item-defaults.auto-renewal-enabled (defaults to true)

  • broadleaf.cartoperation.service.subscription-item-defaults.allow-auto-renewal-modification (defaults to true)

Once resolved, these values are stored in the CartItem#internalAttributes using the "autoRenewalEnabled" and "allowAutoRenewalModification" keys.

Subscription Domain

Key Term Fields:

  • Subscription#termDurationType

  • Subscription#termDurationLength

  • Subscription#startOfTermDate

    • Note: this is typically the creation date, but can be delayed by the presence of a free trial.

  • Subscription#endOfTermDate

Key Auto Renewal Fields:

  • Subscription#autoRenewalEnabled

  • Subscription#allowAutoRenewalModification

  • Subscription#subscriptionNextStatus - If auto-renewal is turned off, then this will represent a scheduled cancellation.

  • Subscription#nextStatusChangeDate - If auto-renewal is turned off, then this reflects the end-of-term (if terms are present) or end-of-period (if terms are not present) date.

  • Subscription#nextStatusChangeReason

ModifySubscriptionHandler Implementation

The ChangeSubscriptionAutoRenewalHandler is responsible for handling the CHANGE_AUTO_RENEWAL action type.

When a user initiates an auto-renewal change:

  • Validation:

    • Verifies that the requested CHANGE_AUTO_RENEWAL action is present in the subscription’s availableActions list.

    • Ensures that the subscription product’s allowAutoRenewalModification setting is true and the subscription itself is in a valid state.

  • Direct Modification: Unlike other subscription modification actions (such as Edit, Upgrade, or Downgrade) which generate a cart to facilitate a complex modification, changing auto-renewal is a simple toggle. The ChangeSubscriptionAutoRenewalHandler updates the autoRenewalEnabled property directly on the subscription record.

  • Triggering Workflow: After the direct modification, the handler uses the StartChangeAutoRenewalWorkflowService to initiate a CHANGE_AUTO_RENEWAL workflow. This workflow typically handles notifying third-party systems about the changed intent to auto-renew.

UI Interaction & Flow

Surfacing the Action

In the My Subscriptions UI, a list of available actions is provided on the SubscriptionWithItems object. The UI can check if the CHANGE_AUTO_RENEWAL action is present in the availableActions list:

const isChangeAutoRenewalAllowed = !!subscriptionWithItems.availableActions
  .find(action => action.actionType === DefaultSubscriptionActionType.CHANGE_AUTO_RENEWAL)

Initiating the Action

If the action is permitted, the Broadleaf demo UI renders a button to toggle the status. Because this action does not require a checkout process, the action simply modifies the state directly and stays on the My Subscriptions page.

When the button is clicked, it calls modifySubscription using the CustomerClient or AccountClient, passing the CHANGE_AUTO_RENEWAL action type and the desired boolean value for autoRenewalEnabled.

const request = {
  subscriptionId: id,
  action: {
    actionType: DefaultSubscriptionActionType.CHANGE_AUTO_RENEWAL
  },
  autoRenewalEnabled
}
await customerClient.modifyCustomerSubscription(request, customerId, options);

Fulfillment Workflow Execution

Because the auto-renewal change does not involve a cart checkout, the workflow is triggered programmatically by the ChangeSubscriptionAutoRenewalHandler using the StartChangeAutoRenewalWorkflowService.

Sample Configuration for a Change Auto-Renewal Workflow:

broadleaf:
  workflow:
    client:
      flows:
        fulfillmentTypeAChangeAutoRenewalWorkflow:
          description: Change Auto Renewal Workflow for Type-A Subscriptions
          historical-reset-enabled: true
          retry-enabled: true
      steps:
        fulfillmentTypeAChangeAutoRenewalWorkflow:
          myCustomChangeAutoRenewalActivityForFulfillmentTypeA:
            admin-selectable: true

This workflow typically handles notifying third-party systems about the changed intent to auto-renew.

Initial Workflow Context Parameters

  • Subscription.id

  • Application.id

  • Tenant.id

  • subscriptionActionFlow (CHANGE_AUTO_RENEWAL)

  • OrderFulfillment.fulfillmentWorkflow

  • autoRenewalEnabled

Workflow Activity Descriptions

  1. myCustomChangeAutoRenewalActivityForFulfillmentTypeA - An example of a custom workflow activity that might be executed for a specific fulfillment type to notify external services of the toggle in auto-renewal standing.

Additional Way of Turning Auto-Renewal Off

From customer requests, auto-renewal can be turned off via requesting cancellation, when the subscription’s CancellationPolicy is configured with a CANCEL_AUTO_RENEWAL cancellation strategy (see Subscription Cancellation).

In this case, the same *ChangeAutoRenewalWorkflow is triggered to support any additional communication to 3rd party vendors or to the customer.