Money and volume

Settlement modes

Who takes the traveller's money is a per-booking decision, not an account setting. You send it as a field on the booking request, which means you can run both models side by side and move between them without a migration.

The field

POST /v1/hotels/bookings

{
  "rateId": "rate_01JD…",
  "settlement": "partner",   // or "vacabee"
  "guests": [ … ]
}

Which values your keys may send is agreed in your contract and enforced on our side. A mode you are not enabled for is rejected with 403.

Side by side

	partner — you collect	vacabee — we collect
Merchant of record	You	Vacabee
Price the API returns	Net rate: our purchase price plus our agreed B2B margin	Consumer price, including your own markup
Traveller pays	You, through your own checkout	Vacabee, through a hosted checkout we return
Traveller's invoice	Issued by you	Issued by Vacabee
You earn	Whatever you add on top of the net rate	A commission on your markup, paid out monthly
Chargeback risk	Yours	Ours
Security we hold	A deposit and a credit limit	A rolling reserve against maturing commissions
You owe us	The net rate per booking, settled against your account	Nothing — we net your commission out

The search and booking endpoints are identical in both modes. What changes is the number in price and what comes back from the booking call.

Mode A — you are merchant of record

Send settlement: "partner". Prices are net, you set your own retail price, you take the payment, and you owe us the net amount. Settlement runs against a current account we keep for you.

Deposit. You fund the account up front, normally by bank transfer using the reference shown in the portal — no card fee on a five-figure amount. Card and SEPA direct debit are available as a second route. Partial payments are fine.
Available credit is your deposit plus your credit limit, minus your outstanding balance and minus any holds currently open.
Two-phase booking. A booking places a hold against available credit before we go to the supplier. A confirmed booking converts the hold to a charge; a failed one releases it. A hold that is never resolved expires by itself, so a crashed request cannot silently block your credit.
Not enough credit is 402, before the supplier is contacted. Subscribe to ledger.low_balance so you top up in advance rather than finding out in front of a traveller.
Settlement. Per booking, weekly, fortnightly or monthly, as agreed. Each run produces an invoice that includes your search fees.
Non-payment moves the account from active to read-only — searches keep working, new bookings do not — and then to suspended. You are notified at each step, and the state is visible in the portal.

Net rates are confidential

Net rates are our purchase conditions. Your contract restricts what you may do with them, and the API is rate-limited against bulk price extraction. Show retail prices to travellers, not the net rate you received.

Mode B — we are merchant of record

Send settlement: "vacabee". The booking call returns a hosted checkoutUrl instead of a confirmed booking. Send the traveller there; we take the payment, issue their invoice, and confirm the booking. You are told through booking.confirmed.

No deposit, no ledger, no credit check. You never owe us money for a booking.
Prices include your markup, within the ceiling agreed in your contract.
Your commission is booked when the booking confirms and matures after a clawback period — long enough to cover refunds and chargebacks. Matured commissions are paid out on a monthly statement, with a PDF in the portal.
A refund or chargeback reverses the commission automatically.
Traveller emails come from us. Whether they are sent under your brand, and whether they are sent at all, is configured on your account.

Price drift

Supplier prices move between the moment you search and the moment you book. Within the tolerance set in your contract, the booking simply goes through at the new price. Beyond it, the call fails with 409 price_changed and returns the new price, so you can decide — or ask your traveller — instead of being surprised after the fact.

Both cases are reproducible in the sandbox with sbx_price_changed. Handle this path before you go live: it is the single most common source of post-launch disputes. See sandbox.

NextWebhooksEvents, signature verification and retries.