Package org.killbill.billing.entitlement.api

Interface Entitlement

  • All Superinterfaces:
    Entity
    All Known Subinterfaces:
    Subscription
    public interface Entitlement
extends Entity
    An Entitlement is created using the EntitlementApi

    It contains apis to return entitlement state (i.e information about whether the user can access the service purchased through the subscription), and also apis to modify the state of the subscription (upgrade, downgrade, cancellation).

    The apis cancelEntitlement and changePlan are relying on either dates and/or policies to achieve correct result.

    The dates provided are LocalDate and they are interpreted by the system using the the account timezone:

    Example: Let's assume for instance a point in time set to 2017-04-24:00.00.01.000Z, and a user that makes a changePlan api call by specifying an effective date of 2017-04-24 for an account with a UTC-8 TZ. In the account timezone, the clock shows 2017-04-23:16.00.01.000(-8), and so the change will be effective in the future, any time during the 24 hours period that starts at 2017-04-24:00.00.00.000(-8), with no specific guarantee about the time.

    In order to ensure that the api call happens immediately (as the call returns), one can pass a null effective date.

    The policies provide an easy way to achieve desired results without having to do any date computation. However, when using the IMMEDIATE policy, it is interesting to notice that the policy will be converted into an effective date and so the same principle discussed earlier with interpreting the date into the account timezone will occur, resulting in the operation to not necessarily happen immediately (as the call returns) but instead within the 24 hours window. The result will be correct in the sense that the service will move to the new Plan on the right day, and if necessary billing pro-ration will show the correct amount.

    In the case of PENDING subscriptions, that is for which the (billing and/or entitlement) effective start date are in the future, providing an IMMEDIATE policy or a null effective date will default to the effective start date of the subscription.

    See Also:
    EntitlementApi

    • Method Detail

      • getBaseEntitlementId

        UUID getBaseEntitlementId()
        Returns:
        the unique id of the base entitlement

      • getExternalKey

        String getExternalKey()
        Returns:
        external key

      • getBundleId

        UUID getBundleId()
        Returns:
        the unique Id of the SubscriptionBundle

      • getBundleExternalKey

        String getBundleExternalKey()
        Returns:
        the bundle external key associated with this entitlement

      • getAccountId

        UUID getAccountId()
        Returns:
        the account id

      • getEffectiveStartDate

        org.joda.time.DateTime getEffectiveStartDate()
        Returns:
        the start date of the entitlement

      • getEffectiveEndDate

        org.joda.time.DateTime getEffectiveEndDate()
        Returns:
        the end date of the entitlement, that is the date at which it got cancelled.

      • getLastActiveProduct

        Product getLastActiveProduct()
        Returns:
        the last Product prior to cancellation

      • getLastActivePlan

        Plan getLastActivePlan()
        Returns:
        the last Plan prior to cancellation

      • getLastActivePhase

        PlanPhase getLastActivePhase()
        Returns:
        the last Phase prior to cancellation

      • getLastActivePriceList

        PriceList getLastActivePriceList()
        Returns:
        the last active PriceList

      • getLastActiveProductCategory

        ProductCategory getLastActiveProductCategory()
        Returns:
        the last active ProductCategory

      • getBillCycleDayLocal

        Integer getBillCycleDayLocal()
        The billCycleDay should be interpreted in the account timezone. The billCycleDay is used to determine when to bill a specific subscription

        Returns:
        the billCycleDay for that subscription

      • getQuantity

        Integer getQuantity()
        Returns:
        the quantity or number of subscription that should be billed for.

      • cancelEntitlementWithDate

        Entitlement cancelEntitlementWithDate​(org.joda.time.LocalDate effectiveDate,
                                      boolean overrideBillingEffectiveDate,
                                      Iterable<PluginProperty> properties,
                                      CallContext context)
                               throws EntitlementApiException
        Cancels the Entitlement at the specified date. After this operation, the existing object becomes stale.

        Parameters:
        effectiveDate - the date at which the entitlement should be cancelled
        overrideBillingEffectiveDate - use effectiveDate for billing cancellation date as well, instead of relying on default catalog policies.
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the cancellation was performed
        Throws:
        EntitlementApiException - if cancellation failed

        The date is interpreted by the system to be in the timezone specified at the Account

      • cancelEntitlementWithDate

        Entitlement cancelEntitlementWithDate​(org.joda.time.DateTime entitlementEffectiveDate,
                                      org.joda.time.DateTime billingEffectiveDate,
                                      Iterable<PluginProperty> properties,
                                      CallContext context)
                               throws EntitlementApiException
        Cancels the Entitlement with the specified entitlementEffectiveDate and billingEffectiveDate After this operation, the existing object becomes stale.

        Parameters:
        entitlementEffectiveDate - the datetime at which the entitlement should be cancelled
        billingEffectiveDate - the datetime at which billing should be cancelled
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the cancellation was performed
        Throws:
        EntitlementApiException - if cancellation failed

        The date is interpreted by the system to be in the timezone specified at the Account

      • cancelEntitlementWithPolicy

        Entitlement cancelEntitlementWithPolicy​(Entitlement.EntitlementActionPolicy policy,
                                        Iterable<PluginProperty> properties,
                                        CallContext context)
                                 throws EntitlementApiException
        Cancel the Entitlement with a policy. After this operation, the existing object becomes stale.

        The billing effective date will be computed from the default catalog policies.

        Parameters:
        policy - the policy that is used by the system to calculate the entitlement cancellation date
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the cancellation was performed
        Throws:
        EntitlementApiException - if cancellation failed

      • cancelEntitlementWithDateOverrideBillingPolicy

        Entitlement cancelEntitlementWithDateOverrideBillingPolicy​(org.joda.time.LocalDate effectiveDate,
                                                           BillingActionPolicy billingPolicy,
                                                           Iterable<PluginProperty> properties,
                                                           CallContext context)
                                                    throws EntitlementApiException
        Cancels the Entitlement at the specified date After this operation, the existing object becomes stale.

        Parameters:
        effectiveDate - the date at which the entitlement should be cancelled
        billingPolicy - the billingPolicy that should be use to compute the billing cancellation date
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the cancellation was performed
        Throws:
        EntitlementApiException - if cancellation failed

      • cancelEntitlementWithPolicyOverrideBillingPolicy

        Entitlement cancelEntitlementWithPolicyOverrideBillingPolicy​(Entitlement.EntitlementActionPolicy policy,
                                                             BillingActionPolicy billingPolicy,
                                                             Iterable<PluginProperty> properties,
                                                             CallContext context)
                                                      throws EntitlementApiException
        Cancels the Entitlement at the specified date and overrides the default billing policy. After this operation, the existing object becomes stale.
        Parameters:
        policy - the policy that is used by the system to calculate the cancellation date
        billingPolicy - the override billing policy
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the cancellation was performed
        Throws:
        EntitlementApiException - if cancellation failed

      • uncancelEntitlement

        void uncancelEntitlement​(Iterable<PluginProperty> properties,
                         CallContext context)
                  throws EntitlementApiException
        Removes a pending future cancellation on an entitlement.

        The call will only succeed if the entitlement has been cancelled previously and if the effectiveDate of the cancellation did not occur yet. In such a case it will remove both the cancellation event at the entitlement and billing level-- regardless of when is the effectiveDate of the billing cancellation event.

        Parameters:
        properties - plugin specific properties
        context - the context
        Throws:
        EntitlementApiException

      • changePlanWithDate

        Entitlement changePlanWithDate​(EntitlementSpecifier spec,
                               org.joda.time.LocalDate effectiveDate,
                               Iterable<PluginProperty> properties,
                               CallContext context)
                        throws EntitlementApiException
        Change Entitlement plan at the specified date. After this operation, the existing object becomes stale.

        Parameters:
        spec - the product specification for the change
        effectiveDate - the effective date at which the entitlement and billing should be changed
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the change was performed
        Throws:
        EntitlementApiException - if change failed

      • changePlanWithDate

        Entitlement changePlanWithDate​(EntitlementSpecifier spec,
                               org.joda.time.DateTime effectiveDate,
                               Iterable<PluginProperty> properties,
                               CallContext context)
                        throws EntitlementApiException
        Change Entitlement plan at the specified date. After this operation, the existing object becomes stale.

        Parameters:
        spec - the product specification for the change
        effectiveDate - the effective datetime at which the entitlement and billing should be changed
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the change was performed
        Throws:
        EntitlementApiException - if change failed

      • changePlanOverrideBillingPolicy

        Entitlement changePlanOverrideBillingPolicy​(EntitlementSpecifier spec,
                                            org.joda.time.LocalDate effectiveDate,
                                            BillingActionPolicy billingPolicy,
                                            Iterable<PluginProperty> properties,
                                            CallContext context)
                                     throws EntitlementApiException
        Change Entitlement plan at the specified date and overrides the billing policy. After this operation, the existing object becomes stale.

        The date is interpreted by the system to be in the timezone specified at the Account

        Parameters:
        spec - the product specification for the change
        effectiveDate - unused (reserved for future use)
        billingPolicy - the overriden billing policy that will determine effective date for the changePlan operation.
        properties - plugin specific properties
        context - the context
        Returns:
        the new Entitlement after the change was performed
        Throws:
        EntitlementApiException - if change failed

      • updateBCD

        void updateBCD​(int bcd,
               org.joda.time.LocalDate effectiveFromDate,
               CallContext context)
        throws EntitlementApiException
        Parameters:
        bcd - the new BCD for that subscription
        effectiveFromDate - date after which that BCD change becomes active
        context - the context
        Throws:
        EntitlementApiException

      • updateQuantity

        void updateQuantity​(int quantity,
                    org.joda.time.LocalDate effectiveFromDate,
                    CallContext context)
             throws EntitlementApiException
        Parameters:
        quantity - the quantity or equivalent number of subscriptions that should be billed
        effectiveFromDate - date after which that quantity change becomes active
        context - the context
        Throws:
        EntitlementApiException