The Broadleaf Subscription ecosystem provides a robust, enterprise-grade foundation for recurring revenue models, complex billing lifecycles, and subscription management. Designed to integrate seamlessly with the existing Commerce, Order, and Catalog domains, these components allow businesses to model recurring goods and services, orchestrate payment lifecycles, and handle sophisticated modification workflows like subscription edits, upgrades, downgrades, and cancellations.
This document serves as an entry point into the various concepts and capabilities that make up the Subscription framework. For detailed guides on specific flows, please see the following sections:
Product & Pricing Setup: Learn how to configure subscription products, add-ons (item choices), and term-based pricing.
Purchase & Fulfillment: Understand the add-to-cart process, checkout validations, and the fulfillment workflow that creates new subscriptions.
Subscription Management: Explore how customers can modify their subscriptions (edit, upgrade, downgrade, cancel, and auto-renewal changes), including details on sandboxing, locking, and delayed prepaid actions.
Recurring Billing: Dive into the BillingService, which is responsible for billing subscriptions beyond the initial sign-up.
CSR Interactions: See how Customer Service Representatives can manage subscriptions by applying discounts or updating prices for existing subscriptions.
Subscription functionality is deeply woven into the Broadleaf microservices architecture. Here is a breakdown of the role each service plays in the subscription lifecycle:
Catalog Service: Acts as the system of record for defining subscription products, acceptable terms, and allowed add-ons (ItemChoice options). It enables the MERCHANDISING_PRODUCT type used for subscription bundles. See Catalog Services.
Pricing Service: Manages recurring pricing via PriceData records. It evaluates the terms, frequencies, and payment strategies (Prepaid vs Postpaid) to return the correct price for a given subscription configuration. See Pricing Services.
Promotion (Offer) Service: Enables discounts specifically targeted at subscriptions, including first-time subscriber logic, recurring discounts, and maintaining free trials through subscription modifications. See Offer Services.
Cart Operation Service: Orchestrates the checkout process for purchasing new subscriptions and modifying existing ones. It validates cart items, enforces subscription-specific checkout rules (like requiring authentication and saved payment methods), and maps subscription pricing details into the cart. See Cart Operation Services.
Order Operation Service: Listens for successful checkouts and triggers the appropriate fulfillment workflows. It is responsible for initiating the creation of pending subscription records and splitting fulfillments for subscription products. See Order Operation Services.
Subscription Operation Service: The central orchestration engine for the subscription lifecycle. It manages complex state transitions, sandboxed modifications (edits, upgrades, downgrades, cancellations), locking mechanisms, and the calculation of prorated prices and estimated future payments. See Subscription Operation Services.
Billing Service: The heart of recurring billing. It decouples billing events from orders, orchestrating recurring billing cycles, generating BillingEvent s, and managing the recurring payment capture and refund lifecycles. See Billing Services.
Workflow Service: Powers the orchestration of business logic sequences. Incorporating the broadleaf-subscription-operation-services-workflow and broadleaf-order-operation-services-workflow dependencies, it drives the multi-step processes required to fulfill subscription creations, modifications, and cancellations safely. See Workflow Services.
Audit Service: Provides a high-performance trail of mutations, tracking lifecycle changes, edits, and price modifications for customer service and compliance purposes. See Audit Services.
|
Important
|
The Subscription Operation Service, Billing Service, and related workflow extensions are optional modules and are not available for general use with the standard license. An extended commercial license is required to obtain, deploy, and utilize this functionality. Please contact your Broadleaf representative to discuss licensing details and access rights. |
To enable the Subscription and Billing capabilities, several dependency additions and property changes are required across your existing microservices.
You must include the subscription and order workflow dependencies in your deployment manifest. Add the following dependencies to the data and workflow modules:
<dependency>
<groupId>com.broadleafcommerce.microservices</groupId>
<artifactId>broadleaf-order-operation-services-workflow</artifactId>
</dependency>
<dependency>
<groupId>com.broadleafcommerce.microservices</groupId>
<artifactId>broadleaf-subscription-operation-services-workflow</artifactId>
</dependency>The subscription-related services and metadata are disabled by default. You must explicitly enable them using the following properties across your microservices:
| Property | Value | Required Services |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
The subscription ecosystem offers several properties to fine-tune its behavior. While the enablement properties above are required, the following properties provide additional configuration options (shown with their default values):
broadleaf.subscriptionoperation.service.active-subscription-statuses ([ACTIVE, PENDING_CANCELLATION, PAUSED, PENDING_FULFILLMENT, FULFILLMENT_IN_PROCESS]): Defines which statuses represent an active subscription.
broadleaf.subscriptionoperation.service.allowed-actions-by-subscription-status: A map defining which subscription modification actions (e.g., EDIT, CANCEL) are allowed based on the subscription’s current status.
broadleaf.subscriptionoperation.cancellation.discount-allowed-for-cancellation-charge (false): Whether a discount amount can be applied to the cancellation charge.
broadleaf.subscriptionoperation.cancellation.tax-allowed-for-cancellation-charge (false): Whether tax should be calculated on the cancellation charge.
broadleaf.subscriptionoperation.cancellation.start-change-auto-renewal-workflow-enabled (false): Whether to trigger the workflow when changing subscription auto-renewal settings.
broadleaf.subscriptionoperation.pricing.bulk-update-batch-size (100): The batch size to use when performing bulk pricing updates for subscriptions.
lock.subscription.subscription-lock-expiration-enabled (false): Whether subscription lock expiration is enabled.
lock.subscription.subscription-lock-expiration (24h): The duration of time that a subscription lock is valid for before expiring.
lock.subscription.min-subscription-lock-poll-interval (24h): The minimum interval between polling attempts for subscription locks.
lock.subscription.max-subscription-lock-poll-interval (26h): The maximum interval between polling attempts for subscription locks.