Example Scenario

Let's work through a scenario in which a user takes certain actions on the client side and look at how you can ensure these are reflected on the imin side.

First things first, you need to make sure the user exists in the system. For this, an account for a customer will need to be created on the client side. In turn, a call will be made to the imin Customer Account Management APIs to create that customer on our side. If at any point that customer updates or deletes their account, this will need to be reflected on our side using the suite of Customer Account Management APIs.

X-API-KEY must be provided when making the request to update a customer. This authorises you to access the API.

This will allow you to use the Authenticated Checkout, but instead of including the customer's info in the Authenticated Checkout Request Webhook, you use the Customer Identifier included in the Response Webhook that you get back from the Create Customer Account endpoint. Let's take a look at an example:

1. Louis creates a new account using Acme Fitness' user facing platform. At the backend, you call the Create Customer Account endpoint to create a record for Louis at the imin side:

POST https://book.imin.co/api/v2/customer-accounts
{
  "email": "[email protected]",
  "givenName": "Louis",
  "familyName": "Wu",
  "imin:is13OrOver": false
}

You will get a response like this:

{
  "type": "Person",
  "email": "[email protected]",
  "givenName": "Louis",
  "familyName": "Wu",
  "imin:is13OrOver": false,
  "identifier": "MAlnTNiZut",
  "id": "https://book.imin.co/api/v2/customer-accounts/MAlnTNiZut"
}

So the imin identifier for Louis is MAlnTNiZut.

2. If Louis were to update his account information (e.g. his email address) on Acme Fitness, you need to update that customer on our side, too, using the Update Customer Account endpoint:

PATCH https://book.imin.co/api/v2/customer-accounts/MAlnTNiZut
{
   "email": "[email protected]"
}

3. Louis does a search on the Acme Fitness activity finder and finds a session he wants to book. He hits "Book Now" (or whatever the button is called). Because Louis is already logged into his account on Acme Fitness, you know that Louis is imin identifier = MAlnTNiZut.

4. You use Louis' identifier in all Authenticated Checkout requests:

POST https://checkout.yourapp.com/api/checkout-sessions
{
	"@context": [
		"https://openactive.io/",
		"https://imin.co/"
	],
	"type": "imin:CheckoutSession",
	"imin:initialOrder": {
		"type": "OrderQuote",
		"customer": "https://book.imin.co/api/v2/customer-accounts/MAlnTNiZut",
		"broker": {
			"type": "Organization",
			"name": "Acme Fitness",
			"url": "acmefitness.co.uk"
		},
		"orderedItem": [
			{
				"type": "OrderItem",
				"acceptedOffer": "http://opendata.provider.com/api/feeds/offers/adult",
				"orderedItem": {
					"type": "ScheduledSession",
					"identifier": "http://opendata.provider.com/api/feeds/scheduled-sessions/00000000000000001741"
				}
			}
		]
	},
	"imin:navigationLinks": [
		{
			"type": "WebPage",
			"name": "Back to Broker",
			"imin:linkType": "https://imin.co/BackToBrokerLink",
			"url": "https://www.imin.co/bookingsuccess"
		},
		{
			"type": "WebPage",
			"name": "Back to Broker User Profile",
			"imin:linkType": "https://imin.co/BackToBrokerUserProfileLink",
			"url": "https://www.imin.co/useraccounts/12345"
		}
	]
}

Where the orderedItem.acceptedOffer is the price level Louis chooses on the Acme Fitness activity finder before seeing the imin Branded Checkout, and orderedItem.identifier is from the specific subEvent of the session he wants to book.

5. You will get a response with a potentialAction.target URL that you load for Louis. He completes the Checkout steps, pays for his session, and gets a confirmation screen followed by a confirmation email to [email protected].

6. When Louis goes into his account page on Acme Fitness, you can use any of the Order (by ID), Upcoming OrderItems or Order History endpoints with his identifier. For example:

GET https://book.imin.co/api/v2/order-items?customerIdentifier=MAlnTNiZut