How to create and propagate Entitlements with Limio

Subscribers typically want to receive access to their purchase as soon as the purchase is confirmed. This can be challenging when there are multiple systems in the order provisioning or fulfilment process. Enter Limio Entitlement! As the commerce platform, Limio is the first to know about successful purchases and can therefore provision real-time webhooks to Access and Identity platforms to grant specific features.

Entitlements are the features or access that a customer gets when subscribing to a particular product. For example, entitlements could be used to ensure that a basic subscriber gets an online product, whereas a gold subscriber gets an online product plus a physical product and online support.

Creating and mapping Entitlements

To create an Entitlement within Limio, click Entitlements on the Catalog side menu. Click on the "+" button, then "Add Entitlements". Make sure to give the Entitlement a name and a label. A code can also be provided to identify the Entitlement within a system external to Limio. 

To associate an Entitlement to a product, click Products on the Catalog side menu. Click on your desired Product, then click on the Entitlements tab. Select your desired Entitlement from the list, and press the Save button in the top right corner.

From there, the Entitlement will map to Offers through the Product. Ultimately, Subscriptions will have the Offer. See a full diagram:

Propagating an Entitlement to other systems

Once the webhook endpoint is setup (How to implement webhooks to track events), Limio will automatically fire entitlements for New Orders, Switch and Cancel/Save. Here is an example of entitlement webhooks sent to Salesforce.

The payload will be of the format below. Note that the identities part of the payload will depend on your authentication provider (How to set up your Authentication provider on Limio)

For a New Order, the payload will look like this:

{
"tracking": { "subscription": "32439PDFQPA0" },
"updated": "2022-07-05T06:58:53.046Z",
"owner": "id-c6281aebbe25728aae1b6223e87f7b2b",
"identities": [
{ "sub": "92779261-f615-4fc6-9fdd-8b71d59b8f0f", "iss": "https://limio-v4.api.zephr.com", "service": "zephr", "type": "user_id" },
{ "sub": "0c2ab33e-97c3-4a68-8b19-e5bdedd37d0f", "iss": "https://limio-v4-daniel-test.cdn.zephr.com/" }
],
"entitlements": [{ "code": "W2" }]
}

For a Switch, you will also find the Effective Date (the date at which the upgrade or downgrade will happen):

{
"tracking":{"subscription":"Digital Annual Switch"},
"effectiveDate":"2023-11-16T00:00:00.000",
"updated":"2022-11-23T16:51:00.206Z",
"owner":"id-438655aadfd9f8855ace51122089688f",
"entitlements":[{"code":"SKU0010002"}],
"identities":[
{"sub":"0012600001mdRaSAAU","iss":"salesforce","service":"salesforce","type":"account"},
{"sub":"d0298190-d8ab-463c-a47f-3e83896c41d2","iss":"https://admin.staging.which-account.blaize.io","service":"zephr","type":"user_id"}
]
}

You can see webhooks in the Limio UI by going to /objects/webhooks/limio .

Please note that previous to Release 86.0, "service" and "type" in the webhook payloads above will appear as "https://limio.com/service" and "https://limio.com/type".

Release 89.0 +

For customers on release 89.0 and above the body of webhooks are updated to include the source of the order i.e. "shop" or "salesforce" and the order name related to the event; see the below example payload: 

{
"tracking": { "subscription": "32439PDFQPA0", "source": "shop", "name": "13L04SESPHMG", "orderReference": "13L04SESPHMG"},
"updated": "2022-07-05T06:58:53.046Z",
"owner": "id-c6281aebbe25728aae1b6223e87f7b2b",
"identities": [
{ "sub": "92779261-f615-4fc6-9fdd-8b71d59b8f0f", "iss": "https://limio-v4.api.zephr.com", "https://limio.com/service": "zephr", "https://limio.com/type": "user_id" },
{ "sub": "0c2ab33e-97c3-4a68-8b19-e5bdedd37d0f", "iss": "https://limio-v4-daniel-test.cdn.zephr.com/" }
],
"entitlements": [{ "code": "W2" }]
}