GetYourGuide API Integration for Travel Experiences

Tours-and-activities inventory is one of the fastest-growing revenue lines for OTAs, TMCs, and DMCs, and GetYourGuide is one of the largest demand channels a supplier can plug into. But connecting to it isn't a simple REST wrapper job — GetYourGuide's Supplier API comes with strict uptime targets, response-time ceilings, a defined retry protocol, and a error-code contract that your integration has to honor exactly, or your products get deactivated automatically.

This guide walks through what a GetYourGuide API integration actually requires: the mandatory endpoints, the authentication model, how to structure error handling, and how to design your system so it survives GetYourGuide's SLA enforcement instead of getting flagged for it.

What GetYourGuide Expects From Your System

GetYourGuide's model puts the supplier in the driver's seat. Your system exposes a set of HTTPS endpoints; GetYourGuide calls them to check availability, place and cancel reservations, and confirm or cancel bookings. You're not calling GetYourGuide most of the time — you're the one being called, which flips the usual integration mindset. Your API has to be reachable, fast, and predictable on GetYourGuide's schedule, not yours.

Every response must be JSON, served with a Content-Type: application/json header, and — this trips up a lot of teams — every response must return HTTP 200, even when you're returning an error. Error state lives inside the JSON payload via an errorCode field, not in the HTTP status line. A non-200 response is treated as a transport failure, not a business error, and it counts against your reliability metrics differently than a well-formed error response does.

Your deserializer also needs to tolerate schema drift. GetYourGuide adds non-breaking fields to its data structures periodically, and the API is localized across 28 languages, so non-ASCII characters need to pass through your pipeline cleanly.

The Mandatory Endpoints

A production-ready GetYourGuide API integration requires five supplier-side endpoints, plus one GetYourGuide-side endpoint your system must call:

Availability query — reports open capacity for a product across a date range
Reservation — places a temporary hold on inventory
Reservation cancellation — releases a hold
Booking — confirms the reservation into a real booking
Booking cancellation — cancels a confirmed booking
Availability update notification (GetYourGuide-side, mandatory for you to call) — pushes vacancy changes back to GetYourGuide as they happen

A ticket redemption endpoint, product reactivation, and a notification webhook are optional, but worth building if you're managing on-site check-in or want proactive control over deactivated listings.

If you're building a multi-supplier system — a ticketing platform or reservation system serving more than one activity provider — GetYourGuide additionally requires support for both individual and group pricing, and both time-point and time-period product types, as baseline features rather than nice-to-haves.

Reservations, Bookings, and the Hold Window

GetYourGuide's flow separates "reserve" from "book" deliberately, so double-booking risk during a customer's checkout flow is minimized. A reservation places a temporary hold; the desired hold window is 60 minutes, with 15 minutes as the absolute floor your system must support. Only after the reservation succeeds does GetYourGuide call your booking endpoint to confirm it.

This two-step model matters for how you design your data layer. A reservation isn't provisional metadata — it needs to actually decrement available inventory in a way that a competing request can see, or you'll end up confirming bookings you can't fulfill. Caching layers used for availability lookups need a short enough TTL, or an active invalidation hook, so a hold made a few seconds ago is reflected in the very next availability query.

sequenceDiagram participant GYG as GetYourGuide participant API as Supplier API participant DB as Inventory Store GYG->>API: GET availability (date range) API->>DB: Read vacancies DB-->>API: Vacancy counts API-->>GYG: 200 OK (availability payload) GYG->>API: POST reserve (product, pax, ticket categories) API->>DB: Decrement + hold inventory DB-->>API: Reservation confirmed API-->>GYG: 200 OK (reservationId, reservationExpiration) GYG->>API: POST book (reservationId) API->>DB: Confirm hold as booking DB-->>API: Booking confirmed API-->>GYG: 200 OK (bookingReference) API->>GYG: Notify availability update

Booking Amendments: A Flow You Have to Get Right

When a customer changes party size or activity date through GetYourGuide, your system doesn't receive an "update" call — it receives a brand-new reservation and booking request carrying the same GYG booking reference but different details. Your integration needs to recognize this as a fresh booking, confirm it, and only then expect a cancellation request against the old supplier booking reference.

Treating this as an edge case rather than a first-class flow is one of the more common integration bugs: teams build "create" and "cancel" as isolated operations and don't account for the sequencing GetYourGuide relies on, which can leave orphaned holds or double-counted inventory during the transition window.

flowchart LR A[Customer requests amendment] --> B[GYG creates new reservation<br/>same GYG booking ref] B --> C[Supplier confirms new booking] C --> D[GYG issues cancellation<br/>for old supplier booking ref] D --> E[Supplier releases old hold]

Authentication: Basic Auth Only

GetYourGuide's authentication model is deliberately simple: HTTP Basic Auth, in both directions. GetYourGuide authenticates to your API using credentials you provide it, and you authenticate to GetYourGuide's API (for availability notifications, ticket redemption, and similar calls) using credentials they provide you. There's no OAuth flow, no bearer token exchange, no signed-request scheme to build — just a username and password on the Authorization header.

The catch is that credentials apply at the system level, not per-supplier. If your platform aggregates multiple underlying suppliers behind one GetYourGuide-facing API, you can't segment access by supplier through GetYourGuide's auth model — that separation has to be handled inside your own application logic, typically by resolving the correct supplier context from the product ID itself rather than from the request credentials.

Error Handling: A Strict Contract, Not a Suggestion

This is where a lot of GetYourGuide API integrations lose points on reliability metrics without realizing it. The error contract is exact: a response contains either the success payload or the errorCode structure — never both — and mixing the two is treated as inconsistent and can cause the request to fail outright.

Errors that apply across all endpoints:

Error Code	Meaning
`AUTHORIZATION_FAILURE`	Credentials are invalid
`INVALID_PRODUCT`	Product doesn't exist or is broken; triggers automatic deactivation
`VALIDATION_FAILURE`	Request data is invalid or incomplete
`INTERNAL_SYSTEM_FAILURE`	Unexpected error, including timeouts

Endpoint-specific errors add more nuance — NO_AVAILABILITY, INVALID_TICKET_CATEGORY, INVALID_PARTICIPANTS_CONFIGURATION, INVALID_RESERVATION, and INVALID_BOOKING each carry structured fields GetYourGuide parses programmatically. INVALID_PARTICIPANTS_CONFIGURATION, for example, expects a participantsConfiguration object with min and max, and for group products it additionally expects a groupConfiguration.max field. Get these structures wrong and GetYourGuide will misconfigure the product's booking rules in its own system, since it applies your returned limits directly.

Two error codes carry consequences beyond a failed request. INVALID_PRODUCT triggers automatic product deactivation on GetYourGuide's side, and repeated NO_AVAILABILITY errors that don't match your own reported vacancy counts can trigger a deactivation for "Invalid No Availability Error." Neither is reversible without local-partner intervention through the Supplier Portal, so returning these codes casually — as a generic catch-all — creates operational cleanup work down the line.

SLA Thresholds Your System Has to Hit

GetYourGuide enforces uptime and latency requirements that determine whether your integration stays live:

Uptime: 99.8% availability per calendar month
Soft timeout: 15 seconds — beyond this, requests are cancelled and can produce inconsistent booking data
Hard timeout: 27 seconds — beyond this, the connection is dropped and it counts against your error rate

Response time targets get tighter for the calls that sit in a real-time customer checkout path:

Endpoint	Desired	95th Percentile	Longest Acceptable
reserve	< 1s	3s	10s
book	< 2s	4s	10s
cancel-reservation	< 1s	2s	4s
cancel-booking	< 1s	4s	6s
get-availability (1 day)	< 1s	3s	6s
get-availability (30+ days)	< 5s	10s	15s

Error rate ceilings apply too: below 0.01% for availability queries, below 1% for reservations, and below 0.5% for bookings and booking cancellations. Cross these consistently and GetYourGuide reduces your booking window automatically, cutting off how far in advance customers can book your products — a quiet revenue penalty that shows up before any manual deactivation does.

Designing for GetYourGuide's Retry Behavior

GetYourGuide automatically retries failed booking calls under specific conditions — INTERNAL_SYSTEM_FAILURE, INVALID_RESERVATION, unrecognized error codes on a non-200 response, no response at all, or a timeout. Retries happen every 10 minutes, up to 10 attempts, and if the original reservation has expired by the time a retry fires, GetYourGuide re-runs the reservation before attempting the booking again.

This has a direct design implication: your booking endpoint has to be idempotent against retries of the same reservation ID. If a retry lands after your system already processed the original request successfully but the confirmation response was lost in transit (a classic timeout-on-success scenario), you need to detect the duplicate and return the same confirmed booking rather than double-booking the slot or returning INVALID_RESERVATION for a reservation that's actually still valid.

A circuit breaker pattern in front of your downstream inventory or supplier systems is worth the build effort here. If your own dependencies start timing out, tripping the breaker and failing fast with a clean INTERNAL_SYSTEM_FAILURE response — rather than hanging until GetYourGuide's 27-second hard limit — keeps you inside the response-time SLA and lets GetYourGuide's retry logic do its job cleanly instead of stacking up slow, ambiguous failures.

flowchart TD A[Booking request received] --> B{Downstream healthy?} B -- Yes --> C[Process booking] C --> D{Success?} D -- Yes --> E[Return 200 + booking reference] D -- No / timeout --> F[Return INTERNAL_SYSTEM_FAILURE] B -- No, breaker open --> F F --> G[GYG retries every 10 min, up to 10x]

Ticket Categories and Product Types

GetYourGuide supports a fixed set of ticket categories — ADULT, CHILD, YOUTH, INFANT, SENIOR, STUDENT, EU_CITIZEN, MILITARY, EU_CITIZEN_STUDENT, COLLECTIVE, and GROUP — and expects your booking response to return tickets matching the exact composition requested. Order two adults and one child, and your response needs three discrete tickets in that split, or a single COLLECTIVE ticket as a fallback if your system can't issue per-category tickets.

Product type matters for how you structure availability data. Time-point products (a scheduled departure) can have any number of time slots per day, each with a full datetime. Time-period products (open access within a window, like a museum's operating hours) are limited to one occurrence per day, with the time component zeroed out and the actual access window carried separately in openingTimes. Mixing these up — sending multiple daily slots for what's configured as a time-period product, for instance — is a validation failure waiting to happen.

Building It So It Stays Live

A GetYourGuide API integration is as much an operational commitment as a technical one. The SLA isn't a one-time certification gate; it's monitored continuously, with automated incident emails for individual booking failures, general booking failure rate drops, and reservation failure spikes — each carrying an expected 48-hour response window. Treat monitoring (via tools like Datadog or the Integrator Portal's analytics) as part of the integration itself, not an afterthought bolted on after go-live.

Get the endpoint contracts, the error structures, the idempotency handling, and the SLA-aware timeout design right up front, and the ongoing operational burden is manageable. Skip any of them, and you're looking at silent deactivations, booking window cutoffs, and a support queue full of avoidable incidents.

Need help scoping or building your GetYourGuide API integration? Teenva AI & Digital Ventures builds and maintains connectivity integrations for OTAs, TMCs, and DMCs. Reach out at sales@teenvaai.com or +91 9572020107.

activity booking api

GetYourGuide API Integration for Travel Experiences: A Developer Guide