Everything that changes the API surface is recorded here and emailed to partner admins. Read the policy below once, and you can tell from any entry whether it needs work from you.
Deprecation policy
The contract behind every entry on this page.
Additive changes land in /v1 without notice. New fields, new optional parameters, new enum values, new endpoints, new webhook events, new response headers. Your integration must ignore unknown fields and tolerate unknown enum values.
Breaking changes only ever appear as a new major version at a new path — /v2. Nothing is removed, renamed, narrowed or given a new meaning inside /v1.
A retired version runs in parallel for at least six months. That is a floor, not a plan; in practice we expect to leave considerably longer.
The superseded version says so in its responses. A Deprecation header and a Sunset header with the date it stops answering. Alert on them — that is the earliest automatic warning you get.
Every deprecation is announced here and by email to your partner admins, with a migration guide, on the day the parallel period starts.
Security is the one exception. A change required to close a vulnerability is made as narrowly as possible and communicated directly, without waiting out a notice period.
Production keys now follow a certification, and it is published
Until today the answer to "when can I create a live key" was to ask your Vacabee contact, and the criteria existed only in that conversation. They are now written down as twelve requirements at /docs/certification, and the burden of proof runs the other way round than you would expect: four of them we prove from our own request log, two we test by firing at your system, and six are yours because they happen where we cannot see. Nothing about how you call the API changed.
addedThe certification catalogue is published at /docs/certification: what each requirement asks for, which tier it is in, what a good proof looks like, the eight states a submission can be in, and what happens at re-certification. Read it before you build — eight of the twelve are satisfied by an integration that was going to be careful anyway, and the four that are not are much cheaper to plan for than to retrofit.
addedPassing a certification switches on your own ability to create production keys in the portal. It creates no key and reveals none, and no key is ever sent by e-mail — every vcb_live_ secret in existence was shown exactly once, in a browser, to somebody signed into your portal account. An approval is good for 365 days; when it lapses, every key you already hold keeps working and only issuing or rotating a new one is blocked.
addedThe six sandbox failure triggers now work. Setting X-Partner-Customer-Ref to sbx_offer_expired, sbx_price_changed, sbx_insufficient_funds, sbx_payment_failed, sbx_supplier_error or sbx_slow makes the sandbox produce that failure on demand and deterministically. A fired trigger is confirmed by X-Sandbox-Trigger on the response; a trigger sent to a route where it cannot apply lets the call through and answers X-Sandbox-Trigger-Ignored; any other sbx_ value is refused with 400 invalid_request listing all six. Live keys are unaffected — no header makes a live call fail on purpose.
changedThe sandbox and overview pages said the triggers were specified but not implemented. That was true when it was written and is not any more, so the wording is withdrawn rather than quietly edited: if you built your own stub to simulate these failures, you no longer need it, and R2_ERROR_HANDLING of the certification expects each of the six to have been provoked and survived in your sandbox traffic.
v1
The API reference is published, and the TypeScript SDK is documented
Until today the only complete description of the endpoints lived in the gateway's OpenAPI document, which nobody outside the team could read. Every operation now has a page under /reference, generated from that document rather than written next to it. The TypeScript SDK is documented alongside it at /docs/sdk — read it now, but note that the package is not on the registry yet and no version of it has ever been uploaded; the entry announcing the first installable version is still to come. Nothing about the API itself changed — this is the surface becoming visible, not moving.
addedThe API reference at /reference covers all 43 operations, grouped by vertical. Each page carries the method and path, the parameters, the request and response schemas with types and required fields, the required scope, the rate-limit class, whether the call consumes a search, whether an Idempotency-Key is mandatory, and the shared error and response-header tables. Every one of those values is derived from the OpenAPI document at build time, so a page cannot describe a route the gateway does not have.
addedThe OpenAPI document now states the scope, the rate-limit class, the billability and the idempotency requirement for every operation, machine-readably, as x-required-scopes, x-rate-limit-class, x-billable-search and x-idempotency. Those four rules have been in force exactly like this the whole time — until now they were only readable in the gateway's source. Additive and descriptive only: no call changes its behaviour, no field moves, no status code differs.
addedThe TypeScript SDK is documented at /docs/sdk, ahead of its release. The package will be called @vacabeedev/partner-api and will carry version 0.10.0: it picks the host from your key prefix, derives the Idempotency-Key from your own order reference so a retry cannot become a second booking, exposes the quota headers, and verifies webhook signatures in constant time. It has no runtime dependencies. Read the page now — nothing in it changes when the package lands — but do not run the install yet: nothing has been uploaded to GitHub Packages, so npm install answers 404 no matter how correct your token is. When it does land, installing needs a GitHub account and a personal access token with read:packages, because GitHub Packages never serves npm packages anonymously — not even public ones; /docs/sdk gives the .npmrc you need. Publishing to npmjs.com, which would need neither, is planned for general availability.
changedThe SDK version follows the contract from now on. Every entry in the API changelog carries the version it was published under, and the classification decides the number: additive is a minor release, a changed answer or a changed shape is a major one, an SDK-only improvement is a patch. The package is still on 0.x, so pin an exact version. The version string the client sends as its user agent is generated from the package version rather than typed in a second time.
v1
Documentation corrected: six things we described but never shipped
An audit against the running code found six places where these docs described behaviour that does not exist. They are corrected below rather than quietly edited away, because anyone who has already built against them needs to know which parts of their integration are aimed at nothing. No API behaviour changed with this entry — only what we claim about it.
removedSettlement mode B (`settlement: "vacabee"`, Vacabee as merchant of record) was documented as callable. It is not. No booking endpoint returns the `checkoutUrl` this site promised, no hosted checkout exists behind one, and every key books in mode A today — including keys on accounts whose `settlementModes` lists `vacabee`. The mode B design stays published as a plan, clearly marked. If you built a payment handoff around `checkoutUrl`, it is waiting on a field that has never been sent.
changedThe settlement mode is a property of the API key, not a field on the booking request. The old wording ("the settlement mode you pick per booking") was wrong in a way that mattered: the mode decides whether the API quotes you net or retail prices, and the price is fixed at search time, so a per-booking field could not have governed it. Leave `settlement` out of booking bodies: nothing reads it as an instruction, and an unknown property can fail the whole request. The field is planned as an optional assertion checked against the key — a wrong-credential safety catch, not a switch — and the changelog will say when it is accepted.
removedThe `await_rates` blocking search mode was not something a caller could ever request. The gateway sets it on the upstream call unconditionally, and the request validator rejects unknown body properties, so sending `await_rates` yourself returns 400. Searches are consumed by polling.
removedThe streaming search mode over a WebSocket at `/v1/stream` does not exist — there is no such endpoint, and no connection or subscription limits apply because there is nothing to connect to. The `Sec-WebSocket-Protocol: vcb, <key>` handshake documented on the authentication page is withdrawn with it.
changed`GET /v1/ping` is public and requires no key; it never validated one. It was documented as the way to confirm your credentials, which meant a broken key looked fine. Use `GET /v1/account` to prove a key — it returns your identity, scopes, settlement modes and limits in one call.
deprecatedThe six sandbox triggers (sbx_offer_expired, sbx_payment_failed, sbx_supplier_error, sbx_price_changed, sbx_insufficient_funds, sbx_slow) are specified but not implemented. Sending one in X-Partner-Customer-Ref today is treated as an ordinary traveller reference and the call proceeds normally. The names and meanings are fixed and stay published so you can write handling against them; the go-live checklist no longer asks you to verify them. Implementation is planned.
deprecatedKeys are not bound to a host. We stated that a test key is rejected on the live host and a live key on the sandbox host, with a 401. Neither check exists: a key is validated against its own recorded environment and nothing compares it to the host it arrived on. Host binding is planned. Until it ships, assert the vcb_live_ / vcb_test_ prefix against your configured base URL yourself.
v1
Developer portal and v1 conventions
The portal goes live with the documentation and the cross-cutting rules of the API. The endpoints themselves are still in development — nothing is callable yet, and no key issued today can book anything.
addedPublic documentation covering authentication, idempotency, search quota, settlement modes, webhooks, the sandbox and the error envelope.
addedThe v1 conventions are now fixed: an Idempotency-Key on every POST, the { error: { type, message, requestId, docUrl } } envelope, X-Request-Id on every response, the X-Search-Quota-* headers, integer minor units with an ISO 4217 currency, and cursor pagination.
addedWebhook signatures are defined: X-Vacabee-Signature with t and v1, HMAC-SHA256 over `${t}.${rawBody}`, a five-minute timestamp tolerance and a rotatable secret per endpoint.
addedThe sandbox contract is defined, including the six forced failures sbx_offer_expired, sbx_payment_failed, sbx_supplier_error, sbx_price_changed, sbx_insufficient_funds and sbx_slow.
addedThe deprecation policy below now applies to everything published on this site.
