org.killbill.billing.entitlement.api

Interface EntitlementApi

All Superinterfaces:

KillbillApi

public interface EntitlementApi
extends KillbillApi

Primary API to manage the creation and retrieval of Entitlement.

Method Summary

Methods

Modifier and Type	Method and Description
Entitlement	addEntitlement(UUID bundleId, PlanPhaseSpecifier spec, org.joda.time.LocalDate effectiveDate, CallContext context) Adds an ADD_ON entitlement to previously created entitlement.
Entitlement	createBaseEntitlement(UUID accountId, PlanPhaseSpecifier spec, String externalKey, org.joda.time.LocalDate effectiveDate, CallContext context) Create a new entitlement for that account.
List<Entitlement>	getAllEntitlementsForAccountId(UUID accountId, TenantContext context) Retrieves all the Entitlement for a given account.
List<Entitlement>	getAllEntitlementsForAccountIdAndExternalKey(UUID accountId, String externalKey, TenantContext context) Retrieves all the Entitlement for a given account and matching an external key.
List<Entitlement>	getAllEntitlementsForBundle(UUID bundleId, TenantContext context) Retrieves all the Entitlement attached to the base entitlement.
List<EntitlementAOStatusDryRun>	getDryRunStatusForChange(UUID bundleId, String targetProductName, org.joda.time.LocalDate effectiveDate, TenantContext context) Simulate a change of product for the BP on that bundle and return the effect it would have on the existing ADD_ON-- if any.
Entitlement	getEntitlementForId(UUID id, TenantContext context) Retrieves an Entitlement using its id.
void	pause(UUID bundleId, org.joda.time.LocalDate effectiveDate, CallContext context) Will pause all entitlements associated with the base entitlement.
void	resume(UUID bundleId, org.joda.time.LocalDate effectiveDate, CallContext context) Will resume all entitlements associated with the base entitlement.
UUID	transferEntitlements(UUID sourceAccountId, UUID destAccountId, String externalKey, org.joda.time.LocalDate effectiveDate, CallContext context) Transfer all the Entitlement For the source account and matching the external key to the destination account.
UUID	transferEntitlementsOverrideBillingPolicy(UUID sourceAccountId, UUID destAccountId, String externalKey, org.joda.time.LocalDate effectiveDate, BillingActionPolicy billingPolicy, CallContext context) Transfer all the Entitlement for the source account and matching the external key to the destination account.

Method Detail

createBaseEntitlement

Entitlement createBaseEntitlement(UUID accountId,
                                PlanPhaseSpecifier spec,
                                String externalKey,
                                org.joda.time.LocalDate effectiveDate,
                                CallContext context)
                                  throws EntitlementApiException

Create a new entitlement for that account.

The PlanPhaseSpecifier should refer to a ProductCategory.BASE of ProductCategory.STANDALONE.

Parameters:

accountId - the account id

spec - the product specification for that new entitlement

externalKey - the external key for that entitlement-- which must be unique in the system

effectiveDate - the date at which the entitlement should start

context - the context

Returns:

a new entitlement

Throws:

EntitlementApiException - if the system fail to create the Entitlement.

addEntitlement

Entitlement addEntitlement(UUID bundleId,
                         PlanPhaseSpecifier spec,
                         org.joda.time.LocalDate effectiveDate,
                         CallContext context)
                           throws EntitlementApiException

Adds an ADD_ON entitlement to previously created entitlement.

The PlanPhaseSpecifier should refer to a ProductCategory.ADD_ON. The new entitlement will be bundled using the externalKey that was specified when creating the base entitlement.

Parameters:

bundleId - the id of the bundle

spec - the product specification for that new entitlement

effectiveDate - the date at which the entitlement should start

context - the context

Returns:

a new entitlement

Throws:

EntitlementApiException - if the system fail to create the Entitlement

getDryRunStatusForChange

List<EntitlementAOStatusDryRun> getDryRunStatusForChange(UUID bundleId,
                                                       String targetProductName,
                                                       org.joda.time.LocalDate effectiveDate,
                                                       TenantContext context)
                                                         throws EntitlementApiException

Simulate a change of product for the BP on that bundle and return the effect it would have on the existing ADD_ON-- if any.

Parameters:

bundleId - the id of the bundle

targetProductName - the target product name for the BP

effectiveDate - the date at which the change would occur

context - the context

Returns:

the status for the existing ADD_ON Entitlement

Throws:

EntitlementApiException - if this operation is not carried on a base plan.

pause

void pause(UUID bundleId,
         org.joda.time.LocalDate effectiveDate,
         CallContext context)
           throws EntitlementApiException

Will pause all entitlements associated with the base entitlement. If there are no ADD_ONN this is only the base entitlement.

Parameters:

bundleId -

effectiveDate -

context -

Throws:

EntitlementApiException - if the system fail to find the base Entitlement

resume

void resume(UUID bundleId,
          org.joda.time.LocalDate effectiveDate,
          CallContext context)
            throws EntitlementApiException

Will resume all entitlements associated with the base entitlement. If there are no ADD_ONN this is only the base entitlement.

Parameters:

bundleId -

effectiveDate -

context -

Throws:

EntitlementApiException - if the system fail to find the base Entitlement

getEntitlementForId

Entitlement getEntitlementForId(UUID id,
                              TenantContext context)
                                throws EntitlementApiException

Retrieves an Entitlement using its id.

Parameters:

id - the id of the entitlement

context - the context

Returns:

the entitlement

Throws:

EntitlementApiException - if the entitlement does not exist

getAllEntitlementsForBundle

List<Entitlement> getAllEntitlementsForBundle(UUID bundleId,
                                            TenantContext context)
                                              throws EntitlementApiException

Retrieves all the Entitlement attached to the base entitlement.

Parameters:

bundleId - the id of the bundle

context - the context

Returns:

a list of entitlements

Throws:

EntitlementApiException - if the entitlement does not exist

getAllEntitlementsForAccountIdAndExternalKey

List<Entitlement> getAllEntitlementsForAccountIdAndExternalKey(UUID accountId,
                                                             String externalKey,
                                                             TenantContext context)
                                                               throws EntitlementApiException

Retrieves all the Entitlement for a given account and matching an external key.

Parameters:

accountId - the account id

externalKey - the external key

context - the context

Returns:

a list of entitlements

Throws:

EntitlementApiException - if the account does not exist

getAllEntitlementsForAccountId

List<Entitlement> getAllEntitlementsForAccountId(UUID accountId,
                                               TenantContext context)
                                                 throws EntitlementApiException

Retrieves all the Entitlement for a given account.

Parameters:

accountId - the account id

context - the context

Returns:

a list of entitlements

Throws:

EntitlementApiException - if the account does not exist

transferEntitlements

UUID transferEntitlements(UUID sourceAccountId,
                        UUID destAccountId,
                        String externalKey,
                        org.joda.time.LocalDate effectiveDate,
                        CallContext context)
                          throws EntitlementApiException

Transfer all the Entitlement For the source account and matching the external key to the destination account.

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

The Entitlement on the source account will be cancelled at effective date and the Entitlement on the destination account will be created at the effectiveDate.

Parameters:

sourceAccountId - the unique id for the account on which the bundle will be transferred For

destAccountId - the unique id for the account on which the bundle will be transferred to

externalKey - the externalKey for the bundle

effectiveDate - the date at which this transfer should occur

context - the user context

Returns:

the id of the newly created bundle for the destination account

Throws:

EntitlementApiException - if the system could not transfer the entitlements

transferEntitlementsOverrideBillingPolicy

UUID transferEntitlementsOverrideBillingPolicy(UUID sourceAccountId,
                                             UUID destAccountId,
                                             String externalKey,
                                             org.joda.time.LocalDate effectiveDate,
                                             BillingActionPolicy billingPolicy,
                                             CallContext context)
                                               throws EntitlementApiException

Transfer all the Entitlement for the source account and matching the external key to the destination account.

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

The Entitlement on the source account will be cancelled at effective date and the Entitlement on the destination account will be created at the effectiveDate. The billingPolicy will be used to override the default billing behavior for the cancellation of the subscriptions on the source account.

Parameters:

sourceAccountId - the unique id for the account on which the bundle will be transferred For

destAccountId - the unique id for the account on which the bundle will be transferred to

externalKey - the externalKey for the bundle

effectiveDate - the date at which this transfer should occur

billingPolicy - the override billing policy

context - the user context

Returns:

the id of the newly created base entitlement for the destination account

Throws:

EntitlementApiException - if the system could not transfer the entitlements