Itinerary Schema

The itinerary is one of the four primary Versa event types. It shares the same underlying schema as a receipt, booking, or invoice, but excludes all financial data (totals, taxes, payments, etc.) and is focused only on travel information. E-commerce itemizations are not supported.

A JSON Schema document and corresponding TypeScript Types are available on GitHub or via the @versa/schema package.

Wrapper

Itineraries use the same top-level wrapper as the Versa schema, but without the payments field.

Field	Type	Description
`schema_version`	`string`	Version of the schema; useful for validating the object.
`header`	`object`	Header.
`itemization`	`object`	Itemization object.
`footer`	`object`	The footer includes supplemental text.

The header mirrors the schema header, but with all financial info (totals, etc.) removed.

Field	Type	Description
`third_party`	`nullable object`	Third party involved in the transaction, where applicable.
`customer`	`nullable object`	Customer involved in the transaction, where applicable.

Itemization

The Itemization section describes the record of services that compose the itinerary. Based on the type of purchase, the object conforms to one of five templates: Car Rental, Flight, Lodging, Service, or Transit Route. Exactly one itemization template must be non-null.

"itemization": {
  "car_rental": null,
  "flight": { ... },
  "lodging": null,
  "service": null,
  "transit_route": null
}

Car Rental Object

Car Rental

View a complete car rental itinerary example.

"car_rental": {
  "rental_at": 1713196492,
  "return_at": 1713415500,
  "confirmation_number": null,
  "record_locator": null,
  "vendor_code": null,
  "rental_location": { ... },
  "return_location": { ... },
  "vehicle": {
    "description": "Polestar 2",
    "image": null
  },
  "drivers": [{ ... }],
  "odometer_reading_in": 100,
  "odometer_reading_out": 210,
  "items": [ ... ],
  "metadata": [],
}

Field	Type	Description
`rental_at`	`integer`	Rental time. Measured in seconds since the Unix epoch.
`return_at`	`integer`	Return time. Measured in seconds since the Unix epoch.
`confirmation_number`	`nullable string`	Rental confirmation number.
`record_locator`	`nullable string`	PNR or booking record locator.
`vendor_code`	`nullable string`	Two-letter GDS vendor code, e.g. `ZI` for Avis, `ZB` for Budget.
`rental_location`	`object`	A place describing the rental location.
`return_location`	`object`	A place describing the return location.
`vehicle`	`object`	A vehicle object.
`drivers`	`nullable array`	Array of person objects.
`odometer_reading_in`	`nullable integer`
`odometer_reading_out`	`nullable integer`
`items`	`array`	An array of generic item objects.
`metadata`	`array`	Array of metadata objects, for any additional info.

Vehicle

Field	Type	Description
`description`	`string`	Type of car.
`image`	`nullable string`	Image of car.

Flight Object

Flight

View a complete flight itinerary example.

Field	Type	Description
`tickets`	`array`	An array of ticket objects.
`itinerary_locator`	`nullable string`

Tickets

Field	Type	Description
`segments`	`array`	Array of segments.
`number`	`nullable string`
`record_locator`	`nullable string`
`passenger`	`nullable object`	A person object.
`metadata`	`array`	Array of metadata objects, for any additional info.

Segments

Field	Type	Description
`departure_airport_code`	`string`	The three-letter IATA airport code that the flight departed from.
`arrival_airport_code`	`string`	The three-letter IATA airport code of the flight’s destination.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`departure_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`arrival_tz`	`nullable string`	A list of possible time zone values is maintained at the IANA Time Zone Database.
`flight_number`	`nullable string`	The two-letter IATA airline designator followed by a one to four digit number (e.g. 'DL123').
`class_of_service`	`nullable string`
`seat`	`nullable string`
`aircraft_type`	`nullable string`	The ICAO code of the aircraft.
`metadata`	`array`	Array of metadata objects, for any additional info.

Lodging Object

Lodging

View a complete lodging itinerary example.

"lodging": {
  "check_in": 1713196492,
  "check_out": 1713473361,
  "confirmation_number": null,
  "chain_code": null,
  "property_id": null,
  "record_locator": null,
  "guests": [ ... ],
  "room": "806",
  "location": { ... },
  "items": [ ... ],
  "metadata": [],
}

Field	Type	Description
`check_in`	`int`	Check-in date-time. Measured in seconds since the Unix epoch.
`check_out`	`int`	Check-out date-time. Measured in seconds since the Unix epoch.
`confirmation_number`	`nullable string`	Hotel confirmation number.
`chain_code`	`nullable string`	Two-character chain code, e.g. `MC` for Marriott, `HY` for Hyatt.
`property_id`	`nullable string`	Property identifier. Examples: `gds.sabre:19835`, `gds.amadeus:BWNYCMQ`, `chain.marriott:NYCMQ`, `giata:17324`.
`record_locator`	`nullable string`	PNR or booking record locator.
`guests`	`nullable array`	Array of person objects.
`room`	`nullable string`	Room number.
`location`	`nullable object`	A place object describing the hotel / lodging.
`items`	`array`	An array of generic item objects. This includes the room rate, as well as incidentals / full folio.
`metadata`	`array`	Array of metadata objects, for any additional info.

Service Object

Service

For airport parking, SaaS subscriptions, phone bills, etc. View a complete service itinerary example.

"service": {
  "service_items": [{
    "service_location": {
      "name": "Cars R Park'd",
      "address": {
        "street_address": "2741 Camp Creek Parkway",
        "city": "College Park",
        "region": "GA",
        "postal_code": "30337",
        "country": "US",
        "tz": "America/New_York"
      }
    },
    "description": "Uncovered parking (1 month)",
    "current_period_start_at": 1679609767,
    "current_period_end_at": 1682288167,
    "metadata": []
  }]
}

Field	Type	Description
`service_items`	`array`	An array of service item objects.

Service Item

Field	Type	Description
`service_location`	`nullable object`	A place object describing the location where the service was provided (e.g., parking lot, service center).
`description`	`string`	Description of the service.
`current_period_start_at`	`nullable integer`	Start of the current period of the service. Measured in seconds since the Unix epoch.
`current_period_end_at`	`nullable integer`	End of the current period. Measured in seconds since the Unix epoch.
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.

Transit Route Object

Transit Route

A route, typically used by rideshare / taxi services, or rail / bus / ferry / etc. View complete taxi itinerary or rail itinerary examples.

"transit_route": {
  "transit_route_items": [{
    "departure_address": {
      "street_address": "273 Sesame St",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.68266,
      "lon": -73.94237,
      "tz": "America/New_York"
    },
    "arrival_address": {
      "street_address": "141 Broadway",
      "city": "Brooklyn",
      "region": "NY",
      "country": "US",
      "postal_code": "11205",
      "lat": 40.69954,
      "lon": -73.97064,
      "tz": "America/New_York"
    },
    "departure_at": 1713196492,
    "arrival_at": 1713197752,
    "passenger": null,
    "polyline": "syhwFxzhbMrFtdAmpAhOlGzmAi%5CdEaGEDgEoAEMfK",
    "metadata": [],
  }],
}

Field	Type	Description
`transit_route_items`	`array`	Array of transit route item objects.

Transit Route Item

Field	Type	Description
`departure_location`	`object`	The origin place object.
`arrival_location`	`object`	The destination place object.
`departure_at`	`nullable integer`	Departure time. Measured in seconds since the Unix epoch.
`arrival_at`	`nullable integer`	Arrival time. Measured in seconds since the Unix epoch.
`mode`	`nullable enum`	One of `car`, `taxi`, `rail`, `bus`, `ferry`, `other`.
`passenger`	`nullable string`	For ticketed local transit, the passenger name.
`polyline`	`nullable string`	An encoded polyline of the route.
`metadata`	`array`	Array of key/value metadata pairs.

Field	Type	Description
`supplemental_text`	`nullable string`	Terms and conditions or other info. Supports Markdown.

Primitives

Foundational objects used throughout the schema.

Item Primitive

Item

A generic line item.

{
  "description": "Blue Cheese Crumbles",
  "quantity": 10,
  "unit": null,
  "product_image_asset_id": null,
  "group": null,
  "unspsc": null,
  "url": null,
  "date": null,
  "metadata": [{ "key": "SKU", "value": "524959" }]
}

Field	Type	Description
`description`	`string`	Description of the good / service.
`quantity`	`nullable number`	Quantity of items.
`unit`	`nullable string`	Field describing the unit type, typically for weight or volume -based values, e.g. 'kg' or 'gallons'. Leave null for 'each'.
`product_image_asset_id`	`nullable string`	Asset id of uploaded product image.
`group`	`nullable string`	Grouping of line items.
`unspsc`	`nullable string`	The 8-digit UNSPSC code for this item.
`url`	`nullable string`	URL to product page.
`date`	`nullable string`	Date corresponding to the given line item, in ISO 8601 format (YYYY-MM-DD).
`metadata`	`array`	Array of key/value metadata pairs, e.g. SKU.

Edit this doc on GitHub