Bookings API | AnyRoad Help Center
Bookings API
October 18, 2024
The Bookings API is related to bookings created through the AnyRoad platform including booking ID, dates, and checkout questions.
To make requests to our API, you will need an API key. Your AnyRoad user id and password are your normal AnyRoad account login credentials. Once you receive your API key, you will be able to make requests to all endpoints. Please keep your API key secure. If you believe your key has been compromised, please contact us for a new one.
All responses adhere to the JSON: API formatting guidelines found here: JSON API — A specification for building APIs in JSON.
Requesting an API Key
Please reach out to your AnyRoad Account Manager to activate your API key. Once activated, send the below request to receive your API key. You will need the AnyRoad account registered email and password associated with the owner of the account.
Request:
curl https://app.anyroad.com/external/api/v1/users/key -u "janedoe@example.com:SuperSecretPa$word"
Response:
Status: 200
{
"data": {
"type": "users",
"id": "123",
"attributes": {
"key": "example-key-1234"
}
}
}
API Key Verification
To verify that your API key is active, send the following request, where
Request:
curl -H 'X-API-KEY: <your_api_key>' https://app.anyroad.com/external/api/v1/users/profile
Response:
Status: 200
{
"data": {
"type": "users",
"id": "123",
"attributes": {
"first_name": "Jane",
"last_name": "Doe",
"email": "janedoe@example.com"
}
}
}
Key Terminology
It is important to understand the definitions of booking and date attributes to accurately request AnyRoad data.
Bookings
Bookings are the purchase or reservation of an experience (e.g. a tour) by a guest. Each booking represents an individual reservation for an experience, with associated revenue, additional guests, and add-ons. For example, a booking can be for £20.00 for a Distillery Tour that happens on 2018-04-01 at 13:30, for 4 guests with a Bottle Opener add-on.
It is important to note that a booking record can change over time because it can be modified or canceled by staff. For example, a booking made on 2018-03-01 for £20.00 could then be cancelled on 2018-03-02 with a £20.00 refund to your guest. If you query that booking on 2018-03-01, revenue for that booking will be returned as £20.00. If you query that booking on 2018-03-03, revenue for that booking will be returned as £0.00. Your staff can modify booking amounts, reschedule bookings and cancel bookings up to 7 days after your guest has attended their booked experience. Therefore, the dates on which you query bookings can determine the accuracy of your final revenue reporting.
Booking Dates
There are two key dates for bookings:
- Booking Date: the date when the original booking was placed, whether by the guest themselves (e.g. online) or by your staff (e.g. via Front Desk).
- Experience Date: the date on which your guest will attend their booked experience.
Because a booking can change over time, we highly recommend querying data based on experience date for accurate reporting. Bookings can and will change between the time they are booked and the time of the experience, but once the experience is over it’s unlikely they will change. In reality, bookings can be modified up to 7 days after the experience date. Therefore, to get accurate and timely revenue data we recommend querying booking data after the experience has passed. For example, if you request data on 2018-04-02 for all bookings with an experience date before 2018-04-02 your data will be highly accurate.
Revenue Summary
Revenue Summary returns summarized revenue data for the selected time period in the currency set on your account.
The Revenue Summary Object
{
"data": {
"type": "revenue_summary",
"id": "-",
"attributes": {
"currency": "USD",
"total_revenue": "123.45",
"total_vat": "20.00",
"total_revenue_excluding_vat": "103.45",
"total_add_on_revenue": "23.45",
"experiences": [
{
"experience_name": "Example One",
"experience_revenue": "80.00",
"experience_vat": "10.00",
"experience_revenue_excluding_vat": "70.00"
},
{
"experience_name": "Example Two",
"experience_revenue": "20.00",
"experience_vat": "10.00",
"experience_revenue_excluding_vat": "10.00"
}
],
"addons": [
{
"addon_name": "Example One",
"addon_revenue": "20.00"
},
{
"addon_name": "Example Two",
"addon_revenue": "3.45"
}
]
}
}
}
Attributes:
- currency (string): ISO 4217 currency code. Example: “EUR”. Currency is based on the currency set on your AnyRoad account.
- total_revenue (decimal): The total revenue charged and collected from your guest for a booking after all applied discounts, excluding applicable service and credit card fees.
- total_vat (decimal): the total amount of vat included in total_revenue. The vat rate is set by you on your AnyRoad account.
- total_revenue_excluding_vat (decimal): the total revenue charged minus the total vat amount.
- total_add_on_revenue (decimal): the total revenue associated with add-ons purchased.
- experiences (collection): A list of each experience and its associated revenue.
Bookings
Bookings returns all individual booking records for the selected time period in the currency set on your AnyRoad account.
The Booking Object
{
"data": {
"id": "123",
"type": "bookings",
"attributes": {
"custom_account_id": "account123",
"booking_date": "2020-01-21T17:09:14",
"booking_source": "Online",
"affiliate_name": "Hilton Hotels",
"booking_status": "Confirmed",
"payment_method": "Credit Card",
"experience_name": "Example Tour",
"experience_date": "2020-01-01",
"experience_time": "16:00",
"number_guests_booked": "3",
"number_guests_checked_in": "2",
"guest_first_name": "John",
"guest_last_name": "Smith",
"guest_email": "john.smith@example.com",
"guest_phone": "14151231234",
"guest_country": "US",
"total_number_addons": "2",
"currency": "USD",
"total_revenue": "85.00",
"total_vat": "19.78",
"total_revenue_excluding_vat": "65.22",
"total_discount_amount": "0.00",
"payout_dates": ["2020-02-01", "2020-02-08"],
"location": {
"id": "1234",
"name": "Example Location"
},
"created": "2020-01-21T17:09:14Z",
"updated": "2020-01-21T17:09:14Z",
"addons": [
{
"custom_id": "addon123",
"addon_name": "Example One",
"number_addons": "2",
"addon_price": "10.00",
"addon_revenue": "20.00",
"vat_rate": "15.00",
"addon_vat": "2.61",
"addon_revenue_excluding_vat": "17.39"
},
{
"custom_id": "addon456",
"addon_name": "Example Two",
"number_addons": "1",
"addon_price": "5.00",
"addon_revenue": "5.00",
"vat_rate": "15.00",
"addon_vat": "0.65",
"addon_revenue_excluding_vat": "4.35"
}
],
"tickets": [
{
"custom_id": "ticket123",
"ticket_name": "Adult",
"number_tickets": "3",
"ticket_price": "20.00",
"ticket_revenue": "60.00",
"vat_rate": "15.00",
"ticket_vat": "16.52",
"ticket_revenue_excluding_vat": "43.48"
}
],
"private_notes": "Private notes here"
}
}
}
}
Attributes:
- id (integer): the unique id of a booking
- custom_account_id (string): A custom location or account id, as defined by you on your AnyRoad account.
- booking_date (datetime): the date a booking was purchased or reserved in UTC time. RFC 3339 date representation. Example: “2018-01-01T14:00:00 00:00”.
- booking_source (string): The medium through which your guest booked their experience. Attributes include:
- Online: bookings purchased by guests through the AnyRoad integration on your website.
- Added Frontdesk: bookings added by your staff through the AnyRoad iOS Front Desk application. These include walk-in guests.
- Added Web: bookings added by your staff through the AnyRoad online dashboard.
- Invoice: bookings sent and paid via AnyRoad invoices.
- Affiliates: bookings added by or associated to an affiliate.
- affiliate_name (string): The name of the affiliate associated with the booking, if booking_source = affiliates.
- booking_status (string): The current state of a booking. Attributes include:
- Confirmed: an active or past valid booking.
- Cancelled: a cancelled booking.
- payment_method (string): The guest payment method used to book the experience. Attributes include:
- Credit Card: any card-based transaction, including EMV.
- Cash: payment marked as collected in cash.
- None: no payment method and $0 in total revenue.
- Unpaid: no payment method and $0 in total revenue. These are unpaid bookings that have an outstanding, unpaid balance.
- experience_name (string): the name of the experience
- experience_date (datetime): the date of the experience in local time. Example: “2023-01-01”
- experience_time (time): the time of the experience in local time. Example: “21:00”.
- number_guests_booked (integer): The total number of guests booked for the experience.
- number_guests_checked_in (integer): The total number of guests who checked in for the experience.
- guest_first_name (string): The first name of the guest booking the experience.
- guest_last_name (string): The last name of the guest booking the experience.
- guest_email (string): The email address of the guest booking the experience.
- guest_phone (string): The phone number of the guest booking the experience.
- guest_country (string): The country of the guest booking the experience in ISO alpha-2 representation. Example: “US”
- total_number_addons (integer): The total number of add-ons booked.
- currency (string): string: ISO 4217 currency code. Example: “EUR”. Currency is based on the currency set on your AnyRoad account.
- total_revenue (decimal): The total revenue charged and collected from your guest for a booking after all applied discounts, excluding applicable service and credit card fees.
- total_vat (decimal): the total amount of vat included in total_revenue. The vat rate is set by you on your AnyRoad account.
- total_revenue_excluding_vat (decimal): the total revenue charged minus the total vat amount.
- total_discount_amount (decimal): The total discount amount applied to the booking. You can determine the total booking amount pre-discount by adding total_discount_amount and total_revenue.
- payout_dates (collection of datetime): The date or dates the booking revenue is paid out to you. Certain bookings can be paid out on multiple dates.
- location (object): The location associated with the booking.
- created (datetime): Date and time the booking was created in UTC time in RFC 3339 representation.
- updated (datetime): Date and time the booking was updated in UTC time in RFC 3339 representation.
- addons (collection): A list of each add-on and its associated revenue.
- tickets (collection): A list of each ticket type (e.g. Adults, Kids) and its associated revenue.
- private_notes (string) - Private notes related to the booking.
Endpoints
Retrieve Revenue Summary
Retrieve revenue summary details based on the provided parameters.
Data can be requested for a from_date and to_date.
URL:
https://app.anyroad.com/external/api/v1/overview/revenue
Parameters:
- date_type (string) - optional: The type of date queried by from_date and to_date. If date_type is not provided, queries will default to experience date.
- from_date (datetime) - optional: RFC 3339 date representation. In local time for experience date with time ignored. In UTC time for booking date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, beginning of day.
- to_date (datetime) - optional: RFC 3339 date representation. In local time for experience date with time ignored. In UTC time for booking date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, end of day.
- excluded_payment_methods (string) - The guest payment methods that will be excluded from the search results.
Example Request:
curl -H 'X-API-KEY: <your_api_key>' https://app.anyroad.com/external/api/v1/overview/revenue?date_type=booking&from_date="2018-01-01T00:00:00 00:00"
Example Response:
Status: 200
Retrieve a Booking
Retrieve details about an existing booking record. Requires the booking_id to be passed in as a URL parameter in order to look up the corresponding record.
URL:
https://app.anyroad.com/external/api/v1/bookings/
Example Request:
curl -XGET -H 'X-API-KEY: <your_api_key>' 'https://app.anyroad.com/external/api/v1/bookings/'
Example Response:
Status: 200 - OK
{
"data": {
"id": "123",
"type": "bookings",
"attributes": {
"custom_account_id": "account123",
"booking_date": "2020-01-21T17:09:14",
"booking_source": "Online",
"affiliate_name": "Hilton Hotels",
"booking_status": "Confirmed",
"payment_method": "Credit Card",
"experience_name": "Example Tour",
"experience_date": "2020-01-01",
"experience_time": "16:00",
"number_guests_booked": "3",
"guest_first_name": "John",
"guest_last_name": "Smith",
"guest_email": "john.smith@example.com",
"guest_phone": "14151231234",
"guest_country": "US",
"total_number_addons": "2",
"currency": "USD",
"total_revenue": "85.00",
"total_vat": "19.78",
"total_revenue_excluding_vat": "65.22",
"total_discount_amount": "0.00",
"payout_dates": ["2020-02-01", "2020-02-08"],
"location": {
"id": "1234",
"name": "Example Location"
},
"created": "2020-01-21T17:09:14Z",
"updated": "2020-01-21T17:09:14Z",
"addons": [
{
"custom_id": "addon123",
"addon_name": "Example One",
"number_addons": "2",
"addon_price": "10.00",
"addon_revenue": "20.00",
"vat_rate": "15.00",
"addon_vat": "2.61",
"addon_revenue_excluding_vat": "17.39"
},
{
"custom_id": "addon456",
"addon_name": "Example Two",
"number_addons": "1",
"addon_price": "5.00",
"addon_revenue": "5.00",
"vat_rate": "15.00",
"addon_vat": "0.65",
"addon_revenue_excluding_vat": "4.35"
}
],
"tickets": [
{
"custom_id": "ticket123",
"ticket_name": "Adult",
"number_tickets": "3",
"ticket_price": "20.00",
"ticket_revenue": "60.00",
"vat_rate": "15.00",
"ticket_vat": "16.52",
"ticket_revenue_excluding_vat": "43.48"
}
]
}
}
}
}
Status: 401 - Unauthorized
{ error: "Invalid API key." }
Status: 404 - Not Found
{ error: "Not Found." }
List all Bookings
List all bookings records that have been created.
Data can be requested for a from_date and to_date.
URL:
https://app.anyroad.com/external/api/v1/bookings
Parameters:
- date_type (string): optional: The type of date queried by from_date and to_date. If date_type is not provided, queries will default to experience date.
- from_date (datetime): optional: RFC 3339 date representation. In local time for experiencedate with time ignored. In UTC time for booking, created and updated date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, beginning of day.
- to_date (datetime): optional: RFC 3339 date representation. In local time for experiencedate with time ignored. In UTC time for booking, created and updated date with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_date is not provided, queries will default to yesterday, end of day.
Example Request:
curl -XGET -H 'X-API-KEY: <your_api_key>' 'https://app.anyroad.com/external/api/v1/bookings'
Example Response:
Status: 200 - OK
{
"data": [
{
"id": "11111",
"type": "bookings",
"attributes": { ... },
},
{ ... },
{ ... },
]
}
If you have any additional questions, you can contact our Customer Experience team via chat or at support@anyroad.com.