Sandbox

Create a test key in the portal.

Every sandbox response is generated inside the gateway from your own request. It is deterministic — the same request gives the same answer, which is what makes it usable in a test suite — and it follows the published response schemas field for field, which is what makes it usable for building your client. It is not a copy of production data and no number in it means anything.

• Ids. Everything is prefixed sbx_ — sbx_htl_…, sbx_rate_…, sbx_qte_…, sbx_plan_…. Never copy one into a fixture you also use against live, and do not pin a regex to the live rate_ shape.
• Hotels. A search returns exactly three generated properties named after the destination you asked for, with prices hashed from your criteria and always in EUR. Rates are two per hotel, one refundable and one not, with cancellation windows that are fixed dates in 2026, so they will read as being in the past once that year is gone. The search always comes back status: "complete" with rateStatus: "available", and a booking is always immediately CONFIRMED.
• Flights. Three generated offers from a made-up carrier (SB, Sandbox Airways) with fixed departure times, each with exactly one slice. This is not the supplier's test mode — no Duffel call is made, so multi-slice and connection handling cannot be exercised here.
• Transfers. Two offers per search, in USD, with different quoteIds — booking the wrong one is the most common integration mistake, so the sandbox makes it possible to get wrong. An order always comes back with settlement.funds: "captured", and the cancellation quote is deliberately a partial refund.
• eSIM. Countries and regions are a fixed short list, but plans are generated per country or region you ask for — including for a country that is not in the list, so do not read a plan coming back as proof that we cover that country. Prices are hashed and the currency arrives lower-case ("usd"). Orders complete and produce a profile; nothing is provisioned on a real network.

The paths that break in production are the ones a happy-path integration never exercises. Setting X-Partner-Customer-Ref to one of six reserved values makes the sandbox produce that failure on demand, deterministically. Any other value is an ordinary traveller reference and is passed through untouched, and nothing of this applies to a vcb_live_ key: no header makes a live call fail on purpose.

curl -sS -D - "https://sandbox-api.vacabee.com/v1/hotels/bookings" \
  -H "Authorization: Bearer $VACABEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Partner-Customer-Ref: sbx_price_changed" \
  -H "Content-Type: application/json" \
  -d '{
        "rateId": "sbx_rate_…",
        "externalReference": "booking-2026-0915-abc",
        "guests": [ { "firstName": "Ada", "lastName": "Lovelace" } ],
        "contact": { "email": "ada@example.com" }
      }'

# HTTP/1.1 409 Conflict
# X-Sandbox-Trigger: sbx_price_changed

• X-Sandbox-Trigger on the response is the proof it fired. Read it rather than inferring from the status code — it is also what certification counts.
• X-Sandbox-Trigger-Ignored means right trigger, wrong route. The first four below only make sense where money moves, so on a search or a read the call proceeds and carries this header instead. Move the trigger to a booking call.
• A typo is refused, loudly. Any value starting with sbx_ that is not one of the six answers 400 invalid_request and lists all six in knownTriggers, because a silently ignored sbx_offer_expred would look exactly like a broken feature.

sbx_slow together with idempotency is the pairing worth spending real time on: it is the exact situation — a timed-out booking that may or may not have succeeded — that produces duplicate reservations in integrations that skipped it. Shorten your own client timeout, let it fire against a sbx_slow call and retry with the SAME idempotency key: a retry that lands while the first attempt is still in flight answers 409 idempotency_key_in_progress, which is the answer your code has to survive.

What you can verify here, and what certification will ask you to have shown:

• A booking retried after a timeout, with the same idempotency key, results in exactly one booking.
• Each of the six failure triggers was provoked once AND followed by a successful call on the same route. Provoking a failure and stopping proves only that you can send a header.
• Every error path in your code reads the { error: { type, message, requestId, docUrl } } envelope and branches on type, not on a parsed message string.
• Your webhook endpoint verifies signatures, rejects stale timestamps and survives the same event twice. Remember that a test delivery carries the type webhook.test and will not reach your booking.confirmed handler — exercise that with a sandbox booking.
• You store X-Request-Id for every call you make.
• Your rendering copes with all three shapes a cancellation policy arrives in: an array of windows on a rate, a single string on a confirmed hotel booking, and a conditions object on a flight offer.
• Your keys live in a secret manager, never in the repository or a client bundle.
• Your configuration asserts the key prefix matches the host you point it at — nothing on our side does this for you yet.

Then swap the host and the key — but do not expect that to be the whole change. The response shapes are identical, and that is what the sandbox is for. The behaviour is not: live you will meet partial searches, pending bookings, expired handles, an account that can run out of credit, real currencies other than the sandbox's EUR and USD, and ids that do not start with sbx_. Plan a supervised first day rather than a silent cutover.