The EntitlementPluginApi exists to develop
entitlement plugins. Those plugins are called from the core entitlement system to provide a way for the plugins to intercept any of the subscription operations (e.g., intercept creation/cancellation, etc. for subscriptions). This is similar to the PaymentControlPluginApi, but instead of intercepting payment calls, this intercepts subscription-related calls.
Each of the individual APIs take the following parameters:
context: Provides the full
EntitlementContextassociated with the (set of) subscription(s) (account, operation type, etc.)
properties: A list of
PluginPropertythat are passed all the way from the client making the API call to the plugin. The properties can control a plugin in order to achieve the desired result as well as provide additional state (in addition to the basic subscription state) to other plugins.
Implementers of such plugins need to implement the following APIs:
priorCall: This is the method that will be invoked prior doing any subscription operation. This method will return a
EntitlementContextthat will allow to:
abort the call if desired
adjust the parameters for the call (e.g use a different
Planto create a subscription, or creates a price override, …)
onSuccessCall: This is invoked after the subscription operation was executed successfully. This method will return a
OnSuccessEntitlementResultwhich is currently set to an empty result
onFailureCall: This is invoked after the subscription operation failed to execute successfully. This method will return
OnFailureEntitlementResult, which is also set to an empty result.
If registering multiple entitlement plugins, there is no guarantee on the ordering of which one will be invoked first; therefore it is not recommended to have multiple plugins implement the
EntitlementPluginApi and active on the same deployement.
There are many use cases that can benefit from this API:
Any logic that requires changing price information on the fly (i.e., right before the subscription is created. A demo coupon plugin that highlights such a mechanism.
Any logic that requires creating state associated with the subscriptions (e.g., adding custom fields to such subscriptions).
Any logic that requires dynamically creating a (catalog)
Planand using such plans for the subscription calls. In this case, this would also require a catalog plugin, but this is also where things can become powerful and interesting.