Download OpenAPI specification:
B2B partner API for booking accommodation, car rental and private transfers through Trekko with an API key (instead of the interactive web login). Every booking you make is attributed to your agency in Trekko, and every price you receive is already your price from Trekko (your agency's commercial conditions are applied on the Trekko side).
/extras/cars/...) - locations, search, book, cancel./extras/transfers/...) - search, add-on pricing,
book, cancel, list bookings, PDF voucher. Hourly chauffeur service ("as
directed") uses the same endpoints with service_mode: hourly.set_allow_rebooking), the savings ledger (account/savings) and the
signed booking.rebooked webhook. Agency-wide rebooking settings and the
rebooking history screen live in the Trekko web portal (web login); they
are not part of this API./core/sandbox/... (hotels) with a
self-serve, email-verified signup.REST only; SDKs are planned. No client library is published or supported for external use yet. Integrate over HTTPS using this OpenAPI file (or generate a client from it) and the Postman collection from the developer portal.
Send credentials with either header form (the first is preferred):
Authorization: ApiKey key:secretX-Api-Key: key and X-Api-Secret: secretKeys are prefixed trk_live_ (production) or trk_test_ (sandbox, issued
by POST /core/sandbox/signup then POST /core/sandbox/signup/verify).
The secret is shown only once and is stored hashed server-side - store
it on receipt. Rotate it with POST /accommodation/account/rotate_key. A
bad, inactive or malformed key returns 401 with
error.code = invalid_api_key.
application/json (the transfer voucher is
application/pdf).Accept-Language: send Accept-Language: en on every request; an
empty or unsupported value is refused with 403 (supported: en, es,
fr, de, it, pt, ar). A missing header is treated as en./core/... (there is no /api/ prefix on the public host).Every error returned to an API-key caller (including a rejected key) uses
one envelope, with the same id in the X-Request-Id response header:
{"error": {"code": "invalid_api_key", "message": "Invalid API credentials.", "request_id": "3f9c1a7b2e04"}}
error.code - stable, machine-readable snake_case: branch on it.error.message - human-readable, may change; do not parse it.error.request_id - quote it to Trekko support.error.details - optional object with the extra fields an endpoint
returns for that error (for example the new price on a 409 price change).| HTTP | Typical error.code |
What to do |
|---|---|---|
| 400 | invalid_request, invalid_json, guest_age_required, bad_request, availability_expired, endpoint-specific codes |
fix the request / search again |
| 401 | invalid_api_key, auth_missing, auth_scheme_invalid |
check the key and secret; send Authorization: ApiKey <key>:<secret> |
| 402 | payment_required, insufficient_funds |
pay / fund the wallet first |
| 403 | forbidden |
not allowed for this key |
| 404 | not_found (also returned for another agency's booking) |
check the id |
| 409 | booking_conflict, rate_no_longer_available, price_changed, policy_changed, confirm_price_below_quote, possible_duplicate_booking, idempotency_in_progress (with Retry-After: 1) |
read error.details; for idempotency_in_progress retry with the same key after Retry-After |
| 422 | idempotency_key_reused |
the Idempotency-Key was already used with a different request: use a new key |
| 429 | rate_limited (with Retry-After) |
retry after Retry-After seconds |
| 5xx | booking_failed, vendor_error, service_unavailable, idempotency_unavailable (money endpoints, nothing was processed), internal_error |
retry with backoff |
For compatibility, a rejected key also keeps a top-level detail string
next to error.
Responses that do not use the envelope. An edge proxy in front of the
API can answer 429 with {"detail":"rate_limited","retry_after":60} and
Retry-After: 60 (no error object); a gateway failure (502/504) can
be an empty or non-JSON body. Treat any non-JSON or envelope-less error as
retryable with backoff. Unknown routes, malformed JSON, a missing or
wrong-scheme Authorization header and unhandled server errors return the
envelope with not_found, invalid_json, auth_missing /
auth_scheme_invalid and internal_error respectively. (rolling out:
until it reaches your environment these cases can still return a bare
{"error": "<string>"} body, so read error defensively: it is an object
in the envelope and a string in the legacy shape.)
nett_price - the price you pay Trekko: your price, with the
Trekko margin applied to your agency's rates. Despite the name it is not the supplier
net. At checkout it is rounded up to a whole unit of the currency
(312.40 becomes 313). Prices in availability use the same model; the
figure that binds is the one checkout returns.minimum_price / maximum_price - an informational band, 5% below and
5% above the unrounded price. Display only: nothing is charged at either
figure, and they are not a negotiation range.pay_by_funds.amount must equal the nett_price returned by checkout,
and confirm_booking must carry that same nett_price and
currency_code. Do not use maximum_price as the amount to pay.old_price / new_price in a price_changed 409 are both your prices
in currency and directly comparable.Limits apply per API key (not per IP) over a rolling one-minute window.
Every throttled response carries RateLimit-Limit, RateLimit-Remaining
and RateLimit-Reset; a 429 also carries Retry-After.
| Bucket | Endpoints | Default |
|---|---|---|
| search | accommodation/search |
30 / min |
| availability | get_accommodation_availability and list_available_accommodations (one shared bucket) |
30 / min |
| booking | checkout, pay_by_funds, pay_later, confirm_booking, cancel_booking, set_allow_rebooking, Request Desk calls (one shared bucket) |
30 / min |
| list | list_bookings, get_booking, account/*, webhooks |
60 / min |
Separately from the per-minute counters, the number of simultaneous
in-flight calls per key is capped: 4 for destination search
(list_available_accommodations), 8 for single-hotel availability, plus 6
slots reserved for checkout-time rechecks that declare X-Lane: recheck
(also proxy, quote, book). A concurrency 429 carries
Retry-After: 5 and RateLimit-Remaining can still be above zero: when
the two disagree, obey Retry-After. Sandbox: 120 calls / min per key; signup is
limited to 10 per hour per IP.
A rate_plan_code or booking_code is not a reservation and carries no
guaranteed validity window. The checkout quote that confirm_booking
needs is kept for 24 hours; a rate cached from a destination search has no
expiry of its own and can be hours old; the supplier's own rate can
disappear within minutes. Always run checkout immediately before payment.
When a rate is gone the API answers 409 with error.code = rate_no_longer_available (reason_code: rate_gone) and refresh_hint: true: re-run the search with refresh=1 (query or body flag of
list_available_accommodations; at most 5 forced refreshes per minute,
beyond that the flag is silently ignored and you get the cached answer),
or call get_accommodation_availability, which is always live.
Idempotency-Key (max 200 characters, remembered 24 hours, scoped to your
agency) is honoured on pay_by_funds (mandatory), pay_later and
confirm_booking, and on book in the car and transfer endpoints. It is
not supported on cancel_booking: after a timeout, read the booking with
get_booking before retrying. A replay carries Idempotency-Replayed: true. (rolling out) Only successful (2xx) answers and final 409s about
the quote are replayed; any other error releases the key so a corrected
retry with the same key runs again. A second request with the same key
while the first is still running answers 409 idempotency_in_progress
with Retry-After; the same key with a different body answers
422 idempotency_key_reused; if the idempotency store is unavailable the
money endpoints answer 503 idempotency_unavailable without processing
the request. Until this is deployed, 4xx answers (for example a 402
before you fund the wallet) are replayed for 24 hours: use a new key for
each attempt that follows a business error.
Events emitted today: booking.rebooked and booking.hotel_confirmed.
booking.confirmed and booking.cancelled are not emitted yet. The
URL must be https; redirects are not followed (a 3xx counts as a
failed delivery). A delivery succeeds on any 2xx within 10 seconds.
Failures are retried up to 3 times with a short, randomised exponential
backoff (delays of at most about 1, 2 and 4 seconds), so an endpoint that
is down for more than a few seconds will miss the event: treat webhooks as
a notification and reconcile with get_booking / account/savings.
Delivery is at-least-once: dedupe on event_id. Ordering is not
guaranteed. There is no delivery log, replay endpoint or secret rotation
yet (delete the endpoint and register a new one to change the secret).
Verify Trekko-Signature: t=<unix>,v1=<hex> with HMAC_SHA256(signing_secret, "<t>.<raw_body>") over the raw bytes, compare in constant time and
reject timestamps older than five minutes.
The sandbox keeps the same paths and mostly the same field names, but it is
a simulator, not a copy of the live engine. Differences you will meet:
four fixed hotels (ids 9000001, 9000002, 9000010, 9000020); EUR pricing;
no guests validation; search is POST and list_bookings accepts GET or
POST; every sandbox route except signup needs your test key (401 auth_missing otherwise); there is no
payment step (pay_by_funds, pay_later) and confirm_booking needs no
invoice_id; cancellation rules use lowercase {from, amount, currency}
instead of the live From / To / DateFrom ... ladder; booking ids look
like TRK-TEST-<n>; and it does not simulate 402 or price-change 409
conditions (the only 429 is the plain per-key rate limit). It does
validate what production validates: malformed input is a 400
(invalid_request, invalid_date, invalid_parameter), a rate code it
never issued is 409 rate_no_longer_available, and Idempotency-Key on
confirm_booking is honoured (replay returns the same booking; a different
body under the same key is 422 idempotency_key_reused). There is no
destination search, rotate_key, account/usage, Request Desk or extras in the sandbox. Test
the failure branches (price change, rate gone, insufficient funds, rate
limit) from the response shapes documented here, not from the sandbox.
Live (trk_live_) keys are provisioned by Trekko after the production
access review and funding steps; test (trk_test_) keys are self-serve
with a verified company email. A key authenticates as your agency and can
do everything the agency can through this API, including paying from your
wallet, cancelling and registering webhooks; there are no read-only keys,
spend limits or IP allowlists yet. Restrict outbound access to the API
from your own network and keep the secret server-side. rotate_key is an
immediate hard cut-over: the old pair stops working at once, the new
secret is shown once, and a lost response means Trekko must re-issue
credentials. Update every consumer before you call it.
info.version is the date of the last contract revision. Changes are
additive where possible (new optional fields, new endpoints, new error
codes), so ignore unknown fields and unknown error.code values. Trekko
does not make breaking changes without notice to registered integrators.
Support: Trekko Developer Support (see the contact link of this
specification); quote X-Request-Id or error.request_id in any report.
Returns the platform's known cities to help resolve a city for
searching. No API key is required (sending it is harmless). Pass an
optional country_id to filter to one country.
| country_id | integer Restrict the list to a single country. |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
[- {
- "id": 2,
- "name": "Madrid"
}, - {
- "id": 3,
- "name": "Barcelona"
}, - {
- "id": 4,
- "name": "Dubai"
}
]Free-text search. search_by_type indicates the entity type:
0 Accommodation · 1 City · 2 Area · 3 Landmark. Use the returned
search_by_id / search_by_type to drive availability.
| query required | string Example: query=Barcelona Free-text search term, e.g. |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "data": [
- {
- "name": "Villa White Rock, Ban Amphur",
- "sub_name": "",
- "search_by_id": "1376114",
- "search_by_type": 0,
- "latitude": 12.843385,
- "longitude": 100.935948,
- "landmarks": [ ],
- "area": [ ]
}, - {
- "name": "Ban Mai Subdistrict",
- "sub_name": "Thailand",
- "search_by_id": "57789",
- "search_by_type": 1,
- "latitude": 19.288262,
- "longitude": 99.765417,
- "landmarks": [ ],
- "area": [ ]
}
]
}Returns bookable rate plans (prices include the Trekko margin applied to your agency's rates) for a hotel
over a date range. Carry every field you receive (vendor,
booking_code, the price fields, cancellation_policy,
cancellation_policy_rules, room_codes, board_plan_text) forward into
checkout and confirm. 204 means no availability for that query.
Guest rules (enforced server-side): guests is a flat list of
{id, age}; guest ids must be unique; the booking needs at least one
adult (age ≥ 18). guests_room_distribution assigns every guest id to
exactly one room, and each room must contain at least one adult.
Send age for every guest: children are priced by age, and an omitted
age is treated as 30 (an adult). (rolling out: API-key requests
without a guest age are rejected with 400 guest_age_required.)
nationality is OPTIONAL but changes the market the supplier prices
and binds the rate to. When it is omitted the supplier's default
market applies (typically ES), so
send it explicitly. An explicit JSON null is rejected with 400
(Nationality must be a string). start_date must be today (UTC) or
later; end_date must not be before start_date. Maximum 4 rooms.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| accommodation_id required | integer |
| start_date required | string <date> |
| end_date required | string <date> |
required | Array of objects (Guest) |
required | Array of objects (GuestRoomDistribution) |
| nationality | string OPTIONAL. 2-letter ISO-3166-1 alpha-2 country code. When omitted the supplier default market applies (typically ES). An explicit null is rejected with 400. |
| currency_code | string ISO-4217. Defaults to EUR. |
{- "accommodation_id": 1376114,
- "start_date": "2026-09-01",
- "end_date": "2026-09-04",
- "guests": [
- {
- "id": 1,
- "age": 34
}, - {
- "id": 2,
- "age": 30
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 1,
- 2
]
}
], - "nationality": "ES",
- "currency_code": "EUR"
}{- "accommodation_id": 0,
- "name": "string",
- "options": [
- {
- "vendor": "src_3f9a2b",
- "rate_plan_code": "RP-ABC-123",
- "booking_code": "BC-XYZ-789",
- "room_codes": [
- "string"
], - "board_plan_text": "Room Only",
- "nett_price": 312.4,
- "minimum_price": 296.78,
- "maximum_price": 328.02,
- "currency_code": "EUR",
- "currency_symbol": "€",
- "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "From": "0",
- "To": "3",
- "DateFrom": "2026-02-09",
- "DateFromHour": "00:00",
- "DateTo": "2026-02-13",
- "DateToHour": "00:00",
- "Type": "V",
- "FixedPrice": "0",
- "PercentPrice": "100",
- "Nights": "0",
- "ApplicationTypeNights": "Average"
}
]
}
]
}Every hotel of a destination for the dates/occupancy, streamed as a
concatenation of JSON arrays (one per batch: [{...},{...}][{...}]).
Parse incrementally (split on ][, JSON.parse each piece); every
element carries an accommodation_id; a search with no hotels streams
a single [].
Cache contract. Results come from availability_snapshot (keyed by
destination, dates, occupancy, nationality, locale) with no TTL in
production (SNAPSHOT_TTL_HOURS=0 is the production setting; the
code default is 6 h): rows are served until refreshed on a cache miss
or evicted after a failed checkout (409 rate_no_longer_available);
a checkout re-quote does NOT rewrite the row. Each row carries price_as_of
(ISO-8601 or null); price_age_hours / price_is_stale are present
only when Trekko runs PRICE_STALE_MODE=mark. The hotel page
(get_accommodation_availability) and checkout are always live —
send the card price as expected_price (+ expected_policy_rules) to
checkout to turn any drift into a 409 instead of a silent 200.
Time budget: the supplier fan-out is cut at ~95 s; the stream then
closes cleanly with a partial result (missing hotels are absent, not
"unavailable"). Every response carries X-Trekko-Search-Run-Id.
Send emit_end_event: true to receive a final SearchEndEvent
(run_id, partial, end_reason) as the last array of the stream, and
max_hotels: N (opt-in, no default) to stop after N distinct hotels.
Rate limit: the availability bucket (30/min) + a per-key cap on
simultaneous in-flight searches. A concurrency 429 carries
Retry-After: 5 and may show RateLimit-Remaining > 0 — always obey
Retry-After.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| search_by_type required | integer Enum: 0 1 2 3 0 accommodation · 1 city · 2 area · 3 landmark (from /accommodation/search). |
| search_by_id required | integer >= 1 |
| start_date required | string <date> |
| end_date required | string <date> |
required | Array of objects |
required | Array of objects |
| nationality | string = 2 characters ISO-3166 alpha-2; part of the cache key. |
| currency_code | string Default: "EUR" |
| accommodation_type | string Enum: "Apartment" "Country House" "Hotel" "Others" "Resort" "Singular House" "Villa" |
| max_hotels | integer or null >= 1 OPTIONAL, opt-in, never a default. Stop the stream once this many DISTINCT hotels (accommodation_id) were sent. Supplier batches not yet served are treated like those left over by the time budget (they finish into the availability cache, or are re-run in the background; none is thrown away), and the run ends with |
| emit_end_event | boolean Default: false OPTIONAL, opt-in. When true, the stream ends with ONE extra array holding a |
{- "search_by_type": 1,
- "search_by_id": 40725,
- "start_date": "2026-12-15",
- "end_date": "2026-12-17",
- "guests": [
- {
- "id": 1,
- "age": 34
}, - {
- "id": 2,
- "age": 30
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 1,
- 2
]
}
], - "nationality": "ES",
- "currency_code": "EUR"
}[- {
- "accommodation_id": 0,
- "price": 0,
- "currency_code": "string",
- "currency_symbol": "string",
- "price_as_of": "2019-08-24T14:15:22Z",
- "price_age_hours": 0,
- "price_is_stale": true,
- "available_rooms": [
- { }
]
}
]Re-validates the selected option and returns the locked price plus the
booking_code / room_codes / cancellation policy you carry into the
payment + confirm steps. Send the guest list and room distribution again
(same validation rules as availability). Checkout does NOT return an
invoice_id — that comes from the payment step (see the lifecycle
below).
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| 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 (Guest) |
required | Array of objects (GuestRoomDistribution) |
| currency_code | string Default: "EUR" |
{- "accommodation_id": 1376114,
- "vendor": "src_3f9a2b",
- "rate_plan_code": "RP-ABC-123",
- "start_date": "2026-09-01",
- "end_date": "2026-09-04",
- "guests": [
- {
- "id": 1,
- "age": 34
}, - {
- "id": 2,
- "age": 30
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 1,
- 2
]
}
], - "currency_code": "EUR"
}{- "vendor": "src_3f9a2b",
- "booking_code": "string",
- "room_codes": [
- "string"
], - "minimum_price": 296.78,
- "maximum_price": 328.02,
- "nett_price": 313,
- "currency_code": "EUR",
- "currency_symbol": "€",
- "start_date": "2026-02-12",
- "end_date": "2026-02-13",
- "board_plan_text": "Room Only",
- "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "From": "0",
- "To": "3",
- "DateFrom": "2026-02-09",
- "DateFromHour": "00:00",
- "DateTo": "2026-02-13",
- "DateToHour": "00:00",
- "Type": "V",
- "FixedPrice": "0",
- "PercentPrice": "100",
- "Nights": "0",
- "ApplicationTypeNights": "Average"
}
], - "hotel_comments": "string"
}The payment step that produces the invoice_id confirm_booking
requires. Partners on a credit/prepaid account use this funds path:
Trekko charges your virtual wallet / credit balance and returns an
invoice_id plus the matching payment_type
("Booking Payment by Funds"). Pass that same invoice_id and
payment_type into confirm.
Other payment paths exist for web/card flows
(/accommodation/bookings/pay_by_own_card,
/accommodation/bookings/pay_by_clients_card,
/accommodation/bookings/pay_later); each likewise yields an
invoice_id + payment_type.
amount must equal the nett_price returned by checkout, which is
the price you will confirm. Insufficient funds returns
402 insufficient_funds to API-key callers. The Idempotency-Key
header is mandatory (400 idempotency_key_required without it).
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| Idempotency-Key required | string <= 200 characters Stable unique value (e.g. a UUID) per payment attempt. A replay within 24h returns the original answer and never charges twice. |
| amount required | number Amount to charge. Equal to the checkout |
| currency_code | string Default: "EUR" |
{- "amount": 313,
- "currency_code": "EUR"
}{- "invoice_id": 24881,
- "payment_type": "Booking Payment by Funds"
}Alternative payment step for agencies on a credit line: no money
moves now; Trekko records a pay-later invoice and returns the
invoice_id + payment_type ("Booking Payment (Pay Later)") that
confirm_booking requires; the booking then stays
payment_status: Pending until settled by its payment_due_date
(read it back with get_booking). Agencies without a credit line can
only hold rates whose free-cancellation window ends >= 30 days out.
An indicative headroom check answers 402 credit_limit_exceeded with
error.details.exposure — a courtesy guard-rail, not a credit
control. Non-refundable rates on a credit line are debited from the
wallet at confirm time. See HOTEL_API_FOR_CLIENTS.md §3.4a for the
exact money rules.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| start_date required | string <date> |
| end_date required | string <date> |
| nett_price required | number The checkout |
| currency_code | string Default: "EUR" |
| cancellation_policy_rules required | Array of objects The array returned by checkout. |
| vendor required | string Opaque vendor token from checkout. |
| non_refundable | boolean Echo the option's |
| booking_code | string Recommended (since 2026-11-08). The |
{- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "nett_price": 312.4,
- "currency_code": "EUR",
- "cancellation_policy_rules": [
- { }
], - "vendor": "src_3f9a2b",
- "non_refundable": true,
- "booking_code": "BC-7f3a9c"
}{- "invoice_id": 24990,
- "payment_type": "Booking Payment (Pay Later)"
}Creates the booking and attributes it to your agency in the CRM. Requires
a paid invoice_id (from the payment step) and its matching
payment_type; an unpaid/invalid invoice returns 402 payment_required.
Guests: guests_information is a SINGLE OBJECT carrying the lead
guest plus an optional guests array of extra occupants. The lead guest
is treated as id == 1 and must be at least 18. rooms_data and
guests_room_distribution are required. room_codes is required when the
vendor is a specific source.
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.
Price and currency must be the checkout's. Send nett_price and
currency_code exactly as checkout returned them. The bound is the
agency SELL fixed at checkout (tolerance 0.01 in the quote currency);
quotes created before this check existed are accepted for up to 24 h.
A lower nett_price, a different currency_code, or a non-numeric
nett_price is refused with 409 and
error.code = confirm_price_below_quote before anything is booked or
charged.
To recover: call checkout again and confirm with the price and
currency it returns, reusing the same invoice_id. Do not pay
again: the paid invoice stays on hold, and a price above the paid
amount is auto-refunded with
402 INVALID_INVOICE_WITH_REFUND_CONFIRMATION.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| Idempotency-Key | string Stable unique value (e.g. a UUID) per booking attempt. Remembered for 24h. |
| accommodation_id required | integer |
| vendor required | string non-empty |
| booking_code required | string |
| room_codes | Array of strings Required when |
| invoice_id required | integer From the payment step (e.g. pay_by_funds). |
| payment_type required | string Enum: "Booking Payment by Own Card" "Booking Payment by Funds" "Booking Payment (Pay Later)" "Booking Payment by Clients Card" Must match the invoice. One of the long invoice-type strings. |
| minimum_price required | number Echo of the checkout |
| maximum_price required | number Echo of the checkout |
| nett_price required | number Exactly the checkout |
| base_price | number Deprecated Optional and ignored. The server uses the checkout quote it stored for this |
| base_currency | string Deprecated Default: "EUR" Optional and ignored (see |
| currency_code | string Default: "EUR" |
required | object (GuestsInformation) Single object carrying the lead guest plus any extra occupants. |
required | Array of objects (GuestRoomDistribution) |
object | |
| cancellation_policy required | string non-empty |
required | Array of objects (CancellationPolicyRule) |
| board_plan_text required | string or null |
required | Array of objects (RoomData) |
| start_date required | string <date> |
| end_date required | string <date> |
| agencies_internal_booking_ref | string or null <= 64 characters Optional. Your own reference, surfaced in the Trekko CRM (max 64 characters; omit or send empty to leave it blank). Add, change or clear it at any time with |
| idempotency_key | string Optional stable per-attempt key; a duplicate submit returns the original booking. If omitted, the server derives one from invoice_id. |
| allow_rebooking | boolean Per-booking rebooking opt-out. Omitted/true = the booking is eligible for SBPO rebooking (the default). Set false if this booking must never be rebooked (e.g. you cannot tolerate a booking_number change for it). Can be changed later via |
{- "accommodation_id": 0,
- "vendor": "string",
- "booking_code": "string",
- "room_codes": [
- "string"
], - "invoice_id": 0,
- "payment_type": "Booking Payment by Funds",
- "minimum_price": 0,
- "maximum_price": 0,
- "nett_price": 0,
- "base_price": 0,
- "base_currency": "EUR",
- "currency_code": "EUR",
- "guests_information": {
- "id": 1,
- "lead_guest_title": "Mr",
- "lead_guest_name": "Ada",
- "lead_guest_surname": "Lovelace",
- "lead_guest_email": "user@example.com",
- "lead_guest_phone": "string",
- "lead_guest_nationality": "ES",
- "lead_guest_age": 34,
- "lead_guest_date_of_birth": "1990-04-12",
- "lead_guest_document_number": "string",
- "guests": [
- {
- "id": 0,
- "title": "string",
- "name": "string",
- "surname": "string",
- "age": 30,
- "date_of_birth": "1990-04-12",
- "document_number": "string"
}
]
}, - "guests_room_distribution": [
- {
- "guest_ids": [
- 0
]
}
], - "special_requests": {
- "arrival_time": "string",
- "other_requests": "string"
}, - "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "From": "0",
- "To": "3",
- "DateFrom": "2026-02-09",
- "DateFromHour": "00:00",
- "DateTo": "2026-02-13",
- "DateToHour": "00:00",
- "Type": "V",
- "FixedPrice": "0",
- "PercentPrice": "100",
- "Nights": "0",
- "ApplicationTypeNights": "Average"
}
], - "board_plan_text": "string",
- "rooms_data": [
- {
- "room_name": "Double Room",
- "bed_reference": "1 double bed",
- "no_of_adults": 2,
- "no_of_children": 0,
- "guest_name": "Ada Lovelace"
}
], - "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "agencies_internal_booking_ref": "string",
- "idempotency_key": "string",
- "allow_rebooking": true
}{- "booking_number": 1045,
- "booking_id": "TK-1045"
}Cancels a booking, subject to the rate's cancellation policy / fees.
Identify the booking by the stable booking_id (recommended — it
survives SBPO rebooking and always resolves to the currently-active
reservation) or by the integer booking_number. One of the two plus
a non-empty cancellation_reason is required.
The success body is only {"message": "<localised text>"}: it carries
no fee, refund amount or refund state. Read the booking with
get_booking and your wallet with account/balance to see the
outcome. This endpoint does not accept Idempotency-Key; if a call
times out or answers 503, check get_booking before retrying.
Rebooking safety: if you send a booking_number that has been
superseded by a rebooking (the row is cancelled and a live
replacement exists), the call answers 409 booking_conflict with the
current booking_id/booking_number in the error body — retry with
those to cancel the active reservation instead of orphaning it.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_number | integer |
| booking_id | string Stable id that survives rebooking (preferred). |
| cancellation_reason required | string non-empty |
{- "booking_number": 1045,
- "booking_id": "TK-1045",
- "cancellation_reason": "Guest requested cancellation"
}{- "message": "string"
}Updates allow_rebooking on the currently-active booking of the
given identity. false excludes the booking from the SBPO rebooking
engine (it will never be rebooked); true re-includes it. Identify
the booking by the stable booking_id (preferred — survives
rebooking) or the integer booking_number. Bookings owned by another
agency return 404.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_id | string |
| booking_number | integer |
| allow_rebooking required | boolean |
{- "booking_id": "TK-1045",
- "booking_number": 1045,
- "allow_rebooking": false
}{- "booking_id": "TK-1045",
- "booking_number": 1045,
- "allow_rebooking": false
}Reads all filters from the query string. Returns the agency's bookings, newest first.
| page_no | integer >= 1 Default: 1 |
| items_per_page | integer >= 1 Default: 5 |
| status | string Enum: "upcoming" "completed" "cancelled" |
| check_in | string <date> |
| check_out | string <date> |
| booking_date | string <date> |
| booking_id | integer Trekko's INTEGER row id of the booking (same number as |
| guest_name | string |
| country | string |
| city | string |
| currency_code | string |
| travel_agency_ref | integer |
| booking_type | string Enum: "Rebooked" "Original" |
| search_query | string |
| agencies_internal_booking_ref | string |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "total_pages": 0,
- "current_page": 0,
- "items_per_page": 0,
- "data": [
- {
- "booking_id": 2,
- "is_rebooked": false,
- "old_booking_number": 0,
- "nights": 2,
- "rooms": 1,
- "check_in_date": "2025-06-15",
- "check_out_date": "2025-06-17",
- "cancellation_policy": "string",
- "free_cancellation_until": "2025-06-12",
- "booking_date": "2025-01-28 07:17:58",
- "is_paid": true,
- "payment_option": "credit card",
- "price_wo_added_services": 150,
- "client_price": 125,
- "commission": 25,
- "commission_percentage": 25,
- "supplier_id": 0,
- "travel_agency_ref": 0,
- "agent_name": "string",
- "guest_name": "string",
- "hotel_name": "Hotel Copacabana",
- "hotel_address": "string",
- "hotel_country": "Spain",
- "hotel_city": "Palma de Mallorca",
- "cancellation_fee": 0,
- "currency_code": "EUR",
- "currency_symbol": "€",
- "is_updated": true
}
]
}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 | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_id | string |
| booking_number | integer |
{- "booking_id": "TK-1045"
}{- "booking_id": "TK-1045",
- "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,
- "partner_savings": 0,
- "credited_to": "virtual_wallet",
- "last_rebooked_at": "2019-08-24T14:15:22Z"
}
}Your own reference (agencies_internal_booking_ref, max 64 characters)
is optional at booking time and can be added, changed or cleared at any
time afterwards - also after check-in or cancellation - without
re-booking. Send an empty string or null to clear it. Only the owning
agency can edit (404 otherwise, like a missing booking). Every change is kept in an audit
history; the booking detail returns agency_internal_booking_ref and
agency_reference_last_change (by_label, at, source). Limit:
about 30 edits per hour per user. {booking_id} is the integer
booking number.
| booking_id required | integer |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| agency_internal_booking_ref required | string or null <= 64 characters |
{- "agency_internal_booking_ref": "FILE-2026-0042"
}{- "booking_id": 0,
- "agency_internal_booking_ref": "string",
- "changed": true,
- "agency_reference_last_change": {
- "by_label": "string",
- "at": "string",
- "source": "portal"
}
}Same behaviour as the hotel endpoint above, for a transfer, hourly
chauffeur or car rental. Your own reference (agencies_internal_booking_ref
at booking time, max 64 characters) is optional and can be added,
changed or cleared at any time - also after pick-up or cancellation.
Send an empty string or null to clear it. Only the owning agency can
edit (404 otherwise, like a missing booking). {booking_id} is the
integer id of the transfer / car rental booking (the id returned by
GET /extras/transfers/bookings), not a hotel booking number. The
booking list/detail return agency_internal_booking_ref and (detail)
agency_reference_last_change. Limit: about 30 edits per hour per user.
| booking_id required | integer |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| agency_internal_booking_ref required | string or null <= 64 characters |
{- "agency_internal_booking_ref": "FILE-2026-0042"
}{- "booking_id": 0,
- "agency_internal_booking_ref": "string",
- "changed": true,
- "agency_reference_last_change": {
- "by_label": "string",
- "at": "string",
- "source": "portal"
}
}Only for accounts in hold/request mode (booking_mode: hold_request
in get_user_info; any other account answers 403 booking_mode_direct).
Re-quotes the rate on the server and answers whether the account may
place a hold (refundable rate, readable policy, free-cancellation
deadline minus the 2-day buffer at least hold_threshold_hours away
in the earliest time zone) or a request (everything else). Writes
nothing. Same body as /bookings/hotel/request. GET is accepted too
with the body JSON-encoded in ?payload=.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| accommodation_id required | integer |
| vendor required | string |
| rate_plan_code required | string |
| currency_code | string |
| start_date required | string <date> |
| end_date required | string <date> |
| guests required | Array of objects |
| guests_room_distribution required | Array of objects |
| guests_information required | object |
| rooms_data | Array of objects |
| special_requests | object |
| nationality | string |
| agency_reference | string <= 64 characters |
| idempotency_key | string <= 128 characters |
{- "accommodation_id": 0,
- "vendor": "string",
- "rate_plan_code": "string",
- "currency_code": "EUR",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "guests": [
- { }
], - "guests_room_distribution": [
- { }
], - "guests_information": { },
- "rooms_data": [
- { }
], - "special_requests": { },
- "nationality": "string",
- "agency_reference": "string",
- "idempotency_key": "string"
}{- "kind": "hold",
- "reason": "ok",
- "rate_secured_until": "2026-11-08",
- "free_until": "2026-11-10",
- "hold_threshold_hours": 48,
- "selling_total": 1000,
- "currency": "EUR",
- "non_refundable": false
}The only booking-like write of an account in hold/request mode. The
server re-quotes and decides: kind: hold = the rate is secured with
the supplier until rate_secured_until and Trekko staff confirm by
email (no charge, no voucher until confirmed); kind: request = no
rate is secured, staff place the request with the supplier. The
account's own reference travels as agency_reference. Idempotent
with idempotency_key.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| accommodation_id required | integer |
| vendor required | string |
| rate_plan_code required | string |
| currency_code | string |
| start_date required | string <date> |
| end_date required | string <date> |
| guests required | Array of objects |
| guests_room_distribution required | Array of objects |
| guests_information required | object |
| rooms_data | Array of objects |
| special_requests | object |
| nationality | string |
| agency_reference | string <= 64 characters |
| idempotency_key | string <= 128 characters |
{- "accommodation_id": 0,
- "vendor": "string",
- "rate_plan_code": "string",
- "currency_code": "EUR",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "guests": [
- { }
], - "guests_room_distribution": [
- { }
], - "guests_information": { },
- "rooms_data": [
- { }
], - "special_requests": { },
- "nationality": "string",
- "agency_reference": "string",
- "idempotency_key": "string"
}{- "kind": "hold",
- "request_id": 118,
- "booking_id": 20451,
- "trekko_reference": "TK-7781",
- "rate_secured_until": "2026-11-08",
- "status": "received"
}Accounts in hold/request mode never cancel or modify directly: they
file a request that Trekko staff handle with the supplier. One open
request per type per item (409 request_already_open).
| booking_id required | integer |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| type required | string Enum: "cancellation" "change" |
| reason | string <= 2000 characters |
| changes | object Free-form description of the requested change (dates, occupancy, room). |
{- "type": "cancellation",
- "reason": "string",
- "changes": { }
}{- "kind": "request",
- "request_id": 119,
- "booking_id": 20451,
- "trekko_reference": "TK-7781",
- "rate_secured_until": null,
- "status": "received"
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "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 | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| 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,
- "currency_code": "string",
- "data": [
- {
- "booking_id": "string",
- "rebooked_at": "2019-08-24T14:15:22Z",
- "partner_savings": 0,
- "credited_to": "string"
}
]
}API-key callers only (a JWT session answers 403). No grace period for the old pair — deploy the new one everywhere before calling.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "api_key": "trk_live_...",
- "api_secret": "string",
- "note": "string"
}API-key callers only. Totals, error count, success rate, per-status and per-endpoint breakdown with average latency for the last days days.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| days | integer [ 1 .. 365 ] Default: 30 |
{- "days": 30
}{- "window_days": 0,
- "total_requests": 0,
- "error_requests": 0,
- "success_rate_pct": 0,
- "by_status": {
- "property1": 0,
- "property2": 0
}, - "by_endpoint": [
- {
- "endpoint": "string",
- "count": 0,
- "avg_latency_ms": 0
}
]
}Register an HTTPS URL to receive signed events. Events emitted
today: booking.rebooked and booking.hotel_confirmed only;
booking.cancelled / booking.confirmed are reserved names, planned,
not yet delivered. 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>"). The URL must be https;
URLs resolving to private/loopback/metadata addresses are rejected,
and redirects are not followed at delivery time. Event names in
events are not validated: a name that is never emitted simply never
matches. Failed deliveries are retried 3 times within seconds (see
"Webhooks" in the API description).
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| 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 | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "data": [
- {
- "id": 0,
- "url": "string",
- "events": "string",
- "is_active": true
}
]
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| id required | integer The endpoint id from POST/GET (alias |
{- "id": 12
}{- "message": "Webhook deactivated."
}Car rental locations, search, booking and cancellation (EUR). Search results carry structured cancellation and no-show terms on your price.
Returns airports, cities, stations and rental offices matching q.
Send the returned ref back verbatim as pickup_location_id /
dropoff_location_id in /extras/cars/search (it is an opaque token).
| q required | string Example: q=Malaga At least 2 characters (name or IATA code). |
| limit | integer <= 50 Default: 20 |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "results": [
- {
- "ref": "iata:AGP",
- "name": "Malaga Airport (AGP)",
- "type": "airport",
- "country": "ES",
- "iata": "AGP"
}
]
}Live offers for a rental period. Prices are EUR. price_gross_eur is
the price you pay Trekko for the rental. Search can take 20-60 s.
Cancellation and no-show terms come structured in details, already
expressed on your price (never on a supplier cost):
free_cancellation_until - last moment (ISO 8601) to cancel free of
charge; null means the offer is non-refundable.details.cancellation_policies[] - {amount, currency, capped_at_total}: the fee charged when cancelling after the free
window.details.no_show_fee - {amount, currency, capped_at_total}: the fee
if the renter does not show up to collect the car. amount: 0 means no fee.capped_at_total: true means the fee equals the whole booking amount:
show it as "up to the total booking amount", not as a figure.Echo the whole result object back as quote_raw when booking. Fields
not described below (e.g. price_net_eur, agency_markup_pct,
vendor_status) are internal and are not part of the contract: do
not display or rely on them.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| pickup_city required | string Human-readable label (city or airport). Always required, even with a location id. |
| dropoff_city | string Defaults to pickup_city. A different value requests a one-way rental. |
| pickup_location_id | string Optional |
| dropoff_location_id | string |
| pickup_datetime required | string Local time at the location (ISO 8601, no offset). |
| dropoff_datetime required | string Local time at the location (ISO 8601, no offset). |
| driver_age | integer Default: 30 |
| driver_residence | string Default: "ES" ISO 3166-1 alpha-2. |
| category | string Default: "CAR" Enum: "CAR" "VAN" |
| locale | string Default: "en" |
{- "pickup_city": "Malaga Airport (AGP)",
- "pickup_datetime": "2027-04-10T10:00:00",
- "dropoff_datetime": "2027-04-11T10:00:00",
- "driver_age": 30
}{- "currency": "EUR",
- "results": [
- {
- "vendor": "<routing-token>",
- "vendor_quote_id": "<quote-id>",
- "vehicle_name": "Ford Ka",
- "vehicle_class": "Mini",
- "seats": 4,
- "luggage_large": 1,
- "luggage_small": 0,
- "transmission": "manual",
- "fuel_type": "petrol",
- "air_conditioning": true,
- "unlimited_mileage": true,
- "supplier": "WIber",
- "pickup_location": {
- "name": "AGP",
- "type": "airport",
- "lat": null,
- "lon": null
}, - "dropoff_location": {
- "name": "AGP",
- "type": "airport",
- "lat": null,
- "lon": null
}, - "currency": "EUR",
- "price_gross_eur": "38.13",
- "free_cancellation_until": "2027-04-09T10:00:00",
- "deposit_amount": "1000.0",
- "on_request": false,
- "details": {
- "fuel_policy": "full_to_full",
- "deposit": {
- "amount": 1000,
- "currency": "EUR"
}, - "cancellation_policies": [
- {
- "amount": 0,
- "currency": "EUR",
- "capped_at_total": false
}
], - "no_show_fee": {
- "amount": 0,
- "currency": "EUR",
- "capped_at_total": false
}
}
}
]
}Books one offer from /extras/cars/search and charges it. The price is
re-checked server-side against the search; a changed price is refused
instead of charged. Send an Idempotency-Key header (or body
idempotency_key) so a retry never books twice.
payment_method is required: funds (your Trekko wallet) or
card (needs card_token or card_id plus redirect_url for 3-D
Secure). Insufficient wallet funds answer 402 insufficient_funds
before any booking is made.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| Idempotency-Key | string |
| vendor required | string The |
| vendor_quote_id required | string |
| quote_raw required | object The chosen result object exactly as returned by search. |
| payment_method required | string Enum: "funds" "card" |
| card_token | string |
| card_id | string |
| redirect_url | string <uri> |
required | object |
{- "vendor": "string",
- "vendor_quote_id": "string",
- "quote_raw": { },
- "payment_method": "funds",
- "card_token": "string",
- "card_id": "string",
- "traveller": {
- "title": "Mr",
- "first_name": "string",
- "last_name": "string",
- "email": "user@example.com",
- "phone": "string",
- "date_of_birth": "2019-08-24",
- "nationality": "string",
- "flight_number": "string"
}
}{- "trekko_booking_id": "string",
- "db_id": 0,
- "status": "confirmed",
- "voucher_url": "string",
- "confirmation_number": "string"
}Cancels with the rental supplier and refunds to your wallet according
to the booking's cancellation terms. Another agency's (or an unknown)
booking answers 404.
| booking_id required | integer The |
| reason | string |
{- "booking_id": 0,
- "reason": "string"
}{- "ok": true,
- "booking_id": 4211,
- "status": "cancelled",
- "refunded": true,
- "refund_status": "refunded",
- "refund_amount": 38.13,
- "refund_percent": 100
}| booking_id required | integer |
| payment_method required | string Value: "funds" |
{- "booking_id": 0,
- "payment_method": "funds"
}{- "invoice_id": 123,
- "payment_status": "paid",
- "amount": 82.43,
- "currency": "EUR"
}Sends an agency-branded quote email for a search result. Rate-limited per agency.
{ }{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}Live offers for a transfer. Always priced in EUR; price_gross_eur is
the price you pay Trekko (and return_price_gross_eur for the
return leg of a round trip). free_cancellation_until is the last
moment to cancel free of charge. When pickup or drop-off is an airport,
flight_info_required: true means airline and flight_number are
mandatory at booking. For hourly service send service_mode: hourly
and hours (no dropoff needed). Search can take 20-60 s.
Fields not described below (e.g. price_net_eur,
return_price_net_eur, agency_markup_pct, vendor_search_id) are
internal and not part of the contract. Echo the whole result object
back as quote_raw when pricing add-ons or booking.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
required | object (TransferLocation) Either |
object (TransferLocation) Either | |
| pickup_datetime required | string Local time (ISO 8601, no offset). |
| return_datetime | string or null Set for a round trip (local ISO 8601). |
| num_passengers | integer Default: 2 |
| num_luggage | integer Default: 2 |
| service_mode | string Default: "point_to_point"
|
| hours | integer Required when service_mode is hourly. |
| locale | string Default: "en" |
{- "pickup": {
- "address": "Ngurah Rai International Airport (DPS), Bali",
- "latitude": -8.7482,
- "longitude": 115.1675,
- "iata": "DPS"
}, - "dropoff": {
- "address": "Seminyak, Bali",
- "latitude": -8.6905,
- "longitude": 115.1681
}, - "pickup_datetime": "2027-04-10T14:00:00",
- "num_passengers": 2
}{- "currency": "EUR",
- "results": [
- {
- "vendor": "<routing-token>",
- "vendor_quote_id": "<quote-id>",
- "vehicle_name": "Daihatsu Sigra or Similar",
- "vehicle_class": "standard",
- "max_passengers": 3,
- "max_luggage": 3,
- "supplier": "Bali Fast Track Indonesia",
- "price_gross_eur": "6.42",
- "currency": "EUR",
- "free_cancellation_until": "2027-04-09T08:00:00",
- "flight_info_required": true,
- "on_request": false,
- "wait_minutes_included": 90,
- "tolls_included": true,
- "gratuity_included": true,
- "amenities": [
- {
- "key": "meet_and_greet",
- "name": "Meet & Greet",
- "included": true
}, - {
- "key": "baby_seats",
- "name": "Child Seat (1-5 years)",
- "included": false,
- "price_gross_value": "4.04"
}
], - "pickup_datetime": "2027-04-10T14:00:00",
- "pickup_iata": "DPS",
- "num_passengers": 2,
- "service_mode": "point_to_point"
}
]
}Authoritative total for one offer plus the paid add-ons you select
(amenity keys with included: false). Book with the same keys so
the charge matches this price.
| vendor required | string |
| vendor_quote_id required | string |
| quote_raw required | object |
| optional_amenities | Array of strings |
{- "vendor": "string",
- "vendor_quote_id": "string",
- "quote_raw": { },
- "optional_amenities": [
- "baby_seats"
]
}{- "price_gross_eur": "string",
- "currency": "EUR",
- "amenities": [
- { }
]
}Books one offer and charges it (payment_method as in car rental:
funds or card). Idempotent with the Idempotency-Key header (or
body idempotency_key): a retry replays the original answer. A booking
that looks like one you already have (same agency, route, pickup time
and traveller email) answers 409 possible_duplicate_booking without
booking; resend with confirm_duplicate: true if it is intentional
(e.g. a second vehicle).
| Idempotency-Key | string |
| vendor required | string |
| vendor_quote_id required | string |
| quote_raw required | object |
| optional_amenities | Array of strings |
| payment_method required | string Enum: "funds" "card" |
| confirm_duplicate | boolean Default: false |
required | object |
{- "vendor": "string",
- "vendor_quote_id": "string",
- "quote_raw": { },
- "optional_amenities": [
- "string"
], - "payment_method": "funds",
- "confirm_duplicate": false,
- "traveller": {
- "title": "Mr",
- "first_name": "string",
- "last_name": "string",
- "email": "user@example.com",
- "phone": "string",
- "country_code": "string",
- "airline": "string",
- "flight_number": "string",
- "special_requests": "string"
}
}{- "trekko_booking_id": "string",
- "status": "confirmed"
}Cancel by booking_id. A round trip has one booking per leg: cancel
each. Refunds to your wallet per the cancellation terms. Another
agency's (or an unknown) booking answers 404.
| booking_id required | integer |
{- "booking_id": 0
}{- "cancelled": true,
- "refunded": true,
- "refund_status": "string",
- "refund_amount": 0,
- "refund_percent": 0
}Your agency-branded voucher with the driver/operator contact the
traveller needs. The voucher never shows a price (it is meant to be
handed to your client); with_price is accepted for backwards
compatibility and ignored.
| id required | integer |
| with_price | integer Deprecated Default: 0 Enum: 0 1 Ignored - the voucher never shows a price. |
| locale | string Default: "en" |
{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}| booking_id required | integer |
| payment_method required | string Value: "funds" |
{- "booking_id": 0,
- "payment_method": "funds"
}{- "invoice_id": 123,
- "payment_status": "paid",
- "amount": 82.43,
- "currency": "EUR"
}Sends an agency-branded quote email for a search result. Rate-limited per agency.
{ }{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}Self-serve test surface under /core/sandbox; trk_test_ keys, no real vendors/money.
Public, no-auth self-serve signup. With email verification on (the
default) it answers 202 verification_required and emails a
6-digit code; redeem it on /sandbox/signup/verify to receive the
trk_test_* key/secret pair (secret shown ONCE) plus the sandbox base
URL — the key is not created until then. Use the key to call any
/sandbox/... endpoint and run the full
search→availability→checkout→confirm→(trigger_rebooking)→cancel loop with
no real vendors, money or production data.
An email and company name are both required. Any non-disposable
mailbox works for the sandbox (free consumer mailboxes such as Gmail are
accepted); disposable mailboxes are refused with 400. Production
activation requires a business email. The code is valid for
expires_in_minutes (60 by default) and 5 wrong attempts burn it
(request a new one with /sandbox/signup/resend). Errors on the three
signup endpoints have the shape {"error": "<code>", "message": "..."}
(the code is a string, not the envelope object). Signup is limited to
10 requests per hour per IP.
| email required | string <email> Email address (any non-disposable mailbox works for the sandbox; production activation requires a business email). |
| company_name required | string |
{- "email": "dev@yourcompany.com",
- "company_name": "Example Travel"
}{- "sandbox_account_id": 0,
- "email": "string",
- "api_key": "trk_test_abcdef0123456789",
- "api_secret": "string",
- "mode": "test",
- "auth_header_example": "string",
- "note": "string"
}| sandbox_account_id | integer |
string <email> Alternative to sandbox_account_id. | |
| code required | string |
{- "sandbox_account_id": 0,
- "email": "user@example.com",
- "code": "482913"
}{- "sandbox_account_id": 0,
- "email": "string",
- "api_key": "trk_test_abcdef0123456789",
- "api_secret": "string",
- "mode": "test",
- "auth_header_example": "string",
- "note": "string"
}Always 202 for a syntactically valid address (never reveals whether it has a pending request).
| email required | string <email> |
{- "email": "user@example.com"
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}Mirrors the live search contract; backed by the isolated sandbox engine. Accepts query as a query param or in the body. Requires a test key (401 auth_missing without one).
| query | string Example: query=Barcelona |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "error": {
- "code": "invalid_api_key",
- "message": "Invalid API key or secret.",
- "request_id": "a1b2c3d4e5f6"
}
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| accommodation_id required | integer |
| start_date required | string <date> |
| end_date required | string <date> |
required | Array of objects (Guest) |
required | Array of objects (GuestRoomDistribution) |
| nationality | string OPTIONAL. 2-letter ISO-3166-1 alpha-2 country code. When omitted the supplier default market applies (typically ES). An explicit null is rejected with 400. |
| currency_code | string ISO-4217. Defaults to EUR. |
{- "accommodation_id": 1376114,
- "start_date": "2026-09-01",
- "end_date": "2026-09-04",
- "guests": [
- {
- "id": 1,
- "age": 34
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 0
]
}
], - "nationality": "ES",
- "currency_code": "EUR"
}{- "error": {
- "code": "invalid_api_key",
- "message": "string",
- "request_id": "string",
- "details": { }
}, - "detail": "string"
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| 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 (Guest) |
required | Array of objects (GuestRoomDistribution) |
| currency_code | string Default: "EUR" |
{- "accommodation_id": 0,
- "vendor": "string",
- "rate_plan_code": "string",
- "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "guests": [
- {
- "id": 1,
- "age": 34
}
], - "guests_room_distribution": [
- {
- "guest_ids": [
- 0
]
}
], - "currency_code": "EUR"
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}Honours Idempotency-Key like production (24 hours, per sandbox account):
the same key and body replays the original response (same booking,
Idempotency-Replayed: true); the same key with a different body is
422 idempotency_key_reused.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| Idempotency-Key | string <= 200 characters |
| accommodation_id required | integer |
| vendor required | string non-empty |
| booking_code required | string |
| room_codes | Array of strings Required when |
| invoice_id required | integer From the payment step (e.g. pay_by_funds). |
| payment_type required | string Enum: "Booking Payment by Own Card" "Booking Payment by Funds" "Booking Payment (Pay Later)" "Booking Payment by Clients Card" Must match the invoice. One of the long invoice-type strings. |
| minimum_price required | number Echo of the checkout |
| maximum_price required | number Echo of the checkout |
| nett_price required | number Exactly the checkout |
| base_price | number Deprecated Optional and ignored. The server uses the checkout quote it stored for this |
| base_currency | string Deprecated Default: "EUR" Optional and ignored (see |
| currency_code | string Default: "EUR" |
required | object (GuestsInformation) Single object carrying the lead guest plus any extra occupants. |
required | Array of objects (GuestRoomDistribution) |
object | |
| cancellation_policy required | string non-empty |
required | Array of objects (CancellationPolicyRule) |
| board_plan_text required | string or null |
required | Array of objects (RoomData) |
| start_date required | string <date> |
| end_date required | string <date> |
| agencies_internal_booking_ref | string or null <= 64 characters Optional. Your own reference, surfaced in the Trekko CRM (max 64 characters; omit or send empty to leave it blank). Add, change or clear it at any time with |
| idempotency_key | string Optional stable per-attempt key; a duplicate submit returns the original booking. If omitted, the server derives one from invoice_id. |
| allow_rebooking | boolean Per-booking rebooking opt-out. Omitted/true = the booking is eligible for SBPO rebooking (the default). Set false if this booking must never be rebooked (e.g. you cannot tolerate a booking_number change for it). Can be changed later via |
{- "accommodation_id": 0,
- "vendor": "string",
- "booking_code": "string",
- "room_codes": [
- "string"
], - "invoice_id": 0,
- "payment_type": "Booking Payment by Funds",
- "minimum_price": 0,
- "maximum_price": 0,
- "nett_price": 0,
- "base_price": 0,
- "base_currency": "EUR",
- "currency_code": "EUR",
- "guests_information": {
- "id": 1,
- "lead_guest_title": "Mr",
- "lead_guest_name": "Ada",
- "lead_guest_surname": "Lovelace",
- "lead_guest_email": "user@example.com",
- "lead_guest_phone": "string",
- "lead_guest_nationality": "ES",
- "lead_guest_age": 34,
- "lead_guest_date_of_birth": "1990-04-12",
- "lead_guest_document_number": "string",
- "guests": [
- {
- "id": 0,
- "title": "string",
- "name": "string",
- "surname": "string",
- "age": 30,
- "date_of_birth": "1990-04-12",
- "document_number": "string"
}
]
}, - "guests_room_distribution": [
- {
- "guest_ids": [
- 0
]
}
], - "special_requests": {
- "arrival_time": "string",
- "other_requests": "string"
}, - "cancellation_policy": "string",
- "cancellation_policy_rules": [
- {
- "From": "0",
- "To": "3",
- "DateFrom": "2026-02-09",
- "DateFromHour": "00:00",
- "DateTo": "2026-02-13",
- "DateToHour": "00:00",
- "Type": "V",
- "FixedPrice": "0",
- "PercentPrice": "100",
- "Nights": "0",
- "ApplicationTypeNights": "Average"
}
], - "board_plan_text": "string",
- "rooms_data": [
- {
- "room_name": "Double Room",
- "bed_reference": "1 double bed",
- "no_of_adults": 2,
- "no_of_children": 0,
- "guest_name": "Ada Lovelace"
}
], - "start_date": "2019-08-24",
- "end_date": "2019-08-24",
- "agencies_internal_booking_ref": "string",
- "idempotency_key": "string",
- "allow_rebooking": true
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_number | integer |
| booking_id | string |
{- "booking_number": 0,
- "booking_id": "string"
}{- "error": {
- "code": "invalid_api_key",
- "message": "Invalid API key or secret.",
- "request_id": "a1b2c3d4e5f6"
}
}| page_no | integer >= 1 Default: 1 |
| items_per_page | integer [ 1 .. 100 ] Default: 20 |
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "error": {
- "code": "invalid_api_key",
- "message": "string",
- "request_id": "string",
- "details": { }
}, - "detail": "string"
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| page_no | integer >= 1 Default: 1 |
| items_per_page | integer [ 1 .. 100 ] Default: 20 |
{- "page_no": 1,
- "items_per_page": 20
}{- "error": {
- "code": "invalid_api_key",
- "message": "string",
- "request_id": "string",
- "details": { }
}, - "detail": "string"
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_id | string |
| booking_number | integer |
{- "booking_id": "string",
- "booking_number": 0
}{- "error": {
- "code": "invalid_api_key",
- "message": "string",
- "request_id": "string",
- "details": { }
}, - "detail": "string"
}Simulate SBPO rebooking a confirmed sandbox booking to a cheaper rate — applies the real money model, credits savings, and fires booking.rebooked.
| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| booking_id | string |
| booking_number | integer |
{- "booking_id": "string",
- "booking_number": 0
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
{- "error": {
- "code": "invalid_api_key",
- "message": "Invalid API key or secret.",
- "request_id": "a1b2c3d4e5f6"
}
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| page_no | integer Default: 1 |
| items_per_page | integer Default: 20 |
{- "page_no": 1,
- "items_per_page": 20
}{- "error": {
- "code": "invalid_api_key",
- "message": "Invalid API key or secret.",
- "request_id": "a1b2c3d4e5f6"
}
}| Accept-Language | string Default: en Enum: "en" "es" "fr" "de" "it" "pt" Response language. Send |
| url required | string <uri> |
{
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}Read-only. Authenticate with your test key (trk_test_*). Returns
whether your account is promoted/live, the required minimum deposit, and
your current funding (wallet deposit + credit line). See
SELF_SERVE_PRODUCTION.md.
{- "mode": "test",
- "production_active": true,
- "deposit_required": 3000,
- "available_balance": 0,
- "gap": 0,
- "currency": "EUR"
}Authenticate with your test key. Requires an approved production
access request (/account/production/activation/request, then
/account/production/activation/verify_email, then Trekko's review;
until then the answer is an activation_* error such as
activation_not_requested or activation_pending_review). Promotes
your account to a real agency and mints your trk_live_ key (secret
shown ONCE) — only once your wallet deposit + credit line reach
the minimum (€3,000 by default).
There is no payment in this call: fund your wallet first via the normal
channels (card top-up or bank transfer). Until funded it returns
pending_deposit with how much is left.
string <email> Required only if not set at signup. | |
| company_name | string |
{- "email": "dev@yourcompany.com"
}{- "mode": "live",
- "production_active": true,
- "agency_id": 0,
- "api_key": "trk_live_…",
- "api_secret": "string",
- "deposit_required": 3000,
- "available_balance": 0,
- "gap": 0,
- "currency": "EUR"
}Authenticate with your test key. Company email and registered
company name are required (personal mailboxes are refused). A 6-digit
code is emailed to that address; after
/account/production/activation/verify_email the Trekko team reviews
the request. Approval alone does not mint a live key: see
/account/production/activate.
string <email> | |
| company_name | string |
{- "email": "user@example.com",
- "company_name": "string"
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}| code required | string |
{- "code": "string"
}{- "error": {
- "code": "invalid_request",
- "message": "Field 'start_date' is required.",
- "request_id": "a1b2c3d4e5f6"
}
}