Trip Details

Returns the full detail of one trip in a single call: live seat availability (segments[].seats_map, segments[].free_seats_count), the passenger fields the provider requires to book (required_passenger_fields), ancillary services (baggage), per-fare cancellation rules (fares[].cancellation_info), and applicable discounts.

INFO

This is a POST (not a cacheable GET) because the response carries live seat availability that must not be cached, and to stay uniform with Search and Recalculate. The passengers party composition is required because required fields and per-passenger pricing/availability depend on it.

Endpoint

Method: POST

URL: /v1/trip

Request Headers

Parameter	Type	Required	Description
Authorization	String	Yes	Bearer <token> from Login

Request Parameters

Parameter	Type	Required	Description
└ trip_id	String	Yes	Trip id from a Search result
└ locale	String	No	Language, refer to Locale List
└ currency	String	No	Requested pricing currency
└ passengers	Object	Yes	Passenger party composition
└ adults	Integer	Yes	Number of adults (≥ 1)
└ children	Integer	No	Number of children (≥ 0)

Request Example

{
  "trip_id": "trip_8f21",
  "locale": "en",
  "currency": "UAH",
  "passengers": {
    "adults": 2,
    "children": 1
  }
}

Response Parameters

The response wraps a single trip object. It contains every field from the Search trip, plus the detail fields below.

Parameter	Type	Required	Description
└ trip	Object	Yes	Full trip detail
└ id	String	Yes	Trip identifier
└ currency	String	Yes	Pricing currency
└ price	Number	Yes	Price per adult
└ departure	Place	Yes	Departure point (see Place)
└ arrival	Place	Yes	Arrival point (see Place)
└ fares	[Fare]	Yes	Available fare options (see Fare)
└ segments	[Segment]	No	Trip segments / legs with seat maps (see Segment)
└ stops	[Stop]	No	Intermediate stops (see Stop)
└ discounts	[Discount]	No	Available discounts (see Discount)
└ baggage	[Baggage]	No	Ancillary baggage options (see Baggage)
└ required_passenger_fields	RequiredPassengerFields	No	Fields needed to book (see Required Passenger Fields)

Shared Schemas

Segment

Parameter	Type	Required	Description
id	String	No	Segment identifier
index	Integer	No	Sequence position in the trip
departure_name	String	No	Departure stop name
arrival_name	String	No	Arrival stop name
departure	Place	No	Departure point (see Place)
arrival	Place	No	Arrival point (see Place)
price	Number	No	Segment price
currency	String	No	Currency
free_seating	Boolean	Yes	true = open/unassigned seating (board anywhere); false = passengers must choose a seat from seats_map. Providers MUST set this explicitly.
free_seats_count	Integer	No	Available seats
seats_map	[SeatMap]	No	Seat grid (when not free_seating)

SeatMap

Parameter	Type	Description
id	String	Seat identifier (used as seat_id in Create Order)
number	String	Seat number (e.g. 12A)
type	Integer	Cell type, refer to Seat Type Legend
coor_x	Integer	X coordinate on the coach plan
coor_y	Integer	Y coordinate on the coach plan
coor_z	Integer	Z coordinate / deck (default 0)

Stop

Parameter	Type	Description
index	Integer	Sequence position
id	String	Stop identifier
name	String	Stop name
address	String	Stop address
departure	String	Departure datetime (ISO-8601)
arrival	String	Arrival datetime (ISO-8601)
is_technical_stop	Boolean	Whether this is a technical (non-boarding) stop
latitude	Number	Latitude
longitude	Number	Longitude
timezone	String	IANA timezone

Discount

Parameter	Type	Description
discount_id	String	Discount identifier (used by Recalculate)
discount_code	String	Discount code (e.g. child)
discount_name	String	Display name
description	String	What the discount applies to
discount_percent	Number	Discount percentage (e.g. 50)
age_start	Integer	Minimum age (inclusive)
age_end	Integer	Maximum age (inclusive)

Baggage

Parameter	Type	Description
id	String	Baggage option identifier
type	String	One of small, medium, large
title	String	Display name
length	Integer	Length in cm
width	Integer	Width in cm
height	Integer	Height in cm
weight	Integer	Max weight in kg
max_per_person	Integer	Max items per passenger
price	Number	Price per item
provision_percent	Number	Provider commission percentage
currency	String	Currency

CancellationRule

Returned inside each fares[].cancellation_info.

Parameter	Type	Description
id	String	Rule identifier
description	String	Human-readable rule text
hours_before_departure	Number	Hours before departure this rule applies from (e.g. 24)
refund_rate	Number	Refund fraction (e.g. 0.75 = 75% refunded)
ticket_price	Number	Ticket price the rule is computed against
refund_amount	Number	Resulting refund amount

Required Passenger Fields

A boolean map of the passenger fields the provider requires to book this trip. Recognised keys: need_birth, need_doc, need_doc_type, need_doc_expiry, need_doc_issue_date, need_doc_issue_country, need_nationality, need_residency, need_patronymic, need_gender, need_phone, need_latin_names, need_email, need_city, need_street_name, need_building_apartment_number, need_zip_code, need_seat, need_visa_permit_type. Unknown keys are ignored.

Response Example

{
  "trip": {
    "id": "trip_8f21",
    "currency": "UAH",
    "price": 650.0,
    "departure": { "code": "2200001", "name": "Kyiv Central Bus Station", "datetime": "2026-07-01T08:00:00+03:00" },
    "arrival": { "code": "2218000", "name": "Lviv Bus Station", "datetime": "2026-07-01T16:00:00+03:00" },
    "fares": [
      {
        "code": "adult",
        "name": "Standard",
        "price": 650.0,
        "currency": "UAH",
        "is_default": true,
        "cancellation_info": [
          { "id": "r1", "description": "More than 24h before departure", "hours_before_departure": 24, "refund_rate": 0.9 }
        ]
      }
    ],
    "segments": [
      {
        "id": "seg_1",
        "index": 0,
        "free_seating": false,
        "free_seats_count": 30,
        "seats_map": [
          { "id": "s12a", "number": "12A", "type": 1, "coor_x": 1, "coor_y": 6, "coor_z": 0 }
        ]
      }
    ],
    "discounts": [
      { "discount_id": "d_child", "discount_code": "child", "discount_name": "Child", "discount_percent": 50, "age_start": 0, "age_end": 11 }
    ],
    "required_passenger_fields": { "need_birth": true, "need_doc": true, "need_phone": true }
  }
}

Error Code List

code	message	Description
UNAUTHORIZED	Invalid token	The bearer token is missing, invalid, or expired (401).
NOT_FOUND	Trip not found	The trip_id is unknown or has expired.