-
Notifications
You must be signed in to change notification settings - Fork 4
Integration flow for Partners
This document is addressed towards our integration partners. Quick links to navigate:
- APIs walk through and live Headout site parallels
- Product flow with integration suggestion to partners
- Major FAQs
Sample url: https://www.headout.com/api/v1/product/listing/list-by/city?cityCode=DUBAI
Documentation link: https://github.com/headout/api-docs/blob/master/apis/product.md#GET-/product/listing/list-by/city
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/product-models.md#product-listing
This API returns list of all Headout products in a particular city. A parallel in headout live website can be found here where we list products in Dubai and paginate the product results. An item in product list response is a subset of product model with basic information about a single product. Note the cityCode param in the url. This param can accept all headout live city codes (Ex: DUBAI, ABU_DHABI, NEW_YORK). Also note that pricing information is not a part of this API.
Future additions:
- We will add a new API soon which will give out list of all Headout live cities and their info.
Sample url: https://www.headout.com/api/v1/product/get/1866
Documentation link: https://github.com/headout/api-docs/blob/master/apis/product.md#GET-/product/get/%7Bproduct_id%7D
Corresponding Model link: https://github.com/headout/api-docs/blob/master/object-models/product-models.md
This API returns all details of a Headout product. Find the link to Headout live product parallel here. All the content visible in the product page in our site comes from the product API (this includes images, text description, faqs, reviews etc). Product api contains the details of all variants of a single product. Each variant gives different experience for end users and inventory/pricing details needs to be fetched for all variants separately. Ex: Given Sample url response has three variants 'Skip the Line' (id: 2636), 'Sunrise' (id: 2637), 'General Admission' (id: 2638). Each variant has its own inventory and pricing types. Refer the details here Each variant has its own set of input fields that needs to be filled out by user for a successful checkout. User responses for all input fields needs to be sent as part of the booking request. Refer more details here. Note that pricing and inventory information is not a part of this API.
Sample url: https://www.headout.com/api/v1/inventory/list-by/variant?variantId=2636&forDays=30
Documentation link: https://github.com/headout/api-docs/blob/master/apis/inventory-pricing.md
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/inventory-pricing-models.md
This API returns inventory details of a variant. Major verticals of inventory are Date and Time. Once fetched for all variants, data from inventory API can be used to give out a product flow similar to the one you can find in our Headout web app. Checkout the product flow post content page here. Note the forDays param in the API. This param can be used to fetch inventory for forDays number of days from the date api fetch is requested to product. Note that inventory becomes highly volatile (both from pricing and availability standpoint) (We maintain active inventory of ~90days for each product). Inventory must be actively refreshed for all variants to maintain pricing and availability accuracy. (TODO: what is the default forDays?) We have different types of inventory and pricing constructs which might dictate the user checkout experience. You can go through the differences [here]
Sample url: https://www.headout.com/api/v1/booking/create
Documentation url: https://github.com/headout/api-docs/blob/master/apis/booking.md
Corresponding model link: https://github.com/headout/api-docs/blob/master/object-models/booking-models.md
TODO: Auth TODO: 2 step TODO: Enquiry TODO: Cancel TODO: Booking fetch TODO: Error codes
Product flow starts with city level decisions. For now, we assume that your application, at any given point, shows products of only one city. Assuming that the user selects a city in your application, you can list Headout products that are live in the selected city (Ex: Headout product list page). (Api to fetch Headout live cities is WIP).
City codes for major cities:
- New York - NEW_YORK
- Dubai - DUBAI
- Abu Dhabi - ABU_DHABI
Products in a particular city can be fetched using our product list api. The order of products in the api is decided based on best selling and trending patterns. We advise our partners to retain the order of products.
Note: If your application shows products of different cities at once (Ex: a portal which lists Dubai and Abu Dhabi products together), let us know so that we can provision another product list api which gives out list of products from any number of cites together. This can be done using two separate fetches from our product list api too but the order of products post the merge needs to be handled yourselves.
Once a user selects a product, user is taken to a product page (Ex: Headout live page - https://www.headout.com/tour/1866). The product page can make use of content from our product content api to showcase and explain the product to the end customer.
Once a user selects a product, we expect three decisions from the user before going to the checkout page.
- Variant of the experience
- Date of the experience
- Time of the experience
Internally these are represented by the inventory id from the inventory fetch api of a particular variant.
UX flow can be designed with any combinations of above. Headout live site of our major products follows below paradigm:
- Date of the product needs to be selected first. This date is the possible date user can experience (A merge of inventory details of all variants of a particular product)
- Variant and time - Once a user selects a date, we showcase all variants and time combinations for that particular date together. Another combination is to get user to select variant (or time) of possible variants (or times) for the selected data before proceeding with the third option.
A sample flow can be found here
Once the user selects a product-inventory(variant-date-time) unit, we proceed to ask user for number of tickets he wants to purchase. Note that the number of possible tickets customer can purchase need to be capped from the inventory data. Inventory can be of two types - per-person and per-group. In a per-person type, we have different profiles or ticket types that user can purchase (typical being Adult, Child etc). In a per-group type, user need to purchase bulk tickets of single type. Majority of Headout products (~95%) follow per-person pricing. We advise partners to integrate per-person products into their system first (i.e, manually filter our per-group products from product list api) and include per-group products in subsequent version.
Once user selects, product-inventory-pax we proceed to collect input from user as per input-fields requirement from the product fetch api. Email, Full name, Phone number are mandatory fields from Primary user that will always be in input-fields data of a product. (Note that primary user and email address are the ones which will be used to log the booking in our system and tickets are expected to be used by. Secondary users are other folks accompanying the primary user to the experience when pax > 1) It is advised to integrate input fields into the booking flow to avoid delay in ticket delivery to customers post booking. But partners can let us know if the integration for input fields needs to be standardised for version 1 rollout and we can provide a variant of booking api and product flow which doesn't use input fields as above.
TODO: Booking flow
Given that we provide a lot of products in a single city we advise caching our api responses for better user experience. Sample effective way of caching and usage.
- All product list api responses for a single city are fetched and saved (preserving the order) The refresh rate can be 1day. Lesser the better to capture last minute events
- Product content fetches are done for all products in the city and cached. Refresh rate can be 1day. Lesser the better to capture our live media and content changes
- Product inventory fetches are done for all products in the city for next 90 days. Refresh can be 5-10minutes. Lesser the better to capture inventory and pricing details properly. If user sees a stale price, booking fails from our end.
- When showcasing products to user, use the cached inventory data to filter out products. Primary filter is to remove products which doesnt have inventory. Any other filters like date range, date, time range etc can be applied and products that doesnt match the criteria can be removed using cached inventory data.
TODO: Auth keys TODO: Contact info