> [HTML](https://integrator.getyourguide.com/documentation/overview) · [OpenAPI YAML](https://integrator.getyourguide.com/assets/api_documentation/supplier-api-overview.bundled.yaml) · [OpenAPI JSON](https://integrator.getyourguide.com/assets/api_documentation/supplier-api-overview.bundled.json) # Overview This document describes the standards used to establish connectivity between a supplier’s system and GetYourGuide.

To achieve this connectivity, the supplier must provide an API consisting of endpoints that allow GetYourGuide to query the availability of products, place reservations and bookings, as well as cancel them. All of these supplier-side endpoints must be implemented for a successful integration.

The system also includes some endpoints that are provided by GetYourGuide, which should be used by the supplier to send notifications about changes in availability (**mandatory**) and ticket redemption (optional). ## API Format The API must be implemented as a set of regular HTTPS endpoints that handle data as JSON formatted payloads as per specifications. It is important that the HTTP Content-type header is set to `application/json` for all responses.

Please note as well that we always expect a `200` HTTP status code, as long as the response contains an expected payload (this includes error codes). All non `200` HTTP status codes are considered transport and/or server failures.

Please also note that we might add additional non-breaking fields to each data structure at our convenience; your JSON deserializer should be flexible enough to handle these new fields without breaking.

Consider as well that as GetYourGuide application is localized in 28 languages, it’s mandatory for your API to properly handle non ASCII characters. # Service Level Agreement In light of GetYourGuide's mission of making sure our customers love where they are going, we aim to provide a swift and uninterrupted service experience to all our customers.

The following section outlines the minimum guarantees required from service providers connecting to the GetYourGuide system through the provided GetYourGuide Supplier API. In practice, we expect a much better service than what is defined in this document. Failure to accept or comply with these terms will render a service partner ineligible for live connectivity integration. ## Service Uptime Every service provider is expected to ensure API availability 99.8% of the time in any given calendar month.

Any API unable to respond to a request within a maximum of 15 seconds (_soft-limit_) will also be considered unavailable. In such cases, the request will be cancelled potentially leading to inconsistent booking data. ## Response times When it comes to response times, the expectations are defined based on the measured impact on our customers experience. For that reason, these expectations are higher for real-time API calls and slightly more relaxed for offline processes. The table below describes the 95th percentile as well as the longest accepted for the remaining calls. All times in seconds. Whenever a call to an endpoint exceeds 27seconds (hard-limit), the connection will be dropped and it will count against the partner error rate.

**Please note that if you connect to a third-party system we still expect the operation response time to be within the limits shown below.**

API endpoint Desired (seconds) Acceptable 95th percentile (seconds) Acceptable Longest response (seconds)
reserve < 1 3 10
book < 2 4 10
cancel-reservation < 1 2 4
cancel-booking < 1 4 6
get-availability (1 day) < 1 3 6
get-availability (30+ days) < 5 10 15
## Minimum Required implementation In order to ensure a seamless experience for our customer, we require partners building an integration to our GetYourGuide Supplier API to develop and implement the following mandatory components:

- API Endpoints - Availability query - Reservation - Reservation cancellation - Booking - Booking cancellation - Availability Update Notification The following elements are mandatory implementations for any systems open to more than one supplier, e.g., ticketing providers and reservation systems:

- Support for both individual and group pricing. - Support for both time-point and time-period products. - The desired reserve time is 60 minutes, and the minimum reserve time is 15 minutes (see `reservationExpiration` under the [Reservation](/documentation/supplier_endpoints#operation/post-reserve) Responses). The following endpoint is of optional implementation:

- Ticket redemption endpoint. Implementation is recommended when you handle activities where customers need to redeem a ticket and the supplier needs to have date on ticket redemption. - Reactivate a Deactivated Product. - Notification Webhook. Failure to develop and implement all of the mandatory elements will result in the integration being considered incomplete and not ready for production. ## API Updates and Developments In a constant effort to improve the service experienced by our customers, GetYourGuide will continuously release updates and new elements to its API. These updates will be communicated to all partners in a timely manner. If the update is considered to be of mandatory implementation (due to the impact to our customers), then GetYourGuide will not only communicate such fact to the partner, but will also provide them with support and sufficient time for its implementation. Failure of a service partner to implement an update to the GetYourGuide Supplier API, deemed as mandatory by GetYourGuide, will result in such integration being deemed as not ready for live service.

All changes implemented in our API are listed in the Change Log.

New elements will be added to our API on a regular basis. We expect our partners to ignore any additionally added fields if they do not intend to use them. ## Incidents Monitoring To provide last-minute availability to our customers and ensure a seamless experience, we expect our Connectivity Partners to address any incidents involving API errors and failed reservations and bookings.

In order to monitor these issues on the partner side we suggest taking advantage of monitoring tools such as [Airbrake](https://airbrake.io/), [NewRelic](https://newrelic.com/), [Datadog](https://www.datadoghq.com/), or [Kibana](https://www.elastic.co/products/kibana). If you already have an integration with GetYourGuide, please regularly check the Integrator Portal Analytics Performance section.

Additionally, GetYourGuide will generate automated email notifications to our Local Partners and Connectivity Partners whenever there is a prolonged incident involving one or more bookings and one or more products.

GetYourGuide currently generates the following automatic incident alerts:
Incident Email Trigger Recipient Expected Response
Individual booking failure When a booking fails to confirm. Connectivity Partner & Local Partner Immediate action & reply within 48-hours is expected (prioritize by customer travel date).
General booking failure When the success rate of the booking call drops below 70%. We will automatically increase cut-off of affected options. Connectivity Partner Immediate action & reply within 48-hours is expected (prioritize by customer travel date).
Reservation failure success rate drop When the success rate of the reserve call drops below 70%. Connectivity Partner Action & reply is expected.
Further to the automated incident alerts mentioned above, in certain situations, GetYourGuide will proactively reach out to our Connectivity Partners by email. We will endeavour to clarify the issue being reported and provide our partners with data to support its resolution. GetYourGuide expects its partners to proactively respond and act upon our contact.

In certain circumstances, GetYourGuide reserves the right to deactivate affected tour options. We will notify the Connectivity Partner and the Local Partner via email when an option is disconnected and deactivated. Local Partners will be able to re-connect and activate the products in GetYourGuide Supplier Portal when the issue is fixed.

Incident Email Trigger Recipient Expected Response
Tour option deactivated: Invalid No Availability Error When a NO_AVAILABILITY error code on reserve is returned and when requesting availability for the datetime returns enough vacancies to complete a successful reservation. Connectivity Partner & Local Partner Support the Local Partner in resolving the issue.
Tour option deactivated: Invalid Product When an INVALID_PRODUCT error code is returned. Local Partner No action needed unless the error code was returned in error.
## Booking Retries When we encounter certain error scenarios on the book endpoint, we will automatically retry our booking requests to attempt to confirm the booking. These retries occur when:

- An `INTERNAL_SYSTEM_FAILURE` errorCode is returned - An `INVALID_RESERVATION` errorCode is returned - We receive a non-200 response and the errorCode returned is not one of our accepted error codes - Our call fails and we receive no response - Our system times out waiting for a response **Retry Limit:**
There will be a maximum of ten retries if the specified conditions are met. **Retry Interval:**
- The first retry will occur 10 minutes after the initial failed attempt. - Subsequent retries will also occur every 10 minutes, up to a maximum of ten retries. **Invalid Reservation Handling:**
In cases of `INVALID_RESERVATION` errorCode or if the initial valid reservation request expires (The retries run after the Hold time), the system will attempt to retry the reservation before proceeding with the booking call.
**Manual Retry:**
If a booking is still not confirmed after these retries, the failed booking may be manually retried (via API) by GetYourGuide staff. ## Error rates Besides Incident Monitoring, GetYourGuide’s API partners receive bi-weekly metrics via email. This is to provide you with as much visibility as possible and to help you ensure that your GetYourGuide activities are working properly.

As part of our initiative to ensure our customers have incredible experiences on our platform, the following SLAs will be in effect as of 1/2/2020.
Error type Maximum acceptable
get-availability < 0.01%
reserve < 1%
book < 0.5%
cancel-booking < 0.5%
# Errors When an error occurs, it should be categorized into one of the types listed in the table below in order to facilitate automatic responses to errors, error handling and debugging.

**Please note, the error structure must be present in the response only if the request is not successful. The API response will accept either the data structure with the successful response or the errorCode structure, not both. Inconsistency might lead to the API requests to fail.** ## Errors applicable to all endpoints
Error Code Explanation
AUTHORIZATION_FAILURE The provided credentials are not valid. 
      
      {
          "errorCode": "AUTHORIZATION_FAILURE",
          "errorMessage": "The provided authentication credentials are not valid."
      }
INVALID_PRODUCT The specified product does not exist or is broken for another reason (excluding availability issues). When this error code is sent the product is automatically deactivated in our system and the supplier will be notified by email. 
      
        {
          "errorCode": "INVALID_PRODUCT",
          "errorMessage": "This activity should be deactivated; not sellable."
        }
VALIDATION_FAILURE The request object contains inconsistent or invalid data or is missing data, such as incorrect date range requested, timeslots are in the past, etc. Please provide as much detail as possible in the error message. 
      
      {
          "errorCode": "VALIDATION_FAILURE",
          "errorMessage": "The requested travel date is in the past."
      }
INTERNAL_SYSTEM_FAILURE An error occurred that is unexpected and/or doesn’t fit any of the types above, including timeouts, service not reachable, etc. Please provide as much detail as possible in the error message.

When this errorCode is returned we will retry the booking request per our booking retries logic. 
      
      {
        "errorCode": "INTERNAL_SYSTEM_FAILURE",
        "errorMessage": "A timeout has occured. The request exceeded 10 seconds."
      }
## Errors applicable to specific endpoints
Error Code Explanation
NO_AVAILABILITY Applicable endpoint: Reservation, Booking
The reservation or booking call cannot be fulfilled because there is insufficient availability. 
        
        {
            "errorCode": "NO_AVAILABILITY",
            "errorMessage": "This activity is sold out; requested 3; available 0."
        }
INVALID_TICKET_CATEGORY Applicable endpoint: Reservation, Booking
The reservation or booking call specified a ticket category that is not configured for the requested product. 
      
        {
            "errorCode": "INVALID_TICKET_CATEGORY",
            "errorMessage": "The ticket category student is not sellable.",
            "ticketCategory": "STUDENT"
        }
ticketCategory must match a ticket category supported. The value for this field should be the (or one of the) unexpected ticket categories that have been requested.
INVALID_PARTICIPANTS_CONFIGURATION Applicable endpoint: Reservation, Booking
The reservation or booking call specified a ticket quantity that is not allowed for the requested product. This is based on the minimum or maximum number of participants per booking that have been configured for this product in your system.

Individual Ticket Categories
For Individual ticket categories, which consists of all ticket categories except Group or Collective, the expected response is: 
      
        {
            "errorCode": "INVALID_PARTICIPANTS_CONFIGURATION",
            "errorMessage": "The activity requires a minimum of 4 participants.",
            "participantsConfiguration": {
              "min": 4,
              "max": 10
            }
        }
In this example we might have made a request for two Adult tickets. This did not meet the product’s minimum participant number (four) in your system, so we received this error response.

When we receive this error response, we will update the relevant product’s configuration in the GetYourGuide Supplier Portal to prevent our customers from booking an invalid number of participants in future. The min (Integer, at least 1) and max (Integer, or ‘null’ if there is no maximum) in your response will be applied as the minimum and maximum participants per booking for all timeslots of this product.

Group Ticket Category
If you are returning an error to a booking request for a Group ticket, you must include the groupConfiguration structure: 

{
  "errorCode": "INVALID_PARTICIPANTS_CONFIGURATION",
  "errorMessage": "The activity can only be booked for 1 group.",
  "participantsConfiguration": {
    "min": 1,
    "max": 20
  },
  "groupConfiguration": {
    "max": 1
  }
}
The groupConfiguration structure with the element max (Integer, at least 1) specifies how many Group tickets can be booked for each timeslot.

You only need to include the groupConfiguration structure if you are returning an error on a booking request for a Group ticket. For all Individual ticket categories this structure should be omitted.
INVALID_RESERVATION Applicable endpoint: Booking
The booking call cannot be fulfilled because specified reservation does not exist or is not in a valid state. 
         
         {
             "errorCode": "INVALID_RESERVATION",
             "errorMessage": "Expired reservation; 60min hold time was exceeded."
         }
INVALID_BOOKING Applicable endpoint: Booking Cancellation
The booking cancellation call cannot be fulfilled because booking does not exist or is not in a valid state. 
         
         {
             "errorCode": "INVALID_BOOKING",
             "errorMessage": "The booking has been cancelled already."
         }
INVALID_SUPPLIER Applicable endpoint: Get Products List
The request is not valid because the supplier does not exist or is not configured to sell on GetYourGuide. 
         
         {
             "errorCode": "INVALID_SUPPLIER",
             "errorMessage": "Supplier does not exist in the system."
         }
# General Definitions ## Datetime formats Points in time are expressed as strings using the `ISO 8601` datetime format (e.g. “`2020-12-05T14:00:00+02:00`”). We always expect the local time with its timezone as UTC offset.

Example Burj Khalifa entrance Ticket in Dubai for the 5th of December 2020 at 14:00 (local time):

**Expected**: `2020-12-05T14:00:00+04:00`

**Not expected**: `2020-12-05T10:00:00+08:00` / `2020-12-05T18:00:00+00:00`

Please note that although the above examples express the same point in time, we consider only the first one valid as we always require the date and time in reference to the location of the activity. ## Time period vs time points GetYourGuide distinguishes between what we refer to as time point and time period products. While a time point product is an activity starting at a specific point in time (example: bus leaves at 10am), a time period product represents the times between which the customer is granted access to an activity (example: opening hours, between 10am and 5pm).

When a product is setup in the GetYourGuide supplier backend it must be chosen what type of product it is.

In the context of the API we require you to treat the two types differently.

### Time point - You can send us as many time points for an activity for a given day as you conduct it - The DateTime format is expected to contain the complete date and time information, for example: `2020-12-05T14:00:00+04:00` ### Time period - You may only send us 1 occurrence per any given day - The DateTime format is expected to contain the date information and the time to be set to `00:00:00`, for example: `2020-12-05T00:00:00+04:00` - You must provide us the opening hours (openingTimes) - Opening times spanning the full day can be expressed by setting `fromTime` to `00:00` and `toTime` to `23:59`. Any availability containing `24:00` in the opening times definition will be ignored by our system. ## Ticket categories Please find the list of the supported ticket categories below. All categories describe an individual with the exception of `COLLECTIVE` and `GROUP`.

Complete list of supported categories:
`ADULT`,
`CHILD`,
`YOUTH`,
`INFANT`,
`SENIOR`,
`STUDENT`,
`EU_CITIZEN`,
`MILITARY`,
`EU_CITIZEN_STUDENT`,
`COLLECTIVE`,
`GROUP`

Please note the difference between the `COLLECTIVE` and the `GROUP` category. While a `GROUP` is a category we would be using if products on GetYourGuide are set up as group products, `COLLECTIVE` is merely used to represent the case where no individual (or per group) tickets can be issued.

If we for example place an order 2 `ADULT` and 1 `CHILD` we expect you to respond with 3 tickets, 2 of type `ADULT` and 1 of type `CHILD`. Failing to return tickets that match what was placed will result in the order being unconfirmed. Alternatively GetYourGuide accepts 1 (and only 1) `COLLECTIVE` ticket.

If we order 3 tickets of type `GROUP`, each group of 8 people, you would respond with 3 tickets, each of type `GROUP`. If you cannot issue group tickets you may as an alternative return 1 (and only 1) `COLLECTIVE` ticket. ## Product ID The ID of the requested product in the supplier’s system. Each product ID maps to one tour option on GetYourGuide. A tour option can have multiple starting times, but a single product ID needs to respond to all of them. It can be up to 255 characters long. Please refrain from using the character `%` in your Product ID, as it is used as an escape character during [URL encoding](https://en.wikipedia.org/wiki/URL_encoding#:~:text=Reserved%20characters%5B,raw%20/.). The use of `%` may lead to failed encoding of the product ID in the URL, particularly when GetYourGuide is making availability queries to your system. Please note that we will not map individual time slots, different languages and different ticket categories but you can encode all this information into the product ID (e.g. via a JSON structure) as long as you provide a string of maximum 255 characters long.

# API Request Flows This section documents the API request flows that involves multiple API calls and what is expected. ## Booking Change When a customer contacts GetYourGuide to make an amendment to a booking (e.g. to lower the pax nr or the activity starting date/time) we create a new reservation and booking with the same GYG booking reference but with different details as pax or activity start date/time.

In this situation we expect the system to detect the changed details and return a new booking. After this succeeds we will then issue a cancellation request with the old supplier booking reference. For the expected amendment flow, please see the picture below. ![Booking Flow](../assets/api_documentation/booking_and_amendment_flows.png) # Authentication API authentication in both directions (from GetYourGuide to your API system and from your system to GetYourGuide API) is achieved using HTTP’s [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side). I.e. username and password are provided in the Authorization header field according to the HTTP specification.

Security Scheme Type HTTP
HTTP Authorization Scheme basic
No other forms of authentication are allowed (e.g OAuth or Bearer token are not accepted). ### From GetYourGuide to your API System: We will require credentials to communicate with your API system (e.g. reserve, book) both for testing and production (credentials can be the same or different for the two environments).

Credentials will define the access to the complete API and it's not possible to provide different username and password based on the suppliers hosted on your system.

### From your system to GetYourGuide API: Additionally, we will provide credentials for you to make calls to GetYourGuide API system (e.g. availability notification, ticket redemption) # Change Log
Date Version Author Changes
2025-09-23 48 PLH
  • Added Live Availability and Pricing feature documentation
  • Added comprehensive documentation for real-time availability and pricing retrieval
  • Added circuit breaker configuration and performance standards documentation
  • Added supplier experience guidelines for Live A&P implementation
2025-03-24 47 MS
  • Added support for availability by ticket category.
  • Added new object field vacanciesByCategory to Availability Query
  • Added new object field vacanciesByCategory to Notify Availabity Updated
  • Added new validation for oneOf vacancies or vacanciesByCategory can be provided in avalabilities
2024-12-19 46 US
  • Added 3 new error codes in Booking Cancellation Endpoints to support rejection of cancellation
2024-10-01 45 US
  • Added tieredPricesByCategory object to the Availability Object to enable tiered pricing.
  • Added new endpoint to consume AddOns setup in the SRS
2024-04-17 44 US
  • Added new GetYourGuide endpoint to register new suppliers who are not yet registered with GetYourGuide (API documentation).
2023-10-05 43 US
  • Added new endpoint Product Details over Api to fetch details of a product based on a requested External product ID
  • Added new endpoint Product List Over Api to query a list of supplier products
2023-09-20 42 US
  • Added 3 New GetYourGuide endpoints to list, create and delete deals in GetYourGuide system
2023-08-29 41 US
  • Added new endpoint Pricing Categories over Api that allows GetYourGuide to import the price category data for a given product.
2023-08-29 40 US
  • New feature hub to enable our connectivity partners to manage all their features from a central hub
2023-03-14 39 US
  • Added sandbox endpoint for pre production testing of notify-availability-update endpoint
2022-12-01 38 US
  • Added new object field currency and pricesByCategory to Availability Object in notify-availability-update endpoint to accept price information
  • pricesByCategory has nested subfields retailPrices
2022-10-11 37 US
  • Maintenance Page - a visual way to inform users about the maintenance window.
2022-10-10 36 US
  • Added new notification webhook to notify your system of the event that occurs on your connected product.
2022-09-21 35 US
  • Added new GetYourGuide API endpoint to reactivate a deactivated product (API documentation).
2022-07-13 34 US
  • New Feature: Price Over Api to enable automatic retail price updates from your reservation system.
2022-07-01 33 US
  • Added new fields retailPrice and currency in BookRequest
2020-11-19 32 LS
  • Added error structure for group configuration of error type INVALID_PARTICIPANTS_CONFIGURATION
  • Separated errors section into applicable to all and applicable to specific endpoints
  • Added json error response example to each error type
2020-08-04 31 LS
  • Added error type INVALID_PARTICIPANTS_CONFIGURATION
2020-04-09 30 GP
  • Added the optional field cutoffSeconds to Availability Query
2020-02-14 29 GP
  • Added reservation expiration
  • Support accepting vacancy update
  • Clarify reserve, reserve cancellation and booking cancellation fields
2020-01-23 28 BB
  • Error monitoring SLAs added
2019-11-22 25 BB
  • Clarify product definitions and availability notification
2019-03-19 26 MS
  • Clarify endpoint definitions and usage
2018-11-15 25 MG
  • Added INVALID_TICKET_CATEGORY
2018-09-21 24 MG
  • Clarified GetYourGuide endpoints
2018-08-13 23 MS
  • Added sample flows
2018-07-31 22 MG
  • Added Incidents Monitoring paragraphs
  • Clarified expected behavior for failed bookings
2018-07-24 21 MG
  • Fixed typos
2018-02-13 20 MT
  • Added Ticket Redemption by Ticket Code endpoint
  • Added Ticket Redemption by Booking Reference endpoint
2018-01-17 19 MS
  • Clarified endpoint definitions
  • Make categories consistent
2017-08-10 18 MG
  • Simplified the entire documentation
  • Clarified endpoints and parameters
2017-05-30 17 RN
  • Added Table of Contents
  • Added Service Level Agreement
  • Added Change Log
  • Fixed formatting and typos
2017-01-25 16 RS
  • Clarified DateTime formats
  • Added Time Period/Time Point definitions
  • Clarified Collective and Group categories
  • Fixed formatting and typos
2016-09-16 10 PM
  • Initial public release