Package 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 Detail

      • createBaseEntitlement

        UUID createBaseEntitlement​(UUID accountId,
                           EntitlementSpecifier spec,
                           String bundleExternalKey,
                           org.joda.time.LocalDate entitlementEffectiveDate,
                           org.joda.time.LocalDate billingEffectiveDate,
                           boolean isMigrated,
                           boolean renameCancelledBundleIfExist,
                           Iterable<PluginProperty> properties,
                           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
        bundleExternalKey - the bundle external key
        entitlementEffectiveDate - the date at which the entitlement should start. if this is null this is assumed now
        billingEffectiveDate - the date at which the billing for the subscription should start. if this is null this is assumed now
        isMigrated - whether this subscription comes from a different system (migrated into Kill Bill)
        renameCancelledBundleIfExist - rename bundle external key associated to other bundles with same key where subscriptions were cancelled
        properties - plugin specific properties
        context - the context
        Returns:
        the entitlement id created
        Throws:
        EntitlementApiException - if the system fail to create the Entitlement.

      • createBaseEntitlementsWithAddOns

        List<UUID> createBaseEntitlementsWithAddOns​(UUID accountId,
                                            Iterable<BaseEntitlementWithAddOnsSpecifier> baseEntitlementWithAddOnsSpecifier,
                                            boolean renameCancelledBundleIfExist,
                                            Iterable<PluginProperty> properties,
                                            CallContext context)
                                     throws EntitlementApiException
        Create multiple new entitlements with addOn entitlements for that account.

        Parameters:
        accountId - the account id
        baseEntitlementWithAddOnsSpecifier - a list of baseEntitlementWithAddOns specifier
        renameCancelledBundleIfExist - rename bundle external key associated to other bundles with same key where subscriptions were cancelled
        properties - plugin specific properties
        context - the context
        Returns:
        the list of entitlement id created
        Throws:
        EntitlementApiException - if the system fail to create the List of Entitlement.

      • addEntitlement

        UUID addEntitlement​(UUID bundleId,
                    EntitlementSpecifier spec,
                    org.joda.time.LocalDate entitlementEffectiveDate,
                    org.joda.time.LocalDate billingEffectiveDate,
                    boolean isMigrated,
                    Iterable<PluginProperty> properties,
                    CallContext context)
             throws EntitlementApiException
        Adds an ADD_ON|STANDALONE entitlement to previously created entitlement.

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

        Parameters:
        bundleId - the id of the bundle
        spec - the product specification for that new entitlement
        entitlementEffectiveDate - the date at which the entitlement should start. if this is null this is assumed now
        billingEffectiveDate - the date at which the billing for the subscription should start. if this is null this is assumed now
        isMigrated - whether this subscription comes from a different system (migrated into Kill Bill)
        properties - plugin specific properties
        context - the context
        Returns:
        the entitlement id created
        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,
           Iterable<PluginProperty> properties,
           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 -
        properties - plugin specific properties
        context -
        Throws:
        EntitlementApiException - if the system fail to find the base Entitlement

      • resume

        void resume​(UUID bundleId,
            org.joda.time.LocalDate effectiveDate,
            Iterable<PluginProperty> properties,
            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 -
        properties - plugin specific properties
        context -
        Throws:
        EntitlementApiException - if the system fail to find the base Entitlement

      • getEntitlementForId

        Entitlement getEntitlementForId​(UUID id,
                                boolean includeDeletedEvents,
                                TenantContext context)
                         throws EntitlementApiException
        Retrieves an Entitlement using its id.
        Parameters:
        id - the id of the entitlement
        includeDeletedEvents - flag that specifies whether deleted events should be returned
        context - the context
        Returns:
        the entitlement
        Throws:
        EntitlementApiException - if the entitlement does not exist

      • getAllEntitlementsForAccountIdAndBundleExternalKey

        List<Entitlement> getAllEntitlementsForAccountIdAndBundleExternalKey​(UUID accountId,
                                                                     String bundleExternalKey,
                                                                     TenantContext context)
                                                              throws EntitlementApiException
        Retrieves all the Entitlement for a given account and matching an external key.
        Parameters:
        accountId - the account id
        bundleExternalKey - the bundle external key
        context - the context
        Returns:
        a list of entitlements
        Throws:
        EntitlementApiException - if the account does not exist

      • transferEntitlements

        UUID transferEntitlements​(UUID sourceAccountId,
                          UUID destAccountId,
                          String bundleExternalKey,
                          org.joda.time.LocalDate effectiveDate,
                          Map<UUID,​String> subExtKeys,
                          BcdTransfer bcdTransfer,
                          Iterable<PluginProperty> properties,
                          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
        bundleExternalKey - the bundle external key for the bundle
        effectiveDate - the date at which this transfer should occur
        subExtKeys - an optional map to set subscription external keys
        bcdTransfer - a policy to determine how to transfer per-subscription BCD values
        properties - plugin specific properties
        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 bundleExternalKey,
                                               org.joda.time.LocalDate effectiveDate,
                                               Map<UUID,​String> subExtKeys,
                                               BillingActionPolicy billingPolicy,
                                               BcdTransfer bcdTransfer,
                                               Iterable<PluginProperty> properties,
                                               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
        bundleExternalKey - the bundle external Key for the bundle
        effectiveDate - the date at which this transfer should occur
        subExtKeys - an optional map to set subscription external keys
        bcdTransfer - a policy to determine how to transfer per-subscription BCD values
        billingPolicy - the override billing policy
        properties - plugin specific properties
        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