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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Entitlement.EntitlementActionPolicy Used to control the effective date that should be used on Plan change or on cancellation.
static class	Entitlement.EntitlementSourceType Possible Entitlement source types.
static class	Entitlement.EntitlementState Possible states of an Entitlement

Method Summary

Modifier and Type	Method and Description
Entitlement	cancelEntitlementWithDate(org.joda.time.LocalDate effectiveDate, boolean overrideBillingEffectiveDate, java.lang.Iterable<PluginProperty> properties, CallContext context) Cancels the Entitlement at the specified date.
Entitlement	cancelEntitlementWithDateOverrideBillingPolicy(org.joda.time.LocalDate effectiveDate, BillingActionPolicy billingPolicy, java.lang.Iterable<PluginProperty> properties, CallContext context) Cancels the Entitlement at the specified date After this operation, the existing object becomes stale.
Entitlement	cancelEntitlementWithPolicy(Entitlement.EntitlementActionPolicy policy, java.lang.Iterable<PluginProperty> properties, CallContext context) Cancel the Entitlement with a policy.
Entitlement	cancelEntitlementWithPolicyOverrideBillingPolicy(Entitlement.EntitlementActionPolicy policy, BillingActionPolicy billingPolicy, java.lang.Iterable<PluginProperty> properties, CallContext context) Cancels the Entitlement at the specified date and overrides the default billing policy.
Entitlement	changePlan(PlanPhaseSpecifier spec, java.util.List<PlanPhasePriceOverride> overrides, java.lang.Iterable<PluginProperty> properties, CallContext context) Change Entitlement plan using default policy.
Entitlement	changePlanOverrideBillingPolicy(PlanPhaseSpecifier spec, java.util.List<PlanPhasePriceOverride> overrides, org.joda.time.LocalDate effectiveDate, BillingActionPolicy billingPolicy, java.lang.Iterable<PluginProperty> properties, CallContext context) Change Entitlement plan at the specified date and overrides the billing policy.
Entitlement	changePlanWithDate(PlanPhaseSpecifier spec, java.util.List<PlanPhasePriceOverride> overrides, org.joda.time.LocalDate effectiveDate, java.lang.Iterable<PluginProperty> properties, CallContext context) Change Entitlement plan at the specified date.
java.util.UUID	getAccountId()
java.util.UUID	getBaseEntitlementId()
java.lang.Integer	getBillCycleDayLocal() The billCycleDay should be interpreted in the account timezone.
java.util.UUID	getBundleId()
org.joda.time.LocalDate	getEffectiveEndDate()
org.joda.time.LocalDate	getEffectiveStartDate()
java.lang.String	getExternalKey()
PlanPhase	getLastActivePhase()
Plan	getLastActivePlan()
PriceList	getLastActivePriceList()
Product	getLastActiveProduct()
ProductCategory	getLastActiveProductCategory()
Entitlement.EntitlementSourceType	getSourceType()
Entitlement.EntitlementState	getState()
void	uncancelEntitlement(java.lang.Iterable<PluginProperty> properties, CallContext context) Removes a pending future cancellation on an entitlement.
void	undoChangePlan(java.lang.Iterable<PluginProperty> properties, CallContext context)
void	updateBCD(int bcd, org.joda.time.LocalDate effectiveFromDate, CallContext context)

Methods inherited from interface org.killbill.billing.util.entity.Entity

getCreatedDate, getId, getUpdatedDate

Method Detail

getBaseEntitlementId

java.util.UUID getBaseEntitlementId()

Returns:

the unique id of the base entitlement

getBundleId

java.util.UUID getBundleId()

Returns:

the unique Id of the SubscriptionBundle

getAccountId

java.util.UUID getAccountId()

Returns:

the account id

getExternalKey

java.lang.String getExternalKey()

Returns:

the external key that was supplied when creating the base entitlement

getState

Entitlement.EntitlementState getState()

Returns:

the state of the entitlement

getSourceType

Entitlement.EntitlementSourceType getSourceType()

Returns:

the entitlement source type

getEffectiveStartDate

org.joda.time.LocalDate getEffectiveStartDate()

Returns:

the start date of the entitlement

getEffectiveEndDate

org.joda.time.LocalDate 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

java.lang.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

cancelEntitlementWithDate

Entitlement cancelEntitlementWithDate(org.joda.time.LocalDate effectiveDate,
                                      boolean overrideBillingEffectiveDate,
                                      java.lang.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

cancelEntitlementWithPolicy

Entitlement cancelEntitlementWithPolicy(Entitlement.EntitlementActionPolicy policy,
                                        java.lang.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,
                                                           java.lang.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,
                                                             java.lang.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(java.lang.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

changePlan

Entitlement changePlan(PlanPhaseSpecifier spec,
                       java.util.List<PlanPhasePriceOverride> overrides,
                       java.lang.Iterable<PluginProperty> properties,
                       CallContext context)
                throws EntitlementApiException

Change Entitlement plan using default policy. After this operation, the existing object becomes stale.

Parameters:

spec - the product specification for the change

overrides - the price override for each phase and for a specific currency

properties - plugin specific properties

context - the context

Returns:

the new Entitlement after the change was performed

Throws:

EntitlementApiException - if change failed

undoChangePlan

void undoChangePlan(java.lang.Iterable<PluginProperty> properties,
                    CallContext context)
             throws EntitlementApiException

Parameters:

properties - plugin specific properties

context - the context

Throws:

EntitlementApiException

changePlanWithDate

Entitlement changePlanWithDate(PlanPhaseSpecifier spec,
                               java.util.List<PlanPhasePriceOverride> overrides,
                               org.joda.time.LocalDate effectiveDate,
                               java.lang.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

overrides - the price override for each phase and for a specific currency

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

changePlanOverrideBillingPolicy

Entitlement changePlanOverrideBillingPolicy(PlanPhaseSpecifier spec,
                                            java.util.List<PlanPhasePriceOverride> overrides,
                                            org.joda.time.LocalDate effectiveDate,
                                            BillingActionPolicy billingPolicy,
                                            java.lang.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

overrides - the price override for each phase and for a specific currency

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