Search results

When integrating with GetYourGuide, it is crucial to understand the key mandatory endpoints that ensure a smooth booking process. These endpoints allow for effective communication between your system and GetYourGuide, providing accurate availability information and efficient reservation management. Below is an overview of the essential endpoints and their functionalities, along with a flow of the integration process.

1. Availability Query

• Purpose: Retrieve up-to-date availability for various products.
• Details:
  
  • Provides availability for each time slot within a specified period.
  • Indicates the number of available slots or shows if none are available.
  • Optional cut-off time parameter defines the advance notice required for bookings.
  • Supports long-term availability checks (up to 365 days in advance).

2. Reservation

• Purpose: Initiate the booking process by reserving product quantities.
• Details:
  
  • Reserves requested quantities for a defined holding time,
  • This step also serves as a double-check with your system to ensure the booking can be completed. It verifies product availability and confirms that all conditions (such as available slots, capacity, and any other prerequisites) are met before the booking proceeds.
  • Ensures selected products remain available for booking within the holding time.

3. Reservation Cancellation

• Purpose: Manage inventory when a customer removes an item from their cart.
• Details:
  
  • Frees up reserved products, ensuring accurate inventory management.

4. Booking

• Purpose: Confirm a previously placed reservation.
• Details:
  
  • Completes the booking process and provides additional customer and booking details.
  • Includes a retry mechanism in case of confirmation failure.

5. Booking Cancellation

• Purpose: Notify your system of a cancellation to keep inventory accurate.
• Details:
  
  • Updates inventory to reflect the canceled booking.

6. Notify Availability

• Purpose: Proactively inform GetYourGuide about significant changes in availability.
• Details:
  
  • Notify about major changes in availability.
  • Complements regular scheduled calls for availability to keep information updated.

Additional Note on Pricing

• Integration of Pricing:
  Prices can be included in the availability information flow. While not mandatory, integrating pricing can enhance the customer experience by providing up-to-date pricing during the booking process. This will allow to easily differentiate prices per day or timeslot. 

Key Takeaways:

• Seamless Integration: These endpoints are essential for ensuring smooth communication between systems.
• Real-Time Updates: Bookings, reservations, and cancellations are accurately managed to provide a great customer experience.
• Optional Pricing Integration: Adding pricing to the flow can further improve supplier experience and  satisfaction.

‍

When mapping an option for the first time, GetYourGuide will quickly request availability for the next 365 days to check for open vacancies. After this initial request, availability will be checked regularly, with more frequent checks for dates that are closer.

The availability check follows this schedule:

• Once per day for the next 30 days
• Every 4 days for the period between 31 and 90 days from today
• Every 8 days for the period between 91 and 365 days from today

If an option is mapped for both availability and prices, availability for the upcoming 7 days will be double-checked every 4 hours.

To optimize response times and reduce payload, the system divides these date ranges into smaller intervals. The size of these intervals depends on the number of timeslots you are providing; more timeslots per day will result in smaller date ranges, with a minimum interval of 1 day.

For further efficiency, availability checks are not performed all at once. Instead, based on the above frequency, these checks are distributed over 8 days.

Please note that bookings received from GetYourGuide are already accounted for in our system until the next availability check. However, we understand that significant changes in availability can sometimes occur. To ensure the most accurate availability and the best customer service experience, we strongly recommend implementing the Notify-availability endpoint.

‍

The Integrator Portal provides tools to help you test your reservation system integration in both testing and production environments. Below are the details on what you can test in each environment:

Credentials Setup

• You will need to provide credentials for both the testing and production environments.

Self-Testing Tool

The portal includes a self-testing tool to run integration tests in each environment, offering instant results and detailed failure information.

Testing Environment

• By entering the designated product ID, you can test the entire booking flow. This includes all mandatory endpoints, excluding the notify availability endpoint.
• The following features can be tested in the testing environment:
  
  • Availability Calls
  • Reserve and Cancel Reserve Endpoints
  • Book and Cancel Booking Endpoints
  • Error Handling: Verifies proper error responses
  • Modification Flow: Tests ability to modify bookings

Production Environment

• In production, you can test the full reservation flow:
  
  • Availability Checks
  • Reserve and Cancel Reserve Actions
  • Error Handling: Ensures your system manages errors as expected
• Additionally, a dedicated space is available for testing all supplementary feature endpoints.

‍

If you or the supplier receive an error while mapping an option, and the error mentions a lack of availability, please review all details in the error message. This could indicate an issue related to either the get-availability or the reservation test.

Step 1: Troubleshooting Get-Availability Errors

When mapping an option, our system attempts to locate at least two available timeslots within the next 365 days, starting from the closest dates. If the error states that no available dates could be found, confirm that the product ID is correctly returning availability.

To troubleshoot availability:

1. Use our [testing tool] and select Test Get-Availabilities as the test case.
2. Enter your product ID and availability type, then select the dates for which availability should be returned.

If no dates are returned, check that the product ID is correctly set up to return availability for the requested period.

‍

Step 2: Troubleshooting Reservation Errors

If the error message indicates a lack of availability during a reservation attempt, the cause might be different. This issue often arises due to a NO_AVAILABILITY error encountered during the reservation test.

Our system only initiates reservation tests for dates where availability has already been provided, and the requested vacancies won’t exceed those indicated by the supplier.

To troubleshoot reservations:

1. Confirm that the NO_AVAILABILITY error is being returned correctly. This error should only be returned if there aren’t enough vacancies to meet the reservation request.
2. Use the Test Reserve/Cancel-Reservation test case in the testing tool.

When testing, select dates with confirmed availability and ensure that the same categories specified by the supplier for the option on GetYourGuide are included. You can also test single categories to confirm the correct responses:

• If a category is unavailable or must be booked together with an adult, an INVALID_CATEGORY error should be returned instead of a NO_AVAILABILITY error.

Following these steps will help verify that the NO_AVAILABILITY error is being returned correctly during reservations.

‍

Essential Steps for Configuring Your Connected Product

To successfully configure your connected product on GetYourGuide, it's important to focus on three key details:

• Pricing Categories: Define the different pricing tiers for your product to accommodate various customer needs (e.g. Adult, Child, Infant, etc.).

‍

‍

• Capacity information: Provide clear details on the available spots for each experience to help manage customer expectations and bookings.

‍

• Price: Set your product's price, ensuring it reflects the value and quality of the experience offered.

‍

All of these details need to be completed in the Availability & Pricing section of your option in the Supplier Portal, as shown below the header here:

Related articles: 

• Pricing Categories for Connected Products
• Importing Capacity for Connected Products
• Price Page for Connected Products

‍

In addition to the mandatory endpoints that cover the essential flow of integration, several additional endpoints are available to enhance supplier performance and product management on the GetYourGuide platform. Here is a summary of these endpoints and their purposes:

• Products (Supplier Endpoint)

These endpoints enable suppliers to create and map their offerings efficiently, while avoiding mismatches between the two systems. Key functionalities include:

Product List Endpoint: Provides a list of all active product IDs for the supplier, enabling the identification and selection of products to connect to the platform.

Product Details Endpoint: Delivers detailed information for selected product IDs, including titles, descriptions, and locations, ensuring accurate and consistent product representation.

Pricing Categories Endpoint: Retrieves pricing data to support the creation, review, and refinement of pricing categories, including group size definitions and rates, ensuring seamless integration and consistency between systems.

‍

This integration aims to streamline the management of your activities on GetYourGuide, enabling seamless communication between your system and our platform. By establishing a robust connection, you will gain full control over availability, reservations, and bookings, ensuring a smooth experience for both your suppliers and their customers.

The flow involves GetYourGuide periodically querying availability for products, reserving quantities to initiate the booking process, and subsequently confirming the reservation to ensure successful bookings

To successfully create a system that integrates with GetYourGuide, you must develop all mandatory endpoints along with any additional, based on your specific needs. The mandatory endpoints include:

• Availability Query
• Reservation (with a minimum holding time)
• Reservation Cancellation
• Booking
• Booking Cancellation
• Availability Update Notification

These mandatory endpoints are essential for managing your activity on GetYourGuide, starting from the moment you provide us with availability to the moment you receive a booking. While all other endpoints are optional, they can only be implemented in addition to the mandatory ones.

Furthermore, the integration will occur at the option level. This means that for every option you have on GetYourGuide, your system will have a corresponding product ID linked to it.

For detailed requirements to integrate your system with our portal, please refer to our API Documentation .

Below, you will find a more comprehensive guide to our endpoints:

• Supplier Endpoints
• GetYourGuide Endpoints

‍

Essential Steps for Configuring Your Connected Product

To successfully configure your connected product on GetYourGuide, it's important to focus on three key details:

• Pricing Categories: Define the different pricing tiers for your product to accommodate various customer needs (e.g. Adult, Child, Infant, etc.).

‍

‍

• Capacity information: Provide clear details on the available spots for each experience to help manage customer expectations and bookings.

‍

• Price: Set your product's price, ensuring it reflects the value and quality of the experience offered.

‍

All of these details need to be completed in the Availability & Pricing section of your option in the Supplier Portal, as shown below the header here:

Related articles: 

• Pricing Categories for Connected Products
• Importing Capacity for Connected Products
• Price Page for Connected Products 

‍

Requirements: This endpoint should have been already tested and activated.

The Price Categories endpoint is designed to help suppliers configure options by providing key pricing information. This endpoint is triggered when the supplier begins adding prices to an option and imports the relevant data.

Steps for Creating Prices

• Upon successfully calling the Price Categories endpoint, categories, capacity, and prices are automatically suggested to the supplier. Suppliers can modify these values or save them and proceed to the next step.
• Once imported, this pricing information is fixed for the option, meaning the price will remain consistent across the entire calendar.

Alternative: Sending Prices Along with Availability

• Alternatively, if you choose to send rates along with availability via API, the price data received will override any previously imported information.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

GetYourGuide (GYG) supports API connections at an option level, enabling you to tailor your system to meet specific requirements.

Overview of Activities on GetYourGuide

Activities on GYG are structured into Tours and Options:

a Tour is a generic product that represents an experience or activity available for booking. It includes all the information about the activity, such as its description, location, highlights, and main details. However, you cannot book a tour directly. it serves as the overarching product that groups its specific, bookable variations.

A Tour Option represents the specific experience a customer will book. It  is a specific, bookable instance of a tour that includes all the details necessary for customers to make a booking, such as: Availability, Pricing, conditions

Key Requirements for Options

To be available for sale, each option must have both availability and pricing. Also, Options for the same tour may differ in features, such as:

Inclusion of meals (e.g., lunch)

Availability of additional services (e.g., audioguides)

Different pickup points or durations

For this reason, any option must have its specific Availability and pricing.

Start Times and Opening Hours

Each option can specify its starting times and opening hours:

Starting times: Indicate when a specific activity begins.

Opening hours: Refer to the overall time frame during which a venue or service is available to customers.

This information is essential for providing accurate availability and helping customers plan their activities effectively. Ensure your system accounts for these details to enhance the booking experience.

Price Categories

For each option, you can specify allowed price categories, which may have distinct pricing structures, rates, age ranges, and participant requirements.

Key note: Price categories must represent individuals (e.g., adult, child).

For more details on permitted categories, click here, and to review best practices for the GROUP category, please refer to the specific article in Basics of Connectivity.

‍

What should I do if I'm experiencing errors with the API?

If you encounter errors with the API connection (e.g., availability issues), please contact your Reservation System for support. Your reservation system is the main point of contact for troubleshooting your API connection. 

GetYourGuide cannot access your Reservation System account nor provide direct troubleshooting. Your Reservation System has access to tools to troubleshoot API integrations in our Integrator Portal. Describe your connection issue and they can test it from their end.

What should I do if I've already contacted my Reservation System and am still having trouble with the API?

Our Connectivity Support team can guide you through the API documentation and provide further information. Please ask your Reservation System to log a ticket with the Connectivity Support team at GetYourGuide via support-api@getyourguide.com. According to GetYourGuide’s SLAs, your Reservation System will receive a response from our Connectivity Team within 24 hours. 

Related links:

• Product not connecting

‍

Read this to learn how to configure Add-ons for your activities via your reservation system.

Add-ons are additional services or items that customers can purchase alongside an activity, such as drinks, audio guides, or helmets.

Important note: While this feature is live on GetYourGuide, your reservation system might not have integrated it just yet. We're teaming up with reservation systems to enable these for you. Please reach out to your reservation system to learn about and request the adoption of this new capability.

How to setup Add-ons in the Supplier Portal

1. Verify that your reservation system supports Add-ons. If so, you can configure and import these directly from your system.

2. Go to your product and navigate to Availability & Pricing under Edit Option.

3. Go through Pricing Categories, Capacity and Price. 

3. Under Add-ons, select "yes".

4. This triggers the Fetch_AddOns endpoint, importing details from your reservation system.

5. Review the add-ons and click Save and continue to validate the setup.

Frequently Asked Questions

• What if I can't see the Add-ons option?
  Ensure your reservation system supports Add-ons. If not, this feature won't be available. If a reservation system doesn't support Add-ons, the following error message will be displayed: "Your reservation system does not support this feature".
• Can I add new Add-ons manually?
  No, you can only use Add-ons imported from your reservation system. You cannot add or remove Add-ons beyond those imported.
• Can I change the price of an Add-on?
  Yes, you can edit the price directly in the Add-ons section.

By setting up Add-ons, you enhance your offerings and provide more value to your customers. Start configuring your Add-ons today to boost your sales and improve customer satisfaction.

Related Links:

• Setting up Tiers over API
• Connecting a new product to your Reservation system

Related to:

• API
• Availability & Pricing

‍

If you've updated the availability in your system, but the modifications are not visible on GetYourGuide website, here are some steps to help you troubleshoot:

1. Verify the Availability Reply
   Begin by confirming that your system’s response for the target dates is accurate. You can easily check this using our troubleshooting tool in the Integrator Portal. Please see [this guide] for instructions on verifying your availability response.
2. Timing of the Update
   When was the availability last updated? Keep in mind that GetYourGuide schedules regular calls to your system to check for updates. Closer dates are checked more frequently but still won’t be displayed immediately. For a detailed overview of the frequency of these checks, refer to the related article.

Best Practice: If the availability change is significant or time-sensitive, consider using the Notify-Availability endpoint to push the update immediately. This will ensure that the new vacancies are reflected faster on our website.

Note: Remember that if you are sending prices over the API, this is considered part of the availability. Any price changes not reflected online should be treated as part of the availability issue and should be troubleshooted in the same way.

3. Avoid Removing Time Slots
   It’s crucial not to remove time slots that have become unavailable from your reply. For example, if a specific time slot is now fully booked, set its availability to zero instead of omitting it from your response. If we don’t receive an update that availability has changed to zero, the time slot will still appear as available on GetYourGuide.

‍

Target Endpoint: Products List,  Product Details, Register a new supplier

Supplier ID, or Supplier External ID, refers to any identifier assigned to the supplier in your reservation system that allows for identifying their account and products within your system.

‍

A Reservation refers to the process of initiating a booking by temporarily holding a requested product quantity. It corresponds to the moment when a customer adds a product to their cart, ensuring that availability is verified before finalizing the booking. 

This process helps reduce the risk of booking failure by confirming that the requested product can be secured before payment. If the booking is not completed within the defined holding period, the reservation is automatically canceled, and the availability is released.

‍

Troubleshooting Product Connection Issues

Ensure your external reservation system information matches GetYourGuide's system for proper connection. If a connection fails, review the error message and contact your reservation system for support, if needed.

Common Connection Issues:

Invalid Product

• Ensure the product ID matches with both GetYourGuide and your reservation system.
• Make sure you’ve enabled the connection in your reservation system for all products you want to connect.

‍

‍

No Availability

If there are insufficient availability slots in your product, it won't be able to connect.

• Check that you have at least two available time slots in your external reservation system and that you are sharing availability via API with GetYourGuide.

‍

‍

Invalid Ticket Category

• Ensure ticket categories (e.g., Adult, Child) match between GetYourGuide and your reservation system.

‍

‍

Retail Prices Cannot Be Null or Empty

• When connecting via price over API, make sure to receive the correct pricing from your reservation system.

Mismatched Date and Time Zone

• Ensure the same time zone is set in both systems. Time zones must be set to the location of the activity’s meeting point.

Related Articles: 

• Setting Up Product Configuration for Connected Products
• Connecting a New Product to Your Reservation System

‍

Requirement: The Product List endpoint is an optional feature. Before troubleshooting, ensure that it has been successfully tested and activated in the Feature list.

For our system to call this endpoint, the supplier’s account on GetYourGuide (GYG) must be associated with the Supplier ID from your system. This association occurs under the following conditions:

• The supplier has registered through the API.
• The supplier has at least one product connected to the system.

Once a product is connected, our system will call the Product Details endpoint, where we retrieve the Supplier ID.

Troubleshooting: No Product List Displayed

If the product list isn't shown, there are three possible reasons:

1. No Connected Products
   The supplier has no connected products. You can verify this using our analytics to check whether the supplier has already connected a product.
2. Invalid Product Details Payload
   The payload received via the Product Details endpoint may contain invalid data, preventing successful validation. Please review the parameters for this endpoint to ensure accuracy. [Review parameters here]
3. Product Details Endpoint Not Triggered
   No product has been connected since the Product Details endpoint was activated. This should be verified to ensure the connection was correctly established.

Troubleshooting: Specific Product Not Displayed

If a specific product isn’t appearing in the list, the issue may be due to:

1. Multiple Supplier Accounts
   The supplier has multiple accounts in your system. In GYG, a supplier’s account can only be associated with a unique Supplier ID (typically the one linked to the first product connected). Therefore, the supplier will only see products from the account that matches the associated Supplier ID.
2. Product Linked to a Different Option
   The specific product might already be connected to a different option. You can troubleshoot this through our analytics.

Manual Product Addition

If the product isn’t displayed in the list, you can use the option provided at the end of the list to manually add the product.

‍

Understanding the Product Validation Process

After you've set up Pricing Categories, Capacity, and Price for your products, GetYourGuide initiates an automatic validation process. This crucial step ensures that your product meets all our necessary criteria. If successful, it allows your product to go live on the platform.

Navigating Validation Challenges

There are sometimes instances where a product might not pass the validation phase. This could be due to various reasons, often related to discrepancies or issues within the data provided.

If Your Product Does Not Pass Validation

Should your product encounter validation issues, please reach out to your Reservation System provider. They play a critical role in troubleshooting and resolving any problems that might have led to the validation failure.

Related Article:

Product Not Connecting

‍

Direct Import from Your Reservation System

If your system has adopted pricing categories over API, pricing category data will be automatically imported.

Manual Input for Pricing Categories

If your reservation system does not support the Price Categories over API feature, you must manually enter pricing details.

‍

• Determining your pricing structure:                                                                                                      
  
  • Price Per Person: Choose this for individual pricing categories (e.g., youth, adult, child).
  • Price Per Group/Vehicle: Opt for this if pricing is based on group size or per vehicle capacity.

‍

Note: It's not possible to mix both pricing structures (Group and Per Person) in the same option. Please submit each pricing setup as distinct options if your activity accommodates both.

Adding New Pricing Categories

‍

Select Pricing Basis: Decide if your pricing is fixed or age-dependent.

‍

• Fixed pricing: Select "The price is the same for everyone."
• Age-dependent pricing: Choose "Price depends on age" and specify categories like adults, children, seniors, etc.

‍

‍

Note: Ensure your age groups span from 0 to 99 years, marking any age groups as "Not Permitted" where necessary.

‍

Utilizing Advanced Category Settings

‍

Enable the “advanced settings” to further refine your category specifications as needed for activity-specific restrictions, such as age limits for participation, ticket requirements, and adult supervision for children.

‍

‍

Note: Any modifications to the imported data could lead to discrepancies between GetYourGuide and your reservation system configurations, potentially hindering your product's online availability. Ensure accuracy before making any changes.

‍

Related articles 

• Price over API
• Price Page for Connected Products
• Connecting a New Product to Your Reservation System

‍

Requirements: Endpoints must be tested and activated.

‍

All product endpoints are GET endpoints, which means data can only be pulled from GetYourGuide’s system, not sent to it. Here is a description of which scenarios trigger the call to these endpoints:

• Product List:
  
  • Purpose: Pulls the list of all active product IDs for the supplier.
  • Trigger: This endpoint is called when the supplier selects the reservation system to connect GYG Option..
  • Functionality: Once a product is selected, the system maps options without manual entry by the supplier.
  • Prerequisite: The system must already have identified the supplier ID.
• Product Details:
  
  • Purpose: Pulls detailed product information once a product ID is added.
  • Trigger: Automatically called when a new product ID is selected, updating details on GYG’s side.
• Pricing Categories:
  
  • Purpose: Pulls pricing information from your system when suppliers begin creating price categories on GYG 
  • Trigger: The call is triggered when the supplier clicks "Add New Pricing."
  • Functionality: Pricing data can be reviewed and modified by the supplier before finalizing.

Note: Supplier ID is provided via the Product Details endpoint. If no product is connected for the supplier, the Product List endpoint cannot be called.

‍

Choosing your pricing method

• Select Yes:
  If your reservation system supports Price over API and you want to import the prices' setup from your reservation system.
  
  
• Select No:
  If you want to manually setup your prices 

Manual price setup

‍

Note: The above commission rate is shown as an example. Your commission rate is applicable based on your current operating geographical area. Please also ensure you use the correct currency for your pricing.

Pricing tiers

Setting up price tiers is optional. Price tiers are scaled prices that allow you to have different prices per person depending on the number of people the customer books. The tiers you enter will apply to all of your age groups. 

Example: If you would like to offer a cheaper price for customers who book groups in bigger numbers, you can set up a price tier.

‍

The above tiered pricing setup means that if a customer books for 8 people, they would need to pay 72€ (9€ x 8) altogether.

Related articles:

• How to connect a product to a reservation system?
• Pricing Categories for Connected Products

‍

Within GetYourGuide, the term "Product" can have different meanings depending on the context. For instance, when discussing tours, you may see "Product" used to refer to activities.

In connectivity terms, any mention of "Product," "Product ID," or "External Product ID" in our documentation specifically refers to the activity identifier in your system. This is the product that is connected to our platform, and for which we will request availability.

Overview

• Feature: Price over API allows automatic retail price updates from your reservation system.
• Advantages: This eliminates manual updates, minimizes booking discrepancies, and supports different prices for different time slots.
• Integration: Not all reservation systems support price over API. Contact your reservation system to see if they support this feature.

‍

Important Notes

• Supported Categories: All of GetYourGuide’s ticket categories are supported: Adult, Child, Youth, Infant, Senior, Student, EU Citizen, Military, and Group tickets.
• Requirements: Prices must include taxes/fees, cover all time slots, and match the currency set in GetYourGuide.
• Manual Override: API prices override manually configured prices.

‍

Price Update Frequency & Dynamic Pricing

Similarly to availability, pricing information is pulled from your reservation system on a pre-defined schedule and is not updated in real-time. GetYourGuide's current default frequency of updates for most systems is as follows (this may vary based on different factors, such as errors or booking volume): 

• Every 8 days we fetch availability (and prices) for the next 365 days
• Every 4 days we fetch availability (and prices) for the next 90 days
• Every 1 day we fetch availability (and prices) for the next 30 days
• Every 4 hours we fetch availability (and prices) for the next 7 days

Note: For last minute price changes, it’s necessary to implement the push availability endpoint. Please ask your reservation system about using this endpoint. 

‍

Enabling Price over API

1. Confirm your system supports Price over API.
2. Create and connect a product in the GetYourGuide Supplier Portal.
3. Under the Availability & Pricing section of your option, set up pricing categories and participant capacity.
4. On the Price page, select “Yes. I want to import my pricing configuration.”
5. Complete the validation step.
6. Ensure the Availability & Pricing section displays “Consumed by the reservation system”, as shown at the end of the video below, and check that the pricing is correct on the live site.

‍

https://drive.google.com/file/d/18G_V-hvcqtcfb3ZCq8128OzYRJtZ4esK/view?usp=sharing

‍

Disabling Price over API:

1. In the Supplier Portal, go to Manage → Products.
2. Go to your desired activity and select Edit Option. 
3. Under Availability & Pricing, on the Price page, select “No. I will manually add the pricing configuration.”
4. Enter retail prices manually.
5. Complete the validation step.
6. Ensure the Availability & Pricing section displays “Set manually”, as shown at the end of the video below, and check that the pricing is correct on the live site.

‍

https://drive.google.com/file/d/1E4W4-UFR5H9njvAt5UCjT8Xdbr0HahQ8/view?usp=sharing

‍

Related Links

• Supported Systems & Instructions
• Setting up Product Configuration for Connected Products
• Uploading products

‍

⚠️ This information is only relevant for Suppliers who have registered with GetYourGuide on (or) After 27.02.2024

Automated Capacity Import via API:

• If your reservation system supports the Product Details feature over API, capacity information will be imported directly.
• You will see a prefilled form with all capacity data from your reservation system.
• You can edit the imported information, but be cautious: changes may cause mismatches between GetYourGuide and your reservation system, potentially preventing your product from going online.

Manual Input:

• If your reservation system does not support Price Categories over API, manual input is required:

1. Minimum Participants: Enter the minimum number of people required for your product.
2. Maximum Participants: Enter the maximum number of participants allowed per booking.

• After finalizing capacity information, click "Save and Continue" to proceed to the Price Page.

The page for both manual and imported capacity looks like the following:

‍

Related Articles:

• Connecting a New Product to Your Reservation System
• Pricing Categories for Connected Products

‍

Requirements: Product Endpoints  should have been already  tested and activated.

While option creation begins in the Supplier Portal, implementing the Product endpoints can streamline the setup process by letting suppliers import essential details directly. These GET endpoints pull data at key stages, enabling suppliers to import option descriptions, locations, price categories, and related settings into the system.

When all three endpoints are fully activated, suppliers gain flexibility in managing product details with greater speed and accuracy, reducing reliance on manual input through the Supplier Portal.

‍

The book call is triggered when the customer completes the booking by paying online. This call is meant to confirm a reservation that was placed previously, providing additional details to finalize the booking.

The 2 steps booking process aims to prevent situations in which customers complete a booking that can not be allocated. 

Let review the 2 steps:

Step 1: Reservation
Initially, the customer adds the product to its cart, specifying the number of people and the date. This action is managed by the "reserve" endpoint, which checks the possibility to proceed with the booking and, in case of success response, holds the reservation temporarily. Key checks, such as availability and settings, are performed at this stage, when the booking is not yet confirmed.

Part of the information recommended for this endpoint is a reservation-expiration: this information allows you to specify how long the reservation made will be held in your system. You can review more about this parameter here

Step 2: Booking Confirmation
Once the customer proceeds with payment, the "book" call is triggered to finalize the reservation. If the partner system returns an error or invalid response, the booking will still be confirmed on the customer side, but he won’t be able to receive your ticket until this is solved. 

Of course we understand that there may be other technical reasons that could let a book call fail. In this situation we prevent the possibility to retry the book call and try to confirm the booking.

You can find more information about the retry process here

‍Key note: While the "reserve" call ensures that basic checks are performed, an invalid response or an error during the "book" call will not refuse a booking, but only create a bad customer experience.

Yes, even if you’re creating an integration solely for your own company or a single supplier, you must still implement all mandatory endpoints to ensure full compatibility with GetYourGuide.

However, we recognize that your company might work with a specific configuration type. When registering your system, specify that it’s being developed for a single supplier. This allows you to test only the configurations you need, tailored to your business requirements.

Note: For systems developed for a single supplier, your integration will only support option mapping for that specific supplier’s account.

‍

The GetYourGuide integration requires a complete set of endpoints to function effectively. It is not possible to develop the integration solely to retrieve bookings or update availability independently; all mandatory functionalities must be implemented as part of the complete system. To ensure full integration, the following key endpoints must be developed:

• Availability Query
• Reservation (with a minimum holding time)
• Reservation Cancellation
• Booking
• Booking Cancellation
• Notify Availability

These mandatory endpoints are essential for managing your products, starting from the availability query through to successful booking. For more detailed information on these endpoints, please refer to our API Documentation.

‍

Our endpoints and the information they request are structured to display availability online as per our documentation. We understand that some of your activities might have unique requirements or rely on different data retrieval processes. However, additional information that isn't specified in our requests will not be validated.

To ensure a smooth integration, please match the required information as closely as possible. If you need to include extra details, you can add them directly to the tour option in the Supplier Portal.

Example:
If your activity requires both a starting time and an arrival time to confirm availability (e.g., for a transportation service where both times are typically needed), but our API only requests the starting time, a suitable solution is to:

• Set the trip duration in the option description.
• Provide only the starting time in the API request.

This approach maintains alignment with our API while still giving users a clear understanding of the total trip time.

‍

Step-by-step connection process:‍

Begin by enabling GetYourGuide integration within your Reservation System and note the product IDs provided by your system. 

Link your product in GetYourGuide:

• Navigate to Products → Manage in the Supplier Portal.
• Select See Details →  Edit option for your desired product.
• Go to Connectivity Settings.
• Under “Do you use an online reservation system?”, select “Yes, I use a reservation system.”
• Select your Reservation System from the dropdown menu. 
  
  • If your reservation system is not listed, review our Supported Systems and Instructions. For systems not currently integrated, encourage your provider to visit our Integrator Portal for guidance on developing compatibility with GetYourGuide.
• Select your External Product ID from the dropdown menu or enter it manually. 
  
  • For your first connection, manual entry of the product ID is always required.
  • Product list sync (NEW): If your reservation system has implemented the product list endpoint for automatic product ID generation, you can select the name of your product from the dropdown menu. If your reservation system has not implemented this endpoint, manual entry of the product ID is still required.

‍

Setting up the product configuration: 

Once you've completed the Connectivity Settings, setting up your product configuration is necessary for the product you created to be visible online. You will be prompted to provide and review the following input:

• Pricing Categories
• Capacity information
• Price 

‍

Product validation process:

The validation process will run automatically after setting up pricing categories, capacity, and price. Should the validation conclude without issues, your product will go live and be ready for customers to book.

https://drive.google.com/file/d/1G4Prh55a9sQXg6n4F4dqilGssyEh4U1T/view?usp=sharing

Note: If your product fails validation, please contact your reservation system to resolve the issue.

‍

Additional pricing blocks (date-based pricing)

If you want to use different prices on certain dates, you can create additional pricing blocks by clicking on Add New Pricing.

You will then be asked to enter the below details: 

• Name of the pricing block (e.g. "Summer pricing", "Valentine’s price")
• Prices for all categories
• All date ranges that you want the pricing to apply to

https://drive.google.com/file/d/13-wyRWQiAcjQyiOTviAx049HIe7JbvQ8/view?usp=sharing

Note:

• Multiple pricing blocks can be created, but all additional pricing blocks and the default pricing block must share the same price categories, capacity information, and price tiers.
• Date ranges cannot overlap between pricing blocks.

Related Articles:

• Price Page for Connected Products 
• Pricing Categories for Connected Products 
• Capacity Information for Connected Products

‍

Requirements: Your Reservation system must have passed successfully the live testing phase in order to be able to activate the additional features.

Supplier Endpoints

All additional feature endpoints can be tested directly in the Integrator Portal.

In your production environment, you will have a dedicated tab, "Test Additional Features," where you can use a self-test tool to assess all additional "Supplier endpoints."

In the dropdown menu, you can select the endpoint you want to test and add your product ID. Note that the Product Details endpoint will be tested alongside the Product List endpoint.

You can track your progress in the table at the top of the page.

‍

GetYourGuide Endpoints

For the GetYourGuide endpoints, including Push Availability, deals over API, and supplier registration, use the "Test GetYourGuide Endpoints" tab in the production environment.

Here, you'll find the sandbox URL to test your calls, as well as tools to monitor your progress and results.

Important: Important: Your HTTP Basic Auth credentials for any GetYourGuide endpoints can be found at the bottom of the "Set Up Your Testing Configuration" tab.

How to Activate These Endpoints

Once an endpoint has passed its tests successfully, the system will allow you to activate it.

Go to Manage Features under Manage Your Integration to toggle on the endpoint you wish to activate.

In GetYourGuide’s API, categories are structured to enhance the searchability of activities by associating them with individual participant-based categories only. This means all products must fit into specific categories that describe individual ticket options, like Adult, Child, Youth, or Senior. General or abstract category labels that might represent non-individual characteristics aren’t supported in the system; instead, suppliers are encouraged to align all unique category ideas with the individual-focused categories available in the API.

The single exception is the "GROUP" category, which allows suppliers to define a single ticket for an entire group rather than for each participant. This category specifies the group size for a ticket, allowing it to function independently of individual participant counts and provides flexibility for activities designed for group bookings. 

For more details on permitted categories, click [here], and to review best practices for the GROUP category, please refer to the specific article in Basics of Connectivity.

‍

‍

GetYourGuide automatically deactivates options for the following two errors: 

Invalid Product errors and No Availability errors.

What should I do if I receive a notification about my product being deactivated?

‍
Please contact your reservation system as they are able to identify the root cause of the issue and can suggest the best solution. They will also receive an email notifying them when products are deactivated.

Should I contact GetYourGuide if my product was deactivated?

There is no need to contact us unless you have specific questions about changing your product configuration in the GetYourGuide Supplier Portal.

What should I do to put my product back online?

‍
Once your booking platform confirms that the issue has been resolved, please activate your tour option in the GetYourGuide Supplier Portal.

To reactivate the option check the step-by-step instructions here.

Invalid Product Error 

If your product was deactivated due to invalid product error, it’s because your booking system has notified us that your product or your Product ID does not exist, is broken, or is misconfigured. Please verify if:

• Your product is connected via API
• Your product is mapped with the correct product ID
• Your product is correctly configured and this configuration is supported by GetYourGuide
• You’ve enabled the API connection with GetYourGuide in your booking system

You can update the product configuration and connectivity settings in the Supplier Portal. If the product should be connected and online, please reactivate it in the Supplier Portal once the issue is resolved. 

If you have checked all of the above and you can’t identify the reason for disconnection, please contact your reservation system for support.

No Availability Error 

If there are insufficient availability slots in your product, it won't be able to connect.

• Check that you have available time slots in your external reservation system and that you are sharing availability via API with GetYourGuide.
• If problems persist, please contact your reservation system.
  
  

How do you disconnect a product from API?

• Go to your option and navigate to the Availability & Pricing section.
• Select No under “Do you use a booking system for your availability?”
• Select Continue to save the setting.

‍

Example of a deactivated product from the customer’s side.

Related links

• How to Reactivate Options in the Supplier Administration
• Product Not Connecting

‍

The GetYourGuide (GYG) booking reference is a unique identifier for each customer’s booking journey, from initial reservation through to booking confirmation. Here we can see how it operates at each stage:

1. Reservation and Confirmation:
   
   • A unique booking reference is generated during the reservation phase. Once the customer confirms the booking, the reference continues through the booking confirmation.
   • If the customer cancels the reservation without completing the booking, this reference is not reused in any future attempts.
   • You will not receive duplicate GYG booking references for unrelated requests.
2. Re-used References:
   There are only two scenarios in which you may encounter a previously issued booking reference:
   
   • Reconfirmation Attempts: If a previous booking attempt failed, the same reference might be used to attempt reconfirmation.
   • Booking Modifications: If a customer modifies an existing booking, the original booking reference remains the same to maintain continuity.

Tips for Integration:

• It’s recommended that your system checks the GYG booking reference with each request to identify if it has been used before.
• If an incoming booking reference matches a previous one, this generally indicates a modification request by the customer. Correctly identifying this allows you to manage the modification effectively and confirm it within your system.
• Ensuring accurate identification of modifications helps maintain up-to-date booking records and supports a smoother customer experience.

Note: In the API Request Flow, initial reservation details and a booking reference are issued first. Upon payment confirmation, this reference finalizes the booking. If modifications or reconfirmation are necessary, the reference remains consistent to simplify tracking and customer support.

‍

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The GROUP category in GetYourGuide's API is designed for activities or services where the product is sold as a single booking, regardless of the number of participants. This category is ideal when pricing is fixed for the activity itself rather than for each individual. Here is how to use the GROUP category effectively in scenarios like these:

1. Fixed-Priced Tours: If a tour has a set price that does not change based on the number of participants, the GROUP category is suitable. For example, a private sightseeing tour priced at $200 would stay the same whether one person or six people join.
2. Private Rentals: For rentals like vehicles that are intended for private use, the GROUP category allows customers to book without needing individual tickets for each participant. This applies to bookings such as private boat rentals or exclusive car hires, where the total price is for the vehicle, not the number of people.
3. Exclusive Bookings (e.g., Restaurant Table Reservations): When customers are booking an exclusive or private experience—such as reserving a table at a restaurant that cannot be shared with other customers—using the GROUP category ensures they have a dedicated booking for their group only.

By using the GROUP category, suppliers can provide flexible booking options for activities where a single ticket covers the full experience, regardless of individual participant numbers, creating a smooth, user-friendly booking process for private experiences.

Please note, since the price set for the GROUP category is tied to the maximum number of individuals allowed, bookings through this category will always be allowed from 1 participant up to the maximum group size specified. If for any reason an option requires a minimum number of participants different from one, then this must be set through individual categories

Requirements: System has been already registered and live tested. 

When connecting an option, the system performs several tests to ensure proper integration and functionality. The following outlines what is needed and what is tested during this process:

Endpoints Tested

1. Get-availability
2. Reserve
3. Cancel Reserve

Availability Check

• Format Validation: The system verifies that availability data is retrieved in a valid format.
• Price Verification: If prices are connected via the API, the system checks that the prices categories match those set in the Supplier Portal.
• Time Slots Requirement: At least two time slots with vacancies must be provided for testing purposes.

• Response time: An overall reply-time accordingly with our SLA is required. 
• Consistency: The system will check if all available time slots are having the same availability format (time point or time period), In case connecting price over API, the same price categories should be returned for all available dates. 

Reservation Tests

The system conducts reservation tests under various conditions to ensure reliability:

• Single Person Reservation
• Multiple People Reservation
• Different Categories

A positive response is expected for all these tests. Any errors encountered during these tests may cause the validation to fail.

Cancellation Tests

• Cancel Reservation: The system attempts to cancel the reservation, expecting a positive response.

Availability Management Verification

• Post-Reservation Check: After making a reservation, the system verifies that the vacancies have decreased appropriately.
• Post-Cancellation Check: After canceling the reservation, the system ensures that the released vacancies are correctly added back to your inventory.

‍

We recommend not connecting multiple options to the same product.

Here is why:

• Each option will call availability on a different schedule, so shared availability can lead to inconsistencies.
• Cached availability won’t reflect bookings made for other options, which could result in overbookings.
• As noted in our documentation, information about which option is booked is not sent by default from our system, so you may not be able to track which specific option received the booking.

For more reliable availability handling, we suggest creating separate products for each option. This minimizes booking conflicts and ensures each option’s availability is accurately managed.

‍

No, you won’t be able to test with a live GYG option until the final testing phase. However, this isn’t necessary for initial testing.

After registering your new reservation system, you’ll go through three testing phases:

1. Phase 1: Initial Self-Testing
   
   • Use the self-testing tool to check basic functionality with only your product ID.
   • This phase confirms that your system’s core connections are working, without requiring a live GYG option.
2. Phase 2: Advanced Self-Testing
   
   • Continue self-testing to verify advanced interactions using your product ID.
   • This ensures that your setup is ready for real-time data and mappings, all without needing access to live GYG options.
3. Phase 3: Live Testing with GYG Options
   
   • In this final phase, the GetYourGuide Connectivity team will test your system with active GYG options.

Once this is successfully completed, your system will appear in the Supplier Portal, enabling you to self-map options.

Until Phase 3, you can complete all necessary testing steps with just your product ID, without needing a live GYG option.

‍

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

When multiple customers book an activity, GetYourGuide requires a unique ticket for each customer in the booking. Issuing the same ticket for different customers is not valid and will cause the system to fail in confirming the booking.

Using the "Collective" Category

If the supplier cannot provide multiple tickets per booking, you can instead use the "COLLECTIVE" category. This category allows you to issue a single ticket that covers all participants in the booking.

What Needs to be Done:

• No changes are required in other endpoints or the way you manage availability.
• During the reservation and booking process, GetYourGuide will send a request specifying the relevant categories and the number of participants.
• The only adjustment you need to make is to return the "COLLECTIVE" category in your booking response.

‍

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Benefits of Connecting Your GetYourGuide Product Options

Connecting your GetYourGuide product options with your system allows for:

‍

• Automatic updates of product availability and pricing, eliminating manual updates.
• Automatic processing of bookings in your system.
• Seamless booking and redemption experience for customers with your ticket barcodes/QR codes added to GetYourGuide vouchers.

Core Features and Capabilities of API Connection

Important note: 

All these features and functionalities are accessible via the Integrator Portal, which might not be accessible to our local partners. This is just an overview of the features and can be shared with your reservation system for further integration.

‍

Notify Availability Update:

‍

• The notify availability update proactively informs GetYourGuide of availability changes, such as additional availability or sold-out activities, to quickly reflect updates and capture more bookings.

‍

Price over API:

‍

• The price over API feature updates retail prices automatically based on your system's data, reducing manual updates and booking discrepancies.

‍

Booking Cut-Off:

‍

• Automatically adjusts cut-off times based on your system's data, allowing last-minute bookings by setting a lower cut-off time.

‍

Reservation Expiration:

‍

• Provides recommended reservation times for customers to complete checkout, with a default of 60 minutes if not supported by your system.

‍

Error Codes:

‍

• Classifies API error messages to automatically resolve common connection issues, such as re-attempting failed bookings or temporarily deactivating products to prevent further failures.

‍

Pricing Categories:

• The Pricing Categories API endpoint allows GetYourGuide to import and manage price category data for a specified product, accepting only supported categories and requiring feature activation via the Manage Feature panel.

‍

Products List:

‍

• The Product List API endpoint allows GetYourGuide to query and retrieve a complete list of supplier products from the supplier’s reservation system for seamless self-mapping by suppliers.

‍

Product Details:

‍

• The Product Details endpoint returns content and configuration settings for a product based on a requested external product ID from the supplier’s reservation system. 

‍

List Deals:

‍

• The List Deals endpoint enables you to retrieve all existing deals for a product from the supplier’s reservation system, displaying only those deals that were created through the API.

‍

Create a Deal:

‍

• The Create a Deal endpoint allows you to submit a new deal for a specific product in your system.

‍

Delete a Deal:

‍

• The Delete Deals endpoint allows you to remove deals that were created using the Create Deals endpoint.

‍

Reactivate a Deactivated Product:

‍

• The Reactivation endpoint allows you to reactivate a deactivated product by providing the GetYourGuide Option ID and your system's Product ID.
• The endpoint is rate-limited to 1000 requests per hour per partner, with a 429 error code if exceeded.

‍

Additional Information

If your system does not support these features, refer to the GetYourGuide Integrator Portal for technical details and support. We are dedicated to enhancing integration performance and features for our local partners.

‍

Related Articles: 

‍

• Supported Systems & Instructions

‍