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 endpoint.
Linked Accounts
When a Customer's Broker Entitlement is set, it is also fanned out to its (as long as the Broker Entitlement maps onto a Seller Entitlement for that Seller).
Integration with Search
Use the 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
GEThttps://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.
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.
{
"@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": { ... }
}
]
}
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
{
"@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": { ... }
}
]
]
