Concepts
The availability ledger, channel adapters, the canonical reservation model, and the reliability guarantees that hold across every integration.
Five ideas explain almost everything about integrating with StayBind. Read this once and the rest of the docs will feel obvious.
1. The availability ledger is the source of truth
Every booking, block, and rate lives in StayBind's internal availability ledger first. OTAs, your storefront, and your own OTA are downstream mirrors of it, never the other way around.
The ledger has a database-level constraint that makes two overlapping bookings for the same unit physically impossible to commit. This is not application logic that can be bypassed; it is the spine of the whole double-booking promise. When a real clash does happen across channels (two OTAs sell the same night within the propagation window), StayBind detects it as a terminal conflict and raises it for a human, rather than silently dropping a booking.
2. Channels connect through adapters
Every channel, whether an aggregator, your own OTA, or a direct storefront, plugs in through a small, uniform adapter behind one interface. The core never depends on a specific provider.
| Provider code | What it is |
|---|---|
partner | your own OTA or booking source. The path most integrators use. |
direct | a StayBind-hosted storefront (the Booking API + a checkout). |
channex | external OTAs (Airbnb, Booking.com, Agoda, MMT, Goibibo, …) reached through an aggregator, surfaced to operators as a neutral "OTA Network." |
ical | a long-tail iCal fallback. |
You don't implement an adapter from scratch to connect a custom OTA. The partner adapter already handles HTTP, retries, and signature checks; you provide a single mapping function and your credentials. See Connect a custom OTA.
Vendor masking
The aggregator behind external OTAs is never named in StayBind's product or
API. It is always presented as the neutral provider network ("OTA Network").
When you integrate your own OTA via the partner adapter, your brand is
yours; this only affects how aggregator-reached channels appear.
3. The canonical reservation model
Adapters translate each provider's payloads to and from a small set of canonical, provider-agnostic types at their boundary, so nothing provider-specific leaks into the core. The most important is the CanonicalReservation, the normalized shape every booking is reduced to regardless of where it came from. The full schema is in the Reference.
Two fields carry the idempotency contract:
providerResId— the per-delivery key. Each distinct value is ingested exactly once. Re-delivering the sameproviderResIdis a safe no-op.providerBookingId— the stable booking id, constant across revisions. Amodifiedorcancelleddelivery targets this id to update the existing booking rather than create a new one.
4. Money and dates are exact
- Money is always an integer in minor units (paise), currency
INR.₹7,500.00is750000. Never send floats. - Dates are property-local
YYYY-MM-DDstrings, never timestamps. Check-out is exclusive: a stay ofcheckIn: 2026-02-20,checkOut: 2026-02-22occupies the nights of the 20th and 21st.
5. Everything inbound is idempotent and self-healing
This pattern repeats in every flow:
Verify the signature (your connection's secret, or an API key).
Dedupe on a stable provider id (providerResId for reservations, the payment id for captures).
Acknowledge fast. The webhook endpoint answers 200 even on a downstream error, so the provider's own retry plus StayBind's reconcile pass heal any missed work. No webhook storms, no lost bookings.
Two background sweeps back this up: a reconcile pull (every ~15 minutes) that catches missed inbound reservations, and a nightly full sync that re-pushes availability to correct any drift. As an integrator you get this for free, your job is just to be idempotent on your side too.
Next: Authentication.