Download OpenAPI specification:
B2B partner API for booking accommodation through Trekko using an API key (instead of the interactive web login). Every booking you confirm is attributed to your agency in Trekko's CRM, and prices already include your configured markup (applied at egress on the Trekko side).
This document describes the live contract only (the 6 endpoints shipped
in PR #47). The automated rebooking (SBPO) money-flow and webhook design is
tracked separately in REBOOKING_FOR_PARTNERS.md and is not part of this
live spec yet — we keep the spec equal to what actually runs.
application/json.Accept-Language is required on every request (en, es, fr, de,
it, or pt); requests without a valid value are rejected.error.code is machine-readable and stable;
error.message is human-readable and may change). Every response carries
X-Request-Id.Returns the platform's known cities to help resolve a city for searching.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
{- "data": [
- {
- "id": 0,
- "name": "string",
- "country": "string"
}
]
}| query required | string Example: query=Barcelona Free-text search term, e.g. |
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
{- "data": [
- {
- "name": "Barcelona",
- "sub_name": "Catalonia, Spain",
- "search_by_id": "1376114",
- "search_by_type": 1,
- "latitude": 41.3874,
- "longitude": 2.1686
}
]
}Returns bookable rate plans (prices include your markup) for a hotel
over a date range. Carry every field you receive (vendor,
rate_plan_code, booking_code, price fields, cancellation policy) into
checkout and confirm. 204 means no availability for that query.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| accommodation_id required | integer |
| start_date required | string <date> |
| end_date required | string <date> |
required | Array of objects (GuestRoom) |
| nationality required | string ISO-3166-1 alpha-2 |
| currency_code required | string ISO-4217 |
{- "accommodation_id": 1376114,
- "start_date": "2026-09-01",
- "end_date": "2026-09-04",
- "guests": [
- {
- "room_no": 1,
- "adults": 2,
- "children_ages": [ ]
}
], - "nationality": "ES",
- "currency_code": "EUR"
}{- "accommodation_id": 0,
- "name": "string",
- "options": [
- {
- "vendor": "TRAVELGATE",
- "rate_plan_code": "RP-ABC-123",
- "booking_code": "BC-XYZ-789",
- "board_plan_text": "Bed and Breakfast",
- "nett_price": 312.4,
- "minimum_price": 330,
- "maximum_price": 360,
- "currency_code": "EUR",
- "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "from": "2019-08-24T14:15:22Z",
- "amount": 0,
- "currency": "string"
}
], - "rooms_data": [
- {
- "room_no": 0,
- "room_code": "string"
}
]
}
]
}Re-validates the selected option and returns an invoice_id to confirm against.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| accommodation_id required | integer |
| vendor required | string |
| rate_plan_code required | string |
| start_date required | string <date> |
| end_date required | string <date> |
required | Array of objects (GuestRoom) |
| currency_code required | string |
{- "accommodation_id": 1376114,
- "vendor": "TRAVELGATE",
- "rate_plan_code": "RP-ABC-123",
- "start_date": "2026-09-01",
- "end_date": "2026-09-04",
- "guests": [
- {
- "room_no": 1,
- "adults": 2,
- "children_ages": [ ]
}
], - "currency_code": "EUR"
}{- "invoice_id": 24881,
- "booking_code": "string",
- "nett_price": 0,
- "minimum_price": 0,
- "maximum_price": 0,
- "currency_code": "string"
}Creates the booking and attributes it to your agency in the CRM. Send a
stable idempotency_key in the body and the Idempotency-Key
header (same value): a retry/timeout then replays the original response
instead of double-booking. The replayed response carries
Idempotency-Replayed: true.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| Idempotency-Key | string Stable unique value (e.g. a UUID) per booking attempt. Remembered for 24h. |
| accommodation_id required | integer |
| vendor required | string |
| booking_code required | string |
| invoice_id required | integer |
| idempotency_key required | string Stable per-attempt UUID; a duplicate submit returns the original booking. |
| payment_type required | string |
| minimum_price | number |
| maximum_price | number |
| nett_price | number |
| base_price | number |
| base_currency | string |
| currency_code required | string |
required | Array of objects (GuestInformation) |
Array of objects (GuestRoomDistribution) | |
| cancellation_policy | string |
Array of objects (CancellationPolicyRule) | |
| board_plan_text | string |
Array of objects (RoomDatum) | |
| start_date required | string <date> |
| end_date required | string <date> |
| agencies_internal_booking_ref | string Your own reference, surfaced in the Trekko CRM. Use an |
{- "accommodation_id": 0,
- "vendor": "string",
- "booking_code": "string",
- "invoice_id": 0,
- "idempotency_key": "string",
- "payment_type": "credit",
- "minimum_price": 0,
- "maximum_price": 0,
- "nett_price": 0,
- "base_price": 0,
- "base_currency": "string",
- "currency_code": "string",
- "guests_information": [
- {
- "room_no": 0,
- "title": "Mr",
- "first_name": "string",
- "last_name": "string",
- "is_lead_guest": true,
- "age": 0,
- "nationality": "string"
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 0
]
}
], - "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "from": "2019-08-24T14:15:22Z",
- "amount": 0,
- "currency": "string"
}
], - "board_plan_text": "string",
- "rooms_data": [
- {
- "room_no": 0,
- "room_code": "string"
}
], - "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "agencies_internal_booking_ref": "string"
}{- "booking_number": "TRK-AB12CD34",
- "is_confirmed": true,
- "is_cancelled": true,
- "total_price": 0,
- "currency_code": "string"
}Cancels a booking, subject to the rate's cancellation policy / fees.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| booking_number required | string |
{- "booking_number": "TRK-AB12CD34"
}{- "message": "string"
}| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| page_no | integer >= 1 Default: 1 |
| items_per_page | integer [ 1 .. 100 ] Default: 20 |
{- "page_no": 1,
- "items_per_page": 20
}{- "current_page": 0,
- "total_pages": 0,
- "no_of_items": 0,
- "data": [
- {
- "booking_number": "string",
- "accommodation_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "is_confirmed": true,
- "is_cancelled": true,
- "total_price": 0,
- "currency_code": "string",
- "agencies_internal_booking_ref": "string"
}
]
}Returns the CURRENT active booking for a stable booking_id (which
survives SBPO rebooking) or an integer booking_number, including a
rebooking block when the booking was rebooked to a cheaper rate. The
partner stores booking_id and uses this to map it to the live
booking_number (e.g. before cancelling). See REBOOKING_FOR_PARTNERS.md.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| booking_id | string |
| booking_number | integer |
{- "booking_id": "TRK-AB12CD34"
}{- "booking_id": "TRK-AB12CD34",
- "booking_number": 1045,
- "accommodation_name": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "is_confirmed": true,
- "is_cancelled": true,
- "total_price": 0,
- "currency_code": "string",
- "agencies_internal_booking_ref": "string",
- "rebooking": {
- "rebooked": true,
- "times_rebooked": 0,
- "original_booking_number": 0,
- "gross_savings": 0,
- "trekko_fee": 0,
- "partner_savings": 0,
- "credited_to": "virtual_wallet",
- "last_rebooked_at": "2019-08-24T14:15:22Z"
}
}| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
{- "currency_code": "EUR",
- "funding_type": "prepaid",
- "virtual_wallet": 0,
- "credit_balance": 0,
- "credit_limit": 0
}One row per SBPO rebooking — the "we saved you €X after booking" data.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| page_no | integer Default: 1 |
| items_per_page | integer Default: 20 |
{- "page_no": 1,
- "items_per_page": 20
}{- "current_page": 0,
- "total_pages": 0,
- "total_partner_savings": 0,
- "total_trekko_fee": 0,
- "currency_code": "string",
- "data": [
- {
- "booking_id": "string",
- "rebooked_at": "2019-08-24T14:15:22Z",
- "gross_savings": 0,
- "trekko_fee": 0,
- "partner_savings": 0,
- "credited_to": "string"
}
]
}Register an HTTPS URL to receive signed events (e.g. booking.rebooked).
The signing_secret is returned ONCE. Each delivery carries a
Trekko-Signature: t=<unix>,v1=<hex> header where
v1 = HMAC_SHA256(secret, "<t>.<raw_body>"). URLs resolving to
private/loopback/metadata addresses are rejected.
| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
| url required | string <uri> |
| events | string Comma-separated event types, or '*'. |
{- "events": "booking.rebooked"
}{- "id": 0,
- "url": "string",
- "events": "string",
- "signing_secret": "whsec_..."
}| Accept-Language required | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. One of |
{- "data": [
- {
- "id": 0,
- "url": "string",
- "events": "string",
- "is_active": true
}
]
}