Entitlement

Manage a Customer's Entitlement

A Customer's Entitlement gives it access to better deals. For example, a Customer may have an Acme Young Person Discount Entitlement if their age is below or equal to 22. This Entitlement may give them a special 20%-off Offer for Swim & Gym sessions.

You, the Broker, determine what Entitlement a Customer may have access to. You can manage these using the APIs herein.

Initial Set-up

There are two types of Entitlements, which are both required in order to unlock special offers:

• Broker Entitlements: Entitlements that you, the Broker, determine and manage.

• Seller Entitlements: Entitlements that each Seller (e.g. Acme Leisure Centre) determines and manages.

You must agree with us, beforehand:

• A list of your Broker Entitlements

• A mapping which maps from each of these to a list of Seller Entitlements.

A Customer can only make use of a Broker Entitlement when it maps onto a Seller Entitlement for the Seller that they are purchasing an Opportunity with.

When these are agreed, the resulting data will be found in the Get All Broker Entitlements endpoint.

Linked Accounts

When a Customer's Broker Entitlement is set, it is also fanned out to its Linked Accounts (as long as the Broker Entitlement maps onto a Seller Entitlement for that Seller).

Integration with Search

Use the Entitlement Pricing in Search in order to show a Customer's Entitlement prices at Search.

All requests that require the X-Api-Key header must be made Server-side. Otherwise, it would be possible to view the secret API key with a browser.

Get All Broker Entitlements

GET https://book.imin.co/api/v2/entitlements

A list of all your Broker Entitlements that we have pre-agreed. Each entitlement has an @id, which is persistent and therefore suitable for hard-coding if necessary.

Headers

Name	Type	Description
X-Api-Key	string	API Key

200 In this example, the Broker who is making the request is called "Globex" and has this pre-agreed list of Entitlements:

{
  "@context": "https://openactive.io/",
  "id": "https://meta.imin.co/v2/globex/entitlements",
  "title": "Entitlements for Globex",
  "type": "ConceptScheme",
  "license": "https://creativecommons.org/licenses/by/4.0/",
  "concept": [
    {
      "id": "https://meta.imin.co/v2/globex/entitlements#228f7f70-6c42-4b10-b3cb-621b63ea2732",
      "type": "Concept",
      "prefLabel": "Globex Adult Resident"
    },
    // ...
  ]
}

Set Entitlement

POST https://book.imin.co/api/v2/customer-accounts/:customerIdentifier/actions

Update a Customer's Entitlement. This Entitlement is also fanned out to all of the Customer's Linked Accounts. If a different Entitlement has been set previously, it is removed and replaced with this one (both in imin and in Linked Accounts).

Path Parameters

Name	Type	Description
customerIdentifier	string	Customer Identifier

Headers

Name	Type	Description
X-Api-Key	string	API Key

Request Body

Name	Type	Description
object.validUntil	string	ISO-8601 Datetime - when the Entitlement will expire.
object.entitlementType	string	The ID of the Entitlement to apply to this Customer. Note that this is the ID of the Broker Entitlement.

200 The Entitlement was successfully updated in imin. The error field includes any errors that occurred for updating the Entitlement in any of the Linked Accounts. If there is no error associated with a given Seller, then the Customer's Entitlement was successfully updated in the Customer's Linked Account within that Seller. If this list is empty, then all Linked Accounts were updated successfully ✅

{
  "@context": "https://openactive.io/",
  "@type": "imin:EntitlementUpdateAction",
  "actionStatus": "https://schema.org/CompletedActionStatus",
  "object":  {
    "@type": "Entitlement",
    "validUntil": "2021-05-10T10:45:33+00:00",
    "entitlementType": {
      "id": "https://meta.imin.co/v2/globex-broker/entitlements#8dfbad55-fdb5-4479-86a4-b873b18ecff1",
      "type": "Concept",
      "prefLabel": "Adult Resident"
    }
  },
  // 👇 included if there was an error applying this entitlement for any Linked Account
  "error": [
    {
      "@context": "https://openactive.io/",
      "@type": "EntitlementConflict",
      "name": "The entitlement cannot be applied due to other entitlements already associated with the Customer.",
      "description": "This customer already has a paid monthly membership",
      "seller": { ... }
    }
  ]
}

Request Example:

{
  "@context": "https://openactive.io/",
  "@type": "imin:EntitlementUpdateAction",
  "object": {
    "@type": "Entitlement",
    "validUntil": "2021-05-10T10:45:33+00:00",
    "entitlementType": "https://meta.imin.co/v2/globex-broker/entitlements#8dfbad55-fdb5-4479-86a4-b873b18ecff1"
  }
}

Delete Entitlement

POST https://book.imin.co/api/v2/customer-accounts/:customerIdentifier/actions

Remove the Entitlement from this Customer in imin and each of the Customer's Linked Accounts.

Path Parameters

Name	Type	Description
customerIdentifier	string	Customer Identifier

Headers

Name	Type	Description
X-Api-Key	string	API Key

200 The Entitlement was successfully removed in imin. The error field includes any errors that occurred for removing the Entitlement in any of the Linked Accounts. If there is no error associated with a given Seller, then the Customer's Entitlement was successfully removed in the Customer's Linked Account within that Seller. If this list is empty, then the Entitlement was successfully removed from all Linked Accounts ✅

{
  "@context": "https://openactive.io/",
  "@type": "imin:EntitlementRemovalAction",
  "actionStatus": "https://schema.org/CompletedActionStatus",  
  // 👇 included if there was an error applying this entitlement for any Linked Account
  "error": [
    {
      "@context": "https://openactive.io/",
      "@type": "EntitlementConflict",
      "name": "The entitlement cannot be removed due to other entitlements already associated with the Customer.",
      "description": "This customer already has a paid monthly membership",
      "seller": { ... }
    }
  ]
]

Request Example:

{
  "@context": "https://openactive.io/",
  "@type": "imin:EntitlementRemovalAction"
}