Channel API · v1

Connect your channel to Native Travel App.

A plain REST API for OTAs and channel managers. Read a destination’s published inventory and per-day availability, push sold reservations, move and cancel them. JSON in, JSON out — no SDK and no schema package required.

Base URL
https://nativetravel.app/api/channels/v1
Live tenant
Visit Almaty (nativetravel.app/en/almaty) — every city on Native Travel App serves the same API on its own domain.
Format
JSON over HTTPS, UTF-8. Dates are ISO 8601; calendar days are UTC.

Authentication

Send a partner key as a bearer token on every request. Each tenant issues its own keys; a key is bound to that tenant and can only see that tenant’s data. Keys start with nt_pk_.

GET /api/channels/v1/listings
Authorization: Bearer nt_pk_xxxxxxxxxxxxxxxxxxxxxxxx

The secret is shown once, when the key is issued; we store only its SHA-256 hash, so a lost key cannot be recovered — ask for a new one. A missing, wrong or revoked key always answers 401 with the same body, so a probe cannot tell the cases apart. A revoked key stops working immediately.

Scopes

Each key carries a list of scopes; a call outside them answers 403 FORBIDDEN.

ScopeGrants
listings:readList and read published listings.
availability:readPer-day availability and price of an offering.
availability:writeCreate, move and cancel reservations.
partners:readReferral report for the one listing a key is bound to.
verification:readTourist ID attestation status (granted per contract).

A channel key is tenant-wide and carries the first three by default. A key bound to a single listing (partner network) carries only partners:read.

Listings

GET /listings

Published listings of the tenant, newest first, cursor-paginated. Scope: listings:read.

QueryTypeDefaultNotes
limitint501–200.
cursorstring—nextCursor from the previous page.
{
  "items": [
    {
      "id": "ckl…",
      "slug": "demo-cottage",
      "type": "STAY",
      "title": "Demo Cottage",
      "tagline": "Mountain retreat",
      "description": "…",
      "address": "…",
      "latitude": 43.222,
      "longitude": 76.851,
      "currency": "KZT",
      "coverImageUrl": "https://…",
      "offerings": [
        {
          "id": "cko…",
          "kind": "ROOM",
          "bookingMode": "DATE_RANGE",
          "title": { "en": "Double", "ru": "…", "kk": "…" },
          "basePrice": "32000.00",
          "currency": "KZT",
          "capacityPerSlot": 3
        }
      ]
    }
  ],
  "nextCursor": "ckl…"
}

type is one of the 14 catalogue sections: STAY, DINING, NIGHTLIFE, CULTURE, ENTERTAINMENT, NATURE, ACTIVITIES, SPORT, WELLNESS, SHOPPING, SERVICES, TRANSPORT, EVENTS, JOBS. Older integrations may have stored ATTRACTIONS and TOURS — they are now CULTURE and ACTIVITIES.

Places imported from open city data are published before an owner claims them: they come with coverImageUrl: null, an empty gallery and no offerings. Treat image and offering fields as optional.

GET /listings/:slug

One published listing: the same fields plus its gallery (in display order) and offerings with descriptions. 404 when the slug is not a published listing of this tenant.

Availability

GET /availability/:offeringId?from=YYYY-MM-DD&to=YYYY-MM-DD

Per-day capacity and price for one offering. Scope: availability:read. Both dates are required; a window is capped at 90 days — walk longer calendars in 90-day pages. Prices are in minor units (priceCents) with the offering’s currency.

{
  "offeringId": "cko…",
  "kind": "TOUR_SLOT",
  "bookingMode": "TIME_SLOT",
  "from": "2026-11-01",
  "to": "2027-01-29",
  "slots": [
    {
      "date": "2026-11-01",
      "capacity": 10,
      "used": 3,
      "remaining": 7,
      "closed": false,
      "priceCents": 1500000,
      "currency": "KZT"
    }
  ]
}

Days apply the same rules as a direct booking: a closed day reads capacity: 0, closed: true; per-day overrides and weekday rules replace the offering’s capacity; used counts confirmed and checked-in bookings plus holds that have not expired.

Reservations

POST /reservations

Commit a reservation you have already sold and collected payment for. It lands CONFIRMED immediately and a unit is assigned on the spot. Scope: availability:write.

{
  "offeringId": "cko…",
  "externalRef": "EXP-1234567",
  "startAt": "2026-11-15T00:00:00Z",
  "endAt": "2026-11-18T00:00:00Z",
  "quantity": 2,
  "guestName": "Alice Marsh",
  "guestEmail": "[email protected]",
  "note": "Late arrival"
}

offeringId, externalRef (≤ 200 chars), startAt, endAt and guestName are required; quantity is 1–100 (default 1). 201 Created for a new booking, 200 OK for a retry of the same externalRef:

{
  "booking": {
    "id": "ckb…",
    "bookingRef": "CH-XYZ",
    "status": "CONFIRMED",
    "startAt": "2026-11-15T00:00:00.000Z",
    "endAt": "2026-11-18T00:00:00.000Z",
    "quantity": 2,
    "totalAmount": "96000",
    "currency": "KZT",
    "externalRef": "EXP-1234567"
  },
  "idempotent": false
}

The reservation goes through the same booking core as a direct guest, under the offering’s lock: 409 when a day is closed or full, 400 when the property has paused bookings or the request breaks the offering’s quantity or lead-time rules. An offering of another tenant answers 404, never 403.

PATCH /reservations/:externalRef

New dates and/or quantity for a confirmed reservation. Checked like a new one, but against capacity without itself — moving a stay by a night on a full property works. Repriced at the offering’s price; keeps its unit while it stays free.

{ "startAt": "2026-11-16T00:00:00Z", "endAt": "2026-11-19T00:00:00Z", "quantity": 1 }

200 OK with { "booking": … }; 409 when the new dates do not fit or the reservation is no longer confirmed.

POST /reservations/:externalRef/cancel

The guest cancelled on your side. No body. 200 OK with the reservation in CANCELLED; a repeat answers the same with "idempotent": true. A checked-in guest cannot be cancelled from outside (409); an unknown reference is 404.

Idempotency

Your externalRef is the idempotency key: the pair (your key’s partner, externalRef) is unique. Retrying POST /reservations after a timeout returns the original booking — same id, same bookingRef, "idempotent": true — and never touches capacity twice. Cancel is idempotent the same way. Retry on network errors and 5xx freely; do not retry 4xx unchanged.

Referral report

GET /partners/report?days=30

Who the bound listing sent guests to, who sent guests to it, and how many reached payment. Needs partners:read and a key bound to a listing — a tenant-wide key is refused with 403. days is 1–365 (default 30). The figures are the ones the owner sees in their cabinet.

{
  "listing": { "id": "ckl…", "title": "Demo Cottage", "slug": "demo-cottage" },
  "since": "2026-09-15T00:00:00.000Z",
  "sent": { "clicks": 12, "paidOrders": 3 },
  "received": { "clicks": 41, "paidOrders": 9, "vouchersRedeemed": 4 },
  "byPartner": [
    { "listing": { "id": "cko…", "title": "Mountain Cafe", "slug": "mountain-cafe" }, "clicks": 27 }
  ]
}

Tourist ID attestation

Operators that accept a traveller’s Tourist ID verify a signed attestation token.

GET /verification/jwks

Public keys for checking the signature. No key needed; cache for up to an hour.

GET /verification/status/:jti

Is this token still good? Needs verification:read. Answers only the status — never who the token belongs to.

{ "jti": "…", "active": true, "expiresAt": "2027-04-09T00:00:00.000Z", "revokedAt": null }

Errors

Every error has the same shape, and the HTTP status mirrors the code:

{ "error": { "code": "NOT_FOUND", "message": "Listing not found" } }
StatuscodeWhen
400BAD_REQUESTMalformed query or body, invalid range or quantity, bookings paused.
401UNAUTHORIZEDMissing, invalid or revoked key.
403FORBIDDENThe key lacks the scope.
404NOT_FOUNDUnknown listing, offering or reservation for this tenant.
409CONFLICTNo room for these dates, a closed day, or a reservation that can no longer change.
429TOO_MANY_REQUESTSThrottled — back off and retry. The per-IP backstop (see below) answers 429 in its own shape (statusCode, error, message); treat any 429 the same way.
500INTERNALUnexpected; we log it — retry with backoff.

Rate limits

There is no per-key quota yet. A per-IP backstop protects the whole API (by default 300 requests a minute); past it you get 429 — wait and retry with exponential backoff. Page through /listings and walk availability in 90-day windows rather than polling day by day. If you expect sustained high volume, tell us before you go live.

Getting keys

Keys are issued by the destination’s team. Write to [email protected] with your company, the destination you want to connect and the scopes you need. Never send a key by e-mail back to us — if one leaks, ask us to revoke it and issue a new one.