This article provides an overview of the ROLLER Data API and best practices for consuming its endpoints.
Overview
The purpose of the Data API is to provide venues with a mechanism to extract a copy of ROLLER data and syndicate that data to an external database such as business intelligence, analytics or cloud platforms.
The Data API does not provide any ability to write data to ROLLER and should not be used for real-time data use cases as it does not allow to query specific records and returns paginated data for a time period. It is optimised for periodic export of records on an hourly or daily frequency.
Documentation
Documentation of the Data API endpoints can be found here.
Access
Information regarding access, authentication, scopes and rate limits - API Overview.
Best practices
Depending on the type and quantity of data, endpoints will either be filtered by date or provide all available data with no ability to further filter records. Endpoints that export data types which change over time will be filtered on the records modified date.
Endpoints which require a date parameter will provide a maximum of one day's data per call.
Modified date
Date filtered endpoints require a start and end date query parameter in yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss format based on the timezone associated with the venue with a maximum date range of one day.
Returning data based on a modified date provides will expose a modified version (changes/updates of previous data) and allows the consumer app to efficiently query deltas of previous requests.
In the event where an existing record is updated, we recommend that you either:
- Perform a PUT within your data whereby the modified version of the data replaces the original version; or
- Delete the original record and insert with the modified version.
Frequency
For daily frequencies, we recommended calls timed in early morning hours such as 02:00 am for the previous day using the yyyy-MM-dd date query parameter.
If the use case necessitates more frequent updates, hourly calls should be implemented using the yyyy-MM-ddTHH:mm:ss whereby the startDate is the endDate of the last call.
Additionally, we recommend consumer apps also execute a daily call and put/replace records as a as described above.
Revenue endpoint
The Revenues endpoint is an exception and DOES NOT filter based on modified date, it filters based on the event date. Booking records can be updated without any change of the event date.
However, the Revenue endpoint enables the consumer app to query based on the booking reference which enables retrieval of adjusted data without querying a large date ranges as follows:
- Identifying an updated revenue event
This occurrence can be identified when a record in the response from the BookingItem endpoint contains a BookingModifiedDate which is not within +/- 5 seconds of BookingCreatedDate - Call associated Revenue record
Call the Revenues endpoint querying the specific booking using data from the BookingItem response to filter, namely:- startDate and endDate = BookingDate
- bookingReferences = BookingReference
- Update the record
As described above, PUT or delete and insert this modified revenue data.
Use cases
Guest spend and visitation
Creation of guest records in ROLLER
Guest records are created in ROLLER via two primary methods.
- Via a booking as the booking holder
- By signing a waiver or having a waiver signed on their behalf
Guest records endpoint - GET Customers.
Associating signed waivers and guests
A signed waiver record has three important identifiers.
- SignedWaiverId – The unique identifier for that specific person’s waiver record
- ParentSignedWaiverId – The unique identifier (SignedWaiverId) of the parent’s signed waiver who has signed on behalf of a minor
- CustomerId – Ties to CustomerId in the Customers endpoint
ParentSignedWaiverId will only be returned for minors who have had their waiver signed by a parent. Each individual will have their own signed waiver record, so a parent who has signed on behalf of two minors would return three signed waiver records, which would result in three unique guest records being created or updated.
Customer records endpoint - GET Signed Waivers.
Associating guests to bookings and tickets
Guests can be associated with bookings in two ways:
- As the booking owner (there can only be one per booking)
- By having their signed waiver record attached to a ticket within the booking (one unique signed waiver record attached to each ticket)
Within the BookingItem endpoint, there is a field for BookingCustomerId which is the CustomerId for the booking owner. If there is a booking owner assigned, then the spend on that booking can be attributed directly to that guest.
Booking owners are assigned for every booking created via the online checkout, however, they are frequently not assigned by operators in POS bookings.
Where venues require waivers, venues will require a waiver to be associated with a ticket and BookingSignedWaivers enables this Customer association. A booking signed waiver is a record of a waiver being linked to a ticket within the booking and the BookingSignedWaivers endpoint will return three key identifiers:
- BookingReference attribute also present in the BookingItems endpoint response;
- TicketId attribute also present in the Tickets endpoint response;
- SignedWaiverId attribute also present in the Signed Waivers endpoint response;
These identifiers enable you to associate specific guests to bookings and individual tickets.
Visitation
Each BookingSignedWaiver can be considered a visit.
The Tickets endpoint response includes ProductId which can be used to quantify the number of visits for a specific product if required. This can be achieved by associating the BookingSignedWaivers to Tickets with a particular ProductId.
The quantity of bookings a guest has as the booking owner can be used, however, frequently the booking owner may not actually be a participant (ticket holder) and therefore would not be associated with a BookingSignedWaiver.
Spend
Spend can be quantified in two ways:
- Booking owner
By the CustomerId associated with Bookings, however, many POS bookings are not assigned a booking owner. - Booking Signed Waivers
This method enables you to associate specific customers with tickets and reference the TicketId from the Revenue endpoint to identify the spend for each ticket.
If you do not wish to allocate spend to minors, then you will need to add logic to reference the ParentSignedWaiverId of the minor and allocating the spend appropriately.
Membership Metrics
Identifying Membership Bookings
Membership bookings do not have an isolated endpoint, they are a product type. The Products endpoint enables membership products to be identified via the ProductSubType attribute.
With the ProductId and the BookingItem endpoint, membership items can be identified. Bookings can contain multiple membership items, however, each membership will have a unique booking item record with a quantity of 1.
Identifying Key membership properties
- Membership status can be identified from the Meta field of the BookingItem endpoint. The Meta attribute MembershipStatus will return the membership status.
- Membership Status endpoint provides a data log of historical membership status changes.
- Membership start date the BookingDate attribute of the BookingItems response provides the date the membership was valid from.
- Cancellation or expiry date the Membership Status endpoint will provide the historical event of cancellation or expiry.
- Membership billing cycle can be identified from the Tickets endpoint via the RecurringPaymentFrequency attribute which return daily, weekly, monthly or yearly. The anniversary date will be the BookingDate returned from the BookingItems endpoint.
- Recurring membership payments can be identified via the TransactionLocation attributed (RecurringPayment) of the Revenues data.
Note to filter those records where EventType is Transaction in case of failed attempts to collect payment. FundsReceived value will be the amount of the recurring payment. - Membership redemptions are recorded in two different ways which the Membership Redemptions endpoint combines both of these actions into one set of redemption data:
- Checking in the membership which would produce a record in the attendances endpoint
- Using the membership ID as a discount code to purchase another product (most common)