Integrator API

Authentication

Send your live API key (from the partner portal) as a Bearer token on every request.

Authorization: Bearer emb_live_ac_b913_9f2k

Missing or invalid credentials return 401. Acting on inventory that isn't yours returns 403.

Booking lifecycle

Check price and availability, then reserve to hold it while the customer pays. A hold auto-expires after 30 minutes unless you confirm it. Either party may cancel a pending or confirmed booking.

availability ──▶ reserve (pending, 30-min hold) ──▶ confirm (confirmed)
                          │                             │
                          └────────── cancel ◀──────────┘
             (unconfirmed holds expire automatically)

Availability & price

Read-only. Returns whether the product is bookable on a date for a party size, with a fully-broken-down price (seasonal rates, offers and taxes applied). Holds nothing.

Dates & times are in the product's timezone - its own IANA timezone if set, otherwise the supplier's. Always read it from the response rather than assuming.

{
  "ok": true,
  "data": {
    "listingId": "lst_catamaran",
    "date": "2026-09-20",
    "timezone": "Europe/Athens",
    "pax": 2,
    "available": true,
    "price": {
      "currency": "EUR",
      "unitPrice": 155, "units": 2,
      "subtotal": 310, "discount": 31, "tax": 0,
      "total": 279
    }
  }
}

Create a reservation

Call this the moment a customer starts to book. It creates a pending hold with a holdExpiresAt timestamp and returns a booking reference. Send an Idempotency-Key header so retries never double-book.

POST /api/integrator/v1/reservations
Authorization: Bearer emb_live_…
Idempotency-Key: 8f14e45f-cea1-4b12-9a11-000000000001
Content-Type: application/json

{
  "listingId": "lst_catamaran",
  "date": "2026-09-20",
  "pax": 2,
  "customer": { "name": "Jordan Lee", "email": "[email protected]", "phone": "+30…" }
}

{
  "ok": true,
  "data": {
    "reference": "EMB-BK-6N2Y",
    "status": "pending",
    "listingId": "lst_catamaran",
    "date": "2026-09-20",
    "timezone": "Europe/Athens",
    "pax": 2,
    "quote": { "total": 279, "currency": "EUR", "…": "…" },
    "customer": { "name": "Jordan Lee", "email": "[email protected]" },
    "holdExpiresAt": "2026-09-01T12:30:00.000Z",
    "createdAt": "2026-09-01T12:00:00.000Z"
  }
}

Confirm a booking

Convert a hold into a firm booking once payment succeeds. Idempotent - confirming an already-confirmed booking returns it unchanged. Confirming an expired or cancelled hold returns 409.

{ "ok": true, "data": { "reference": "EMB-BK-6N2Y", "status": "confirmed",
  "confirmedAt": "2026-09-01T12:04:00.000Z" } }

Cancel a booking

Cancels a pending or confirmed booking and releases the availability. Idempotent. An optional reason is stored with the booking.

{ "reason": "customer changed plans" }

{ "ok": true, "data": { "reference": "EMB-BK-6N2Y", "status": "cancelled",
  "cancellationReason": "customer changed plans", "cancelledAt": "2026-09-01T12:10:00.000Z" } }

Retrieve a booking

Fetch the current state of one booking, or list all of yours (optionally filtered by status). Reading a lapsed hold flips it to expired.

The list is cursor-paginated: pass limit (max 200) and the nextCursor from the previous response to page through. When nextCursor is null, you've reached the end.

Statuses

Idempotency

Pass a unique Idempotency-Key header when creating a reservation. Replaying the same key returns the original booking instead of creating a second hold - safe against network retries. Confirm and cancel are naturally idempotent by reference.

Errors