Business Platform
TravelShop

Référence API

API TravelShop Booking

Recherchez parmi plus de 10 000 circuits, récupérez tarifs et disponibilités en direct, et créez des réservations depuis votre propre plateforme. Cette référence est publique : consultez-la avant de postuler.

Premiers pas

L’API est une API REST classique sur HTTPS qui renvoie du JSON, authentifiée par une clé API unique que vous générez vous-même une fois votre accès validé. Les exemples ci-dessous utilisent {BASE_URL} comme valeur générique : votre URL de base s’affiche à côté de votre clé dans le tableau de bord développeur.

  1. 1

    Postulez

    Présentez-nous votre plateforme. Nous examinons chaque demande manuellement, généralement sous 1 à 2 jours ouvrés.

  2. 2

    Générez votre clé

    Une fois votre accès validé, créez votre clé API dans le tableau de bord développeur et enregistrez les adresses IP des serveurs qui appelleront l’API. La clé n’est affichée qu’une seule fois.

  3. 3

    Appelez l’API

    Envoyez la clé dans l’en-tête X-API-Key de chaque requête. C’est tout ce qu’il faut pour vous authentifier.

Authentification

Envoyez votre clé dans l’en-tête X-API-Key de chaque requête. Pas de flux OAuth, pas d’échange de jetons, pas d’expiration : la clé reste valide jusqu’à ce que vous la régénériez ou la révoquiez.

curl
curl -X GET '{BASE_URL}/b2b/api/apiv2/b2c/tours/search?term=cappadocia&page_size=5' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'
node
const res = await fetch(
  '{BASE_URL}/b2b/api/apiv2/b2c/tours/search',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.TSB_API_KEY,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({ term: 'cappadocia', page_size: 5 }),
  },
)

const data = await res.json()
Appelez l’API depuis votre serveur, jamais depuis du code exécuté dans le navigateur : une clé envoyée au navigateur devient publique. Nous ne conservons qu’une version hachée de votre clé ; elle n’est donc affichée qu’une seule fois, à sa création. Vous l’avez perdue ? Générez-en une nouvelle ; l’ancienne est désactivée immédiatement.

Liste d’IP autorisées

Les endpoints partenaires n’acceptent que les requêtes provenant des adresses IP de serveurs que vous avez enregistrées. Une fois votre accès validé, ajoutez dans le tableau de bord développeur les adresses IP publiques utilisées par vos serveurs pour leurs requêtes sortantes, jusqu’à 3 adresses par défaut.

  • Enregistrez des adresses IPv4 ou IPv6 individuelles. Les plages, les adresses privées ou réservées et les adresses appartenant à Cloudflare sont refusées.
  • Utilisez l’adresse depuis laquelle votre serveur envoie ses requêtes, et non l’IP de votre site web. Si votre site est derrière Cloudflare, cette adresse appartient à Cloudflare et ne peut pas être enregistrée.
  • Si votre serveur dispose d’IPv6, les requêtes peuvent sortir en IPv6. Enregistrez aussi cette adresse ou forcez votre client HTTP à utiliser IPv4. Exécutez les commandes ci-dessous sur le serveur lui-même pour afficher les deux adresses.
  • Les modifications prennent effet en une minute environ.
curl
curl -4 https://api.ipify.org
curl -6 https://api64.ipify.org

Lorsqu’une requête est bloquée

Les requêtes provenant d’une IP non enregistrée sont arrêtées avant d’atteindre l’API : au lieu d’une erreur JSON, vous recevez une réponse HTTP 403 contenant une page de vérification HTML intitulée « Just a moment... ». Tant qu’aucune IP n’est enregistrée, votre clé elle-même n’est pas restreinte par IP, mais les requêtes de vos serveurs recevront cette page. Si vous la voyez, vérifiez quelle IP votre serveur utilise réellement et enregistrez cette adresse.

Dès qu’au moins une IP est enregistrée, votre clé n’est acceptée que depuis ces adresses. Une requête portant votre clé qui atteint l’API depuis une autre IP est refusée avec un statut 403 et le code ip_not_allowed ; le corps de la réponse indique l’IP que nous avons vue. Une clé divulguée est donc inutilisable en dehors de vos serveurs.

Réponse 403
{
  "message": "This API key is not allowed from your IP address. Register it under Allowed server IPs in your developer dashboard.",
  "code": "ip_not_allowed",
  "ip": "203.0.113.10"
}

Limites de débit et quotas

Deux limites indépendantes s’appliquent, toutes deux comptées par partenaire et jamais partagées avec d’autres.

240 requêtes par minute

Une limite de rafale. Chaque réponse inclut les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining pour vous permettre de réguler votre rythme.

20000 requêtes par jour

Le quota quotidien attribué par défaut à la validation. Il est réinitialisé à minuit UTC, et nous l’augmentons sur demande : indiquez-nous votre volume prévu et nous l’ajusterons.

Le dépassement de l’une ou l’autre limite renvoie une erreur 429. Votre consommation actuelle, détaillée par endpoint, est visible dans votre tableau de bord développeur.

Règles de contenu

Les nouveaux circuits sont retenus pendant 30 jours. Un circuit ajouté à notre catalogue n’apparaît dans les résultats de recherche partenaires, le détail des circuits et les réponses de tarifs et de disponibilités qu’après 30 jours. Les requêtes portant sur un seul circuit renvoient une erreur 404 avec le code tour_embargoed et la date à laquelle le circuit sera disponible. Ce délai permet au circuit d’être d’abord indexé sur notre propre site, afin que les moteurs de recherche identifient la source originale. Tous les circuits plus anciens vous sont entièrement accessibles. Si vous êtes également l’un de nos fournisseurs et que votre compte est lié à votre société fournisseur, vos propres circuits font exception : ils sont disponibles immédiatement via l’API, sans délai d’attente.

Les tarifs, dates et contenus sont revalidés chaque jour. Vous pouvez mettre les réponses en cache, mais actualisez tarifs et disponibilités au moins une fois par jour, et revérifiez toujours la disponibilité juste avant de créer une réservation.

Catalogue synchronization

Import complete public tour content and current retail departure schedules through two paginated change feeds.

With pricing=default, use pricing.reference.amount for your reference price. It follows the supplier detail page’s initial traveller count and first available month, with regular retail pricing preferred when offered, otherwise private. The amount is already discounted in EUR. Minimum 0 or 1 selects three travellers capped by the maximum; another minimum selects that minimum. A null reference means no displayable initial price. Do not substitute a minimum over raw rates.

The schedule feed additionally returns pricing.options: equal EUR prices grouped by explicit dates for the default traveller count. Promotions are already applied. In this mode, crossing an hour since modified-since refreshes authorized schedules even without rate edits. A cursor is bound to its pricing mode. On upgrade, restart product pagination from the last saved modified-since to preserve removal markers, and restart schedules with a full scan.

For the first scan, omit modified-since. Follow nextCursor until it is null, sending each cursor without modified-since. Save syncStartedAt from the first page; send it as modified-since on the next run. Each cursor belongs to one partner account and one feed. Apply records by tourId and allow duplicate updates at time boundaries.

Initial scans contain only active, non-deleted, non-custom tours. Incremental product scans return a minimal INACTIVE record when a previously public tour is disabled, made custom or soft-deleted; remove or hide that tour and its saved schedule locally. No disabled tour content or prices are returned. The schedule feed stays active-only. The content embargo applies, except to your own supplier tours when your account is linked. Use syncStartedAt, not an item’s modifiedAt, as the next checkpoint.

Departure dates can pass without a database modification. Remove past dates locally; each incremental schedule update replaces the complete saved schedule for that tour.

GET/b2b/api/products/modified-since

New and modified products

An ACTIVE item contains tourId, slug, modifiedAt, status and product with full public tour content. An INACTIVE item contains only tourId, slug, modifiedAt and status; remove or hide the saved tour. If republished, it arrives again as ACTIVE. Net prices and private company fields are excluded.

ParamètreTypeDescription
modified-sinceISO 8601Timestamp with a timezone offset, for example 2026-10-20T09:00:00Z. Omit for an initial full scan.
countintegerPage size from 1 to 500; defaults to 100.
cursorstringOpaque nextCursor from the previous page. Send it without modified-since.
pricingdefaultOpt in to the public detail page’s default B2C reference quote. Send pricing=default on every cursor page too. Adds pricingPolicy and per-tour pricing.
activeCurrencyEURWith pricing=default, EUR is the only accepted currency and is the default. The legacy raw rates keep their native currencies.
Default reference price in EUR
curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'pricing=default' --data-urlencode 'activeCurrency=EUR' --data-urlencode 'count=100'
Initial request
curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'count=100'
Next page
curl -G '{BASE_URL}/b2b/api/products/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'cursor=NEXT_CURSOR'
Response (product abbreviated)
{
  "products": [
    {
      "tourId": 123,
      "slug": "example-tour",
      "modifiedAt": "2026-10-20T08:00:00+00:00",
      "status": "ACTIVE",
      "product": {
        "id": 123,
        "slug": "example-tour",
        "name": "Example tour",
        "itineraries": []
      }
    }
  ],
  "nextCursor": null,
  "syncStartedAt": "2026-10-20T09:00:00+00:00"
}
Incremental removal marker
{
  "products": [
    {
      "tourId": 123,
      "slug": "example-tour",
      "modifiedAt": "2026-10-20T08:15:00+00:00",
      "status": "INACTIVE"
    }
  ],
  "nextCursor": null,
  "syncStartedAt": "2026-10-20T09:00:00+00:00"
}

INACTIVE records contain no product details or prices. Only active tours appear in an initial scan. A complete incremental scan and saved checkpoint replace periodic full-catalogue comparison for later soft deletions. If active content is temporarily unavailable, retry the 503 page without advancing its cursor.

GET/b2b/api/availability/schedules/modified-since

Modified availability schedules

Each availabilitySchedules[] item contains tourId, slug, modifiedAt and rates: the complete current set of retail rates for that tour, not just the changed rate. Each rate includes its dates from today onward.

ParamètreTypeDescription
modified-sinceISO 8601Timestamp with a timezone offset. Omit for an initial full scan.
countintegerPage size from 1 to 500; defaults to 100.
cursorstringOpaque nextCursor from the previous page. Send it without modified-since.
pricingdefaultOpt in to the public detail page’s default B2C reference quote. Send pricing=default on every cursor page too. Adds pricingPolicy and per-tour pricing.
activeCurrencyEURWith pricing=default, EUR is the only accepted currency and is the default. The legacy raw rates keep their native currencies.
Default reference price in EUR
curl -G '{BASE_URL}/b2b/api/availability/schedules/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'pricing=default' --data-urlencode 'activeCurrency=EUR' --data-urlencode 'count=100'
Incremental request
curl -G '{BASE_URL}/b2b/api/availability/schedules/modified-since' -H 'X-API-Key: YOUR_API_KEY' --data-urlencode 'modified-since=2026-10-20T09:00:00Z'
Response
{
  "availabilitySchedules": [
    {
      "tourId": 123,
      "slug": "example-tour",
      "modifiedAt": "2026-10-20T08:00:00+00:00",
      "rates": [
        {
          "rateId": 456,
          "startsAt": "2026-11-01",
          "endsAt": "2026-11-30",
          "minPax": 1,
          "maxPax": 20,
          "currency": "EUR",
          "departureTypeId": "scheduled",
          "description": {
            "en": "Standard departure"
          },
          "prices": {
            "regular": {
              "dbl": 200
            }
          },
          "dates": [
            "2026-11-05"
          ]
        }
      ]
    }
  ],
  "nextCursor": null,
  "syncStartedAt": "2026-10-20T09:00:00+00:00"
}

When the last rate is deleted, the tour is returned with rates: [] so you can clear its saved schedule. A rate can have a valid period but dates: []. Prices are retail only; supplier net prices and markup are never returned. Successful pages use Cache-Control: private, no-store.

Pricing & availability

Live departure availability and B2C retail prices. Partner API keys do not provide access to supplier net prices.

GET/b2b/api/apiv2/b2c/availability/{slug}

Availability & price for a tour

Departure availability and retail pricing for one tour.

ParamètreTypeDescription
roomTypestringsng, dbl or trp. Defaults to dbl.
dateYYYY-MM-DDA single departure date.
startDateYYYY-MM-DDStart of a date range.
endDateYYYY-MM-DDEnd of a date range.
paxintegerNumber of travellers.
service_typestringService level. Defaults to regular.
roomsarrayRoom breakdown, as [{ id, pax, count }].
include_pricesyes | noInclude the price breakdown.
include_roomsyes | noInclude room options.

An unavailable, deleted, or embargoed tour returns 404.

POST/b2b/api/apiv2/b2c/prices/{type}

Batch prices

One retail price per tour for a list of ids — what listing and category pages need.

ParamètreTypeDescription
idsobligatoireinteger[]Tour ids to price.
roomTypestringsng, dbl or trp. Defaults to dbl.
startDateYYYY-MM-DDDefaults to today.
endDateYYYY-MM-DDOptional range end.

Unavailable, deleted, and embargoed tours are left out of the response.

GET/b2b/api/apiv2/b2c/pricemonths/{type}/{id}

Available months

Available month dates for a tour, for building a departure calendar. This endpoint does not return prices.

An unavailable, deleted, or embargoed tour returns 404.

Destinations & taxonomy

The reference data behind filters, menus and search boxes.

GET/b2b/api/apiv1/b2c/countries/list

Countries

All countries with their id, name, slug and phone code.

GET/b2b/api/apiv1/b2c/quicksearch/locations

Location search

Search destinations by name — cities, regions and countries.

ParamètreTypeDescription
qstringSearch term.
idsstringComma-separated ids, to resolve known locations instead of searching.
limitintegerMax results, 1–50. Defaults to 20.
GET/b2b/api/apiv1/location-parents/{id}

Location ancestors

The parent chain of a location (city → region → country), for breadcrumbs.

GET/b2b/api/apiv1/b2c/quicksearch/tour-categories

Tour categories

Category pages matching a term, with their titles and URLs.

ParamètreTypeDescription
termstringSearch term.
GET/b2b/api/apiv1/b2c/quicksearch/activities

Activities

Activity list (hiking, diving, …) with id, name and slug — the values the activities filter accepts.

ParamètreTypeDescription
termstringSearch term.
GET/b2b/api/apiv1/b2c/tours/available-destinations

Available destinations

Destinations that currently have bookable tours.

Enquiries & bookings

Create demand on our side from your platform. Everything you create here is attributed to your partner account and appears in your dashboard.

POST/b2b/api/apiv1/bookings/new-enquiry

Create an enquiry

A traveller question about a tour. Creates an enquiry record and notifies the operator.

ParamètreTypeDescription
tour_idobligatoireintegerThe tour being asked about.
contact_nameobligatoirestringThe traveller's name.
contact_emailobligatoirestringThe traveller's email.
messageobligatoirestringThe question, up to 5000 characters.
phone_codeintegerLocation id of the phone country code.
contact_phonestringPhone number without the country code.
buyer_currencyUSD | EURCurrency to quote in. Defaults to EUR.

No captcha is required on API-key requests — your key, quota and rate limit are the gate.

POST/b2b/api/apiv1/bookings/new-booking

Create a booking

A booking checkout with travellers and rooms, priced from B2C retail availability. Returns the reference_id and token used for payment.

ParamètreTypeDescription
tour_idobligatoireintegerThe tour being booked.
paxobligatoireintegerNumber of travellers.
dateobligatoireYYYY-MM-DDDeparture date, today or later.
service_typeobligatoirestringService level, as returned by availability.
buyer_currencyobligatoirestringCurrency the traveller pays in. The seller currency is taken from the tour’s own price record.
roomsarrayRequired for tours with accommodation: [{ id: "dbl", pax, count }].
customersobligatoirearrayTravellers. The first is the lead and needs title, first_name, last_name, email, phone_code and phone.
GET/b2b/api/apiv1/bookings/{referenceId}

Booking detail

Read one booking. Pass the booking token as ?token= — the token scopes access to that single booking.

ParamètreTypeDescription
tokenobligatoirestringThe token returned when the booking was created.
POST/b2b/api/apiv1/bookings/{referenceId}/payment-request

Open a payment request

Start a collection against a booking, for a payment page hosted on your own front end. Call it from your server; the amount is calculated from the booking — the client cannot set it. The response carries the payment request’s id, reference_id and token, which your payment page needs for the next step (Take the card payment).

ParamètreTypeDescription
tokenobligatoirestringThe booking token.
payment_modeltotal | depositCollect the full remaining amount or just the deposit.

Do not send card details here. Card data goes from the traveller’s browser straight to us in the next step, so it never passes through your servers.

POST/payments/pay

Take the card payment

Submit this from the traveller’s browser as a plain HTML form post (not from your server). We pass the card to the bank and the traveller continues on the bank’s 3D Secure page. When the bank is done, the traveller lands on your return_url; read the outcome with Payment request status.

ParamètreTypeDescription
referenceobligatoirestringreference_id of the payment request.
tokenobligatoirestringtoken of the payment request (not the booking token).
return_urlobligatoirestringWhere the traveller lands after the bank. Must be on the website registered for your partner account, or one of its subdomains.
card_nameobligatoirestringName on the card.
card_numberobligatoirestringCard number, digits only.
exp_monthobligatoireintegerExpiry month, 1–12.
exp_yearobligatoireintegerExpiry year, two digits.
cvcobligatoirestringSecurity code.

No X-API-Key on this call — it comes from the traveller’s browser; the payment request’s token is what authorises it. A wrong token, a return_url outside your website, or a closed or cancelled booking is refused.

GET/b2b/api/apiv1/bookings/{referenceId}/payment-request/{id}

Payment request status

Poll the state of a payment request. Requires the same token.

ParamètreTypeDescription
tokenobligatoirestringThe booking token.
POST/b2b/api/apiv1/bookings/abandoned-cart

Report an abandoned cart

Tell us a traveller started but did not finish a booking, so our team can follow up. Creates no booking record.

ParamètreTypeDescription
sourceobligatoiretsb | tstWhich storefront the cart came from.
tourobligatoirestringTour slug.
namestringThe traveller's name.
emailstringThe traveller's email.
phone_codeintegerLocation id of the phone country code.
phonestringPhone number.
dateYYYY-MM-DDIntended departure date.
paxintegerNumber of travellers.

Deprecated response fields

Since 3 November 2026, tour search, tour detail and the product feed return the fields below as null. The keys stay in the response until 1 May 2027 so existing integrations keep parsing; after that date they are removed. Do not build on them.

Tour fields: guides, transfers, additional_service_location, is_bokun_completed, free_cancelation, all_inclusive, type, vat, deleted_at, b2c, bokun_id, sales, meta_title, meta_description, content_score and defaults.content_score.

Reviews: reviews is null. The rating and review_count summary is still returned.

name_en keeps its value until 1 May 2027 and is removed after that. Use name instead.

Price fields: the trp_, chd_ and inf_ minimum prices (min_reg_price, min_prv_price and their _pax variants), sng_/dbl_/unit_/adl_min_reg_price_pax and min_prv_price_pax. Keep using price and the sng_/dbl_/unit_/adl_ min_reg_price, min_prv_price and min_prv_price_pax fields; for exact prices and availability, call the pricing endpoints.

In rates[].dates[], id, rate_id and tour_id are null; date is unchanged.

Erreurs

Les erreurs utilisent les codes de statut HTTP standard, avec un corps JSON contenant un champ message et, en cas d’échec de validation, un objet errors indexé par nom de champ.

CodeSignificationQue faire
200OKThe request succeeded.
401UnauthorizedThe X-API-Key header is missing, or the key is not recognised. Check that you are sending the key you generated, not the one it replaced.
403ForbiddenYour API access is suspended or not yet approved. Contact us if you believe this is a mistake.
403IP not allowedThe body carries code ip_not_allowed and the ip we saw. Your key is bound to the server IPs you registered and this request came from another address. Register that address in your developer dashboard, or send the request from a registered server.
403Challenge pageAn HTML page titled "Just a moment..." instead of JSON. The request came from an IP that is not on your allowlist and was stopped before it reached the API. Register your server’s outgoing IP in your developer dashboard; changes take effect within about a minute.
404Not foundThe tour, booking or location is unavailable, deleted, embargoed or unknown; for token-scoped endpoints, the token may not match.
422UnprocessableValidation failed. The body contains a message; field validation may also include an errors object. For change feeds, check the timestamp, count and cursor, and never send cursor with modified-since.
429Too many requestsYou exceeded either the per-minute rate limit or your daily quota. Check the X-RateLimit-Remaining header and back off.
503Temporarily unavailableThe product change feed could not read complete tour content. Wait for Retry-After, then retry the same page without saving or advancing its cursor.
500Server errorSomething failed on our side. Retry with backoff; if it persists, contact us with the time of the request.
Réponse 422
{
  "message": "The given data was invalid.",
  "errors": {
    "tour_id": ["The selected tour id is invalid."],
    "customers.0.email": ["The customers.0.email must be a valid email address."]
  }
}

Gestion des versions

Certains endpoints conservent le chemin historique /b2b/api/apiv1/… ou /b2b/api/apiv2/…. Les endpoints partenaires natifs, y compris les flux de modifications du catalogue, se trouvent directement sous /b2b/api/…. Tous sont actifs et maintenus.

Au sein d’une version, nous ne faisons que des ajouts : nouveaux champs et nouveaux endpoints. Nous ne renommons ni ne supprimons aucun champ sur lequel vous vous appuyez déjà. Toute modification susceptible de casser une intégration est publiée sous un nouveau chemin de version, et nous prévenons chaque partenaire actif par e-mail avant le retrait d’une version.

Prêt à développer ?

Demandez un accès et générez votre clé. Vous hésitez sur l’intégration la plus adaptée ? Notre équipe se fera un plaisir de vous aider.