Skip to main content

Bookings APIs

Maria Tentsou
  • Updated

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.anyguide.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 is your API key:

Request:

curl -H 'X-API-KEY: '
https://app.anyguide.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 canceled 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 (see above), 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. Whereas if you request data on 2018-04-02 for all bookings with a booking date before 2018-04-02 the data will eventually change because at least some of these bookings will be modified before their actual experience date.

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.
    • experience_id (string) - the ID of the experience booked.
    • experience_name (string) - the name of the experience booked.
    • experience_revenue (decimal) - the total amount of revenue associated with each experience. This amount excludes tax revenue. 
    • experience_vat (decimal) - the total amount of vat included in experience_revenue. The vat rate is set by you on your AnyRoad account.
    • experience_revenue_excluding_vat (decimal) - the total experience revenue charged minus the total experience vat amount. 
  • addons (collection): List of each add-on and its associated revenue. 
    • addon_name (string) - the name of the add-on purchased. 
    • addon_revenue (decimal) - the total amount of revenue associated with each add-on. This amount excludes tax 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-21 17: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-21 17:09:14",
       "updated": "2020-01-21 17:09:14",
       "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"
         }
       ]
     }
   }
 }
}

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. 
    • Canceled- a canceled 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. RFC 3339 date representation. Example: “2018-01-01T14:00:00 00:00”. 
  • 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.
  • 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. For example, a booking can be paid out in full after an experience and then refunded 7 days later. The refund will be paid out on a separate date.
  • location (object): The location associated with the booking.
    • id (string): A location id, as defined by you on your AnyRoad account.
    • name (string): A location name, as defined by you on your AnyRoad account. 
  • created (date): Date the booking was created.
  • updated (date): Date the booking was updated.
  • addons (collection): A list of each add-on and its associated revenue. 
    • custom_id (string) - A custom product id, as defined by you on your AnyRoad account.
    • addon_name (string) - the name of the add-on purchased. 
    • number_addons (integer) - The number of add-ons booked.
    • addon_price (decimal) - The list price per unit for an add-on.
    • addon_revenue (decimal) - The total amount of revenue associated with each add-on, or number_addons*addon_price. This amount excludes tax revenue and discounts. Because discounts are applied at the booking level in total_discount_amountthis addon_revenue may not reflect the amount guests actually paid if a discount was applied on the booking. 
    • vat_rate (decimal) - The vat percentage applied to the addon to determine addon_vat.
    • addon_vat (decimal) - The total amount of vat included in addon_revenue. The vat rate is set by you on your AnyRoad account.
    • addon_revenue_excluding_vat (decimal) - The addon_revenue minus addon_vat. 
  • tickets (collection): A list of each ticket type (e.g. Adults, Kids) and it’s associated revenue. 
    • custom_id (string) - A custom product id, as defined by you on your AnyRoad account.
    • ticket_name (string) - The name of the ticket purchased. 
    • number_tickets (integer) - The number of tickets booked.
    • ticket_price (decimal) - The list price per unit for a ticket.
    • ticket_revenue (decimal) - The total amount of revenue associated with each ticket,  or number_tickets*ticket_price. This amount excludes tax revenue and discounts. Because discounts are applied at the booking level in total_discount_amountthis ticket_revenue may not reflect the amount guests actually paid if a discount was applied on the booking.
    • vat_rate (decimal) - The vat percentage applied to the ticket to determine ticket_vat.
    • ticket_vat (decimal) - The total amount of vat included in ticket_revenue. The vat rate is set by you on your AnyRoad account.
    • ticket_revenue_excluding_vat (decimal) - The ticket_revenue minus ticket_vat. 

Endpoints

Retrieve Revenue Summary

Retrieve revenue summary details based on the provided parameters.

Data can be requested for a from_date and to_date. Please refer to Key Terminology to understand the differences between experience date and booking date, and the implications on booking data. 

URL:

https://app.anyguide.com/external/api/v1/overview/revenue

Parameters:

  • date_type (string) - optional: The type of date queried by from_dateand to_date. If date_typeis not provided, queries will default to experience date. 
    • experience- date range applies to the experience date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-04-01 experience date. Experience date is in your local timezone, and the time portion of the query is ignored. For example from_date“2018-01-01T00:00:00 00:00” with to_date“2018-01-01T00:00:00 00:00” will return all bookings that happened on 2018-01-01 local time. “2018-01-01T14:00:00 00:00” will return the same results since time is ignored for experience date.
    • booking- date range applies to the booking date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-03-01 booking date. Booking date is in UTC time and includes the time portion of the query. For example from_date“2018-01-01T14:00:00 00:00” with to_date“2018-01-01T16:00:00 00:00” will return all bookings that were placed between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query booking date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”. 
  • from_date (datetime) - optional: RFC 3339 date representation. In local time for experiencedate with time ignored. In UTC time for bookingdate with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_dateis 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 bookingdate with time and timezone allowed. Example: “2018-01-01T14:00:00 00:00”. If from_dateis 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. Valid parameters are: 
    • 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.

Example Request:

curl -H 'X-API-KEY: ' 
https://app.anyguide.com/external/api/v1/overview/revenue?date_type=booking&from_date="2018-01-01T00:00:00 00:00"

Example Response: 

Status: 200

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

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.anyguide.com/external/api/v1/bookings/

Example Request:

curl -XGET -H 'X-API-KEY: ' 'https://app.anyguide.com/external/api/v1/bookings/'
Example Response:
Status: 200 - OK
{
 "data": {
     "id": "123",
     "type": "bookings",
     "attributes": {
       "custom_account_id": "account123",
       "booking_date": "2020-01-21 17: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-21 17:09:14",
       "updated": "2020-01-21 17:09:14",
       "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 . Please refer to Key Terminology to understand the differences between experience date and booking date, and the implications on booking data.

URL:

https://app.anyguide.com/external/api/v1/bookings

Parameters:

  • date_type (string) - optional: The type of date queried by from_dateand to_date. If date_type is not provided, queries will default to experience date. 
    • experience- date range applies to the experience date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-04-01 experience date. Experience date is in your local timezone, and the time portion of the query is ignored. For example, from_date“2018-01-01T00:00:00 00:00” with to_date“2018-01-01T00:00:00 00:00” will return all bookings that happened on 2018-01-01 local time. “2018-01-01T14:00:00 00:00” will return the same results since time is ignored for experience date.
    • booking- date range applies to the booking date of the booking. For example, if a guest placed their booking on 2018-03-01 for an experience on 2018-04-01, the data returned will be based on the 2018-03-01 booking date. Booking date is in UTC time and includes the time portion of the query. For example from_date “2018-01-01T14:00:00 00:00” with to_date“2018-01-01T16:00:00 00:00” will return all bookings that were placed between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query booking date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”. 
    • created- date range applies to the created date of the bookings. Created date is in UTC time and includes the time portion of the query. For example from_date“2018-01-01T14:00:00 00:00” with to_date “2018-01-01T16:00:00 00:00” will return all bookings that were created between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query the created date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”.
    • updated- date range applies to the updated date of the bookings. Updated date is in UTC time and includes the time portion of the query. For example from_date “2018-01-01T14:00:00 00:00” with to_date “2018-01-01T16:00:00 00:00” will return all bookings that were updated between 2018-01-01 at 14:00 to 2018-01-01 at 16:00 in UTC. If you want to query the updated date based on your own local timezone you can modify the last portion of the query. For example, to translate the UTC time into PDC (UTC -7) you would modify the query like this: “2018-01-01T14:00:00 -07:00”.
  • 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_dateis 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_dateis not provided, queries will default to yesterday, end of day. 
  • number_of_bookings (integer) - optional: The number of bookings to return starting at the from_date. If no to_date is provided, it will use the default from_date (see from_date above).
  • excluded_payment_methods (string) - optional: The guest payment methods that will be excluded from the search results. Valid parameters are:
    • 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.
  • location_id (string) - optional: The location ID for the location to be included in the search results. If location_id is provided, only bookings for that location will be returned. 

Example Request:

curl -XGET -H 'X-API-KEY: ' 'https://app.anyguide.com/external/api/v1/bookings’

Example Response:

Status: 200 - OK
{
 "data": [
     {
       "id": "11111",
       "type": "bookings",
       "attributes": { ... },
     },
     { ... },
     { ... },
     // ...
 ],
 "meta": {
     "totalPages": 1000
 },
 "links": {
     "self": "https://app.anyguide.com/external/api/v1/bookings?page=1",
     "first": "https://app.anyguide.com/external/api/v1/bookings?page=1",
     "prev": null,
     "next": "https://app.anyguide.com/external/api/v1/bookings?page=2",
     "last": "https://app.anyguide.com/external/api/v1/bookings?page=1000"
 }
}

Status: 400 - Bad Request

{ error: "Bad Request." }

Status: 401 - Unauthorized

{ error: "Invalid API key." }

 

If you have any additional questions, you can contact our Customer Experience team at support@anyroad.com.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.