Package com.broadleafcommerce.subscriptionoperation.domain

Class SubscriptionPricingContext

java.lang.Object
com.broadleafcommerce.subscriptionoperation.domain.SubscriptionPricingContext
All Implemented Interfaces:
Serializable
public class SubscriptionPricingContext extends Object implements Serializable
Context object that's used throughout the subscription pricing ecosystem to communicate details about the subscription, action, & subscription periods.
See Also:

  • Constructor Details

    • SubscriptionPricingContext

      public SubscriptionPricingContext()

  • Method Details

    • getActionDateAtBeginningOfDay

      public Instant getActionDateAtBeginningOfDay()

    • getPeriodDefinition

      public PeriodDefinition getPeriodDefinition(Integer period)

    • getExistingSubscriptionItemSubtotal

      @Nullable public javax.money.MonetaryAmount getExistingSubscriptionItemSubtotal(@Nullable String subscriptionItemId)

    • getExistingSubscriptionItems

      public List<SubscriptionItem> getExistingSubscriptionItems()

    • getExistingSubscriptionItem

      @Nullable public SubscriptionItem getExistingSubscriptionItem(@Nullable String existingSubscriptionItemId)

    • getExistingSubscriptionItemUnitPrice

      @Nullable public javax.money.MonetaryAmount getExistingSubscriptionItemUnitPrice(@Nullable String subscriptionItemId)

    • getExistingSubscriptionItemQuantity

      public Integer getExistingSubscriptionItemQuantity(@Nullable String subscriptionItemId)

    • getExistingSubscriptionId

      @Nullable public String getExistingSubscriptionId()

    • getCancellationPolicyOptionally

      public Optional<CancellationPolicy> getCancellationPolicyOptionally()

    • getCancellationPolicyDetailAndValidate

      public CancellationPolicyDetail getCancellationPolicyDetailAndValidate()

    • getCancellationStrategy

      public String getCancellationStrategy()

    • getCancellationChargeStrategy

      public String getCancellationChargeStrategy()

    • hasTerm

      public boolean hasTerm()

    • hasFreeTrial

      public boolean hasFreeTrial()
      Determines if the subscription has a free trial still applied.

      For subscription modification flows, this also check if the free trial was lost via isFreeTrialLost().

      Returns:
      true if the subscription has a free trial, false otherwise
      See Also:

    • isFreeTrialLost

      public boolean isFreeTrialLost()
      Determines whether an existing free trial was lost, different from expired, due to the subscription modification.

      For example, the free trial Adjustment could be lost due to the offer requirement no longer matches from the changes against the subscription.

      This is only relevant to subscription modification flows.

      Returns:
      true if the subscription free trial has been lost, false otherwise

    • isFreeTrialExpired

      public boolean isFreeTrialExpired()
      Determines whether an existing free trial was expired.
      Returns:
      true if the subscription free trial has expired, false otherwise

    • isActionDuringFreeTrial

      public boolean isActionDuringFreeTrial()
      Determines whether the action being performed is within the free trial timeframe, only relevant for subscription modification flows when free trial is involved.
      Returns:
      true if the action is during the free trial, false otherwise

    • shouldRoundUpBillDates

      public boolean shouldRoundUpBillDates()
      Determines whether the bill dates (e.g. bill date, period start date, and period end date) should be rounded up to the end of the month.

      For existing subscriptions, it's determined from the existing Subscription.getInternalAttributes(), unless the free trial is lost as a result of the subscription modification, in which case it's determined based on whether the action date is on a day that is not available every month, e.g. 29th, 30th, and 31st.

      For create flow, it's determined based on whether the subscriptionActionDate is on a day that is not available every month, e.g. 29th, 30th, and 31st

      Note that if free trial is lost, the bill dates should not be rounded up for the first period.

    • isCurrentPeriod

      public boolean isCurrentPeriod(@Nullable Integer periodNumber)
      Determines whether the given period number is the current subscription period.

      When the period number is null, it indicates DueNow, and DueNow is considered the current period if the payment strategy is DefaultSubscriptionPaymentStrategy.PREPAID or if the flow is DefaultSubscriptionActionFlow.CANCEL.

    • getCurrentSubscriptionPeriod

      public int getCurrentSubscriptionPeriod()
      Gets the current subscription period number.

      For DefaultSubscriptionActionFlow.CREATE, this is the first period.

    • hasBillingFrequencyChange

      public boolean hasBillingFrequencyChange()

    • getCurrentPeriodDefinition

      public PeriodDefinition getCurrentPeriodDefinition()
      Gets the current subscription period definition.

    • getZoneId

      protected ZoneId getZoneId(@Nullable String customerTimezone)
      Returns the ZoneId for the given customer timezone string. If the timezone is null, it defaults to ZoneOffset.UTC.
      Parameters:
      customerTimezone - the customer's timezone ID
      Returns:
      the resolved ZoneId
      Throws:
      IllegalArgumentException - if the provided timezone ID is invalid

    • getCart

      public com.broadleafcommerce.cart.client.domain.Cart getCart()
      The Cart containing subscriptions.

    • getFlow

      public String getFlow()
      Describes the subscription action flow that is being executed.
      See Also:

    • getSubscriptionRootItem

      public com.broadleafcommerce.cart.client.domain.CartItem getSubscriptionRootItem()
      The CartItem representing the root SubscriptionItem.

    • getSubscriptionActionDate

      public Instant getSubscriptionActionDate()
      The timestamp at which the subscription action was taken. In most pricing contexts, the action has not been formally submitted, so we'll use today's date for making pricing calculations.

    • getPaymentStrategy

      public String getPaymentStrategy()
      Declares that payments made against a subscription are going towards the goods/services rendered in the previous vs current period.
      See Also:

    • getNextBillDate

      public Instant getNextBillDate()
      Describes the next time that the customer will be billed.

    • getPeriodType

      public String getPeriodType()
      The period type for the price, e.g. MONTHLY, QUARTERLY, ANNUALLY
      See Also:
      • periodFrequency

    • getPeriodFrequency

      public int getPeriodFrequency()
      The frequency with which the recurring price should be charged., e.g., a value of 1 combined with periodType of MONTH would indicate to a subscription service that the price should be charged every 1 month.
      See Also:
      • periodType

    • getPriorPeriodType

      public String getPriorPeriodType()
      The period type for the price, e.g. MONTHLY, QUARTERLY, ANNUALLY
      See Also:
      • priorPeriodFrequency

    • getPriorPeriodFrequency

      public Integer getPriorPeriodFrequency()
      The frequency with which the recurring price should be charged., e.g., a value of 1 combined with periodType of MONTH would indicate to a subscription service that the price should be charged every 1 month.
      See Also:
      • priorPeriodType

    • getStartOfTermDate

      public Instant getStartOfTermDate()
      The date at which the subscription's terms will begin.

    • getEndOfTermDate

      public Instant getEndOfTermDate()
      The date at which the subscription's terms will expire.

    • getPeriodDefinitions

      public Map<Integer,PeriodDefinition> getPeriodDefinitions()
      Describes upcoming subscription billing periods, including the start date, end date, & when the customer will be billed. Map keys are upcoming period numbers, with 1 being the first period. For creation flows, the first period represents the first time that subscription billing will be engaged (i.e. the first bill following the initial purchase). For other flows that act upon the subscription in the middle of a period, the first period definition reflects when the next subscription billing will take place. A key nuance is that this differs for the DefaultSubscriptionPaymentStrategy.POSTPAID vs DefaultSubscriptionPaymentStrategy.PREPAID payment strategies. In the case of Postpaid, the first period includes the active period. The action may include a due now amount, but billing for the subscription itself won't happen until the period has ended. In the case of DefaultSubscriptionPaymentStrategy.PREPAID, the first period represents the next period to be billed. Actions against an DefaultSubscriptionPaymentStrategy.PREPAID subscription can expect to have a due now amount. For example, in the case of an upgrade, the customer has paid for the period at a lower amount, then increases the amount along with the upgrade. This difference in price should be due now.

    • getCancellationPolicy

      public CancellationPolicy getCancellationPolicy()
      The full CancellationPolicy for the subscriptionRootItem if any.

    • getCancellationPolicyDetail

      public CancellationPolicyDetail getCancellationPolicyDetail()
      The relevant CancellationPolicyDetail for the paymentStrategy from the cancellationPolicy.

    • getExistingSubscription

      public Subscription getExistingSubscription()
      The existing Subscription if any. This is most relevant for subscription action flows that are modifying an existing subscription.

    • isSubscriptionInGracePeriod

      public boolean isSubscriptionInGracePeriod()
      Whether the existingSubscription is within its grace period during a cancellation flow.

    • getExistingSubscriptionItemById

      public Map<String,SubscriptionItem> getExistingSubscriptionItemById()
      The existing Subscription if any. This is most relevant for subscription action flows that are modifying an existing subscription.

    • getExistingSubscriptionItemUnitPrices

      public Map<String,javax.money.MonetaryAmount> getExistingSubscriptionItemUnitPrices()
      Map of SubscriptionItem.getId() to the existing SubscriptionItem's unit price.

    • getExistingSubscriptionItemQuantities

      public Map<String,Integer> getExistingSubscriptionItemQuantities()
      Map of SubscriptionItem.getId() to the existing SubscriptionItem's quantity.

    • getRemovedSubscriptionItems

      public List<SubscriptionItem> getRemovedSubscriptionItems()
      List of SubscriptionItems that are not on the cart.

    • getRemovedAdjustments

      public List<RemovedAdjustment> getRemovedAdjustments()
      The list of Adjustments being removed due to the proposed changes.

      For example, an Adjustment could be lost due to the offer requirement no longer matches from the changes against the subscription.

    • getCurrency

      public javax.money.CurrencyUnit getCurrency()
      Currency of this subscription

    • getNumberOfPeriodsLeftInTerm

      public Long getNumberOfPeriodsLeftInTerm()
      The number of billing periods left in a term beyond the current period, if there are terms.

      If changing billing frequency, then the current period is shortened, so this may include a shortened final period in the terms.

    • getFreeTrialEndDate

      public Instant getFreeTrialEndDate()
      The end date of the free trial for this subscription, if applicable, null if none applied.

      For create flow, this is from the applied free trial offer.

      For subscription modification flows, this is from the existing free trial already applied to the existing subscription.

    • getCustomerTimezone

      @Nullable public String getCustomerTimezone()
      The customer's timezone. It's an optional field used to truncate the dates to the beginning of the day in customer's timezone. If null, UTC time is used.

    • getAdditionalAttributes

      public Map<String,Object> getAdditionalAttributes()
      Miscellaneous attributes that can be added to the context in order to provide more information.

    • setCart

      public void setCart(com.broadleafcommerce.cart.client.domain.Cart cart)
      The Cart containing subscriptions.

    • setFlow

      public void setFlow(String flow)
      Describes the subscription action flow that is being executed.
      See Also:

    • setSubscriptionRootItem

      public void setSubscriptionRootItem(com.broadleafcommerce.cart.client.domain.CartItem subscriptionRootItem)
      The CartItem representing the root SubscriptionItem.

    • setSubscriptionActionDate

      public void setSubscriptionActionDate(Instant subscriptionActionDate)
      The timestamp at which the subscription action was taken. In most pricing contexts, the action has not been formally submitted, so we'll use today's date for making pricing calculations.

    • setPaymentStrategy

      public void setPaymentStrategy(String paymentStrategy)
      Declares that payments made against a subscription are going towards the goods/services rendered in the previous vs current period.
      See Also:

    • setNextBillDate

      public void setNextBillDate(Instant nextBillDate)
      Describes the next time that the customer will be billed.

    • setPeriodType

      public void setPeriodType(String periodType)
      The period type for the price, e.g. MONTHLY, QUARTERLY, ANNUALLY
      See Also:
      • periodFrequency

    • setPeriodFrequency

      public void setPeriodFrequency(int periodFrequency)
      The frequency with which the recurring price should be charged., e.g., a value of 1 combined with periodType of MONTH would indicate to a subscription service that the price should be charged every 1 month.
      See Also:
      • periodType

    • setPriorPeriodType

      public void setPriorPeriodType(String priorPeriodType)
      The period type for the price, e.g. MONTHLY, QUARTERLY, ANNUALLY
      See Also:
      • priorPeriodFrequency

    • setPriorPeriodFrequency

      public void setPriorPeriodFrequency(Integer priorPeriodFrequency)
      The frequency with which the recurring price should be charged., e.g., a value of 1 combined with periodType of MONTH would indicate to a subscription service that the price should be charged every 1 month.
      See Also:
      • priorPeriodType

    • setStartOfTermDate

      public void setStartOfTermDate(Instant startOfTermDate)
      The date at which the subscription's terms will begin.

    • setEndOfTermDate

      public void setEndOfTermDate(Instant endOfTermDate)
      The date at which the subscription's terms will expire.

    • setPeriodDefinitions

      public void setPeriodDefinitions(Map<Integer,PeriodDefinition> periodDefinitions)
      Describes upcoming subscription billing periods, including the start date, end date, & when the customer will be billed. Map keys are upcoming period numbers, with 1 being the first period. For creation flows, the first period represents the first time that subscription billing will be engaged (i.e. the first bill following the initial purchase). For other flows that act upon the subscription in the middle of a period, the first period definition reflects when the next subscription billing will take place. A key nuance is that this differs for the DefaultSubscriptionPaymentStrategy.POSTPAID vs DefaultSubscriptionPaymentStrategy.PREPAID payment strategies. In the case of Postpaid, the first period includes the active period. The action may include a due now amount, but billing for the subscription itself won't happen until the period has ended. In the case of DefaultSubscriptionPaymentStrategy.PREPAID, the first period represents the next period to be billed. Actions against an DefaultSubscriptionPaymentStrategy.PREPAID subscription can expect to have a due now amount. For example, in the case of an upgrade, the customer has paid for the period at a lower amount, then increases the amount along with the upgrade. This difference in price should be due now.

    • setCancellationPolicy

      public void setCancellationPolicy(CancellationPolicy cancellationPolicy)
      The full CancellationPolicy for the subscriptionRootItem if any.

    • setCancellationPolicyDetail

      public void setCancellationPolicyDetail(CancellationPolicyDetail cancellationPolicyDetail)
      The relevant CancellationPolicyDetail for the paymentStrategy from the cancellationPolicy.

    • setExistingSubscription

      public void setExistingSubscription(Subscription existingSubscription)
      The existing Subscription if any. This is most relevant for subscription action flows that are modifying an existing subscription.

    • setSubscriptionInGracePeriod

      public void setSubscriptionInGracePeriod(boolean subscriptionInGracePeriod)
      Whether the existingSubscription is within its grace period during a cancellation flow.

    • setExistingSubscriptionItemById

      public void setExistingSubscriptionItemById(Map<String,SubscriptionItem> existingSubscriptionItemById)
      The existing Subscription if any. This is most relevant for subscription action flows that are modifying an existing subscription.

    • setExistingSubscriptionItemUnitPrices

      public void setExistingSubscriptionItemUnitPrices(Map<String,javax.money.MonetaryAmount> existingSubscriptionItemUnitPrices)
      Map of SubscriptionItem.getId() to the existing SubscriptionItem's unit price.

    • setExistingSubscriptionItemQuantities

      public void setExistingSubscriptionItemQuantities(Map<String,Integer> existingSubscriptionItemQuantities)
      Map of SubscriptionItem.getId() to the existing SubscriptionItem's quantity.

    • setRemovedSubscriptionItems

      public void setRemovedSubscriptionItems(List<SubscriptionItem> removedSubscriptionItems)
      List of SubscriptionItems that are not on the cart.

    • setRemovedAdjustments

      public void setRemovedAdjustments(List<RemovedAdjustment> removedAdjustments)
      The list of Adjustments being removed due to the proposed changes.

      For example, an Adjustment could be lost due to the offer requirement no longer matches from the changes against the subscription.

    • setCurrency

      public void setCurrency(javax.money.CurrencyUnit currency)
      Currency of this subscription

    • setNumberOfPeriodsLeftInTerm

      public void setNumberOfPeriodsLeftInTerm(Long numberOfPeriodsLeftInTerm)
      The number of billing periods left in a term beyond the current period, if there are terms.

      If changing billing frequency, then the current period is shortened, so this may include a shortened final period in the terms.

    • setFreeTrialEndDate

      public void setFreeTrialEndDate(Instant freeTrialEndDate)
      The end date of the free trial for this subscription, if applicable, null if none applied.

      For create flow, this is from the applied free trial offer.

      For subscription modification flows, this is from the existing free trial already applied to the existing subscription.

    • setCustomerTimezone

      public void setCustomerTimezone(@Nullable String customerTimezone)
      The customer's timezone. It's an optional field used to truncate the dates to the beginning of the day in customer's timezone. If null, UTC time is used.

    • setAdditionalAttributes

      public void setAdditionalAttributes(Map<String,Object> additionalAttributes)
      Miscellaneous attributes that can be added to the context in order to provide more information.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object