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 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).
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
Headers
Request Body
{"@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
Headers
{"@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": { ... } } ]]