The following tutorial describes common integration use cases for partners in the Things-to-do space. This applies for any partner that sells tickets to museums, attractions, tours, activities and events.
Follow the high level integration process outlined in the end-to-end integration guide, implementing the Order-based methods. Also, all things-to-do partners will integrate with payments, so please reference the enabling payments guide. When connecting tours, activities, and attractions products to locations / POIs, follow the policies in Things-To-Do Vertical Policies for Tours, Activities and Attractions
- Feeds: Generate merchants, services, and availability feeds including
ticket and payment information
- Refer to the How to structure availability with ticket types for help with the availability feed
- Booking Server: Implement the Order-based Implementation
of the booking server with the following methods:
- Real-time updates: Implement the Update Order API that sends a patch request to an existing order
Common Use Cases
Below are integration details for the most common use cases.
Specifying entrance tickets for attractions
By default, an availability slot represents the specific time that a user must arrive at the merchant. For admission and entrance tickets, however, users can go to the venue at any time during a time range (for example, tickets to Disney World). In this case, users can order tickets even after the start time has passed.
- Under SchedulingRules, set admission_policy to TIME_FLEXIBLE
- Under SchedulingRules, set min_booking_buffer_before_end_time as a positive value to allow bookings to be made after the slot begin_sec
- Set time slots to be the venue’s open business hours. If there are no opening hours for the venue, set the time range to be up to 24 hours (for example, 12am to 12am, or 12am to 11:59pm), but make sure that the start and end time works correctly with your booking server, as these times are used to identify the availability slot during booking.
Defining multi-day passes or tickets
- Under SchedulingRules, set admission_policy to TIME_FLEXIBLE
- Under SchedulingRules, set min_booking_buffer_before_end_time as a positive value to enable booking after slot start time
- Ensure the ticket’s validity time is made clear by either of the following:
- Create a different ticket type for each pass (1-day vs. 3-day pass) of a product
- Define detailed service names and descriptions if the duration applies to all tickets of the service
- Include begin_sec, end_sec, and duration per day even if the ticket spans
several days, because these are required fields. Currently, duration cannot be
longer than 24 hours. However, this doesn't mean that the duration that the
ticket is valid for needs to be within 24 hours. The slot duration will not be
shown to users as long as the service scheduling rules are specified correctly.
- Pick an end_sec that is start_sec < end_sec <= start_sec + 24x3600 (preferably after the venue closing time so that tickets can still be booked after the start time has passed when min_booking_buffer_before_end_time is set), and is consistent with how your booking server validates availability for CheckOrderFulfillability and CreateOrder requests.
Specifying tickets or activities with an unknown end time
- Under SchedulingRules, set admission_policy to TIMED_ENTRY_WITH_FLEXIBLE_DURATION
- Include the begin_sec, end_sec, and duration even if the end time is unknown
because they are required field. However, the slot duration will not be shown
to the users as long as the scheduling rules are configured properly.
- Pick an end_sec that is start_sec < end_sec < start_sec + 24x3600 and is consistent with how your booking server validates availability for CheckOrderFulfillability and CreateOrder request
Representing dynamic prices
Dynamic pricing is supported for certain use cases where ticket prices can differ based on time slots, for example, weekend versus weekday prices. This model works best if ticket dates and prices change only occasionally. If prices can fluctuate drastically for your products within 30 days, please reach out to your Google contact for further discussion.
- Define slot level ticket types by pricing, for example adult_weekday, and
- The two ticket types can have the same description (e.g."adult") but different prices
- For each availability slot, set ticket_type_id to the subset of ticket types that are eligible for this slot defined in the services feed
- When a ticket price for a product changes, update the price through a real-time update API call, or update it in the next daily feed
Defining service descriptions
- For structured service descriptions, use HTML. Refer to the specifications to see which tags are supported.
- Items that need to be included in service descriptions:
- A clear description of the service you will be providing. Explicitly describe what is included with the purchase of a ticket.
- What additional items would be required to make full use of this service or that a user might mistake for being included.
- Prerequisites or Condition [if applicable]
- Include any information that could limit who is eligible to make this purchase. Examples include: 18 years or older and child tickets must be purchased with an adult ticket.
- Cancellation Policy
- State what conditions, if any, that refunds are available and how they could be acquired.
- Departure Point [Tours Only]
- A user should be clear on where they will be expected to arrive to use their ticket.
Using custom intake forms
Custom intake forms allow you to collect essential information from users at the time of reservation. Examples of essential information are the weight of a person for a skydiving service and the customer’s pickup location for a taxi tour.
In order to ensure the checkout experience is as frictionless as possible for users, custom intake forms should not be used for non-essential questions such as "how did you hear about us?" (even if the field is not marked as required). Too many questions will reduce the likelihood of users completeing the checkout flow and booking the service.
There are two possible intake forms that can be used:
- Per ticket form: The fields in this form will be repeated for each ticket that the user purchases. You should use this if you need to tie information about the user to the individual ticket.
- General form: The fields in this form are shown once per order regardless of how many tickets are purchased. You should use this to collect party/order level information.
The following question types are available, and each question can be marked as required or optional:
- Short answer
- Multiple choice
- Boolean (yes or no)