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).

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

{
  "@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.

{
  "@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

{
  "@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"
}

Last updated