Documentation

Vacabee Partner API

One REST API for hotels, flights and eSIM data plans. You search, price and book from your own product; we handle suppliers, fulfilment and — depending on the settlement mode you pick per booking — the payment.

Before you write any code

1Your Vacabee contact enables the API channel on your partner account and agrees your terms: which products you may sell, which settlement modes you may use, your net margins, your search allowance and — for mode A — your deposit and credit limit.
2Sign in to the partner portal and create a test key. The secret is shown once, at creation, and never again.
3Build against the sandbox. It is free, never counts against your search quota, and never reaches a real supplier.
4Verify your error handling with the six forced failures, register a webhook endpoint, then swap the test key for a live key. The hosts differ; nothing else does.

Base URLs

Environment	Base URL	Key prefix
Live	`http://vacabee-partner-api-dev`	`vcb_live_…`
Sandbox	`$PARTNER_API_SANDBOX_URL`	`vcb_test_…`

Hosts not configured

This deployment has no gateway URL configured, so the table shows the environment variable names instead of a host. Ask your Vacabee contact for the URLs, or set PARTNER_API_URL and PARTNER_API_SANDBOX_URL if you are running the portal yourself.

A test key is rejected on the live host and a live key is rejected on the sandbox host, so a misconfigured environment fails immediately instead of quietly booking something real.

Conventions

These hold for every endpoint, so they are worth reading once instead of rediscovering per resource.

Versioned path. Every route lives under /v1. Additive changes land in /v1 without notice; breaking changes only ever appear as /v2. See errors and versioning.
Money. Amounts are integers in the minor unit of the currency, always paired with an ISO 4217 code — { "amount": 12950, "currency": "USD" } is 129.50 USD. No floats anywhere, ever.
Time. Timestamps are ISO 8601 in UTC. Travel dates are plain calendar dates in the local timezone of the property or airport, without an offset.
Tracing. Every response carries X-Request-Id. Log it. It is the first thing support will ask for and the only way we can find your call in ours.
Pagination. List endpoints are cursor-based. Follow the returned cursor; never construct one.
Writes. Every POST requires an Idempotency-Key. This is enforced, not advisory.
Cancellation policies. Supplier terms are passed through verbatim. We do not summarise, normalise or reinterpret them — show them to your traveller as we return them.

Your first call

GET /v1/ping needs nothing but a valid key. Use it to confirm your key, your host and your network path before you debug anything else.

Shell

export VACABEE_API_URL="$PARTNER_API_SANDBOX_URL"
export VACABEE_API_KEY="vcb_test_…"

curl -sS "$VACABEE_API_URL/v1/ping" \
  -H "Authorization: Bearer $VACABEE_API_KEY" \
  -D -

Read the response headers, not just the body: X-Request-Id and the X-Search-Quota-* family are on every response and tell you most of what you need to know about your account.

Server side only

An API key is a bearer credential for your entire partner account. Never ship one in a browser bundle, a mobile app, or anything else a traveller can open. Calls originate from your backend.

Search modes

Hotel and flight searches are asynchronous — suppliers take seconds, not milliseconds. Three ways to consume a search, all equivalent in what they return:

Mode	How	Use when
Polling	Create the search, then re-read it until it reports complete	Anything. Always available, no connection to hold.
Blocking	Create the search with `await_rates`	Short-lived request handlers that cannot poll or hold a socket.
Streaming	Subscribe over the WebSocket at `/v1/stream`	You can hold a connection and want results as they arrive.

Streaming is strictly additive: it never returns anything polling would not, and listening is never billable. Only the search that created the room is. Per key: 20 connections and 200 subscriptions.

Everything else

AuthenticationAPI keys, environments, scopes and IP allow lists.IdempotencyWhy every POST needs an Idempotency-Key, and how replay works.Search quotaFree allowance, per-search fee and the quota headers.Settlement modesWho is merchant of record, per booking.WebhooksEvents, signature verification and retries.SandboxFree test environment and the six forced failures.Errors and versioningThe error envelope, retry rules and how /v1 evolves.

NextAuthenticationAPI keys, environments, scopes and IP allow lists.