Flights

POST/v1/flights/orders/{id}/change-options

Priced alternatives for one leg

Name the slice you want to replace and where you want to go instead; you get back priced options, each with a changeId. Nothing is reissued and no money moves — but it does cost us a supplier call, so it carries the booking rate limit rather than the read one. differenceCents is SIGNED: negative means the new itinerary is cheaper and the difference comes back to you.

WHERE removeSliceId COMES FROM: read it from slices[].id on the order. FlightSliceDto — the slice shape on an offer, on an order and on the options below — publishes the supplier id, so the flow runs search → book → read the order → change, entirely from this API. Before 17.09.2026 no response carried one and this endpoint could not be driven end to end; a slices[].id of null still means that particular slice has no supplier id and cannot be named in a change request.

Each option carries its own expiresAt — the airline deadline, which may be null and always is in the sandbox. A changeId is additionally one of our handles, so it also dies about twenty minutes after this call: the earlier of the two ends it, and either way a spent option answers 410 offer_expired on POST …/change.

Auth: API key
Scope: flights:book
Rate limit: BOOKING
Search quota: Free
Idempotency: Idempotency-Key

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Required

Request headers

Header	Type	Required	Description	Example
`Idempotency-Key`	`string`	Required	Mandatory on every POST. The same request with the same key returns the stored response without reaching the supplier again. The same key with a DIFFERENT body is rejected with `409 idempotency_key_reuse`. Retained for 24 hours.	`4f1c358f-6b2e-5acb-8ef5-0c3d0bcc35f5`

Request body

FlightChangeOptionsRequestDto — required, sent as application/json.

Responses

201 · FlightChangeOptionsDto

Errors

Every one of these carries the same envelope. What each error.type means, and whether a retry can succeed, is on the error index — once, for all operations.

Status	When
`401`	No key, or an invalid, revoked or expired key, or a valid key sent to the other environment. `error.type` tells them apart: `authentication_required`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`. On `wrong_environment` the key is fine and the base URL is not — a `vcb_live_…` key was sent to the sandbox host or a `vcb_test_…` key to the live host; `error.gatewayEnvironment` names the host, `error.keyEnvironment` the key. Do not rotate the key, change the URL.
`403`	The key is not allowed to do this. On `insufficient_scope`, `error.missingScope` names the missing scope; on `ip_not_allowed` the request came from an address outside the allowlist.
`409`	The same idempotency key was used with a different body (`idempotency_key_reuse`), or a request with this key is still in flight (`idempotency_key_in_progress`). The second case may be retried after a short wait.
`429`	Quota exhausted. `Retry-After` and `error.retryAfter` give the wait in seconds. This response MAY be retried — after the stated time.
`500`	A failure on our side. The `requestId` in the response belongs in every support request.
`503`	A supplier is unreachable (`upstream_unavailable`). May be retried, with growing backoff.

Response headers

Set on every response of this operation, successful or not.

Header	Type	Meaning
`X-RateLimit-Limit`	`integer`	Upper limit of the class that applied to this request.
`X-RateLimit-Remaining`	`integer`	Remaining requests in the running window.
`X-RateLimit-Reset`	`integer`	Unix time at which the window starts anew.
`X-Request-Id`	`string (uuid)`	Identifier of this request. Quote it in any support request — including on a successful response, in case the outcome becomes questionable later.

Example

POST /v1/flights/orders/{id}/change-options

curl -sS -X POST "$VACABEE_API_URL/v1/flights/orders/<id>/change-options" \
  -H "Authorization: Bearer $VACABEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "removeSliceId": "sbx_sli_hT2mQ1xR9vL4aZ0c",
  "add": {
    "origin": "BER",
    "destination": "LIS",
    "departureDate": "2026-10-04"
  }
}'

Set VACABEE_API_URL to https://api.vacabee.com with a live key, or to https://sandbox-api.vacabee.com with a vcb_test_ key. Binding a host to one kind of key is planned and is not enforced by the host yet, so nothing stops a key from being answered at the wrong base URL — assert the prefix against your configured URL yourself. What the sandbox answers

TypeScript SDK

await vacabee.flights.changeOptions(…);

The typed method sends the right headers, derives the idempotency key where one is required, and returns the response type generated from this document. Installing and using the SDK — it requires GitHub Packages access today; the curl call beside this one needs nothing.