- v1.0.0-latest-prod
since 2.3.0
|
Requirement: An extended commercial license is required to obtain, deploy, and utilize this functionality. If you intend to use these services, please contact your Broadleaf representative to discuss licensing details and access rights. |
The Subscription Operation Service is an orchestration service designed to manage actions against subscriptions within the Broadleaf Microservices ecosystem. It acts as the central engine for creating, modifying, pricing, and maintaining subscriptions for both individual customers and business accounts. It handles complex business logic regarding how subscriptions evolve over time, including billing periods, terms, and pricing adjustments.
For a conceptual overview of the entire subscription ecosystem, see Subscriptions Ecosystem.
Subscription Lifecycle Management
Creation: Supports creating subscriptions directly via API or originating them from an Order (com.broadleafcommerce.subscriptionoperation.service.SubscriptionGenerationService#createNewSubscriptions). See Purchase & Fulfillment.
Retrieval: Provides endpoints to fetch subscriptions by ID or by owner (User or Account), with support for filtering and pagination.
Status Management: Handles status transitions (e.g., Active, Cancelled) and tracks future status changes.
Locking & Sandboxing: Implements a locking mechanism (SubscriptionOperationService#lockSubscription, SubscriptionOperationService#unlockToken) to prevent concurrent modifications during critical operations, utilizing a sandbox state. See Locking and Sandbox Changes.
Advanced Modification Workflows
Actions: Supports specific business actions like Upgrade, Downgrade, Edit, and Cancel. See Subscription Management.
Prepaid Delayed Actions: Delays mid-cycle downgrades or removals for prepaid subscriptions until the next billing cycle. See Prepaid Actions.
Proration & Billing: Calculates financial implications of mid-cycle changes, such as prorated charges, credits for unused time, and "due now" amounts.
Auto-Renewal: Manages auto-renewal settings and term durations. See Recurring Billing and Change Auto-Renewal.
Sophisticated Subscription Pricing Engine
Dynamic Pricing: Calculates current and future pricing estimates (SubscriptionPricingService#priceSubscriptions), taking into account recurring frequencies (monthly, annually, etc.). It generates SubscriptionPriceResponse containing details like preActionSubtotal, postActionSubtotal, amountDueNow, and estimatedFuturePayments. See Subscription Pricing.
Adjustments: Tracks discounts or price adjustments via SubscriptionAdjustment and SubscriptionItemAdjustment. Allows CSRs to manually add adjustments. See CSR Interactions.
Bulk Updates: Capable of performing bulk price updates (SubscriptionPricingService#bulkUpdateSubscriptionPricing) across multiple subscriptions. See CSR Interactions.
Cancellation Policy Handling
Policy Identification: Identifies applicable cancellation policies based on the subscription items.
Rules: Enforces rules regarding cancellation fees, refund strategies (e.g., prorated vs. no refund), and grace periods. See Subscription Cancellation.
Access Control & Multi-Tenancy
Security: Includes specific endpoints and validation logic for Customer vs. Account owned subscriptions (AccountSubscriptionOperationEndpoint, CustomerSubscriptionOperationEndpoint).
Context Awareness: Built with multi-tenancy and sandboxing support (ContextInfo, X-SANDBOX-AWARE headers).
Subscription: The root entity tracking status, billing frequency, terms, and owner.
SubscriptionItem: Represents the specific goods or services (products/variants) included in the subscription.
SubscriptionAdjustment: Represents discounts or price modifiers applied to the subscription.
SubscriptionItemAdjustment: Represents discounts or price modifiers applied to the subscription item.
SubscriptionWithItems: Combines and information for the Subscription and its SubscriptionItem
SubscriptionPeriod: Defines the specific timeframes for billing (start date, end date, bill date).
LockStatus: Represents the subscription lock status (LOCKED, UNLOCKED, REJECTED).