Connecting Your Own Booking System

This page is for operators who already run a reservation system. If that is not you, close it. Nothing here will make the panel work better.

The question that matters before any code

Which system owns availability?

Not which one displays it. Which one is authoritative, so that when the two disagree, one of them is simply wrong and gets corrected.

There are only two workable answers and one catastrophic one.

• Your system owns it. You push availability to us and we never change it except by taking seats when something sells. This is the usual answer for an operator with an established system.
• We own it. You use the panel and read bookings out. This is the usual answer for an operator whose current system is a spreadsheet.
• Both own it. This is the catastrophic one. It ends with a seat sold twice and a family left on a pier, and it always ends that way eventually rather than immediately, which is what makes it tempting.

Issuing a key

API keys, then Issue an API key. Give it a name describing what will use it, so that in a year you can revoke the right one.

The secret is displayed once, under a heading that says Copy this now, and that is not a formality. We store a hash and cannot recover it. If you lose it, revoke the key and issue another.

Choose the sandbox environment while you are building. Sandbox keys carry a vt_test prefix and behave identically, except that anything they create is flagged as a test and kept out of settlement. Swap in a vt_live key when you are ready, and nothing else about your integration changes.

• One key per integration. Your reservation system and a reporting script get different keys, so revoking one does not break the other.
• Keep it server-side. A key in a mobile app or in front-end JavaScript is a key in public.
• Revoke anything you are unsure about. Issuing a new one takes ten seconds.

A key imports, it never exports

Every product a key creates is added to your own products, exactly as if you had built it in the panel: it appears under Products, goes through the same review, and is sold from there on the marketplace and to trade buyers.

A key cannot export products, yours or anyone else's. The OCTO and Distribution v2 catalogues are for trade buyers and refuse an operator's key. On OCTO it can still read the bookings of your own inventory, cancel one you cannot run and redeem vouchers at the gate.

What the API can do

Everything the panel can, and this is literally true rather than aspirational: the panel calls the same service layer the API does. There is no capability that exists only in the interface.

The full reference is on the developer hub, with request and response shapes for every endpoint. This page is the orientation, not the specification.

Webhooks

Polling for new bookings works and is a poor use of everyone's time. Configure a webhook and we call you when something happens.

Two habits make webhook integrations reliable, and skipping either one is the source of most of the trouble we see.

1. Acknowledge immediately, process afterwards. Return a 200 as soon as you have the payload and do the work in a queue. A slow handler looks like a failed one and gets retried.
2. Be idempotent. You will receive the same event twice at some point, because that is what at-least-once delivery means. Key on the booking reference and make a repeat a no-op.

A sensible order to build in

1. Issue a key and call a read endpoint. Prove authentication works before anything else.
2. Create one product through the API, then open it in the panel. The panel is your assertion library here; if it renders correctly, your payload was right.
3. Push availability and rates for that one product for a month. Check the calendar.
4. Book it yourself on the marketplace and watch the seat come out of your system.
5. Only then loop over your whole catalogue.

Operators who push 400 products first and check afterwards spend their first week deleting things.

Testing without selling anything

Keep a product in draft while you integrate. It behaves identically through the API and is invisible to travellers and trade buyers, which makes it a real test fixture rather than a simulated one. Publish it when the integration is right, or delete it and push the real catalogue.