diff --git a/apis/booking.md b/apis/booking.md index a7ad4cb..cdabf55 100644 --- a/apis/booking.md +++ b/apis/booking.md @@ -75,7 +75,7 @@ List all bookings. ### GET `/booking/{id}` -Get a booking by it's ID. +Get a booking by its ID. #### Request @@ -137,7 +137,7 @@ Get a booking by it's ID. Create a new booking object in `UNCAPTURED` state. -The booking creation and acceptance flow is a 2 step flow. Calling this API creates the initial booking in `UNCAPTURED` state and returns back the same booking along with the new booking id. You should call this API before fulfilling the booking flow on your end. Once you get a response, you can then fulfill the booking flow on your end and then call [`PUT /booking`](#PUT-/booking) to capture the booking and start the fulfillment process of the booking on our end. +The booking creation and acceptance flow is a 2-step flow. Calling this API creates the initial booking in `UNCAPTURED` state and returns back the same booking along with the new booking id. You should call this API before fulfilling the booking flow on your end. Once you get a response, you can then fulfill the booking flow on your end and then call [`PUT /booking`](#PUT-/booking) to capture the booking and start the fulfillment process of the booking on our end. If the booking capturing doesn't happen within an hour then the booking status is automatically changed to `CAPTURE_TIMEOUT`. @@ -222,7 +222,7 @@ If the booking capturing doesn't happen within an hour then the booking status i ### PUT `/booking/{id}` -Used to modify a booking. Currently this is only used for capturing the booking and assigning a `partnerReferenceId`. Use this method to capture the booking by specifying the status as `PENDING`. The booking will be fulfilled on our end only once you capture it. +Used to modify a booking. Currently, this is only used for capturing the booking and assigning a `partnerReferenceId`. Use this method to capture the booking by specifying the status as `PENDING`. The booking will be fulfilled on our end only once you capture it. #### Request diff --git a/apis/category.md b/apis/category.md index 926de54..0170c34 100644 --- a/apis/category.md +++ b/apis/category.md @@ -4,9 +4,9 @@ ## APIs -METHOD | URL | AUTH | USAGE ---- | --- | --- | --- -GET | [`/category/list-by/city`](#GET-/category/list-by/city) | no | List all categories by city. +| METHOD | URL | AUTH | USAGE | +|--------|---------------------------------------------------------|------|------------------------------| +| GET | [`/category/list-by/city`](#GET /category/list-by/city) | no | List all categories by city. | ### GET `/category/list-by/city` @@ -14,17 +14,17 @@ List all categories by city. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -QUERY | cityCode | string | no | The city code. Eg: `NEW_YORK`, `DUBAI` -QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|-------|----------|--------|----------|--------------------------------------------------------------------------------------------------------------------| +| QUERY | cityCode | string | no | The city code. Eg: `NEW_YORK`, `DUBAI` | +| QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | #### Response **Object:** [`category`](/object-models/category-models.md#category) -```javascript +```json { "items": [ { diff --git a/apis/city.md b/apis/city.md index b1095ab..a0bd902 100644 --- a/apis/city.md +++ b/apis/city.md @@ -4,9 +4,9 @@ ## APIs -METHOD | URL | AUTH | USAGE ---- | --- | --- | --- -GET | [`/city`](#GET-/city) | no | List all the active cities. +| METHOD | URL | AUTH | USAGE | +|--------|-----------------------|------|-----------------------------| +| GET | [`/city`](#GET~/city) | no | List all the active cities. | ### GET `/city` @@ -14,16 +14,16 @@ List all the active cities. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|-------|--------|--------|----------|--------------------------------------------------------------------------------------------------------------------| +| QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | #### Response **Object:** [`city`](/object-models/common-models.md#city) -```javascript +```json { "items": [ { diff --git a/apis/inventory-pricing.md b/apis/inventory-pricing.md index 3485a2e..bdd1714 100644 --- a/apis/inventory-pricing.md +++ b/apis/inventory-pricing.md @@ -4,9 +4,9 @@ ## APIs -METHOD | URL | AUTH | USAGE ---- | --- | --- | --- -GET | [`/inventory/list-by/variant`](#GET-/inventory/list-by/variant) | no | Get the available inventory for a variant. +| METHOD | URL | AUTH | USAGE | +|--------|-----------------------------------------------------------------|------|--------------------------------------------| +| GET | [`/inventory/list-by/variant`](#GET-/inventory/list-by/variant) | no | Get the available inventory for a variant. | ### GET `/inventory/list-by/variant` @@ -14,24 +14,24 @@ Get the available inventory for a variant. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -QUERY | variantId | string | no | The ID of the variant for which the inventory needs to be fetched. -QUERY | startDateTime | string | yes | The start date time from which the inventory needs to be fetched. If unspecified then the current timestamp is taken into consideration. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* -QUERY | endDateTime | string | yes | The end date time till which the inventory needs to be fetched. If unspecified then this is taken as infinity. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* -QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|-------|---------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| QUERY | variantId | string | no | The ID of the variant for which the inventory needs to be fetched. | +| QUERY | startDateTime | string | yes | The start date time from which the inventory needs to be fetched. If unspecified then the current timestamp is taken into consideration. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* | +| QUERY | endDateTime | string | yes | The end date time till which the inventory needs to be fetched. If unspecified then this is taken as infinity. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* | +| QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* | #### Response **Object:** [`pagination-wrapper`](/object-models/common-models.md#pagination-wrapper)`<`[`inventory`](/object-models/inventory-pricing-models.md#inventory)`>` -```javascript +```json { "items": [ { - "id": "1212121" + "id": "1212121", "startDateTime": "2017-03-30T15:30:00", "endDateTime": "2017-03-30T15:30:00", "availability": "LIMITED/UNLIMITED/CLOSED", diff --git a/apis/product.md b/apis/product.md index e9a8706..4e72b3e 100644 --- a/apis/product.md +++ b/apis/product.md @@ -4,11 +4,11 @@ ## APIs -METHOD | URL | AUTH | USAGE ---- | --- | --- | --- -GET | [`/product/get/{product_id}`](#GET-/product/get/{product_id}) | no | Get product by `id`. -GET | [`/product/listing/list-by/city`](#GET-/product/listing/list-by/city) | no | List product listing by city -GET | [`/product/listing/list-by/category`](#GET-/product/listing/list-by/category) | no | List product listing by category +| METHOD | URL | AUTH | USAGE | +|--------|-------------------------------------------------------------------------------|------|----------------------------------| +| GET | [`/product/get/{product_id}`](#GET-/product/get/{product_id}) | no | Get product by `id`. | +| GET | [`/product/listing/list-by/city`](#GET-/product/listing/list-by/city) | no | List product listing by city | +| GET | [`/product/listing/list-by/category`](#GET-/product/listing/list-by/category) | no | List product listing by category | ### GET `/product/get/{product_id}` @@ -16,20 +16,20 @@ Gets a product by `productId`. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -PATH | product-id | string | no | Product id +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|------|------------|--------|----------|-------------| +| PATH | product-id | string | no | Product id | #### Response **Object:** [`product`](/object-models/product-models.md#product) -```javascript +```json { "id": 512, "name": "Wicked", - "neighbourhood": "Theatre District", - "city": { + "neighbourhood" : "Theatre District", + "city" : { "code": "NEW_YORK", "name": "New York" }, @@ -38,7 +38,7 @@ PATH | product-id | string | no | Product id "name": "United States Dollar", "symbol": "US$", "localSymbol": "$", - "precision": 2, + "precision": 2 }, "images": [ { @@ -70,15 +70,15 @@ PATH | product-id | string | no | Product id "endLocation": { "geo": { "latitude": 40.762393951416016, - "longitude": -73.9851303100586, - } + "longitude": -73.9851303100586 + }, "address": { "line1": "The Gershwin Theatre", "ine2": "222 W 51st Street", "cityName": "New York", "stateName": "New York", "countryName": "United States", - "postalCode": "10036", + "postalCode": "10036" } }, "productType": "EVENT", @@ -98,11 +98,11 @@ PATH | product-id | string | no | Product id "priceType": "PER_PERSON", "pax": { "min": 1, - "max": 9, + "max": 9 }, "cashback": { "value": 10, - "type": "PERCENTAGE", + "type": "PERCENTAGE" }, "ticketDeliveryInfoHtml": "

Your booking confirmation will be emailed to you shortly.

", "inputFields": [ @@ -111,19 +111,19 @@ PATH | product-id | string | no | Product id "name": "Name", "dataType": "STRING", "level": "PRIMARY_CUSTOMER", - "validation": [ - "required": true, + "validation": { + "required" : true, "regex": "\\s*[^\\s]+\\s+[^\\s]+.*", "minLength": 3, "maxLength": 80, "minValue": null, "maxValue": null, - "values": [ + "values" : [ "Vegetarian", - "Non-vegeratian", + "Non-vegetarian", "Diabetic" ] - ] + } } ] } @@ -137,18 +137,18 @@ List product listing using city. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -QUERY | cityCode | string | no | The city code. Eg: `NEW_YORK`, `DUBAI` -QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|-------|--------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| QUERY | cityCode | string | no | The city code. Eg: `NEW_YORK`, `DUBAI` | +| QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* | #### Response **Object:** [`pagination-wrapper`](/object-models/common-models.md#pagination-wrapper)`<`[`product-listing`](/object-models/product-models.md#product-listing)`>` -```javascript +```json { "items": [ { @@ -182,8 +182,8 @@ QUERY | currencyCode | string | yes | The currency in which pricing information "currencyCode": "AED", "minimumPrice": { "originalPrice": 551, - "finalPrice": 518, - } + "finalPrice": 518 + }, "bestDiscount": 28 } } @@ -201,18 +201,18 @@ List product listing using category. #### Request -MODE | KEY | TYPE | OPTIONAL | DESCRIPTION ---- | --- | --- | --- | --- -QUERY | categoryId | string | no | The id of the category. -QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* -QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* +| MODE | KEY | TYPE | OPTIONAL | DESCRIPTION | +|-------|--------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| QUERY | categoryId | string | no | The id of the category. | +| QUERY | offset | string | yes | The offset for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | limit | int | yes | The limit for pagination. *Ref: [Pagination - Request Params](/conventions/basics.md#Pagination--Request-Params)* | +| QUERY | currencyCode | string | yes | The currency in which pricing information will be returned. Eg: `USD`, `AED`. *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* | #### Response **Object:** [`pagination-wrapper`](/object-models/common-models.md#pagination-wrapper)`<`[`product-listing`](/object-models/product-models.md#product-listing)`>` -```javascript +```json { "items": [ { @@ -246,8 +246,8 @@ QUERY | currencyCode | string | yes | The currency in which pricing information "currencyCode": "AED", "minimumPrice": { "originalPrice": 551, - "finalPrice": 518, - } + "finalPrice": 518 + }, "bestDiscount": 28 } } diff --git a/conventions/api-naming-scheme.md b/conventions/api-naming-scheme.md index 36057a7..e0da235 100644 --- a/conventions/api-naming-scheme.md +++ b/conventions/api-naming-scheme.md @@ -10,14 +10,14 @@ The API naming is structured into 4 components. Resource, view, action and filte ##### Definition -Resource specifies a particular model which has it's own identity. Typically a resource will always have a `id` and it will make sense to refer these resources by their IDs and do operations over them. +Resource specifies a particular model which has its own identity. Typically, a resource will always have a `id` and it will make sense to refer these resources by their IDs and do operations over them. ##### Usage The resource is the first part of the API structure (excluding the versioning). ##### Example -`/product/get/{id}`: Refers to the `product` resource identified by the [`product`](/object-models/product-models.md#product) which is being fetched by it's ID. +`/product/get/{id}`: Refers to the `product` resource identified by the [`product`](/object-models/product-models.md#product) which is being fetched by its ID. ### View @@ -47,11 +47,11 @@ A view can occur **only** after a resource. ##### Definition -An action defines the verb which needs to be performed on the resource or on it's view. Each action has a specific functionality. +An action defines the verb which needs to be performed on the resource or on its view. Each action has a specific functionality. -* `get`: Used to fetch the resource or it's view using the ID of the resource. It is mandatory to have `{id}` **immediately after** this action. -* `list`: Used to fetch a list of the resource or it's view using multiple IDs of the resource. It is mandatory to have `ids` as a **query param** for this action. -* `list-by`: Used to fetch a list of the resource or it's view which is filtered by the subsequent filter. The filer criteria is always input in the query params. *Ref: [Filter](#filter)* +* `get`: Used to fetch the resource, or it's view using the ID of the resource. It is mandatory to have `{id}` **immediately after** this action. +* `list`: Used to fetch a list of the resource, or it's view using multiple IDs of the resource. It is mandatory to have `ids` as a **query param** for this action. +* `list-by`: Used to fetch a list of the resource, or it's view which is filtered by the subsequent filter. The filer criteria is always input in the query params. *Ref: [Filter](#filter)* * `create`: Used to create a resource. ##### Usage @@ -60,7 +60,7 @@ An action can occur **only** after either a resource or it's view. ##### Example -`/product/get/{id}`: Fetch the [`product`](/object-models/product-models.md#product) resource identified by it's ID. +`/product/get/{id}`: Fetch the [`product`](/object-models/product-models.md#product) resource identified by its ID. `/product/listing/list`: Fetches a list of `listing` view ([`product-listing`](/object-models/product-models.md#product-listing)) for the `product` identified by the `product` IDs. This will have a query param `ids`. diff --git a/conventions/basics.md b/conventions/basics.md index 9562205..0bba5ca 100644 --- a/conventions/basics.md +++ b/conventions/basics.md @@ -23,16 +23,16 @@ APIs run over `HTTPS`. If you specify `HTTP`, the url will be redirected to `HTT ### Url Prefix -All APIs are prefixed with `/api/public/v{version_number}`. If the current version number is `1` then the your API prefix will be `/api/public/v1`. All previous APIs which worked under the previous paradigm of `/api/v{version_numer}` will still work but it is recommended to shift to the new url structure. +All APIs are prefixed with `/api/public/v{version_number}`. If the current version number is `1` then the API prefix will be `/api/public/v1`. All previous APIs which worked under the previous paradigm of `/api/v{version_numer}` will still work, but it is recommended to shift to the new url structure. ##### Deprecated -~~All APIs are prefixed with `/api/v{version_number}`. If the current version number is `1` then the your api prefix will be `/api/v1`.~~ +~~All APIs are prefixed with `/api/v{version_number}`. If the current version number is `1` then the api prefix will be `/api/v1`.~~ ## Authentication -There are certain APIs which can only be executed with appropriate authentication/authorization in place. Although there are open APIs which do not required authorization, it is recommended that you provide the authorization for every API call so that you do no need to care about which API mandates it. +There are certain APIs which can only be executed with appropriate authentication/authorization in place. Although there are open APIs which do not require authorization, it is recommended that you provide the authorization for every API call so that you do not need to care about which API mandates it. -Currently the authorization happens via api keys provided to concerned parties. +Currently, the authorization happens via api keys provided to concerned parties. ### API Key based @@ -57,26 +57,26 @@ Our testing sandbox can be accessed at Affiliate platform to receive your api keys via email. +Please sign up on our Affiliate platform to receive your api keys via email. ## Pagination All apis which return a list result implement the pagination contract, until and unless, it's specified otherwise in the API which can only be in the case if the resulting list will theoretically always be small. -#### Request Params +#### Request Params You can provide the following **optional** params in the **query params** to control pagination for any request which supports pagination. -KEY | TYPE | DESCRIPTION ---- | --- | --- -offset | string | The offset from which the page should start. Typically this offset is an integer which starts from `0` and going on till `total - 1`, nevertheless, for cursor based apis this offset might be a cursor based string which may not have any correlation with subsequent keys. Such apis will mention this usage. If unspecified the default offset of `0` or the starting point of the cursor is assumed. -limit | int | The number of elements to be fetched. If unspecified this defaults to `20` unless the API states otherwise. +| KEY | TYPE | DESCRIPTION | +|--------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| offset | string | The offset from which the page should start. Typically this offset is an integer which starts from `0` and going on till `total - 1`, nevertheless, for cursor based apis this offset might be a cursor based string which may not have any correlation with subsequent keys. Such apis will mention this usage. If unspecified the default offset of `0` or the starting point of the cursor is assumed. | +| limit | int | The number of elements to be fetched. If unspecified this defaults to `20` unless the API states otherwise. | #### Response Pagination responses are wrapped with a [`pagination-wrapper`](/object-models/common-models.md#pagination-wrapper). You can use the pagination wrapper to help with navigation along with getting to know other metadata about the current pagination. -```javascript +```json { "items": [], "nextUrl": "https://next-url", diff --git a/conventions/formats.md b/conventions/formats.md index c1dc025..acf4d0c 100644 --- a/conventions/formats.md +++ b/conventions/formats.md @@ -12,4 +12,4 @@ Specifies an ISO 8601 local date time agnostic of timezone. `T` serves as a stat **Format:** milliseconds since epoch (1970-01-01T00:00:00) -Specifies an instance in time which is futher in time by the milliseconds value from epoch (1970-01-01T00:00:00). +Specifies an instance in time which is further in time by the milliseconds value from epoch (1970-01-01T00:00:00). diff --git a/object-models/booking-models.md b/object-models/booking-models.md index 12d263e..fdca68e 100644 --- a/object-models/booking-models.md +++ b/object-models/booking-models.md @@ -13,104 +13,104 @@ Represents the seatmap booking request. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- |------| --- | --- -tourId | int | no | The id of the tour. -seatIds | array | no | The array of seat ids. -inventoryLocalDate | string | no | The local date of the inventory. -inventoryLocalTime | string | no | The local time of the inventory. -customerDetails | [`booking-customers-details`](#booking-customers-details) | no | All the details of the customers partaking in the booking. -variantInputFields | array[[`booking-input-field`](#booking-input-field)] | yes | Variant level input field. For `POST` the values that are required to be submitted are specified in [product-variant.inputFields](product-models.md#product-variant). -price | [`price`](common-models.md#price) | no | The price at which the purchase needs is made. This needs to be submitted in `POST` for backend verification. The submitted currency currently should conform to the currency of the product. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|--------------------|-----------------------------------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| tourId | int | no | The id of the tour. | +| seatIds | array | no | The array of seat ids. | +| inventoryLocalDate | string | no | The local date of the inventory. | +| inventoryLocalTime | string | no | The local time of the inventory. | +| customerDetails | [`booking-customers-details`](#booking-customers-details) | no | All the details of the customers partaking in the booking. | +| variantInputFields | array[[`booking-input-field`](#booking-input-field)] | yes | Variant level input field. For `POST` the values that are required to be submitted are specified in [product-variant.inputFields](product-models.md#product-variant). | +| price | [`price`](common-models.md#price) | no | The price at which the purchase needs is made. This needs to be submitted in `POST` for backend verification. The submitted currency currently should conform to the currency of the product. | ### `booking` Represents the complete booking object. -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- |------------| --- -bookingId | string | `GET` | no | The id of the booking. -partnerReferenceId | string | `GET` `PUT` | yes | The reference id provided by a partner while making the booking. This is provided in the second booking step called using `PUT`. -variantId | string | `GET` `POST` | no | ID of the variant of the product that needs to be booked. Every product has atleast 1 bookable variant entry. -inventoryId | string | `POST` | no | ID of the inventory that needs to be booked. This id itself will not be stored, but will be used to fetch `startDateTime`, pricing profile for price validation etc. -inventorySeatIds | array | `POST` | YES | The array of seat ids. (Required only for seatmap bookings) -startDateTime | string | `GET` | no | The start date time of the experience. This could also signify the opening time for an attraction depending upon the inventory type. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)* *Ref: [`product-variant.inventoryType`](product-models.md#product-variant.inventoryType)* -product | [`booking.product`](#booking-product) | `GET` | no | Minimalistic information about the product booked. -customerDetails | [`booking-customers-details`](#booking-customers-details) | `GET` `POST` | no | All the details of the customers partaking in the booking. -variantInputFields | array[[`booking-input-field`](#booking-input-field)] | `GET` `POST` | yes | Variant level input field. For `POST` the values that are required to be submitted are specified in [product-variant.inputFields](product-models.md#product-variant). -price | [`price`](common-models.md#price) | `GET` `POST` | no | The price at which the purchase needs is made. This needs to be submitted in `POST` for backend verification. The submitted currency currently should conform to the currency of the product. -status | enum | `GET` `PUT` | no | The current status of the booking. After `POST` this will always be `UNCAPTURED`. The status can be changed using `PUT` to `PENDING` to specify to the backend. `enum: UNCAPTURED ,PENDING ,COMPLETED ,CANCELLED ,DIRTY , CAPTURE_TIMEDOUT`. *Ref: [`booking.status`](#booking.status)* -voucherUrl | string | `GET` | no | Link to the voucher of the booking. Voucher is inherently a dynamic entity and currently can either be a PDF or an HTML page. -tickets | array[[`ticket`](#ticket)] | `GET` | yes | An array of tickets associated with this booking. This can be empty if the booking hasn't been confirmed or cancelled. -creationTimestamp | int | `GET` | no | The epoch timestamp specifying the time when the booking was created. *Format: [fm-timestamp](/conventions/formats.md#fm-timestamp)*. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|--------------------|-----------------------------------------------------------|--------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| bookingId | string | `GET` | no | The id of the booking. | +| partnerReferenceId | string | `GET` `PUT` | yes | The reference id provided by a partner while making the booking. This is provided in the second booking step called using `PUT`. | +| variantId | string | `GET` `POST` | no | ID of the variant of the product that needs to be booked. Every product has at least 1 bookable variant entry. | +| inventoryId | string | `POST` | no | ID of the inventory that needs to be booked. This id itself will not be stored, but will be used to fetch `startDateTime`, pricing profile for price validation etc. | +| inventorySeatIds | array | `POST` | YES | The array of seat ids. (Required only for seatmap bookings) | +| startDateTime | string | `GET` | no | The start date time of the experience. This could also signify the opening time for an attraction depending upon the inventory type. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)* *Ref: [`product-variant.inventoryType`](product-models.md#product-variant.inventoryType)* | +| product | [`booking.product`](#booking-product) | `GET` | no | Minimalistic information about the product booked. | +| customerDetails | [`booking-customers-details`](#booking-customers-details) | `GET` `POST` | no | All the details of the customers partaking in the booking. | +| variantInputFields | array[[`booking-input-field`](#booking-input-field)] | `GET` `POST` | yes | Variant level input field. For `POST` the values that are required to be submitted are specified in [product-variant.inputFields](product-models.md#product-variant). | +| price | [`price`](common-models.md#price) | `GET` `POST` | no | The price at which the purchase needs is made. This needs to be submitted in `POST` for backend verification. The submitted currency currently should conform to the currency of the product. | +| status | enum | `GET` `PUT` | no | The current status of the booking. After `POST` this will always be `UNCAPTURED`. The status can be changed using `PUT` to `PENDING` to specify to the backend. `enum: UNCAPTURED ,PENDING ,COMPLETED ,CANCELLED ,DIRTY , CAPTURE_TIMEDOUT`. *Ref: [`booking.status`](#booking.status)* | +| voucherUrl | string | `GET` | no | Link to the voucher of the booking. Voucher is inherently a dynamic entity and currently can either be a PDF or an HTML page. | +| tickets | array[[`ticket`](#ticket)] | `GET` | yes | An array of tickets associated with this booking. This can be empty if the booking hasn't been confirmed or cancelled. | +| creationTimestamp | int | `GET` | no | The epoch timestamp specifying the time when the booking was created. *Format: [fm-timestamp](/conventions/formats.md#fm-timestamp)*. | ##### `booking.status` -* `UNCAPTURED`: This state means that the booking entry is created on our system but in a dormant state. It will not be processed by our system until the state is changed to `PENDING`. Bookings with `UNCAPTURED` status are automatically moved to `CAPTURE_TIMEOUT` state after 1 hour and are then rendered uncapturable. +* `UNCAPTURED`: This state means that the booking entry is created on our system but in a dormant state. It will not be processed by our system until the state is changed to `PENDING`. Bookings with `UNCAPTURED` status are automatically moved to `CAPTURE_TIMEOUT` state after 1 hour and are then can not be captured. * `PENDING`: This state means that the booking has been captured and is now being processed by our system. * `COMPLETED`: The booking is successful and has been completed. * `CANCELLED`: The booking has been cancelled. -* `DIRTY`: The booking has been modified from it's original specification. This happens only when specific booking modification requests are made by the customer. This might evolve into a different specification in the future. -* `CAPTURE_TIMEOUT`: If a booking has been there on our system in `UNCAPTURED` state for more than an hour it is move to `CAPTURE_TIMEOUT` state and then cannot be captured. +* `DIRTY`: The booking has been modified from its original specification. This happens only when specific booking modification requests are made by the customer. This might evolve into a different specification in the future. +* `CAPTURE_TIMEOUT`: If a booking has been there on our system in `UNCAPTURED` state for more than an hour it is moved to `CAPTURE_TIMEOUT` state and then cannot be captured. ### `booking-product` -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -id | string | `GET` | no | The id of the product -name | string | `GET` | no | The name of the product -variant | [`booking-product-variant`](#booking-product-variant) | `GET` | no | The variant of the product which was booked. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|---------|-------------------------------------------------------|--------|------------|----------------------------------------------| +| id | string | `GET` | no | The id of the product | +| name | string | `GET` | no | The name of the product | +| variant | [`booking-product-variant`](#booking-product-variant) | `GET` | no | The variant of the product which was booked. | ### `booking-product-variant` -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -id | string | `GET` | no | The is of the variant -name | string | `GET` | yes | The name of the variant. This can be empty if this is the default variant of the product. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|------|--------|--------|------------|-------------------------------------------------------------------------------------------| +| id | string | `GET` | no | The is of the variant | +| name | string | `GET` | yes | The name of the variant. This can be empty if this is the default variant of the product. | ### `booking-customers-details` Represents all the details for the customers partaking in the booking. -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -count | int | `GET` `POST` | no | The number of people partaking in the booking. -customers | array[[`booking-customer`](#booking-customer)] | `GET` `POST` | no | Array of details of every customer. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|-----------|------------------------------------------------|--------------|------------|------------------------------------------------| +| count | int | `GET` `POST` | no | The number of people partaking in the booking. | +| customers | array[[`booking-customer`](#booking-customer)] | `GET` `POST` | no | Array of details of every customer. | ### `booking-customer` Details of a singular customer -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -personType | string | `GET` `POST` | yes | The person type if the `priceType` is `PER_PERSON`. Not required/present if `priceType` is `PER_GROUP`. *Ref: [`product-variant.priceType`](product-models.md#product-variant.priceType) & [`pricing.persons`](inventory-pricing-models.md#pricing)* -isPrimary | bool | `GET` `POST` | no | Specifies whether this customer is the primary customer or not. There needs to be exactly 1 primary customer in [`booking-customers-details.customers`](#booking-customers-details) -inputFields | array[[`booking-input-field`](#booking-input-field) | `GET` `POST` | yes | All the input fields for this level customer as specified in [`product-variant.inputFields`](product-models.md#product-variant). +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|-------------|-----------------------------------------------------|--------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| personType | string | `GET` `POST` | yes | The person type if the `priceType` is `PER_PERSON`. Not required/present if `priceType` is `PER_GROUP`. *Ref: [`product-variant.priceType`](product-models.md#product-variant.priceType) & [`pricing.persons`](inventory-pricing-models.md#pricing)* | +| isPrimary | bool | `GET` `POST` | no | Specifies whether this customer is the primary customer or not. There needs to be exactly 1 primary customer in [`booking-customers-details.customers`](#booking-customers-details) | +| inputFields | array[[`booking-input-field`](#booking-input-field) | `GET` `POST` | yes | All the input fields for this level customer as specified in [`product-variant.inputFields`](product-models.md#product-variant). | ### `booking-input-field` An input field which represents the submission of the contract represented by [`product-variant-input-field`](product-models.md#product-variant-input-field) -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -id | string | `GET` `POST` | no | The ID of the field. -name | string | `GET` | no | The name of the field. Not required for `POST` since the id field signifies the same. -value | string | `GET` `POST` | no | The submitted value of the field. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|-------|--------|--------------|------------|---------------------------------------------------------------------------------------| +| id | string | `GET` `POST` | no | The ID of the field. | +| name | string | `GET` | no | The name of the field. Not required for `POST` since the id field signifies the same. | +| value | string | `GET` `POST` | no | The submitted value of the field. | ### `booking-create-response` Response object for booking create api (api has been deprecated). -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -itineraryId | string | `GET` | no | The ID for the booking. -price | [`price`](common-models.md#price) | `GET` | no | The price payed for the booking. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|-------------|-----------------------------------|--------|------------|----------------------------------| +| itineraryId | string | `GET` | no | The ID for the booking. | +| price | [`price`](common-models.md#price) | `GET` | no | The price payed for the booking. | ### `ticket` Represents information of a ticket. The ticket accessed via `url` is always in PDF format. -KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- | --- -publicId | string | `GET` | no | The public id for the ticket. -url | string | `GET` | no | The url to access the ticket. +| KEY | TYPE | METHOD | NULL/EMPTY | DESCRIPTION | +|----------|--------|--------|------------|-------------------------------| +| publicId | string | `GET` | no | The public id for the ticket. | +| url | string | `GET` | no | The url to access the ticket. | diff --git a/object-models/category-models.md b/object-models/category-models.md index cfb8dab..0b7d062 100644 --- a/object-models/category-models.md +++ b/object-models/category-models.md @@ -1,6 +1,6 @@ # Category/Collection Models -A category (also called collection) is a higher level grouping for products. There can be several products in a category and a product can be there in multiple categories. Also every product has exactly 1 primary category. +A category (also called collection) is a higher level grouping for products. There can be several products in a category and a product can be there in multiple categories. Also, every product has exactly 1 primary category. * [`category`](#category) @@ -8,10 +8,10 @@ A category (also called collection) is a higher level grouping for products. The The category super object. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | The ID of the category. -name | string | no | The display name of the category. -cityCode | string | no | The city of the category. Eg: `NEW_YORK`, `DUBAI` -image | [`image`](common-models.md#image) | no | The primary image for the category. -canonicalUrl | string | no | The canonical url for the category page on `www.headout.com`. If a separate category page is being constructed for this category then you are required to add this url as canonical url in the HTML code using ``. This url can also be used to open the concerned category page on `www.headout.com`. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|--------------|-----------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id | string | no | The ID of the category. | +| name | string | no | The display name of the category. | +| cityCode | string | no | The city of the category. Eg: `NEW_YORK`, `DUBAI` | +| image | [`image`](common-models.md#image) | no | The primary image for the category. | +| canonicalUrl | string | no | The canonical url for the category page on `www.headout.com`. If a separate category page is being constructed for this category then you are required to add this url as canonical url in the HTML code using ``. This url can also be used to open the concerned category page on `www.headout.com`. | diff --git a/object-models/common-models.md b/object-models/common-models.md index 5727629..b81818b 100644 --- a/object-models/common-models.md +++ b/object-models/common-models.md @@ -13,78 +13,78 @@ Representation of a city -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -code | string | no | Code name for the city. Example: `NEW_YORK`, `DUBAI` -name | string | no | Display name of the city -image | [`image`](common-models.md#image) | no | The primary image for the city. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------|-----------------------------------|------------|------------------------------------------------------| +| code | string | no | Code name for the city. Example: `NEW_YORK`, `DUBAI` | +| name | string | no | Display name of the city | +| image | [`image`](common-models.md#image) | no | The primary image for the city. | ### `currency` Complete representation of a currency -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -code | string | no | ISO 4217 currency codes. Example: `USD`, `AED` *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* -name | string | no | Display name of the currency -symbol | string | no | Full symbol representation of the currency. Example: `US$` -localSymbol | string | no | Shorthand symbol representation that would be understood by local people in the currency's native country. Example `$` -precision | int | no | Precision of decimal digits for values in this currency +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------------|--------|------------|----------------------------------------------------------------------------------------------------------------------------------------| +| code | string | no | ISO 4217 currency codes. Example: `USD`, `AED` *Ref: [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217)* | +| name | string | no | Display name of the currency | +| symbol | string | no | Full symbol representation of the currency. Example: `US$` | +| localSymbol | string | no | Shorthand symbol representation that would be understood by local people in the currency's native country. Example `$` | +| precision | int | no | Precision of decimal digits for values in this currency | ### `image` Representation of an image -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -url | string | no | Url of the image +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-----|--------|------------|------------------| +| url | string | no | Url of the image | ### `location` Representation of a point on the map with address information. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -geo | [`geo-location`](#geo-location) | no | The geo location of the point. -address | [`address`](#address) | no | The address representing the point +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------|---------------------------------|------------|------------------------------------| +| geo | [`geo-location`](#geo-location) | no | The geo location of the point. | +| address | [`address`](#address) | no | The address representing the point | ### `geo-location` -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -latitude | float | no | The latitude of the point. -longitude | float | no | The latitude of the point. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-----------|-------|------------|----------------------------| +| latitude | float | no | The latitude of the point. | +| longitude | float | no | The latitude of the point. | ### `address` Represents an address -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -line1 | string | no | Line 1 of the address -line2 | string | yes | Line 2 of the address -cityName | string | no | City name -stateName | string | yes | State name -countryName | string | no | Country name -postalCode | string | yes | Postal/Zip code +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------------|--------|------------|-----------------------| +| line1 | string | no | Line 1 of the address | +| line2 | string | yes | Line 2 of the address | +| cityName | string | no | City name | +| stateName | string | yes | State name | +| countryName | string | no | Country name | +| postalCode | string | yes | Postal/Zip code | ### `price` Represent a price with currency -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -amount | float | no | The amount of the price -currencyCode | string | no | The currency of the price ISO 4217 currency codes. Example: `USD`, `AED` +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|--------------|--------|------------|--------------------------------------------------------------------------| +| amount | float | no | The amount of the price | +| currencyCode | string | no | The currency of the price ISO 4217 currency codes. Example: `USD`, `AED` | -### `pagination-wrapper` +### `pagination-wrapper` -Wrapper object to support pagination. Is used to wrap the the response by all the APIs if the response is a list of results which can be paginated. The API dictates whether it will be using a pagination wrapper or not. +Wrapper object to support pagination. Is used to wrap the response by all the APIs if the response is a list of results which can be paginated. The API dictates whether it will be using a pagination wrapper or not. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -items | array[T] | yes | The response object array whose whole result is being paginated. The object type T is dictated by the api. This can be empty if there were no results. -nextUrl | string | yes | The next page url. Empty if this is the last page. -prevUrl | string | yes | The previous page url. Empty if this is the first page. -total | int | no | Specifies the total results. -nextOffset | int | yes | Specifies the next offset which can be used to create the next url. This will be empty/`null` if there is the last page. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|------------|----------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| items | array[T] | yes | The response object array whose whole result is being paginated. The object type T is dictated by the api. This can be empty if there were no results. | +| nextUrl | string | yes | The next page url. Empty if this is the last page. | +| prevUrl | string | yes | The previous page url. Empty if this is the first page. | +| total | int | no | Specifies the total results. | +| nextOffset | int | yes | Specifies the next offset which can be used to create the next url. This will be empty/`null` if there is the last page. | diff --git a/object-models/inventory-pricing-models.md b/object-models/inventory-pricing-models.md index 8e7170f..59a8626 100644 --- a/object-models/inventory-pricing-models.md +++ b/object-models/inventory-pricing-models.md @@ -9,19 +9,19 @@ Represents the inventory specification. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -startDateTime | string | no | Start local date time for the inventory. This may even specify the opening local date time for the variant. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* -endDateTime | string | no | End local date time for the inventory. This may even specify the closing local date time for the variant. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.endDateTime`](#inventory.endDateTime)* -availability | enum | no | Specifies the type of availability for the inventory. `enum: LIMITED, UNLIMITED, CLOSED`. *Ref: [`inventory.availability`](#inventory.availability)* -remaining | int | no | The total number of seats left which can be booked for this inventory. -pricing | [`pricing`](#pricing) | no | The pricing specifiction for the inventory. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------------|-----------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| startDateTime | string | no | Start local date time for the inventory. This may even specify the opening local date time for the variant. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.startDateTime`](#inventory.startDateTime)* | +| endDateTime | string | no | End local date time for the inventory. This may even specify the closing local date time for the variant. *Format: [fm-date-time](/conventions/formats.md#fm-date-time)*. *Ref: [`inventory.endDateTime`](#inventory.endDateTime)* | +| availability | enum | no | Specifies the type of availability for the inventory. `enum: LIMITED, UNLIMITED, CLOSED`. *Ref: [`inventory.availability`](#inventory.availability)* | +| remaining | int | no | The total number of seats left which can be booked for this inventory. | +| pricing | [`pricing`](#pricing) | no | The pricing specifiction for the inventory. | ##### `inventory.startDateTime` This denotes the start time of the inventory for the variant concerned, if the variant has an `inventoryType` of `FIXED_START_FIXED_DURATION` or `FIXED_START_FLEXIBLE_DURATION`. -If the `inventoryType` is `FLEXIBLE_START_FIXED_DURATION` or `FLEXIBLE_START_FLEXIBLE_DURATION`, then it means that the variant does not have a fixed start time ever. In such a case this can be interpreted as the opening time for the variant's inventory. For eg: Disneyland will have an `inventoryType` of `FLEXIBLE_START_FLEXIBLE_DURATION` and it's `startDateTime` will be 8:00am which signifies it's opening time. If this inventory is bought, the customer can still enter after 8:00am. +If the `inventoryType` is `FLEXIBLE_START_FIXED_DURATION` or `FLEXIBLE_START_FLEXIBLE_DURATION`, then it means that the variant does not have a fixed start time ever. In such a case this can be interpreted as the opening time for the variant's inventory. For eg: Disneyland will have an `inventoryType` of `FLEXIBLE_START_FLEXIBLE_DURATION` and it's `startDateTime` will be 8:00am which signifies its opening time. If this inventory is bought, the customer can still enter after 8:00am. *Ref: [`product-variant.inventoryType`](product-models.md#product-variant.inventoryType)* @@ -41,33 +41,34 @@ If the `inventoryType` is `FIXED_START_FLEXIBLE_DURATION`, `FLEXIBLE_START_FIXED ### `pricing` -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -persons | array[[`pricing-person`](#pricing-person)] | yes | Specifies the specification for per person pricing. This is non-empty only if `priceType` for the variant of the inventory is `PER_PERSON`. *Ref: [`product-variant.priceType`](product-models.md#product-variant)* -groups | array[[`pricing-group`](#pricing-group)] | yes | Specifies the specification for per person pricing. This is non-empty only if `priceType` for the variant of the inventory is `PER_GROUP`. *Ref: [`product-variant.priceType`](product-models.md#product-variant)* +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------|--------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| persons | array[[`pricing-person`](#pricing-person)] | yes | Specifies the specification for per person pricing. This is non-empty only if `priceType` for the variant of the inventory is `PER_PERSON`. *Ref: [`product-variant.priceType`](product-models.md#product-variant)* | +| groups | array[[`pricing-group`](#pricing-group)] | yes | Specifies the specification for per person pricing. This is non-empty only if `priceType` for the variant of the inventory is `PER_GROUP`. *Ref: [`product-variant.priceType`](product-models.md#product-variant)* | ### `pricing-person` Specifies the specification for per person pricing. This is only applicable for `PER_PERSON` price types. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -type | string | no | The person type. Eg: `ADULT`, `CHILD` etc. -name | string | no | The displayable name for the person. Ex: `Adult`, `Child`, `Senior` -ageFrom | int | yes | The minimum age for the type. If this not specified then there is no minimum age. -ageTo | int | yes | The maximum age for the type. If this is not specified then there is no macimum age. -price | float | no | The price payable for this type. -originalPrice | float | no | The original (retail) price of for this type +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------------|--------|------------|--------------------------------------------------------------------------------------| +| type | string | no | The person type. Eg: `ADULT`, `CHILD` etc. | +| name | string | no | The displayable name for the person. Ex: `Adult`, `Child`, `Senior` | +| ageFrom | int | yes | The minimum age for the type. If this not specified then there is no minimum age. | +| ageTo | int | yes | The maximum age for the type. If this is not specified then there is no macimum age. | +| price | float | no | The price payable for this type. | +| originalPrice | float | no | The original (retail) price of for this type | ### `pricing-group` Specifies the specification for per group pricing. This is only applicable for `PER_GROUP` price types. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -size | int | no | The upper bound of the size of this group. The lower bound is the next lowest size overall from this size plus 1. -price | float | no | The price payable for this type. -originalPrice | float | no | The original (retail) price for this type +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------------|-------|------------|-------------------------------------------------------------------------------------------------------------------| +| size | int | no | The upper bound of the size of this group. The lower bound is the next lowest size overall from this size plus 1. | +| price | float | no | The price payable for this type. | +| originalPrice | float | no | The original (retail) price for this type | + ##### Eg: (Assume all currency is in dollars) * `size=4, price=100, originalPrice=120` means headout price for 1-4 persons is 100$ while retail price is $120 (i.e. 20% discount) diff --git a/object-models/product-models.md b/object-models/product-models.md index 5293c50..0a5b684 100644 --- a/object-models/product-models.md +++ b/object-models/product-models.md @@ -1,6 +1,6 @@ # Product Models -Product signifies an experience that can be sold. Typically a product will consist of various variants which are the actual bookable entities. A product will have atleast 1 variant. +Product signifies an experience that can be sold. Typically, a product will consist of various variants which are the actual bookable entities. A product will have at least 1 variant. * [`product`](#product) * [`product-content`](#product-content) @@ -19,69 +19,69 @@ Product signifies an experience that can be sold. Typically a product will consi Represents the full product information. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | Product id -name | string | no | Name of the product -neighbourhood | string | yes | Neighbourhood of the location of the product -city | [`city`](common-models.md#city) | no | City of the product -currency | [`currency`](common-models.md#currency) | no | Native currency of the product. This depends on the country of the product. -images | array[[`image`](common-models.md#image)] | no | Product images -displayTags | array[string] | yes | Tags signifying the product -content | array[[`product-content`](#product-content)] | no | Content specifying the details of the product -startLocation | [`location`](common-models.md#location) | no | Location of the start point -endLocation | [`location`](common-models.md#location) | no | Location of the end point -productType | enum | no | Specifies the type of the product.`enum: TOUR, ACTIVITY, EVENT, ATTRACTION, TRANSFER` -ratingCumulative | [`rating-cumulative`](#rating-cumulative) | no | Cumulative rating of the product -hasInstantConfirmation | boolean | no | `true` if the booking will be instantly confirmed and the tickets will be delivered. If `false` then the booking confirmation and ticket delivery will happen within 20 minutes. -hasMobileTicket | boolean | no | `true` if the ticket can be shown on the mobile at the venue. If `false` you might have to take a print out or show the mobile ticket to get the actual tickets at the venue. The specifics will be mentioned in the product description. -variants | array[[`product-variant`](#product-variant)] | no | Variants of the product. Every product has variants which are the actual bookable entities. If there is only 1 variant, the variant does not have any special significance. If there are more than 1 variant then each variant will have it's own name and description. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|------------------------|----------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id | string | no | Product id | +| name | string | no | Name of the product | +| neighbourhood | string | yes | Neighbourhood of the location of the product | +| city | [`city`](common-models.md#city) | no | City of the product | +| currency | [`currency`](common-models.md#currency) | no | Native currency of the product. This depends on the country of the product. | +| images | array[[`image`](common-models.md#image)] | no | Product images | +| displayTags | array[string] | yes | Tags signifying the product | +| content | array[[`product-content`](#product-content)] | no | Content specifying the details of the product | +| startLocation | [`location`](common-models.md#location) | no | Location of the start point | +| endLocation | [`location`](common-models.md#location) | no | Location of the end point | +| productType | enum | no | Specifies the type of the product.`enum: TOUR, ACTIVITY, EVENT, ATTRACTION, TRANSFER` | +| ratingCumulative | [`rating-cumulative`](#rating-cumulative) | no | Cumulative rating of the product | +| hasInstantConfirmation | boolean | no | `true` if the booking will be instantly confirmed and the tickets will be delivered. If `false` then the booking confirmation and ticket delivery will happen within 20 minutes. | +| hasMobileTicket | boolean | no | `true` if the ticket can be shown on the mobile at the venue. If `false` you might have to take a print out or show the mobile ticket to get the actual tickets at the venue. The specifics will be mentioned in the product description. | +| variants | array[[`product-variant`](#product-variant)] | no | Variants of the product. Every product has variants which are the actual bookable entities. If there is only 1 variant, the variant does not have any special significance. If there are more than 1 variant then each variant will have it's own name and description. | ### product-content A content section of the product -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -title | string | no | Title of the content section -html | string | no | The content of the section in html format. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------|--------|------------|--------------------------------------------| +| title | string | no | Title of the content section | +| html | string | no | The content of the section in html format. | ### rating-cumulative Represent the cumulative rating information. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -avg | float | no | The average rating -count | int | no | The overall entries used to evaluate the rating. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------|-------|------------|--------------------------------------------------| +| avg | float | no | The average rating | +| count | int | no | The overall entries used to evaluate the rating. | ### product-variant Represent a variant entry of the product. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | Variant ID. -name | string | yes | Variant display name. Will be null/empty **only if** there is only 1 variant in a product. -description | string | yes | Variant description. -inventoryType | enum | no | Specifies the inventory type of the variant. `enum: FIXED_START_FIXED_DURATION, FIXED_START_FLEXIBLE_DURATION, FLEXIBLE_START_FIXED_DURATION, FLEXIBLE_START_FLEXIBLE_DURATION`. *Ref: [`product-variant.inventoryType`](#product-variant.inventoryType)* -duration | int | yes | Specifies the duration of the variant in milliseconds. Will be `null` only for `inventoryType` `FIXED_START_FLEXIBLE_DURATION` & `FLEXIBLE_START_FLEXIBLE_DURATION` -priceType | enum | no | The pricing type for this inventory. `enum: PER_PERSON, PER_GROUP`. *Ref: [`product-variant.priceType`](#product-variant.priceType).* -pax | [`product-variant-pax`](#product-variant-pax) | no | Specifies the pax/people limit specification for the variant. -cashback | [`product-variant-cashback`](#product-variant-cashback) | yes | Specified the cashback that can be achieved by purchasing this variant. It can be `null` if there is no cashback available. -ticketDeliveryInfoHtml | string | yes | Specified how the ticket will be delivered. Currently this is in HTML format. This will transition to an `enum` based approach in upcoming api iterations. This can be `null`/empty if the information is currently not available. -inputFields | [`product-variant-input-field`](#product-variant-input-field) | no | These fields represent the information that need to be taken from the consumer and submitted while making a purchase. - -##### `product-variant.inventoryType` +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|------------------------|---------------------------------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id | string | no | Variant ID. | +| name | string | yes | Variant display name. Will be null/empty **only if** there is only 1 variant in a product. | +| description | string | yes | Variant description. | +| inventoryType | enum | no | Specifies the inventory type of the variant. `enum: FIXED_START_FIXED_DURATION, FIXED_START_FLEXIBLE_DURATION, FLEXIBLE_START_FIXED_DURATION, FLEXIBLE_START_FLEXIBLE_DURATION`. *Ref: [`product-variantinventoryType`](#product-variant-inventoryType)* | +| duration | int | yes | Specifies the duration of the variant in milliseconds. Will be `null` only for `inventoryType` `FIXED_START_FLEXIBLE_DURATION` & `FLEXIBLE_START_FLEXIBLE_DURATION` | +| priceType | enum | no | The pricing type for this inventory. `enum: PER_PERSON, PER_GROUP`. *Ref: [`product-variant.priceType`](#product-variant.priceType).* | +| pax | [`product-variant-pax`](#product-variant-pax) | no | Specifies the pax/people limit specification for the variant. | +| cashback | [`product-variant-cashback`](#product-variant-cashback) | yes | Specified the cashback that can be achieved by purchasing this variant. It can be `null` if there is no cashback available. | +| ticketDeliveryInfoHtml | string | yes | Specified how the ticket will be delivered. Currently this is in HTML format. This will transition to an `enum` based approach in upcoming api iterations. This can be `null`/empty if the information is currently not available. | +| inputFields | [`product-variant-input-field`](#product-variant-input-field) | no | These fields represent the information that need to be taken from the consumer and submitted while making a purchase. | + +#### `product-variant-inventoryType` * `FIXED_START_FIXED_DURATION`: Signifies that the variant experience has a fixed start time and a fixed duration. Eg: Broadway Show, it has a fixed start time and ends at a fixed time. * `FIXED_START_FLEXIBLE_DURATION`: Signifies that the variant experience has a fixed start time but a flexible duration. Eg: Entry for Rockefeller - Top of the rock observatory. It has a fixed start time, but once you're in, you can stay over there as long as you want till the place closes down. * `FLEXIBLE_START_FIXED_DURATION`: Signifies that the variant experience has a flexible start time but a fixed duration. Eg: Hot air balloon ride, you can enter at any time, but the duration of the experience is fixed. * `FLEXIBLE_START_FLEXIBLE_DURATION`: Signifies that the variant experience has a flexible start time and a flexible duration. Eg: Entry tickets for Disneyland, you can enter at any time and can stay there till any time (till the venue closes down). -##### `product-variant.priceType` +##### `product-variant.priceType` -* `PER_PERSON`: A `PER_PERSON` price type specifies that there is a price applicable for every person partaking in the booking. There can be different type of people like `Adult`, `Child`, `Senior` etc. with their own age specification. Each individual type can have it's own price point. +* `PER_PERSON`: A `PER_PERSON` price type specifies that there is a price applicable for every person partaking in the booking. There can be different type of people like `Adult`, `Child`, `Senior` etc. with their own age specification. Each individual type can have its own price point. * `PER_GROUP`: A `PER_GROUP` price type specifies that the inventory is on group pricing. Group pricing signifies that a singular price applies to a group of people and might vary for a given range. For example, 1-4 people $100, 5-7 people $120, 8-10 people $150. *See Also: [`inventory.pricing`](/object-models/inventory-pricing-models.md#inventory)* @@ -90,31 +90,31 @@ inputFields | [`product-variant-input-field`](#product-variant-input-field) | no Specified the pax/people limitation specification for a variant -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -min | int | no | Specifies the lower limit for number of people to be present in a booking. If there is no lower limit, this will be 0. -max | int | yes | Specifies the upper limit for number of people that can be present in a booking. If there is no upper limit, this will be `null`. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-----|------|------------|-----------------------------------------------------------------------------------------------------------------------------------| +| min | int | no | Specifies the lower limit for number of people to be present in a booking. If there is no lower limit, this will be 0. | +| max | int | yes | Specifies the upper limit for number of people that can be present in a booking. If there is no upper limit, this will be `null`. | ### `product-variant-cashback` Specifies the cashback specifications for a variant. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -value | float | no | Value of the cashback. -type | string | no | Specified the type of cashback. `enum: ABSOLUTE, PERCENTAGE`. A `value` of `10` with `type` `ABSOLUTE` represents that the user will get an absoute cashback of `10` value in the product's currency. If `type` is `PERCENTAGE` the user will get a cashback of `10%` of the overall variant's price. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-------|--------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| value | float | no | Value of the cashback. | +| type | string | no | Specified the type of cashback. `enum: ABSOLUTE, PERCENTAGE`. A `value` of `10` with `type` `ABSOLUTE` represents that the user will get an absolute cashback of `10` value in the product's currency. If `type` is `PERCENTAGE` the user will get a cashback of `10%` of the overall variant's price. | ### `product-variant-input-field` Specifies a user input field for a variant which is required to make a booking. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | An ID representing the field for the variant. -name | string | no | Display name of the field -dataType | enum | no | Data type of the field. `enum: INT, FLOAT, STRING, BOOL, ENUM`. *Ref: [`product-variant-input-field.dataType`](#product-variant-input-field.dataType)* -level | enum | no | Specified the level of applicability of the field. `enum: PRIMARY_CUSTOMER`, `ALL_CUSTOMERS`, `TOUR`. *Ref: [`product-variant-input-field.level`](#product-variant-input-field.level)* -validation | [`product-variant-input-field-validation`](#product-variant-input-field-validation) | no | Specifies the validation required for the field. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|------------|-------------------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id | string | no | An ID representing the field for the variant. | +| name | string | no | Display name of the field | +| dataType | enum | no | Data type of the field. `enum: INT, FLOAT, STRING, BOOL, ENUM`. *Ref: [`product-variant-input-field.dataType`](#product-variant-input-field.dataType)* | +| level | enum | no | Specified the level of applicability of the field. `enum: PRIMARY_CUSTOMER`, `ALL_CUSTOMERS`, `TOUR`. *Ref: [`product-variant-input-field.level`](#product-variant-input-field.level)* | +| validation | [`product-variant-input-field-validation`](#product-variant-input-field-validation) | no | Specifies the validation required for the field. | ##### `product-variant-input-field.dataType` @@ -126,68 +126,68 @@ validation | [`product-variant-input-field-validation`](#product-variant-input-f ##### `product-variant-input-field.level` -* `PRIMARY_CUSTOMER`: Represents that the field only needs to be asked for the primary customer. A primary customer represents the customer who will be internally linked for the booking. There is only 1 primary customer per booking. There will always be atleast 1 input field representing the primary customer. Typically **Full name**, **Email**, **Phone Number** & **Address** and mostly asked as information required for the primary customer. -* `ALL_CUSTOMERS`: Represents that the field needs to be asked for all the customers included in the booking (including the primary customer). Typically fields asking for all customer information are not there. Nevertheless there can be cases where information like **Weight**, **Height**, **Meal preference** etc. are required for all the customers. -* `VARIANT`: Represents that the field information needs to be taken on a variant level. It is agnostic to customer or the number of customers partaking in a booking. It needs to be collected only once just like `PRIMARY_CUSTOMER`, nevertheless, it does not represent information of a user. Hence a separate enumeration to signify the difference which can help with UI organization. +* `PRIMARY_CUSTOMER`: Represents that the field only needs to be asked for the primary customer. A primary customer represents the customer who will be internally linked for the booking. There is only 1 primary customer per booking. There will always be at least 1 input field representing the primary customer. Typically **Full name**, **Email**, **Phone Number** & **Address** and mostly asked as information required for the primary customer. +* `ALL_CUSTOMERS`: Represents that the field needs to be asked for all the customers included in the booking (including the primary customer). Typically, fields asking for all customer information are not there. Nevertheless, there can be cases where information like **Weight**, **Height**, **Meal preference** etc. are required for all the customers. +* `VARIANT`: Represents that the field information needs to be taken on a variant level. It is agnostic to customer or the number of customers partaking in a booking. It needs to be collected only once just like `PRIMARY_CUSTOMER`, nevertheless, it does not represent information of a user. Hence, a separate enumeration to signify the difference which can help with UI organization. ### `product-variant-input-field-validation` Specifies the validation contract for a variant input field. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -required | bool | no | Specifies whether the input field is mandatory or not. -regex | string | yes | The regex validation for the field -minLength | int | yes | The minimum length required for the field. This can be `null` if not applicable (example for `dataType` `INT` fields) -maxLength | int | yes | The maximum length required for the field. This can be `null` if not applicable (example for `dataType` `INT` fields) -minValue | int | yes | The minimum value required for the field. This can be `null` if not applicable (example for `dataType` `STRING` fields) -maxValue | int | yes | The maximum value required for the field. This can be `null` if not applicable (example for `dataType` `STRING` fields) -values | array[string] | no | Specifies that the field values need to be restricted to entries in this array. This is applicable only for `dataType` `ENUM` fields. For other `dataType`, this will be `null`/empty. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|-----------|---------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| required | bool | no | Specifies whether the input field is mandatory or not. | +| regex | string | yes | The regex validation for the field | +| minLength | int | yes | The minimum length required for the field. This can be `null` if not applicable (example for `dataType` `INT` fields) | +| maxLength | int | yes | The maximum length required for the field. This can be `null` if not applicable (example for `dataType` `INT` fields) | +| minValue | int | yes | The minimum value required for the field. This can be `null` if not applicable (example for `dataType` `STRING` fields) | +| maxValue | int | yes | The maximum value required for the field. This can be `null` if not applicable (example for `dataType` `STRING` fields) | +| values | array[string] | no | Specifies that the field values need to be restricted to entries in this array. This is applicable only for `dataType` `ENUM` fields. For other `dataType`, this will be `null`/empty. | ### `product-listing` Represent a product's listing -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | Product ID. -name | string | no | Product name. -url | string | no | URL for the product -city | [`city`](common-models.md#city) | no | City of the product -image | [`image`](common-models.md#image) | no | The primary image for the product. -neighbourhood | string | yes | The neighbourhood of the location of the product. -primaryCategory | [`product-category`](#product-category) | no | The primary category for the product. -startGeolocation | [`geo-location`](common-models.md#geolocation) | no | The geo location of the product. -ratingCumulative | [`rating-cumulative`](#rating-cumulative) | no | The cumulative rating of the product. -pricing | [`product-listing-pricing`](#product-listing-pricing) | no | Specifies the pricing data for the product listing +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|------------------|-------------------------------------------------------|------------|----------------------------------------------------| +| id | string | no | Product ID. | +| name | string | no | Product name. | +| url | string | no | URL for the product | +| city | [`city`](common-models.md#city) | no | City of the product | +| image | [`image`](common-models.md#image) | no | The primary image for the product. | +| neighbourhood | string | yes | The neighbourhood of the location of the product. | +| primaryCategory | [`product-category`](#product-category) | no | The primary category for the product. | +| startGeolocation | [`geo-location`](common-models.md#geo-location) | no | The geo location of the product. | +| ratingCumulative | [`rating-cumulative`](#rating-cumulative) | no | The cumulative rating of the product. | +| pricing | [`product-listing-pricing`](#product-listing-pricing) | no | Specifies the pricing data for the product listing | ### `product-listing-pricing` Represents the pricing data for the product listing -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -type | enum | no | Specifies the price type for the product. `enum: PER_PERSON, PER_GROUP`. Although this is on a variant level, nevertheless, right now we don't support any products with variants of different price types. Hence this is value is currently specified over here. This might get deprecated in the future. *Ref: [`product-variant.priceType`](#product-variant.priceType).* -currencyCode | string | no | The currency code of the price. -minimumPrice | [`product-listing-pricing-price`](#product-listing-pricing-price) | no | Object specifying the minimum price applicable for the product. -bestDiscount | int | no | The best discount available across all available inventory. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|--------------|-------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | enum | no | Specifies the price type for the product. `enum: PER_PERSON, PER_GROUP`. Although this is on a variant level, nevertheless, right now we don't support any products with variants of different price types. Hence this is value is currently specified over here. This might get deprecated in the future. *Ref: [`product-variant.priceType`](#product-variant-priceType).* | +| currencyCode | string | no | The currency code of the price. | +| minimumPrice | [`product-listing-pricing-price`](#product-listing-pricing-price) | no | Object specifying the minimum price applicable for the product. | +| bestDiscount | int | no | The best discount available across all available inventory. | ### `product-listing-pricing-price` Represents a price object for listing pricing. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -originalPrice | float | no | The original retail price for the corresponding final price -finalPrice | float | no | The final sale price. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|---------------|-------|------------|-------------------------------------------------------------| +| originalPrice | float | no | The original retail price for the corresponding final price | +| finalPrice | float | no | The final sale price. | ### `product-category` Represents a minimal category object for product. -KEY | TYPE | NULL/EMPTY | DESCRIPTION ---- | --- | --- | --- -id | string | no | The ID of the category. -name | string | no | The display name of the category. -cityCode | string | no | The city of the category. Eg: `NEW_YORK`, `DUBAI` -url | string | no | The relative url for the category page. +| KEY | TYPE | NULL/EMPTY | DESCRIPTION | +|----------|--------|------------|---------------------------------------------------| +| id | string | no | The ID of the category. | +| name | string | no | The display name of the category. | +| cityCode | string | no | The city of the category. Eg: `NEW_YORK`, `DUBAI` | +| url | string | no | The relative url for the category page. |