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.
Request:
curl https://app.anyroad.com/external/api/v1/users/key -u "janedoe@example.com:SuperSecretPa$word"
Response:
{ "data": { "type": "users", "id": "123", "attributes": { "key": "example-key-1234" } } }
Request:
curl -H 'X-API-KEY: ' https://app.anyroad.com/external/api/v1/users/profile
Response:
{ "data": { "type": "users", "id": "123", "attributes": { "first_name": "Jane", "last_name": "Doe", "email": "janedoe@example.com" } } }
- 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.
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" } ] } } }
- 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-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" } ] } } } }
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.
- 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 (datetime): Date and time the booking was created in UTC time in RFC 3339 representation. Example: “2018-01-01T14:00:00Z”.
- updated (datetime): Date and time the booking was updated in UTC time in RFC 3339 representation. Example: “2018-01-01T14:00:00Z”
-
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.anyroad.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”.
- 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 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.anyroad.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.anyroad.com/external/api/v1/bookings/
Example Request:
curl -XGET -H 'X-API-KEY: ' 'https://app.anyroad.com/external/api/v1/bookings/'
{ "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-21T17:09:14", "updated": "2020-01-21T17: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." }
URL:
https://app.anyroad.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.anyroad.com/external/api/v1/bookings’
Example Response:
Status: 200 - OK
{ "data": [ { "id": "11111", "type": "bookings", "attributes": { ... },
},
{ ... },
{ ... },
// ...
]
}
{ 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.
Comments
0 comments
Please sign in to leave a comment.