diff --git a/.gitignore b/.gitignore
index 6c46409..e53fa8b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,4 +9,6 @@ nul
*.py
requirements/
dummies-guides/
-dont-include/
\ No newline at end of file
+dont-include/
+issues
+work-in-progress.qea
diff --git a/OTI_18.qea b/OTI_18.qea
new file mode 100644
index 0000000..b2cb354
Binary files /dev/null and b/OTI_18.qea differ
diff --git a/deliverables/1 search offers/lookup.html b/deliverables/1 search offers/lookup.html
new file mode 100644
index 0000000..e0318bd
--- /dev/null
+++ b/deliverables/1 search offers/lookup.html
@@ -0,0 +1,41 @@
+
+
+
+
+
+ OpenAPI Preview — lookup.yaml
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deliverables/1 search offers/lookup.yaml b/deliverables/1 search offers/lookup.yaml
new file mode 100644
index 0000000..d320e4e
--- /dev/null
+++ b/deliverables/1 search offers/lookup.yaml
@@ -0,0 +1,391 @@
+openapi: 3.1.0
+info:
+ title: OTI — Lookup tables
+ version: 0.1.0-draft
+ description: >
+ Provides read-only access to the operator-defined lookup tables (code lists) used in the
+ OTI Search Offers and Lock Offer APIs. Each lookup table is accessible via two path patterns:
+
+ - **REST style** — `GET /{lookup-type}` — returns all items of a given code list.
+ - **OGC Records API style** — `GET /collections/{lookup-type}/items` — returns the same
+ items conforming to the OGC API - Records (Part 1) item-collection response structure.
+
+ The three lookup tables correspond to the attributes marked as `lookup` in the OTI model:
+
+ | Path segment | Used by |
+ |---|---|
+ | `personal-needs` | `OfferRequest.travellers[].personalNeeds[]` |
+ | `ancillary-types` | `Ancillary.type` in offer responses |
+ | `entitlement-types` | `EntitlementRight.entitlementType` |
+
+paths:
+
+ # ─── PERSONAL NEEDS ────────────────────────────────────────────────────────
+
+ /personal-needs:
+ get:
+ summary: List all personal need types
+ operationId: list_personal_needs
+ description: >
+ Returns all valid values for `personalNeeds[]` on a travelling entity.
+ These are operator-defined accessibility and mobility need codes
+ (e.g. motorizedWheelchair, visualImpairment, accompanyingDog).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/personal-needs/items:
+ get:
+ summary: 'OGC Records API: list personal need types'
+ operationId: ogc_list_personal_needs
+ description: >
+ Returns all valid values for `personalNeeds[]` on a travelling entity,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+ # ─── ANCILLARY TYPES ───────────────────────────────────────────────────────
+
+ /ancillary-types:
+ get:
+ summary: List all ancillary types
+ operationId: list_ancillary_types
+ description: >
+ Returns all valid values for `Ancillary.type` in offer responses.
+ These are operator-defined ancillary service codes
+ (e.g. bicycleTransport, vehicleTransport, cabin, meal, extraLuggage).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/ancillary-types/items:
+ get:
+ summary: 'OGC Records API: list ancillary types'
+ operationId: ogc_list_ancillary_types
+ description: >
+ Returns all valid values for `Ancillary.type` in offer responses,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+ # ─── ENTITLEMENT TYPES ─────────────────────────────────────────────────────
+
+ /entitlement-types:
+ get:
+ summary: List all entitlement right types
+ operationId: list_entitlement_types
+ description: >
+ Returns all valid values for `EntitlementRight.entitlementType` on a travelling entity.
+ These are operator-defined entitlement codes
+ (e.g. discountSubscription, loyaltyCard, concession, promotionCode, railcard).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/entitlement-types/items:
+ get:
+ summary: 'OGC Records API: list entitlement right types'
+ operationId: ogc_list_entitlement_types
+ description: >
+ Returns all valid values for `EntitlementRight.entitlementType` on a travelling entity,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+components:
+ schemas:
+
+ # ─── REST RESPONSE ─────────────────────────────────────────────────────────
+
+ LookupCollection:
+ type: object
+ additionalProperties: false
+ description: A paginated collection of lookup items returned by the REST-style endpoints.
+ required:
+ - items
+ properties:
+ items:
+ type: array
+ description: The lookup items on this page.
+ items:
+ $ref: '#/components/schemas/LookupItem'
+ totalCount:
+ type: integer
+ description: Total number of items in the code list (across all pages).
+ offset:
+ type: integer
+ description: Zero-based offset of the first item on this page.
+ limit:
+ type: integer
+ description: Maximum number of items returned per page.
+ links:
+ type: array
+ description: Pagination links (next, prev, self).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ LookupItem:
+ type: object
+ additionalProperties: false
+ description: A single entry in a lookup table (code list).
+ required:
+ - code
+ - name
+ properties:
+ code:
+ type: string
+ description: The machine-readable code value used in API requests and responses.
+ name:
+ type: string
+ description: Human-readable short label for this code (language follows Accept-Language).
+ description:
+ type: string
+ description: Optional longer description of what this code means.
+ validFrom:
+ type: string
+ format: date
+ description: Date from which this code is valid (inclusive). Omitted if always valid.
+ validTo:
+ type: string
+ format: date
+ description: Date until which this code is valid (inclusive). Omitted if open-ended.
+
+ # ─── OGC RECORDS RESPONSE ──────────────────────────────────────────────────
+
+ OgcItemCollection:
+ type: object
+ additionalProperties: false
+ description: >
+ An OGC API - Records (Part 1) item-collection response.
+ Conforms to the FeatureCollection-like envelope used by OGC Records.
+ required:
+ - type
+ - items
+ properties:
+ type:
+ type: string
+ const: ItemCollection
+ description: Fixed GeoJSON-compatible collection type identifier.
+ items:
+ type: array
+ description: The lookup items on this page, each wrapped in an OGC Record Item envelope.
+ items:
+ $ref: '#/components/schemas/OgcItem'
+ numberMatched:
+ type: integer
+ description: Total number of items matching the query (across all pages).
+ numberReturned:
+ type: integer
+ description: Number of items included in this response page.
+ links:
+ type: array
+ description: Pagination and self-description links (next, prev, self, collection).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ OgcItem:
+ type: object
+ additionalProperties: false
+ description: >
+ An OGC API - Records item envelope wrapping a single lookup entry.
+ Conforms to the OGC Records Item schema.
+ required:
+ - type
+ - id
+ - properties
+ properties:
+ type:
+ type: string
+ const: Feature
+ description: Fixed GeoJSON Feature type identifier (required by OGC Records).
+ id:
+ type: string
+ description: Unique identifier of this record — equal to the lookup code.
+ properties:
+ $ref: '#/components/schemas/LookupItem'
+ links:
+ type: array
+ description: Links related to this item (e.g. self, collection).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ # ─── SHARED ────────────────────────────────────────────────────────────────
+
+ Link:
+ type: object
+ additionalProperties: false
+ x-externalDocs:
+ url: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
+ required:
+ - href
+ - rel
+ properties:
+ rel:
+ type: string
+ description: Link relation type (e.g. self, next, prev, collection, alternate).
+ href:
+ type: string
+ format: uri
+ description: The URL of the linked resource.
+ type:
+ type: string
+ description: Media type of the linked resource (e.g. application/json).
+ title:
+ type: string
+ description: Human-readable label for this link.
+ method:
+ type: string
+ enum:
+ - GET
+ - POST
+ - PUT
+ - PATCH
+ - DELETE
+ default: GET
+ description: HTTP method to use for this link.
+
+ # ─── PRIMITIVES ────────────────────────────────────────────────────────────
+
+ dateTime:
+ type: string
+ format: date-time
+ x-pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$
+ description: https://www.rfc-editor.org/rfc/rfc3339#section-5.6
+
+ parameters:
+ acceptLanguage:
+ name: Accept-Language
+ in: header
+ description: >
+ Preferred language for human-readable fields (name, description).
+ Supporting English (en) is mandatory (see RFC 9110).
+ schema:
+ type: string
+
+ limit:
+ name: limit
+ in: query
+ description: Maximum number of items to return per page (default 100).
+ required: false
+ schema:
+ type: integer
+ minimum: 1
+ maximum: 1000
+ default: 100
+
+ offset:
+ name: offset
+ in: query
+ description: Zero-based index of the first item to return (for pagination).
+ required: false
+ schema:
+ type: integer
+ minimum: 0
+ default: 0
+
+ ogcBbox:
+ name: bbox
+ in: query
+ description: >
+ OGC API bounding box filter (minLon,minLat,maxLon,maxLat).
+ Not applicable to lookup tables but included for OGC Records conformance.
+ required: false
+ schema:
+ type: array
+ items:
+ type: number
+ minItems: 4
+ maxItems: 6
+
+ ogcDatetime:
+ name: datetime
+ in: query
+ description: >
+ OGC API temporal filter (RFC 3339 instant or interval).
+ Filters items by their validFrom/validTo range when provided.
+ required: false
+ schema:
+ type: string
+
+ headers:
+ contentLanguage:
+ description: Language of human-readable content in the response (IETF BCP 47 tag, e.g. nl-NL).
+ schema:
+ type: string
+ pattern: ^[a-zA-Z]+-[a-zA-Z]+$
+ required: true
diff --git a/deliverables/1 search offers/mappings/mapping-bob.md b/deliverables/1 search offers/mappings/mapping-bob.md
new file mode 100644
index 0000000..b6a84c1
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-bob.md
@@ -0,0 +1,252 @@
+# Mapping: Search Offers → BoB Product API v3.4.0
+
+Maps each EUDIT **Search Offers** concept to the corresponding concept/property in the **BoB Product API v3.4.0**.
+
+- **Endpoint**: `POST /product`
+- **EUDIT concept / Property** — as defined in `search-offers.yaml`
+- **BoB concept** — the matching schema object in BoB Product API
+- **BoB property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+**Important scope note**: BoB operates at the distribution layer. It searches for purchasable *products*
+by area/route/group, not by a specific trip pattern with individual service journeys. Travellers are
+represented as *category codes* (e.g. ADULT, CHILD) rather than individual profiles. As a result,
+many EUDIT concepts have no BoB equivalent, and the mapping is structural rather than semantic.
+
+---
+
+## OfferRequest
+
+> Root request body for the offer search.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| tripPatterns | TripPattern | 1..* | `productFilter` | `route?` / `area?` / `group?` | BoB does not accept a trip pattern (timetabled legs). The closest equivalent is a spatial/route filter: `route` (origin–destination pair), `area` (geographic zone), or `group` (product group). |
+| travellers | TravellingEntity | 1..* | `productFilter` | `travellers[{ categoryId, quantity }]` | Travellers are expressed as category codes with counts, not individual profiles. `Animal`, `PassengerVehicle`, `VehicleRack`, `Luggage` have no equivalent. |
+| filter | SearchOfferFilter | 0..1 | `productFilter` | `fareIds[]`, `genericCategoryIds[]` | No equivalent for `modes`, `classOfUse`, `mediaTypes`, `requestedSections`. |
+| policy | SearchOfferPolicy | 0..1 | — | — | No equivalent. BoB is synchronous; no pagination or currency control. |
+
+---
+
+## SearchOfferPolicy
+
+> Pagination and currency preferences. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| numberOfResultsBefore | integer | 0..1 | — | — | Not supported. |
+| numberOfResultsAfter | integer | 0..1 | — | — | Not supported. |
+| currency | string | 0..1 | — | — | Currency is operator configuration, not a request parameter. |
+
+---
+
+## SearchOfferFilter
+
+> Constraints on which offers to return.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| modes | string | 0..* | — | — | No equivalent. BoB products are not filtered by transport mode. |
+| classOfUse | string | 0..* | — | — | No equivalent. |
+| mediaTypes | string | 0..* | — | — | No equivalent. |
+| requestedSections | RequestedSections | 0..* | — | — | No equivalent. |
+
+---
+
+## RequestedSections
+
+> Targets offer search to a subset of legs. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## TravellingEntity
+
+> Base class.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | — | — | No per-traveller identifier in BoB; travellers are aggregated by category. |
+| entityType | string | 1..1 | — | — | Discriminator only. `Animal`, `PassengerVehicle`, `Luggage` have no BoB equivalent. |
+| entitlementRights | EntitlementRight | 0..* | `productFilter` | `discountCodes[]` | See **EntitlementRight**. |
+
+---
+
+## Traveller
+
+> Human traveller.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | — | — | Not used; travellers aggregated by `categoryId`. |
+| age | integer | 0..1 | — | — | Age band encoded in `categoryId` (e.g. a "CHILD" category has age bounds defined in `GET /productcat/traveller`). |
+| assistant | boolean | 0..1 | — | — | No equivalent. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent. |
+| externalReference | string | 0..1 | — | — | No equivalent. |
+| personalNeeds | PersonalNeed | 0..* | — | — | No equivalent. |
+| qualifyingCharacteristics | TravellerQualifyingCharacteristics | 0..1 | — | — | No equivalent; eligibility is encapsulated in category codes. |
+
+---
+
+## TravellerQualifyingCharacteristics
+
+> Demographic eligibility data. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | Demographic eligibility is abstracted into traveller categories obtained via `GET /productcat/traveller`. |
+
+---
+
+## PersonalNeed
+
+> Accessibility or personal need. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## LicenseType
+
+> Driving licence. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## Animal
+
+> Animal travelling alongside its owner. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. Pets may be represented as a traveller category if the operator defines one. |
+
+---
+
+## PassengerVehicle
+
+> Traveller-owned vehicle. **No equivalent in BoB product search.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | Vehicle transport outside BoB scope at offer-search level. May appear as a category in some operator configurations. |
+
+---
+
+## VehicleRack
+
+> Rack on a vehicle. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## Luggage
+
+> Bulky item. **No equivalent in BoB product search.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | May be represented as a traveller category if the operator defines one. No dimension/weight input. |
+
+---
+
+## EntitlementRight
+
+> Credential qualifying for reduced fares.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| issuer | string | 0..1 | — | — | No issuer field; discount codes are opaque strings in BoB. |
+| entitlementType | string | 1..1 | — | — | Encoded in `discountCodes[]` string value. |
+| code | string | 0..1 | `productFilter` | `discountCodes[]` | The discount/promotional code is passed directly. |
+
+---
+
+## TripPattern
+
+> Proposed sequence of legs. **No equivalent in BoB.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| tripPatternId | string | 0..1 | — | — | No equivalent. |
+| legs | Leg | 1..* | `productFilter` | `route { from, to }` | At most an origin–destination pair; no leg-level detail. |
+
+---
+
+## TimedLeg / ContinuousLeg / TransferLeg
+
+> All leg sub-types. **No equivalent in BoB.**
+
+| EUDIT concept | BoB concept | Notes |
+|---|---|---|
+| TimedLeg | — | No equivalent. `serviceJourneyRef`, `operatingDate`, `LegBoard`, `LegAlight` not supported. |
+| ContinuousLeg | — | No equivalent. |
+| TransferLeg | — | No equivalent. |
+
+---
+
+## LegBoard / LegAlight / TrainNumber / StopPlace
+
+> All stop/boarding concepts. **No equivalent in BoB.**
+
+| EUDIT concept | BoB concept | Notes |
+|---|---|---|
+| LegBoard | — | No equivalent. |
+| LegAlight | — | No equivalent. |
+| TrainNumber | — | No equivalent. |
+| StopPlace | — | No equivalent. |
+
+---
+
+## Place / StopPlaceInput / AddressInput / PointOfInterest / TopologicalPlace / GeoPosition
+
+> Place hierarchy.
+
+| EUDIT concept | BoB concept | BoB property | Notes |
+|---|---|---|---|
+| StopPlaceInput | `productFilter` | `route { from, to }` | Station codes (e.g. UIC) if supported. |
+| AddressInput | — | — | No equivalent. |
+| PointOfInterest | — | — | No equivalent. |
+| TopologicalPlace | `productFilter` | `area` | BoB `area` is a zone/area code, not a GeoJSON polygon. |
+| GeoPosition | — | — | No equivalent; BoB does not accept geo-coordinates in product search. |
+
+---
+
+## Offer
+
+> Purchasable combination of offer elements.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| offerId | string | 1..1 | `product` | `productId` | BoB returns `product` objects rather than `offer` objects. |
+| elements | OfferElement | 1..* | `product` | `fareIds[]`, `conditions[]` | No discrete offer-element hierarchy; product has fare IDs and conditions. |
+| farePrice | FarePrice | 0..1 | `product` | `price { amount, currency }` | |
+| travelDocument | TravelDocument | 0..1 | `product` | `mediaTypes[]` | BoB lists supported media types per product. |
+
+---
+
+## OfferElement / TravelRight / Ancillary / Reservation / CompositeOfferElement
+
+> Offer element sub-types.
+
+| EUDIT concept | BoB concept | BoB property | Notes |
+|---|---|---|---|
+| OfferElement | `fareProduct` | `fareId`, `name`, `conditions[]` | BoB fare products are the closest equivalent. |
+| TravelRight | `fareProduct` | — | Right to travel implicit in product conditions. |
+| Ancillary | `ancillaryProduct` | — | Some BoB implementations expose ancillary products. |
+| Reservation | — | — | Not modelled in BoB product search. |
+| CompositeOfferElement | `productBundle` | `products[]` | BoB supports product bundles in some implementations. |
+| FarePrice | `price` | `amount`, `currency` | |
+| TravelDocument | — | `mediaTypes[]` | Media type list at product level. |
+| Guarantee | — | — | No equivalent. |
diff --git a/deliverables/1 search offers/mappings/mapping-fgw.md b/deliverables/1 search offers/mappings/mapping-fgw.md
new file mode 100644
index 0000000..e3bdfd4
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-fgw.md
@@ -0,0 +1,294 @@
+# Mapping: Search Offers → FerryGateway 1.3.1
+
+Maps each EUDIT **Search Offers** concept to the corresponding concept/property in **FerryGateway 1.3.1**.
+
+- **EUDIT concept / Property** — as defined in `search-offers.yaml`
+- **FerryGateway concept** — the matching XML message / element in FerryGateway 1.3.1
+- **FerryGateway element** — the matching element/attribute name
+- **Notes** — mapping remarks, gaps, or open questions
+
+**Important scope note**: FerryGateway 1.3.1 uses XML request/response messages (not REST/JSON).
+There is no single "offer search" endpoint; the closest equivalent is a two-step flow:
+
+1. **`GetSailingsRequest`** → availability (timetable + availability per sailing)
+2. **`GetPriceRequest`** → pricing for selected sailings
+
+This mapping covers both messages where relevant. The response mapping covers
+`GetSailingsResponse` and `GetPriceResponse`.
+
+---
+
+## OfferRequest
+
+> Root request body for the offer search.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| tripPatterns | TripPattern | 1..* | `GetSailingsRequest` | `SailingDate`, `RouteCode` | FerryGateway selects sailings by route (UN/LOCODE port pair) and date, not by a NeTEx service journey reference. Multiple trip patterns (e.g. outbound + return) require separate `GetSailingsRequest` calls. |
+| travellers | TravellingEntity | 1..* | `GetSailingsRequest` / `GetPriceRequest` | `Passengers`, `Vehicles` | Human travellers → `Passengers`; vehicles → `Vehicles`. `Animal` and `Luggage` have no direct equivalent. |
+| filter | SearchOfferFilter | 0..1 | — | — | No filter equivalent in FerryGateway; all offer types for the sailing are returned. |
+| policy | SearchOfferPolicy | 0..1 | — | — | No pagination or currency control. |
+
+---
+
+## SearchOfferPolicy
+
+> Pagination and currency preferences. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| numberOfResultsBefore | integer | 0..1 | — | — | No equivalent. |
+| numberOfResultsAfter | integer | 0..1 | — | — | No equivalent. |
+| currency | string | 0..1 | — | — | Currency is operator configuration; not a request parameter. |
+
+---
+
+## SearchOfferFilter
+
+> Constraints on which offers to return. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| modes | string | 0..* | — | — | Ferry is the only mode; filter not applicable. |
+| classOfUse | string | 0..* | — | — | No equivalent; accommodation types returned from the sailing result. |
+| mediaTypes | string | 0..* | — | — | No equivalent. |
+| requestedSections | RequestedSections | 0..* | — | — | No equivalent. |
+
+---
+
+## RequestedSections
+
+> Targets offer search to a subset of legs. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## TravellingEntity
+
+> Base class.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | — | — | No per-entity identifier; passengers aggregated by category code. |
+| entityType | string | 1..1 | — | — | Discriminator only. `Animal` has no equivalent. |
+| entitlementRights | EntitlementRight | 0..* | `GetOfferCodesRequest` | `OfferCode` | Promotional/discount codes are fetched separately; see **EntitlementRight**. |
+
+---
+
+## Traveller
+
+> Human traveller.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | — | — | Not used; passengers aggregated by `CategoryCode`. |
+| age | integer | 0..1 | `Passenger` | `CategoryCode` | Age band encoded in category code (Adult, Child, Infant); age bounds from `GetPassengerAndVehicleTypesRequest`. |
+| assistant | boolean | 0..1 | — | — | No equivalent. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent. |
+| externalReference | string | 0..1 | — | — | No equivalent. |
+| personalNeeds | PersonalNeed | 0..* | — | — | No equivalent in FerryGateway offer search; wheelchair/accessibility needs handled at booking. |
+| qualifyingCharacteristics | TravellerQualifyingCharacteristics | 0..1 | — | — | No equivalent; eligibility encoded in category code. |
+
+---
+
+## TravellerQualifyingCharacteristics
+
+> Demographic eligibility data. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | Eligibility is abstracted into passenger category codes from `GetPassengerAndVehicleTypesRequest`. |
+
+---
+
+## PersonalNeed
+
+> Accessibility or personal need. **No equivalent in FerryGateway offer search.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. Accessibility needs provided at booking stage. |
+
+---
+
+## LicenseType
+
+> Driving licence. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## Animal
+
+> Animal travelling alongside its owner. **No equivalent in FerryGateway offer search.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | Pets may be handled at booking via service codes, not in offer search. |
+| type / assistant | various | 0..1 | — | — | No equivalent. |
+
+---
+
+## PassengerVehicle
+
+> Traveller-owned vehicle to be transported.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | `Vehicle` | — | Direct concept match; ferry bookings typically involve vehicle transport. |
+| type | string | 0..1 | `Vehicle` | `CategoryCode` | Vehicle category from `GetPassengerAndVehicleTypesRequest` (car, motorhome, caravan, motorbike, etc.). |
+| height | integer | 0..1 | `Vehicle` | `Height` | In centimetres (same unit). |
+| width | integer | 0..1 | `Vehicle` | `Width` | In centimetres. |
+| length | integer | 0..1 | `Vehicle` | `Length` | In centimetres. |
+| weight | integer | 0..1 | — | — | No weight field on FerryGateway vehicle; some operators handle via category. |
+| trailer | PassengerVehicle | 0..1 | `Vehicle` | `TrailerId` | FerryGateway has a `TrailerId` field for a towed trailer; full trailer dimensions not modelled. |
+| vehicleRacks | VehicleRack | 0..* | — | — | No equivalent. |
+
+---
+
+## VehicleRack
+
+> Rack mounted on a vehicle. **No equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## Luggage
+
+> Bulky item a traveller brings. **No equivalent in FerryGateway offer search.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | Not modelled in FerryGateway offer search. Bicycles and special luggage are handled via service codes at booking. |
+
+---
+
+## EntitlementRight
+
+> Credential qualifying for reduced fares.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| issuer | string | 0..1 | — | — | Not explicitly modelled; implicit in the offer code value. |
+| entitlementType | string | 1..1 | `GetOfferCodesRequest` | `OfferType` | FerryGateway has a dedicated `GetOfferCodesRequest` / `GetOfferCodesResponse` message flow to retrieve applicable promotional and loyalty codes. |
+| code | string | 0..1 | `GetPriceRequest` | `OfferCode` | The promotional or discount code passed to `GetPriceRequest`. |
+
+---
+
+## TripPattern
+
+> Proposed sequence of legs.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| tripPatternId | string | 0..1 | — | — | No equivalent. |
+| legs | Leg | 1..* | `GetSailingsRequest` | `RouteCode`, `SailingDate` | FerryGateway addresses a single sailing route per request, not a multi-leg trip pattern. Consecutive sailings require multiple calls. |
+
+---
+
+## TimedLeg
+
+> Leg on a fixed timetabled service.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| serviceJourneyRef | string | 0..1 | `Sailing` | `SailingId` | Returned in `GetSailingsResponse`; passed back in `GetPriceRequest`. |
+| operatingDate | date | 0..1 | `GetSailingsRequest` | `SailingDate` | |
+| lineNumber | string | 0..1 | `Sailing` | `RouteCode` | Route code (port pair) is the closest equivalent. |
+| brand | string | 0..1 | — | — | No equivalent. |
+| start (LegBoard) | LegBoard | 0..1 | `GetSailingsRequest` | `RouteCode` (origin port) | Origin port (UN/LOCODE) from `RouteCode`. |
+| end (LegAlight) | LegAlight | 0..1 | `GetSailingsRequest` | `RouteCode` (destination port) | Destination port from `RouteCode`. |
+| intermediateStops | StopPlace | 0..* | — | — | Not applicable to direct ferry sailings. |
+
+---
+
+## ContinuousLeg / TransferLeg
+
+> **No equivalent in FerryGateway.**
+
+| EUDIT concept | Notes |
+|---|---|
+| ContinuousLeg | Ferry sailings are timetabled; no continuous leg concept. |
+| TransferLeg | No equivalent. |
+
+---
+
+## LegBoard
+
+> Boarding event at the start of a timed leg.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `GetSailingsRequest` | `RouteCode` (origin part) | UN/LOCODE port code. |
+| plannedDepartureTime | dateTime | 1..1 | `Sailing` | `DepartureTime` | Returned in `GetSailingsResponse`. |
+| pickupLocation | string | 0..1 | — | — | No equivalent. |
+| trainNumbers | TrainNumber | 0..* | — | — | No equivalent. |
+
+---
+
+## LegAlight
+
+> Alighting event.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `GetSailingsRequest` | `RouteCode` (destination part) | UN/LOCODE port code. |
+| plannedArrivalTime | dateTime | 1..1 | `Sailing` | `ArrivalTime` | Returned in `GetSailingsResponse`. |
+| setDownLocation | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TrainNumber / StopPlace
+
+| EUDIT concept | FerryGateway concept | Notes |
+|---|---|---|
+| TrainNumber | — | No equivalent. |
+| StopPlace.stopPlaceRef | UN/LOCODE port code | Used in `RouteCode` (e.g. `NLRTM-GBHLL`). |
+
+---
+
+## Place / StopPlaceInput / AddressInput / PointOfInterest / TopologicalPlace / GeoPosition
+
+| EUDIT concept | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|
+| StopPlaceInput.placeRef | `GetSailingsRequest` | `RouteCode` (port part) | UN/LOCODE port identifier. |
+| AddressInput | — | — | No equivalent. |
+| PointOfInterest | — | — | No equivalent. |
+| TopologicalPlace | — | — | No equivalent. |
+| GeoPosition | — | — | No equivalent; FerryGateway uses port codes only. |
+
+---
+
+## Offer
+
+> Purchasable combination of offer elements.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| offerId | string | 1..1 | `GetPriceResponse` | `PriceId` / `QuoteId` | FerryGateway returns a price quote with a reference ID. |
+| elements | OfferElement | 1..* | `GetPriceResponse` | `PriceItems[]` | Price items per passenger/vehicle/service category. |
+| farePrice | FarePrice | 0..1 | `GetPriceResponse` | `TotalPrice { Amount, Currency }` | |
+| travelDocument | TravelDocument | 0..1 | — | — | Not returned at price-quote stage; QR/barcode issued at `ConfirmReservationResponse`. |
+
+---
+
+## OfferElement / TravelRight / Ancillary / Reservation
+
+| EUDIT concept | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|
+| TravelRight | `PriceItem` | `Sailing`, `CategoryCode`, `Amount` | Right to travel encoded in a price item per passenger/vehicle. |
+| Ancillary | `ServiceItem` | `ServiceCode`, `Amount` | Optional services (meals, pet transport, etc.) are `ServiceItem`s. |
+| Reservation | — | — | Reservations created via `CreateReservationRequest`, not at price-quote stage. |
+| CompositeOfferElement | — | — | No equivalent. |
+| FarePrice | `PriceItem` | `Amount`, `Currency` | |
+| TravelDocument | — | — | Issued at booking confirmation as a QR code / PDF. |
+| Guarantee | — | — | No equivalent. |
diff --git a/deliverables/1 search offers/mappings/mapping-omsa.md b/deliverables/1 search offers/mappings/mapping-omsa.md
new file mode 100644
index 0000000..2fea8e4
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-omsa.md
@@ -0,0 +1,327 @@
+# Mapping: Search Offers → OMSA 0.1.0
+
+Maps each EUDIT **Search Offers** concept to the corresponding concept/property in **OMSA 0.1.0**.
+
+- **Endpoint**: `POST /processes/search-offers/execute`
+- **EUDIT concept / Property** — as defined in `search-offers.yaml`
+- **OMSA concept** — the matching schema object in OMSA 0.1.0
+- **OMSA property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+OMSA follows the OGC API Processes pattern and is conceptually very close to TOMP-API 2.0.0
+(uses `/execute` instead of TOMP's `/execution`). Key differences are noted below.
+
+---
+
+## OfferRequest
+
+> Root request body for the offer search.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| tripPatterns | TripPattern | 1..* | `searchOfferInput` | `specification` (tripPattern or travelSpecification) | OMSA accepts either a structured `tripPattern` or an open `travelSpecification`. Multiple EUDIT `TripPattern`s have no direct equivalent. |
+| travellers | TravellingEntity | 1..* | `searchOfferInput` | `travellers[]` | `Animal`, `VehicleRack` sub-types have no equivalent. `PassengerVehicle` and `Luggage` map to `assets[]` (see below). |
+| filter | SearchOfferFilter | 0..1 | `searchOfferInput` | `travellerRequirements` (per traveller) | Applied per traveller, not as a global filter. `mediaTypes` and `requestedSections` have no equivalent. |
+| policy | SearchOfferPolicy | 0..1 | — | — | No equivalent. OMSA is synchronous with no pagination or currency control. |
+
+---
+
+## SearchOfferPolicy
+
+> Pagination and currency preferences. **No equivalent in OMSA.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| numberOfResultsBefore | integer | 0..1 | — | — | Not supported. |
+| numberOfResultsAfter | integer | 0..1 | — | — | Not supported. |
+| currency | string | 0..1 | — | — | Not supported at request level. |
+
+---
+
+## SearchOfferFilter
+
+> Constraints on which offers to return. Only partially covered in OMSA.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| modes | string | 0..* | `travellerRequirements` | `mode`, `subMode` | Per traveller in OMSA. |
+| classOfUse | string | 0..* | `travellerRequirements` | `class` | Per traveller. |
+| mediaTypes | string | 0..* | — | — | No equivalent. |
+| requestedSections | RequestedSections | 0..* | — | — | No equivalent. |
+
+---
+
+## RequestedSections
+
+> Targets offer search to a subset of legs. **No equivalent in OMSA.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| startLegId / endLegId / startPlace / endPlace / tripReference | various | 0..1 | — | — | No equivalent. |
+
+---
+
+## TravellingEntity
+
+> Base class.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `traveller` | `id` | |
+| entityType | string | 1..1 | — | — | Discriminator only. `PassengerVehicle` and `Luggage` map to `assets[]`; `Animal` has no equivalent. |
+| entitlementRights | EntitlementRight | 0..* | `card` / `entitlement` | (nested in traveller) | See **EntitlementRight**. |
+
+---
+
+## Traveller
+
+> Human traveller.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `traveller` | `id` | |
+| age | integer | 0..1 | `traveller` | `age` | |
+| assistant | boolean | 0..1 | — | — | No direct field; carer/PRM needs via `travellerRequirements.prmNeeds[]`. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent. |
+| externalReference | string | 0..1 | `traveller` | `customerReference` | |
+| personalNeeds | PersonalNeed | 0..* | `travellerRequirements` | `prmNeeds[]` | |
+| qualifyingCharacteristics | TravellerQualifyingCharacteristics | 0..1 | `userProfile` | (see section) | |
+
+---
+
+## TravellerQualifyingCharacteristics
+
+> Demographic eligibility data.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| fullName | string | 0..1 | `traveller` | `name` | |
+| nationality | string | 0..1 | — | — | No equivalent. |
+| residency | string | 0..1 | — | — | No equivalent. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent. |
+| licenseTypes | LicenseType | 0..* | — | — | No equivalent in OMSA offer-search input. |
+
+---
+
+## PersonalNeed
+
+> Accessibility or personal need.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | `travellerRequirements` | `prmNeeds[]` | Operator-defined PRM need codes. |
+
+---
+
+## LicenseType
+
+> Driving licence. **No equivalent in OMSA offer-search input.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## Animal
+
+> Animal travelling alongside its owner. **No equivalent in OMSA.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | No equivalent. |
+| type | string | 1..1 | — | — | No equivalent. |
+| assistant | boolean | 0..1 | `travellerRequirements` | `prmNeeds[]` | Assistance animal status may be expressed as a PRM need on the accompanying traveller. |
+
+---
+
+## PassengerVehicle
+
+> Traveller-owned vehicle to be transported. Maps to OMSA `assets[]`.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | `asset` | `type` | OMSA uses an `assets[]` array in the request for physical items to transport. |
+| type | string | 1..1 | `asset` | `category` | Vehicle category (car, bicycle, etc.). |
+| height | integer | 0..1 | `asset` | `height` | |
+| width | integer | 0..1 | `asset` | `width` | |
+| length | integer | 0..1 | `asset` | `length` | |
+| weight | integer | 0..1 | `asset` | `weight` | |
+| trailer | PassengerVehicle | 0..1 | — | — | Nested trailer not modelled in OMSA assets. May be a separate asset entry. |
+| vehicleRacks | VehicleRack | 0..* | — | — | No equivalent. |
+
+---
+
+## VehicleRack
+
+> Rack mounted on a vehicle. **No equivalent in OMSA.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## Luggage
+
+> Bulky item. Maps to OMSA `assets[]`.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | `asset` | `type` | |
+| type | string | 1..1 | `asset` | `category` | Luggage category (bicycle, pram, etc.). |
+| length / width / height / weight | integer | 0..1 | `asset` | `length` / `width` / `height` / `weight` | |
+
+---
+
+## EntitlementRight
+
+> Credential qualifying for reduced fares.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| issuer | string | 0..1 | `card` | — / `entitlement` | No explicit issuer field; may be embedded in type code. |
+| entitlementType | string | 1..1 | `card` | `type` / `entitlement` `type` | |
+| code | string | 0..1 | `card` | `id` / `entitlement` `id` | Card or voucher instance number. |
+
+---
+
+## TripPattern
+
+> Proposed sequence of legs.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| tripPatternId | string | 0..1 | — | — | No equivalent. |
+| legs | Leg | 1..* | `tripPattern` | `serviceJourneys[]` (timed) OR `travelSpecification` (open O&D) | Same pattern as TOMP-API. |
+
+---
+
+## TimedLeg
+
+> Leg on a fixed timetabled service.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | Discriminator only. |
+| legId | string | 0..1 | — | — | No equivalent. |
+| sequenceNumber | integer | 0..1 | — | — | Implied by array order. |
+| mode | string | 0..1 | `travellerRequirements` | `mode` | Per traveller. |
+| serviceJourneyRef | string | 0..1 | `ServiceJourneyReference` | `id` | |
+| operatingDate | date | 0..1 | `tripPattern` | `travelDate` | |
+| lineNumber | string | 0..1 | `ServiceJourneyReference` | `lineId` | |
+| brand | string | 0..1 | — | — | No equivalent. |
+| start | LegBoard | 0..1 | — | — | Stop-level boarding data not in OMSA `tripPattern`. |
+| end | LegAlight | 0..1 | — | — | No equivalent. |
+| intermediateStops | StopPlace | 0..* | — | — | No equivalent. |
+
+---
+
+## ContinuousLeg
+
+> Leg without timetabled stops. Partially covered.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| startTime | dateTime | 0..1 | `travelSpecification` | `startTime` | |
+| endTime | dateTime | 0..1 | `travelSpecification` | `endTime` | |
+| startLocation | Place | 0..1 | `travelSpecification` | `origin` (placeReference) | |
+| endLocation | Place | 0..1 | `travelSpecification` | `destination` (placeReference) | |
+
+---
+
+## TransferLeg
+
+> Transfer between services. **No equivalent in OMSA.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## LegBoard
+
+> Boarding event.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | |
+| plannedDepartureTime | dateTime | 1..1 | `tripPattern` | `travelDate` | Date only; no per-leg departure time. |
+| pickupLocation | string | 0..1 | — | — | No equivalent. |
+| trainNumbers | TrainNumber | 0..* | — | — | No equivalent. |
+
+---
+
+## LegAlight
+
+> Alighting event.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | |
+| plannedArrivalTime | dateTime | 1..1 | — | — | No per-leg arrival time in OMSA. |
+| setDownLocation | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TrainNumber
+
+> Commercial train number. **No equivalent in OMSA offer-search input.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| trainNumberId | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## StopPlace
+
+> Reference to an intermediate stop.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | |
+
+---
+
+## Place / StopPlaceInput / AddressInput / PointOfInterest / TopologicalPlace
+
+> Same mappings as TOMP-API; OMSA uses the same `placeReference { id?, coordinates?, name? }` pattern.
+
+| EUDIT concept | OMSA concept | OMSA property | Notes |
+|---|---|---|---|
+| StopPlaceInput.placeRef | `placeReference` | `id` | |
+| AddressInput.addressLine1 | `placeReference` | `name` | No structured address. |
+| PointOfInterest.name | `placeReference` | `name` | |
+| TopologicalPlace.area | `travellerRequirements` | `zones[]` | Zone IDs, not GeoJSON polygon. |
+| GeoPosition.longitude / latitude | `GeoCoordinate` | `lon` / `lat` | |
+
+---
+
+## Offer
+
+> Purchasable combination of offer elements.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| offerId | string | 1..1 | `offer` | `offerId` | |
+| elements | OfferElement | 1..* | `offer` | `legs[].pricing[]` | OMSA returns pricing per leg, similar to TOMP. |
+| farePrice | FarePrice | 0..1 | `offer` | aggregated from `legs[].pricing[]` | Client must aggregate. |
+| travelDocument | TravelDocument | 0..1 | — | — | Not returned at offer-search stage. |
+
+---
+
+## OfferElement / TravelRight / Ancillary / Reservation / CompositeOfferElement
+
+> Same pattern as TOMP-API: pricing is per-leg, no discrete offer-element objects in OMSA response.
+
+| EUDIT concept | OMSA concept | OMSA property | Notes |
+|---|---|---|---|
+| TravelRight | `leg` | `id`, `pricing[]` | Travel right implicit per leg. |
+| Ancillary | — | — | No equivalent in offer-search response. |
+| Reservation | — | — | Not at offer-search stage. |
+| CompositeOfferElement | — | — | No equivalent. |
+| FarePrice | `pricing` | `estimated`, `parts[{ amount, currencyCode }]` | |
+| TravelDocument | — | — | Not at offer-search stage. |
+| Guarantee | — | — | No equivalent. |
diff --git a/deliverables/1 search offers/mappings/mapping-osdm.md b/deliverables/1 search offers/mappings/mapping-osdm.md
new file mode 100644
index 0000000..b63cba5
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-osdm.md
@@ -0,0 +1,443 @@
+# Mapping: Search Offers → OSDM 3.7.1
+
+Maps each EUDIT **Search Offers** concept to the corresponding concept/property in **OSDM 3.7.1**.
+
+- **Endpoint**: `POST /offers`
+- **EUDIT concept / Property** — as defined in `search-offers.yaml`
+- **OSDM concept** — the matching schema object in OSDM 3.7.1
+- **OSDM property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+---
+
+## OfferRequest
+
+> Root request body for the offer search.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| tripPatterns | TripPattern | 1..* | `offerRequest` | `tripSpecification` / `tripIds[]` / `tripSearchCriteria` | OSDM supports three trip-input modes: (1) explicit `tripSpecification.legs[]`, (2) pre-searched `tripIds[]`, (3) open O&D `tripSearchCriteria`. EUDIT `TripPattern` maps to mode (1). Multiple trip patterns map to `inboundTripSpecification` for a return journey. |
+| travellers | TravellingEntity | 1..* | `offerRequest` | `tripCoverage.passengers[]` | Only `Traveller` sub-type maps; `Animal`, `PassengerVehicle`, `VehicleRack`, `Luggage` have no equivalent as passengers. |
+| filter | SearchOfferFilter | 0..1 | `offerRequest` | `searchCriteria` | |
+| policy | SearchOfferPolicy | 0..1 | `offerRequest` | `searchCriteria` (partial) | Partial; see **SearchOfferPolicy**. |
+
+---
+
+## SearchOfferPolicy
+
+> Pagination and currency preferences.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| numberOfResultsBefore | integer | 0..1 | — | — | No equivalent. OSDM does not support pagination relative to departure time. |
+| numberOfResultsAfter | integer | 0..1 | `searchCriteria` | `maxOffers` | Partial match: `maxOffers` limits total results, not results after a given time. |
+| currency | string | 0..1 | `searchCriteria` | `currency` | Direct mapping (ISO 4217). |
+
+---
+
+## SearchOfferFilter
+
+> Constraints on which offers to return.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| modes | string | 0..* | — | — | No explicit mode filter in OSDM offer request; modes are implicit in the trip specification. |
+| classOfUse | string | 0..* | `searchCriteria` | `fareClass` | OSDM `fareClass` (e.g. `FIRST`, `SECOND`). Single value in OSDM vs. array in EUDIT. |
+| mediaTypes | string | 0..* | — | — | No equivalent. OSDM does not filter by fulfilment media type at offer-search stage. |
+| requestedSections | RequestedSections | 0..* | — | — | No equivalent. |
+
+---
+
+## RequestedSections
+
+> Targets offer search to a subset of legs. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | — | — | No equivalent. |
+| endLegId | string | 0..1 | — | — | No equivalent. |
+| startPlace | string | 0..1 | — | — | No equivalent. |
+| endPlace | string | 0..1 | — | — | No equivalent. |
+| tripReference | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TravellingEntity
+
+> Base class.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `passenger` | `passengerRef` | Caller-assigned reference used for cross-referencing. |
+| entityType | string | 1..1 | — | — | Discriminator only. `Animal`, `PassengerVehicle`, `Luggage` not modelled as OSDM passengers. |
+| entitlementRights | EntitlementRight | 0..* | `passenger` | `reductionCards[]` | See **EntitlementRight**. |
+
+---
+
+## Traveller
+
+> Human traveller.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `passenger` | `passengerRef` | |
+| age | integer | 0..1 | `passenger` | `age` | |
+| assistant | boolean | 0..1 | — | — | No equivalent. Carer/assistant needs expressed via `accessibilityNeeds`. |
+| dateOfBirth | date | 0..1 | — | — | No date-of-birth field in OSDM passenger; age used instead. |
+| externalReference | string | 0..1 | — | — | No equivalent. |
+| personalNeeds | PersonalNeed | 0..* | `passenger` | `accessibilityNeeds[]` | |
+| qualifyingCharacteristics | TravellerQualifyingCharacteristics | 0..1 | `passenger` | `type` (partial) | OSDM uses a coarse passenger type enum (`ADULT`, `CHILD`, `INFANT`) rather than detailed characteristics. |
+
+---
+
+## TravellerQualifyingCharacteristics
+
+> Demographic eligibility data.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| fullName | string | 0..1 | — | — | Not a fare-search input in OSDM; provided at booking stage. |
+| nationality | string | 0..1 | — | — | No equivalent in OSDM offer request. |
+| residency | string | 0..1 | — | — | No equivalent. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent. |
+| licenseTypes | LicenseType | 0..* | — | — | No equivalent. |
+
+---
+
+## PersonalNeed
+
+> Accessibility or personal need.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | `passenger` | `accessibilityNeeds[]` | OSDM uses NeTEx `AccessibilityNeedType` values. |
+
+---
+
+## LicenseType
+
+> Driving licence. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## Animal
+
+> Animal travelling alongside its owner. **No equivalent as a passenger in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | Pets may appear as ancillary offer parts in OSDM response but are not modelled as input passengers. |
+| type | string | 1..1 | — | — | No equivalent. |
+| assistant | boolean | 0..1 | `passenger` | `accessibilityNeeds[]` | Assistance animal may be expressed as an accessibility need on the accompanying traveller. |
+
+---
+
+## PassengerVehicle
+
+> Traveller-owned vehicle to be transported. **No equivalent in OSDM (rail-focused standard).**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | Vehicle transport (car/ferry) is outside OSDM scope. |
+| type / height / width / length / weight | various | 0..1 | — | — | No equivalent. |
+| trailer | PassengerVehicle | 0..1 | — | — | No equivalent. |
+| vehicleRacks | VehicleRack | 0..* | — | — | No equivalent. |
+
+---
+
+## VehicleRack
+
+> Rack on a passenger vehicle. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| (all) | — | — | — | — | No equivalent. |
+
+---
+
+## Luggage
+
+> Bulky item a traveller brings.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | Luggage is not an input entity in OSDM; it may appear as an ancillary in the offer response. |
+| type / dimensions / weight | various | 0..1 | — | — | No equivalent as offer-request input. |
+
+---
+
+## EntitlementRight
+
+> Credential qualifying for reduced fares.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| issuer | string | 0..1 | `reductionCard` | `issuerCode` | |
+| entitlementType | string | 1..1 | `reductionCard` | `cardType` | OSDM uses a structured `cardType` enum (e.g. `BAHNCARD`, `RAILPLUS`). |
+| code | string | 0..1 | — | — | Card instance number not standard in OSDM reduction card; may be passed as `passengerRef` extension. |
+
+---
+
+## TripPattern
+
+> Proposed sequence of legs.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| tripPatternId | string | 0..1 | — | — | No equivalent. |
+| legs | Leg | 1..* | `tripSpecification` | `legs[]` | Each EUDIT `TimedLeg` maps to an OSDM leg. `ContinuousLeg` and `TransferLeg` have no equivalent. |
+
+---
+
+## TimedLeg
+
+> Leg on a fixed timetabled service.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | Discriminator only. |
+| legId | string | 0..1 | — | — | No equivalent. |
+| sequenceNumber | integer | 0..1 | — | — | Implied by array order in `tripSpecification.legs[]`. |
+| mode | string | 0..1 | — | — | No explicit mode field on OSDM leg; implicit in `serviceJourneyRef`. |
+| serviceJourneyRef | string | 0..1 | `leg` | `serviceJourneyRef` | Direct mapping. |
+| operatingDate | date | 0..1 | `leg` | `departureDateTime` (date part) | OSDM uses a full `departureDateTime`; date extracted from it. |
+| lineNumber | string | 0..1 | — | — | No equivalent on OSDM leg input. |
+| brand | string | 0..1 | — | — | No equivalent. |
+| start | LegBoard | 0..1 | `leg` | `originStopPlaceRef`, `departureDateTime` | |
+| end | LegAlight | 0..1 | `leg` | `destinationStopPlaceRef`, `arrivalDateTime` | |
+| intermediateStops | StopPlace | 0..* | — | — | Not an input field in OSDM. |
+
+---
+
+## ContinuousLeg
+
+> Leg without fixed timetabled stops. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | No equivalent. OSDM is timetabled-service only. |
+| startTime / endTime | dateTime | 0..1 | — | — | No equivalent. |
+| startLocation / endLocation | Place | 0..1 | — | — | No equivalent. |
+
+---
+
+## TransferLeg
+
+> Transfer between services. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | No equivalent. Transfers are implicit in the leg sequence. |
+
+---
+
+## LegBoard
+
+> Boarding event at the start of a timed leg.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `leg` | `originStopPlaceRef` | UIC or NeTEx stop ID. |
+| plannedDepartureTime | dateTime | 1..1 | `leg` | `departureDateTime` | |
+| pickupLocation | string | 0..1 | — | — | No equivalent. |
+| trainNumbers | TrainNumber | 0..* | — | — | Not an input field in OSDM. |
+
+---
+
+## LegAlight
+
+> Alighting event at the end of a timed leg.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `leg` | `destinationStopPlaceRef` | |
+| plannedArrivalTime | dateTime | 1..1 | `leg` | `arrivalDateTime` | |
+| setDownLocation | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TrainNumber
+
+> Commercial train number.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| trainNumberId | string | 1..1 | — | — | Partially encoded in `serviceJourneyRef`; no separate train-number input in OSDM. |
+
+---
+
+## StopPlace
+
+> Reference to an intermediate stop.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | — | — | Intermediate stops are not input in OSDM; derived from `serviceJourneyRef`. |
+
+---
+
+## Place
+
+> Base place type.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| placeId | string | 0..1 | — | — | No equivalent. |
+| placeType | string | 1..1 | — | — | Discriminator only. |
+| location | GeoPosition | 0..1 | — | — | OSDM uses stop references only; geo-coordinate input is not supported. |
+
+---
+
+## StopPlaceInput
+
+> Stop place identified by reference.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| placeRef | string | 0..1 | `leg` | `originStopPlaceRef` / `destinationStopPlaceRef` | UIC or NeTEx stop ID. |
+
+---
+
+## AddressInput
+
+> Postal address. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| addressLine1 / addressLine2 | string | 0..1 | — | — | OSDM does not support address-based place input. |
+
+---
+
+## PointOfInterest
+
+> Named point of interest. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| name | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TopologicalPlace
+
+> Geographic area or zone.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| area | string | 0..1 | — | — | No equivalent as trip origin/destination input. |
+| range | integer | 0..1 | — | — | No equivalent. |
+
+---
+
+## GeoPosition
+
+> WGS-84 coordinate pair. **No equivalent in OSDM offer-request input.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| longitude | number | 1..1 | — | — | OSDM uses stop-reference IDs only. |
+| latitude | number | 1..1 | — | — | No equivalent. |
+
+---
+
+## Offer
+
+> Purchasable combination of offer elements.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerId | string | 1..1 | `offer` | `offerId` | Direct mapping. |
+| elements | OfferElement | 1..* | `offer` | `fareProducts[]`, `reservations[]`, `ancillaryProducts[]` | Sub-types map to different OSDM arrays. |
+| farePrice | FarePrice | 0..1 | `offer` | `totalPrice { amount, currency }` | |
+| travelDocument | TravelDocument | 0..1 | `offer` | `fulfillmentOptions[]` | OSDM returns fulfilment options (media/barcode type) at offer stage. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `fareProduct` | `fareProductId` | Or `reservationId` for reservation elements. |
+| offerElementType | string | 1..1 | — | — | Discriminator only. |
+| travellingEntities | string | 0..* | `fareProduct` | `passengerRef` | OSDM links fare products to specific passengers. |
+| farePrice | FarePrice | 0..1 | `fareProduct` | `price { amount, currency }` | |
+| travelDocument | TravelDocument | 0..1 | — | — | Fulfilment detail at offer level, not per element. |
+| guarantees | Guarantee | 0..* | — | — | No direct equivalent; connection guarantee is a separate concept in OSDM. |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific leg or zone.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| legRef | string | 0..1 | `fareProduct` | `legRef` / `serviceJourneyRef` | OSDM fare products reference the legs they cover. |
+| zoneRef | string | 0..1 | `fareProduct` | `tariffZoneRef` | Zone-based fares in OSDM reference tariff zones. |
+
+---
+
+## Ancillary
+
+> Optional ancillary service.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | `ancillaryProduct` | `ancillaryProductId` | |
+| type | string | 0..1 | `ancillaryProduct` | `type` | |
+
+---
+
+## Reservation
+
+> Seat or space reservation.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerElementType | string | 1..1 | `reservation` | — | OSDM has a discrete `reservation` object with `reservationId`, `seatInformation`. |
+
+---
+
+## CompositeOfferElement
+
+> Grouped offer elements. Partial equivalent in OSDM via offer parts.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| elements | OfferElement | 2..* | `offerPart` | `fareProducts[]` | OSDM groups fare products into offer parts; no explicit "composite" type. |
+
+---
+
+## FarePrice
+
+> Price of an offer or offer element. (Stub — detail TBD.)
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | `price` | `amount`, `currency` | OSDM `price` object carries amount + ISO 4217 currency code. |
+
+---
+
+## TravelDocument
+
+> Proof of entitlement. (Stub — detail TBD.)
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | `fulfillmentOption` | `mediaType`, `barcodeType` | OSDM returns available fulfilment options (paper, mobile, smart card) per offer. |
+
+---
+
+## Guarantee
+
+> Guarantee associated with an offer element. (Stub — detail TBD.)
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | — | — | No direct equivalent. Connection guarantee is a separate concept in OSDM trip search, not offer search. |
diff --git a/deliverables/1 search offers/mappings/mapping-tm.md b/deliverables/1 search offers/mappings/mapping-tm.md
new file mode 100644
index 0000000..7e7f141
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-tm.md
@@ -0,0 +1,371 @@
+# Mapping: Search Offers → Transmodel v6.2
+
+This file maps each EUDIT **Search Offers** concept to the **Transmodel v6.2** concept(s) it realises.
+Unlike the other mapping files, this is not a standard-to-standard API mapping but a conceptual anchor:
+it shows which Transmodel concepts underpin each EUDIT schema.
+
+- **EUDIT concept** — as defined in `search-offers.yaml`
+- **Transmodel concept** — the TM v6.2 concept(s) realised
+- **TM package** — the Transmodel part / package
+- **Notes** — alignment remarks
+
+---
+
+## Request-side concepts
+
+### OfferRequest
+
+| EUDIT concept | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| OfferRequest | FARE REQUEST | Part 6 — Fare management | Root request for fare calculation; TM FARE REQUEST aggregates the trip context and passenger data. |
+
+---
+
+### SearchOfferPolicy
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| numberOfResultsBefore / numberOfResultsAfter | AVAILABILITY CONDITION | Part 1 — Framework | Bounds the time window in which results are sought. |
+| currency | CURRENCY | Part 6 | ISO 4217 currency for price expression; TM uses CURRENCY TYPE. |
+
+---
+
+### SearchOfferFilter
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| modes | TRANSPORT MODE | Part 1 | TM TRANSPORT MODE (rail, bus, ferry, etc.). |
+| classOfUse | FARE CLASS | Part 6 | TM FARE CLASS (first, second, premium). |
+| mediaTypes | TRAVEL DOCUMENT TYPE | Part 6 | TM TRAVEL DOCUMENT TYPE categorises fulfilment media (paper, mobile, smart card). |
+| requestedSections | SECTION | Part 2 — Public transport network topology | TM SECTION — a part of a route between two points. |
+
+---
+
+### RequestedSections
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| startLegId / endLegId | SECTION | Part 2 | Bounds of the requested section identified by leg references. |
+| startPlace / endPlace | SCHEDULED STOP POINT / PLACE | Part 2 / Part 1 | Origin and destination of the requested section. |
+| tripReference | TRIP | Part 3 — Timing information | The specific trip this section belongs to. |
+
+---
+
+### TravellingEntity
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| travellingEntityId | TRAVELLING ENTITY | Part 6 | TM TRAVELLING ENTITY — the root class for all participants in a journey (TM v6.2 §6.4). |
+| entityType | (discriminator) | — | Implemented as a discriminator over TM sub-types. |
+| entitlementRights | ENTITLEMENT PRODUCT | Part 6 | TM ENTITLEMENT PRODUCT — a product that gives the holder rights to a discount or access condition. |
+
+---
+
+### Traveller
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Traveller (class) | TRANSPORT CUSTOMER | Part 6 | TM TRANSPORT CUSTOMER — an individual (or group) purchasing or using transport services. |
+| age | USER PROFILE | Part 6 | Age is a qualifying attribute of USER PROFILE. |
+| assistant | ASSISTANCE NEED | Part 1 | Whether this person acts as an assistant for another. |
+| dateOfBirth | USER PROFILE | Part 6 | Date of birth is a qualifying attribute used for age-band fare calculation. |
+| externalReference | CUSTOMER ACCOUNT | Part 6 | External identifier linking to the customer's account in the origin system. |
+| personalNeeds | ACCESSIBILITY NEED | Part 1 | TM ACCESSIBILITY NEED — a specific accessibility requirement of a person. |
+| qualifyingCharacteristics | USER PROFILE | Part 6 | See TravellerQualifyingCharacteristics below. |
+
+---
+
+### TravellerQualifyingCharacteristics
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TravellerQualifyingCharacteristics (class) | USER PROFILE | Part 6 | TM USER PROFILE — a demographic / eligibility profile used for fare qualification (§6.4.3). |
+| fullName | PASSENGER | Part 1 | Personal identity attribute. |
+| nationality | USER PROFILE | Part 6 | Nationality as a qualifying attribute. |
+| residency | USER PROFILE | Part 6 | Country of residence as a qualifying attribute. |
+| dateOfBirth | USER PROFILE | Part 6 | Date of birth qualifying attribute. |
+| licenseTypes | LICENSE TYPE | Part 6 | Driving licence categories held by the traveller. |
+
+---
+
+### PersonalNeed
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| type | ACCESSIBILITY NEED | Part 1 | TM ACCESSIBILITY NEED TYPE — enumerated accessibility requirement (wheelchair, visual impairment, etc.). |
+
+---
+
+### LicenseType
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| type | LICENSE TYPE | Part 6 | EU driving licence category (AM, A1, B, C, D, etc.). |
+
+---
+
+### Animal
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Animal (class) | TRAVELLING ENTITY | Part 6 | TM TRAVELLING ENTITY sub-type for non-human participants. |
+| type | ANIMAL TYPE | Part 6 | Category of animal (dog, cat, other). |
+| assistant | ASSISTANCE ANIMAL | Part 1 | Whether the animal is a registered assistance/guide animal. |
+
+---
+
+### PassengerVehicle
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| PassengerVehicle (class) | VEHICLE | Part 1 / Part 6 | TM VEHICLE (traveller-owned); distinct from operator-owned VEHICLE used in scheduling. |
+| type | VEHICLE TYPE | Part 1 | Category of vehicle (car, motorhome, bicycle, etc.). |
+| height / width / length / weight | VEHICLE TYPE | Part 1 | Physical dimensions that may restrict loading capacity. |
+| trailer | VEHICLE | Part 1 | Towed trailer modelled as a nested VEHICLE. |
+| vehicleRacks | EQUIPMENT | Part 1 | Mounted equipment items (TM INSTALLED EQUIPMENT / PLACE EQUIPMENT). |
+
+---
+
+### VehicleRack
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| VehicleRack (class) | EQUIPMENT | Part 1 | TM INSTALLED EQUIPMENT — an item fitted to a vehicle. |
+| type / mounting | EQUIPMENT TYPE | Part 1 | Category and attachment method. |
+| height / width / length / weight | EQUIPMENT | Part 1 | Physical dimensions of the rack with load. |
+
+---
+
+### Luggage
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Luggage (class) | TRAVELLING ENTITY | Part 6 | TM TRAVELLING ENTITY sub-type for transported items. |
+| type | LUGGAGE TYPE | Part 6 | Category of item (bicycle, pram, wheelchair, skis, etc.). |
+| length / width / height / weight | LUGGAGE ALLOWANCE | Part 6 | TM LUGGAGE ALLOWANCE defines dimension/weight constraints on transported items. |
+
+---
+
+### EntitlementRight
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| EntitlementRight (class) | ENTITLEMENT PRODUCT | Part 6 | TM ENTITLEMENT PRODUCT — a credential (card, concession, voucher) conferring access or discount rights (§6.5.4). |
+| issuer | RESPONSIBILITY SET | Part 1 | The organisation issuing the entitlement. |
+| entitlementType | ENTITLEMENT PRODUCT TYPE | Part 6 | Classifies the entitlement (loyalty card, discount card, concession, etc.). |
+| code | CUSTOMER ENTITLEMENT | Part 6 | The instance identifier linking a specific TRANSPORT CUSTOMER to the ENTITLEMENT PRODUCT. |
+
+---
+
+## Trip-context concepts
+
+### TripPattern
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TripPattern (class) | TRIP PATTERN | Part 3 | TM TRIP PATTERN — a planned sequence of legs a passenger intends to travel (§3.5). |
+| tripPatternId | TRIP PATTERN | Part 3 | Caller-assigned identifier for the pattern. |
+| legs | LEG | Part 3 | Each leg in the TRIP PATTERN. |
+
+---
+
+### Trip
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Trip (class) | TRIP | Part 3 | TM TRIP — a specific realisation of a TRIP PATTERN on fixed departures. |
+| tripId | TRIP | Part 3 | |
+| legs | LEG | Part 3 | |
+
+---
+
+### Leg (base)
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Leg (class) | LEG | Part 3 | TM LEG — a single element of a TRIP PATTERN between two consecutive points (§3.5.2). |
+| legId | LEG | Part 3 | |
+| sequenceNumber | LEG | Part 3 | Ordering within the TRIP PATTERN. |
+| mode | TRANSPORT MODE | Part 1 | TM TRANSPORT MODE associated with the leg. |
+| legType | (discriminator) | — | |
+
+---
+
+### TimedLeg
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TimedLeg (class) | SERVICE JOURNEY (LEG) | Part 3 | TM LEG realised by a SERVICE JOURNEY (timetabled). |
+| serviceJourneyRef | SERVICE JOURNEY | Part 3 | Reference to TM SERVICE JOURNEY — a passenger-carrying journey on a specific day. |
+| operatingDate | OPERATING DAY | Part 3 | TM OPERATING DAY on which the SERVICE JOURNEY runs. |
+| lineNumber | LINE | Part 2 | Commercial LINE associated with the SERVICE JOURNEY. |
+| brand | BRANDING | Part 1 | TM BRANDING — a commercial identity applied to a service. |
+| start | CALL (boarding) | Part 3 | TM CALL at the boarding stop; specifically the departure CALL. |
+| end | CALL (alighting) | Part 3 | TM CALL at the alighting stop; specifically the arrival CALL. |
+| intermediateStops | CALL | Part 3 | Intermediate TM CALLs passed but not boarded/alighted. |
+
+---
+
+### ContinuousLeg
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| ContinuousLeg (class) | CONTINUOUS LEG | Part 3 | TM CONTINUOUS LEG — a leg without fixed timetabled stops (walk, cycle, taxi). |
+| startTime / endTime | CONTINUOUS LEG | Part 3 | Planned start/end time. |
+| startLocation / endLocation | PLACE | Part 1 | TM PLACE — origin/destination of the continuous leg. |
+
+---
+
+### TransferLeg
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TransferLeg (class) | INTERCHANGE LEG | Part 3 | TM INTERCHANGE (or CONNECTION) — a leg representing a transfer between services. |
+
+---
+
+### LegBoard
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LegBoard (class) | CALL (departure) | Part 3 | TM CALL — the event of a vehicle stopping at a SCHEDULED STOP POINT, specifically the departure event. |
+| stopPlaceRef | STOP PLACE / SCHEDULED STOP POINT | Part 2 | NeTEx reference to TM SCHEDULED STOP POINT. |
+| plannedDepartureTime | CALL | Part 3 | Planned departure time at the boarding CALL. |
+| pickupLocation | QUAY / BOARDING POSITION | Part 2 | Specific platform or bay within the STOP PLACE. |
+| trainNumbers | TRAIN NUMBER | Part 3 | TM TRAIN NUMBER — commercial number identifying a train service. |
+
+---
+
+### LegAlight
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LegAlight (class) | CALL (arrival) | Part 3 | TM CALL at the alighting stop, specifically the arrival event. |
+| stopPlaceRef | STOP PLACE / SCHEDULED STOP POINT | Part 2 | NeTEx reference to TM SCHEDULED STOP POINT. |
+| plannedArrivalTime | CALL | Part 3 | Planned arrival time at the alighting CALL. |
+| setDownLocation | QUAY / BOARDING POSITION | Part 2 | Specific platform or bay within the STOP PLACE. |
+
+---
+
+### TrainNumber
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| trainNumberId | TRAIN NUMBER | Part 3 | TM TRAIN NUMBER — commercial service number (e.g. ICE 123). |
+
+---
+
+### StopPlace
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| stopPlaceRef | STOP PLACE | Part 2 | TM STOP PLACE — a place where passengers board or alight. |
+
+---
+
+### Place hierarchy
+
+| EUDIT concept | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Place | PLACE | Part 1 | TM PLACE — the root location concept. |
+| StopPlaceInput | STOP PLACE / SCHEDULED STOP POINT | Part 2 | Identified by a NeTEx stop reference. |
+| AddressInput | ADDRESS | Part 1 | TM ADDRESS — a postal address as a place. |
+| PointOfInterest | POINT OF INTEREST | Part 1 | TM POINT OF INTEREST — a named place with no structural role in the network. |
+| TopologicalPlace | TOPOGRAPHIC PLACE | Part 1 | TM TOPOGRAPHIC PLACE — a geographic area (municipality, region, zone). |
+| GeoPosition | LOCATION | Part 1 | TM LOCATION — a geodetic position (WGS-84 latitude/longitude). |
+
+---
+
+## Response-side concepts
+
+### Offer
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Offer (class) | SALES OFFER PACKAGE | Part 6 | TM SALES OFFER PACKAGE — a combination of FARE PRODUCTs available for purchase (§6.5.2). |
+| offerId | SALES OFFER PACKAGE | Part 6 | Server-assigned identifier for the offer. |
+| elements | SALES OFFER PACKAGE ELEMENT | Part 6 | Components of the SALES OFFER PACKAGE. |
+| farePrice | FARE PRICE | Part 6 | TM FARE PRICE — the monetary value assigned to a fare element. |
+| travelDocument | TRAVEL DOCUMENT | Part 6 | TM TRAVEL DOCUMENT — the document issued as proof of entitlement. |
+
+---
+
+### OfferElement
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| OfferElement (class) | SALES OFFER PACKAGE ELEMENT | Part 6 | TM SALES OFFER PACKAGE ELEMENT — a component within a SALES OFFER PACKAGE. |
+| offerElementId | SALES OFFER PACKAGE ELEMENT | Part 6 | |
+| travellingEntities | TRAVELLING ENTITY | Part 6 | The entities to whom this element applies. |
+| farePrice | FARE PRICE | Part 6 | |
+| travelDocument | TRAVEL DOCUMENT | Part 6 | |
+| guarantees | GUARANTEE | Part 6 | TM GUARANTEE — a commitment associated with an offer element (connection guarantee, seat guarantee). |
+
+---
+
+### TravelRight
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TravelRight (class) | ACCESS RIGHT ASSIGNMENT | Part 6 | TM ACCESS RIGHT ASSIGNMENT — assigns a right to travel to a specific passenger on a specific leg or zone (§6.5.3). |
+| legRef | SERVICE JOURNEY | Part 3 | The specific leg to which the travel right applies. |
+| zoneRef | TARIFF ZONE | Part 6 | TM TARIFF ZONE — the zone scope of a zone-based travel right. |
+
+---
+
+### Ancillary
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Ancillary (class) | SUPPLEMENTARY PRODUCT | Part 6 | TM SUPPLEMENTARY PRODUCT — an optional add-on service (seat selection, meal, bicycle transport). |
+| ancillaryId | SUPPLEMENTARY PRODUCT | Part 6 | |
+| type | SUPPLEMENTARY PRODUCT TYPE | Part 6 | Category of ancillary service. |
+
+---
+
+### Reservation
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Reservation (class) | SEAT RESERVATION | Part 6 | TM SEAT RESERVATION — a reserved space on a specific service. |
+
+---
+
+### CompositeOfferElement
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| CompositeOfferElement (class) | SALES OFFER PACKAGE | Part 6 | A nested SALES OFFER PACKAGE grouping two or more SALES OFFER PACKAGE ELEMENTs sold as a unit. |
+| elements | SALES OFFER PACKAGE ELEMENT | Part 6 | |
+
+---
+
+### FarePrice
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| FarePrice (class) | FARE PRICE | Part 6 | TM FARE PRICE — monetary value of a fare or fare element (§6.4.5). Detail TBD. |
+
+---
+
+### FareProduct
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| FareProduct (class) | FARE PRODUCT | Part 6 | TM FARE PRODUCT — an immutable element in a fare structure representing a type of access right (§6.5.1). Detail TBD. |
+
+---
+
+### TravelDocument
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TravelDocument (class) | TRAVEL DOCUMENT | Part 6 | TM TRAVEL DOCUMENT — the issued proof of entitlement (ticket, barcode, smart card record) (§6.6.1). Detail TBD. |
+
+---
+
+### Guarantee
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Guarantee (class) | GUARANTEE | Part 6 | TM GUARANTEE — a contractual commitment associated with an offer element. Detail TBD. |
diff --git a/deliverables/1 search offers/mappings/mapping-tomp.md b/deliverables/1 search offers/mappings/mapping-tomp.md
new file mode 100644
index 0000000..d6a755c
--- /dev/null
+++ b/deliverables/1 search offers/mappings/mapping-tomp.md
@@ -0,0 +1,450 @@
+# Mapping: Search Offers → TOMP-API 2.0.0
+
+Maps each EUDIT **Search Offers** concept to the corresponding concept/property in **TOMP-API 2.0.0**.
+
+- **Endpoint**: `POST /processes/search-offers/execution`
+- **EUDIT concept / Property** — as defined in `search-offers.yaml`
+- **TOMP concept** — the matching schema object in TOMP-API
+- **TOMP property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+---
+
+## OfferRequest
+
+> Root request body for the offer search.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| tripPatterns | TripPattern | 1..* | `searchOfferRequest` | `tripPattern` | TOMP accepts either a fixed `tripPattern` (timetabled journeys) or an open-ended `travelSpecification` (O&D + time window). Multiple EUDIT `TripPattern`s have no direct equivalent; TOMP supports one `tripPattern` or one `travelSpecification` per request. |
+| travellers | TravellingEntity | 1..* | `searchOfferRequest` | `travellers[]` | Traveller sub-types map differently; see individual sections below. `Animal`, `PassengerVehicle`, `VehicleRack`, `Luggage` have no equivalent in TOMP offer search. |
+| filter | SearchOfferFilter | 0..1 | `searchOfferRequest` | `travellerRequirements` (per traveller) | TOMP applies mode/class/operator preferences per traveller, not as a global filter. `mediaTypes` and `requestedSections` have no equivalent. Optionally, `accessType` can be used, but is not preferred |
+| policy | SearchOfferPolicy | 0..1 | — | — | No equivalent. |
+
+---
+
+## SearchOfferPolicy
+
+> Pagination and currency preferences. **No equivalent in TOMP-API.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| numberOfResultsBefore | integer | 0..1 | — | — | Not supported. TOMP returns results with pagination control. |
+| numberOfResultsAfter | integer | 0..1 | — | — | Not supported. TOMP returns results with pagination control. |
+| currency | string | 0..1 | — | — | Not supported at request level; currency is part of operator configuration. |
+
+---
+
+## SearchOfferFilter
+
+> Constraints on which offers to return. Only partially covered in TOMP.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| modes | string | 0..* | `travellerRequirements` | `mode`, `subMode` | Applied per traveller in TOMP, not as a global filter. |
+| classOfUse | string | 0..* | `travellerRequirements` | `class` | Maps to TOMP `class` (e.g. `FIRST`, `SECOND`). Per traveller. |
+| mediaTypes | string | 0..* | — | — | No equivalent. TOMP does not filter by fulfilment media type at offer-search stage. Optionally, `accessType` can be used, but is not preferred |
+| requestedSections | RequestedSections | 0..* | — | — | No equivalent. TOMP does not support section-level offer targeting. |
+
+---
+
+## RequestedSections
+
+> Targets offer search to a subset of legs. **No equivalent in TOMP-API.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | — | — | No equivalent. |
+| endLegId | string | 0..1 | — | — | No equivalent. |
+| startPlace | string | 0..1 | — | — | No equivalent. |
+| endPlace | string | 0..1 | — | — | No equivalent. |
+| tripReference | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TravellingEntity
+
+> Base class; concrete sub-types mapped below.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `traveller` | `id` | Used as correlation identifier. |
+| entityType | string | 1..1 | — | — | Discriminator only; no TOMP equivalent. `Animal`, `PassengerVehicle`, `Luggage` sub-types have no TOMP equivalent in offer search. |
+| entitlementRights | EntitlementRight | 0..* | `card` / `entitlement` | (nested in traveller) | See **EntitlementRight** section. |
+
+---
+
+## Traveller
+
+> Human traveller.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityId | string | 1..1 | `traveller` | `id` | |
+| age | integer | 0..1 | `traveller` | `age` | Direct mapping. |
+| assistant | boolean | 0..1 | — | — | No equivalent. TOMP PRM needs expressed via `travellerRequirements.prmNeeds[]`. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent in TOMP traveller object. Age-band eligibility via `userProfile.minimumAge` / `maximumAge`. |
+| externalReference | string | 0..1 | `traveller` | `customerReference` | |
+| personalNeeds | PersonalNeed | 0..* | `travellerRequirements` | `prmNeeds[]` | TOMP uses operator-defined PRM need codes. |
+| qualifyingCharacteristics | TravellerQualifyingCharacteristics | 0..1 | `userProfile` | (see section) | |
+
+---
+
+## TravellerQualifyingCharacteristics
+
+> Demographic eligibility data.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| fullName | string | 0..1 | `traveller` | `name` | TOMP has a top-level `name` field on traveller. |
+| nationality | string | 0..1 | — | — | No equivalent in TOMP. |
+| residency | string | 0..1 | — | — | No equivalent in TOMP. |
+| dateOfBirth | date | 0..1 | — | — | No equivalent in TOMP. |
+| licenseTypes | LicenseType | 0..* | `travellerCharacteristics` | `licenseTypes` | Driver licence held by traveller. TOMP exposes licence types via `GET /collections/license-types/items` and has a licenseTypes property in the travellersCharachteristics. |
+
+---
+
+## PersonalNeed
+
+> Accessibility or personal need.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | `travellerRequirements` | `prmNeeds[]` | TOMP uses operator-defined PRM need codes (e.g. `WHEELCHAIR`, `VISUAL_IMPAIRMENT`). |
+
+---
+
+## LicenseType
+
+> Driving licence held by a traveller. **No equivalent in TOMP offer-search input.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| type | string | 1..1 | `travellerCharacteristics` | `licenseTypes` | |
+
+---
+
+## Animal
+
+> Animal travelling alongside its owner. **No equivalent in TOMP offer-search input.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | TOMP does not model pet transport in the offer-search request. |
+| type | string | 1..1 | — | — | No equivalent. |
+| assistant | boolean | 0..1 | `travellerRequirements` | `prmNeeds[]` | Assistance animal status may be expressed as a PRM need on the accompanying traveller. |
+
+---
+
+## PassengerVehicle
+
+> Traveller-owned vehicle to be transported.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | `travellerCharacteristics` | `assets` | A traveller can bring along a vehicle |
+| type | string | 1..1 | — | — | No equivalent. |
+| height / width / length / weight | integer | 0..1 | — | — | No equivalent. |
+| trailer | PassengerVehicle | 0..1 | — | — | No equivalent. |
+| vehicleRacks | VehicleRack | 0..* | — | — | No equivalent. |
+
+---
+
+## VehicleRack
+
+> Rack mounted on a passenger vehicle. **No equivalent in TOMP-API.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| type | string | 0..1 | — | — | No equivalent. |
+| mounting | string | 0..1 | — | — | No equivalent. |
+| height / width / length / weight | integer | 0..1 | — | — | No equivalent. |
+
+---
+
+## Luggage
+
+> Bulky item a traveller brings. **No equivalent in TOMP offer-search input.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| entityType | string | 1..1 | — | — | No equivalent. TOMP shared-mobility asset catalogue is separate from offer search. |
+| type | string | 1..1 | — | — | No equivalent. |
+| length / width / height / weight | integer | 0..1 | — | — | No equivalent. |
+
+---
+
+## EntitlementRight
+
+> Credential qualifying for reduced fares.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| issuer | string | 0..1 | `card` | — / `entitlement` | No explicit issuer field in TOMP; issuer may be embedded in the `type` code or `id`. |
+| entitlementType | string | 1..1 | `card` | `type` / `entitlement` `type` | Maps to `card.type` (e.g. `DISCOUNT_CARD`) or `entitlement.type`. |
+| code | string | 0..1 | `card` | `id` / `entitlement` `id` | The instance identifier (card number, voucher code). |
+
+---
+
+## TripPattern
+
+> Proposed sequence of legs.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| tripPatternId | string | 0..1 | — | — | No equivalent; TOMP identifies the trip by the journey reference set, not a caller ID. |
+| legs | Leg | 1..* | `tripPattern` | `serviceJourneys[]` (timed) OR `travelSpecification` (open O&D) | A `TripPattern` containing `TimedLeg`s maps to `tripPattern.serviceJourneys[]`. An open-ended trip maps to `travelSpecification`. `ContinuousLeg` and `TransferLeg` have no TOMP equivalent. |
+
+---
+
+## TimedLeg
+
+> Leg on a fixed timetabled service.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | Discriminator only. |
+| legId | string | 0..1 | — | — | No equivalent. |
+| sequenceNumber | integer | 0..1 | — | — | Implied by order in `serviceJourneys[]`. |
+| mode | string | 0..1 | `travellerRequirements` | `mode` | TOMP applies mode at traveller-requirements level, not per leg. |
+| serviceJourneyRef | string | 0..1 | `ServiceJourneyReference` | `id` | Direct mapping. |
+| operatingDate | date | 0..1 | `tripPattern` | `travelDate` | TOMP has a single `travelDate` for the whole trip pattern. |
+| lineNumber | string | 0..1 | `ServiceJourneyReference` | `lineId` | |
+| brand | string | 0..1 | — | — | No equivalent. |
+| start | LegBoard | 0..1 | — | — | TOMP `tripPattern` does not include stop-level boarding data; only `serviceJourneys[]` and `travelDate`. |
+| end | LegAlight | 0..1 | — | — | No equivalent. |
+| intermediateStops | StopPlace | 0..* | — | — | No equivalent. |
+
+---
+
+## ContinuousLeg
+
+> Leg without fixed timetabled stops (walk, taxi, etc.). **Partially covered by `travelSpecification`.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | Discriminator only. |
+| startTime | dateTime | 0..1 | `travelSpecification` | `startTime` | |
+| endTime | dateTime | 0..1 | `travelSpecification` | `endTime` | |
+| startLocation | Place | 0..1 | `travelSpecification` | `from` (placeReference) | |
+| endLocation | Place | 0..1 | `travelSpecification` | `to` (placeReference) | |
+
+---
+
+## TransferLeg
+
+> Transfer between services. **No equivalent in TOMP-API.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| legType | string | 1..1 | — | — | No equivalent. TOMP does not model interchange legs in offer-search input. |
+
+---
+
+## LegBoard
+
+> Boarding event at the start of a timed leg.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | TOMP references places by ID or coordinates. Stop references in a timed-leg context are not part of `tripPattern.serviceJourneys[]`. |
+| plannedDepartureTime | dateTime | 1..1 | `tripPattern` | `travelDate` | TOMP has date only, not full departure time per leg. |
+| pickupLocation | string | 0..1 | — | — | No equivalent. |
+| trainNumbers | TrainNumber | 0..* | — | — | No equivalent; train number not in TOMP offer search. |
+
+---
+
+## LegAlight
+
+> Alighting event at the end of a timed leg.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | See LegBoard note above. |
+| plannedArrivalTime | dateTime | 1..1 | — | — | No equivalent per-leg arrival time in TOMP. |
+| setDownLocation | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## TrainNumber
+
+> Commercial train number. **No equivalent in TOMP offer-search input.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| trainNumberId | string | 1..1 | — | — | No equivalent. |
+
+---
+
+## StopPlace
+
+> Reference to an intermediate stop along a timed leg.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| stopPlaceRef | string | 1..1 | `placeReference` | `id` | TOMP `placeReference` accepts a stop ID or coordinates. |
+
+---
+
+## Place
+
+> Base place type.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| placeId | string | 0..1 | `placeReference` | — | Caller-assigned ID; no direct field in TOMP `placeReference`. |
+| placeType | string | 1..1 | — | — | Discriminator only; TOMP does not distinguish place sub-types explicitly. |
+| location | GeoPosition | 0..1 | `placeReference` | `coordinates` (GeoCoordinate) | See **GeoPosition** section. |
+
+---
+
+## StopPlaceInput
+
+> Stop place identified by reference.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| placeRef | string | 0..1 | `placeReference` | `id` | |
+
+---
+
+## AddressInput
+
+> Postal address as a place.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| addressLine1 | string | 0..1 | `placeReference` | `name` | TOMP `placeReference` has a single `name` field; no structured address. |
+| addressLine2 | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## PointOfInterest
+
+> Named point of interest.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| name | string | 0..1 | `placeReference` | `name` | |
+
+---
+
+## TopologicalPlace
+
+> Geographic area or zone.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| area | string | 0..1 | `travellerRequirements` | `zones[]` | TOMP supports zone-based filtering via `zones[]` (zone IDs), not GeoJSON polygons. |
+| range | integer | 0..1 | — | — | No equivalent; TOMP does not support radius-based place references. |
+
+---
+
+## GeoPosition
+
+> WGS-84 coordinate pair.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| longitude | number | 1..1 | `GeoCoordinate` | `lon` | |
+| latitude | number | 1..1 | `GeoCoordinate` | `lat` | |
+
+---
+
+## Offer
+
+> Purchasable combination of offer elements returned by the server.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerId | string | 1..1 | `leg` | `id` (leg-level) | TOMP does not return a discrete "offer" object; pricing is returned per leg via `leg.pricing[]`. No offer-level ID. |
+| elements | OfferElement | 1..* | `leg.pricing` | (array) | See **OfferElement** section. |
+| farePrice | FarePrice | 0..1 | `leg.pricing` | `estimated`, `parts[]` | Aggregated across legs by the client. |
+| travelDocument | TravelDocument | 0..1 | — | — | Not returned in offer-search response; issued at booking stage. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements within an offer.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | — | — | No equivalent per-element ID in TOMP pricing. |
+| offerElementType | string | 1..1 | — | — | Discriminator only. |
+| travellingEntities | string | 0..* | — | — | TOMP pricing is leg-level, not traveller-level. |
+| farePrice | FarePrice | 0..1 | `leg.pricing` | `parts[{ amount, currencyCode }]` | |
+| travelDocument | TravelDocument | 0..1 | — | — | Not in offer-search response. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent. |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific leg or zone.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| legRef | string | 0..1 | `leg` | `id` | TOMP prices are attached to `leg` objects; the leg ID is the implicit travel-right scope. |
+| zoneRef | string | 0..1 | `travellerRequirements` | `zones[]` | Zone scope expressed as zone filter, not a response field. |
+
+---
+
+## Ancillary
+
+> Optional ancillary service. **No direct equivalent in TOMP offer-search response.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | — | — | No equivalent. |
+| type | string | 0..1 | — | — | No equivalent. |
+
+---
+
+## Reservation
+
+> Seat or space reservation. **No equivalent in TOMP offer-search response.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerElementType | string | 1..1 | — | — | No equivalent at offer-search stage in TOMP. |
+
+---
+
+## CompositeOfferElement
+
+> Grouped offer elements sold as a unit. **No equivalent in TOMP.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| elements | OfferElement | 2..* | — | — | No equivalent. |
+
+---
+
+## FarePrice
+
+> Price of an offer or offer element. (Stub — detail TBD.)
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | `leg.pricing` | `estimated` (bool), `parts[{ amount, currencyCode }]` | TOMP pricing is per leg; totals must be aggregated. |
+
+---
+
+## TravelDocument
+
+> Proof of entitlement issued to the traveller. (Stub — detail TBD.)
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | — | — | Not part of TOMP offer-search response; issued at booking/confirmation stage. |
+
+---
+
+## Guarantee
+
+> Guarantee associated with an offer element. (Stub — detail TBD.) **No equivalent in TOMP.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| (TBD) | — | — | — | — | No equivalent. |
diff --git a/deliverables/1 search offers/search-offers-model backup day 1.qea b/deliverables/1 search offers/search-offers-model backup day 1.qea
new file mode 100644
index 0000000..7c5472e
Binary files /dev/null and b/deliverables/1 search offers/search-offers-model backup day 1.qea differ
diff --git a/deliverables/1 search offers/search-offers-model-old.qea b/deliverables/1 search offers/search-offers-model-old.qea
new file mode 100644
index 0000000..147b695
Binary files /dev/null and b/deliverables/1 search offers/search-offers-model-old.qea differ
diff --git a/deliverables/1 search offers/search-offers-model.qea b/deliverables/1 search offers/search-offers-model.qea
new file mode 100644
index 0000000..ebf4619
Binary files /dev/null and b/deliverables/1 search offers/search-offers-model.qea differ
diff --git a/deliverables/1 search offers/search-offers.html b/deliverables/1 search offers/search-offers.html
new file mode 100644
index 0000000..3b34459
--- /dev/null
+++ b/deliverables/1 search offers/search-offers.html
@@ -0,0 +1,164 @@
+
+
+
+
+
+ OpenAPI Preview — search-offers.yaml
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deliverables/1 search offers/search-offers.yaml b/deliverables/1 search offers/search-offers.yaml
new file mode 100644
index 0000000..0684953
--- /dev/null
+++ b/deliverables/1 search offers/search-offers.yaml
@@ -0,0 +1,1292 @@
+openapi: 3.1.0
+info:
+ title: OTI — Search offers
+ version: 0.1.0-draft
+ description: Returns a list of SALES OFFER PACKAGEs matching the traveller's trip context, PASSENGER TYPEs, and FARE CONDITIONS.
+paths:
+ /offers:
+ post:
+ summary: 'OSDM 3.7.1: POST /offers'
+ operationId: search_offers_post_offers
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SearchOfferDelivery'
+ /processes/search-offers/execute:
+ post:
+ summary: 'OMSA 0.1.0: POST /processes/search-offers/execute'
+ operationId: omsa_search_offers_post_processes_search_offers_execute
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SearchOfferDelivery'
+ /processes/search-offers/execution:
+ post:
+ summary: 'TOMP-API 2.0.0: POST /processes/search-offers/execution'
+ operationId: search_offers_post_processes_search_offers_execution
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SearchOfferDelivery'
+components:
+ schemas:
+
+ # ─── REQUEST ──────────────────────────────────────────────────────────────
+
+ OfferRequest:
+ type: object
+ additionalProperties: false
+ description: SEARCH OFFER REQUEST — the root object for an offer search.
+ required:
+ - travellers
+ - tripPatterns
+ properties:
+ tripPatterns:
+ type: array
+ minItems: 1
+ description: One or more trip patterns the traveller wants to undertake, for which offers are sought.
+ items:
+ $ref: '#/components/schemas/TripPattern'
+ travellers:
+ type: array
+ minItems: 1
+ description: The travelling entities (travellers, vehicles, animals, luggage) for whom offers are sought.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/Traveller'
+ - $ref: '#/components/schemas/PassengerVehicle'
+ - $ref: '#/components/schemas/Animal'
+ - $ref: '#/components/schemas/Luggage'
+ discriminator:
+ propertyName: entityType
+ mapping:
+ traveller: '#/components/schemas/Traveller'
+ vehicle: '#/components/schemas/PassengerVehicle'
+ animal: '#/components/schemas/Animal'
+ luggage: '#/components/schemas/Luggage'
+ filter:
+ description: Constraints on the offers to be returned.
+ $ref: '#/components/schemas/SearchOfferFilter'
+ policy:
+ description: Controls what the server includes in the response.
+ $ref: '#/components/schemas/SearchOfferPolicy'
+
+ SearchOfferPolicy:
+ type: object
+ additionalProperties: false
+ description: SEARCH OFFER POLICY — controls pagination and currency of the offer response.
+ properties:
+ numberOfResultsBefore:
+ type: integer
+ description: Maximum number of results to return before the requested departure time.
+ numberOfResultsAfter:
+ type: integer
+ description: Maximum number of results to return after the requested departure time.
+ currency:
+ type: string
+ description: ISO 4217 currency code in which prices should be expressed.
+
+ SearchOfferFilter:
+ type: object
+ additionalProperties: false
+ description: SEARCH OFFER FILTER — constrains which offers the server returns.
+ properties:
+ modes:
+ type: array
+ description: Transport modes to include in the search.
+ items:
+ type: string
+ classOfUse:
+ type: array
+ description: Classes of use (e.g. first, second) to include in the search.
+ items:
+ type: string
+ x-extensible-enum:
+ - first
+ - second
+ - premium
+ mediaTypes:
+ type: array
+ description: Fulfilment media types to include (e.g. paperTicket, mobileTicket, smartCard).
+ items:
+ type: string
+ requestedSections:
+ type: array
+ description: Restricts the offer search to specific sections of the journey.
+ items:
+ $ref: '#/components/schemas/RequestedSections'
+
+ RequestedSections:
+ type: object
+ additionalProperties: false
+ description: REQUESTED SECTIONS — identifies a subset of legs within the trip for which targeted offers are requested.
+ properties:
+ startLegRef:
+ type: string
+ description: Reference to the first leg in the requested section.
+ endLegRef:
+ type: string
+ description: Reference to the last leg in the requested section.
+ startPlaceRef:
+ type: string
+ description: Reference to the departure place of the section.
+ endPlaceRef:
+ type: string
+ description: Reference to the arrival place of the section.
+ tripPatternRef:
+ type: string
+ description: Reference to the trip pattern this section belongs to.
+ sectionId:
+ type: string
+ description: Caller-assigned identifier for this requested section.
+
+ # ─── TRAVELLING ENTITIES ──────────────────────────────────────────────────
+
+ TravellingEntity:
+ type: object
+ description: TRAVELLING ENTITY — base class for all entities taking part in a journey. Use the entityType discriminator to select the concrete sub-type.
+ required:
+ - entityType
+ - travellingEntityId
+ properties:
+ travellingEntityId:
+ type: string
+ description: Stable caller-assigned identifier for this entity. Must be unique within the request.
+ entityType:
+ type: string
+ enum:
+ - traveller
+ - vehicle
+ - animal
+ - luggage
+ description: Discriminator identifying the concrete type of this entity.
+ entitlementRights:
+ type: array
+ description: ENTITLEMENT RIGHTs held by this entity that may qualify for reduced fares or special conditions.
+ items:
+ $ref: '#/components/schemas/EntitlementRight'
+
+ Traveller:
+ allOf:
+ - $ref: '#/components/schemas/TravellingEntity'
+ - type: object
+ additionalProperties: false
+ description: TRAVELLER — a human traveller for whom offers are sought.
+ required:
+ - entityType
+ properties:
+ entityType:
+ type: string
+ const: traveller
+ age:
+ type: integer
+ minimum: 0
+ description: Age in years at the time of travel.
+ assistant:
+ type: boolean
+ description: Whether this traveller acts as an assistant to another traveller.
+ dateOfBirth:
+ type: string
+ format: date
+ description: Date of birth. Enables age-band fare calculation. (TBD — final field name pending.)
+ externalReference:
+ type: string
+ description: Caller-assigned external reference for this traveller.
+ personalNeeds:
+ type: array
+ description: Accessibility or personal needs of this traveller (operator-defined lookup values, see /personal-needs).
+ items:
+ type: string
+ qualifyingCharacteristics:
+ description: Additional qualifying characteristics used for eligibility determination.
+ $ref: '#/components/schemas/TravellerQualifyingCharacteristics'
+
+ TravellerQualifyingCharacteristics:
+ type: object
+ additionalProperties: false
+ description: TRAVELLER QUALIFYING CHARACTERISTICS — demographic and eligibility data used for fare calculation. May contain GDPR-sensitive personal data; transmit only when required.
+ properties:
+ fullName:
+ type: string
+ description: Full name of the traveller.
+ nationality:
+ type: string
+ description: Nationality (ISO 3166-1 alpha-2 country code).
+ residency:
+ type: string
+ description: Country of residency (ISO 3166-1 alpha-2) for domestic vs. international fare eligibility.
+ dateOfBirth:
+ type: string
+ format: date
+ description: Date of birth. (TBD — final field name pending.)
+ licenseTypes:
+ type: array
+ description: License types held by this traveller that may affect offer availability.
+ items:
+ type: string
+
+
+
+ Animal:
+ allOf:
+ - $ref: '#/components/schemas/TravellingEntity'
+ - type: object
+ additionalProperties: false
+ description: ANIMAL — an animal travelling alongside its owner.
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: animal
+ type:
+ type: string
+ description: Category of animal (operator-defined, e.g. dog, cat, other).
+ x-extensible-enum:
+ - dog
+ - cat
+ - other
+ assistant:
+ type: boolean
+ description: Whether this animal is a registered assistance animal.
+
+ PassengerVehicle:
+ allOf:
+ - $ref: '#/components/schemas/TravellingEntity'
+ - type: object
+ additionalProperties: false
+ description: PASSENGER VEHICLE — a traveller-owned vehicle to be transported (e.g. on a ferry or car-train).
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: vehicle
+ type:
+ type: string
+ description: Vehicle category.
+ x-extensible-enum:
+ - car
+ - motorhome
+ - caravan
+ - motorbike
+ - bicycle
+ - trailerOnly
+ height:
+ type: integer
+ minimum: 0
+ description: Height of the vehicle in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width of the vehicle in centimetres.
+ length:
+ type: integer
+ minimum: 0
+ description: Total length of the vehicle in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Total weight of the vehicle in kilograms.
+ trailer:
+ description: Details of a towed trailer, if applicable.
+ $ref: '#/components/schemas/PassengerVehicle'
+ vehicleRacks:
+ type: array
+ maxItems: 2
+ description: Vehicle racks (e.g. bike racks) mounted on the vehicle.
+ items:
+ $ref: '#/components/schemas/VehicleRack'
+
+ VehicleRack:
+ type: object
+ additionalProperties: false
+ description: VEHICLE RACK — a rack or carrier mounted on a passenger vehicle (e.g. roof rack, bike carrier).
+ properties:
+ type:
+ type: string
+ description: Type of rack.
+ x-extensible-enum:
+ - roofRack
+ - bikeCarrier
+ - skiCarrier
+ - towbarCarrier
+ - other
+ mounting:
+ type: string
+ description: How the rack is mounted on the vehicle.
+ enum:
+ - roof
+ - towbar
+ - rear
+ height:
+ type: integer
+ minimum: 0
+ description: Height of the rack in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width of the rack in centimetres.
+ length:
+ type: integer
+ minimum: 0
+ description: Length of the rack in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Weight of the rack (including load) in kilograms.
+
+ Luggage:
+ allOf:
+ - $ref: '#/components/schemas/TravellingEntity'
+ - type: object
+ additionalProperties: false
+ description: LUGGAGE — a bulky item a traveller brings that may affect offer availability, space allocation, or price.
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: luggage
+ type:
+ type: string
+ description: Category of item.
+ x-extensible-enum:
+ - bicycle
+ - pram
+ - luggage
+ - wheelchair
+ - skis
+ - snowboard
+ - musicalInstrument
+ - other
+ length:
+ type: integer
+ minimum: 0
+ description: Length in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width in centimetres.
+ height:
+ type: integer
+ minimum: 0
+ description: Height in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Weight in kilograms.
+
+ EntitlementRight:
+ type: object
+ additionalProperties: false
+ description: ENTITLEMENT RIGHT — a credential held by a travelling entity that may qualify for reduced fares or special conditions (loyalty card, discount card, concession, etc.).
+ required:
+ - entitlementType
+ properties:
+ issuer:
+ type: string
+ description: Issuing authority or scheme name.
+ entitlementType:
+ type: string
+ description: Type of entitlement (operator-defined lookup value, e.g. loyaltyCard, discountCard, concession).
+ code:
+ type: string
+ description: Instance identifier such as a card number or voucher code.
+
+ # ─── TRIP PATTERN & LEGS ──────────────────────────────────────────────────
+
+ TripPattern:
+ type: object
+ additionalProperties: false
+ description: TRIP PATTERN (INPUT) — a proposed trip the traveller wants to undertake, consisting of one or more legs.
+ required:
+ - legs
+ properties:
+ tripPatternId:
+ type: string
+ description: Caller-assigned identifier for this trip pattern.
+ legs:
+ type: array
+ minItems: 1
+ description: The legs that make up this trip pattern.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/TimedLeg'
+ - $ref: '#/components/schemas/ContinuousLeg'
+ - $ref: '#/components/schemas/TransferLeg'
+ discriminator:
+ propertyName: legType
+ mapping:
+ timed: '#/components/schemas/TimedLeg'
+ continuous: '#/components/schemas/ContinuousLeg'
+ transfer: '#/components/schemas/TransferLeg'
+
+ Leg:
+ type: object
+ description: LEG (INPUT) — a single leg within a trip. Use the legType discriminator to select the concrete sub-type.
+ required:
+ - legId
+ - legType
+ properties:
+ legId:
+ type: string
+ description: Caller-assigned identifier for this leg.
+ sequenceNumber:
+ type: integer
+ description: Position of this leg within the trip.
+ mode:
+ type: string
+ description: Transport mode for this leg.
+ enum:
+ - rail
+ - coach
+ - bus
+ - ferry
+ - metro
+ - tram
+ - air
+ - other
+ legType:
+ type: string
+ description: Discriminator identifying the concrete leg type.
+ trip:
+ type: string
+ description: Caller-assigned identifier for the trip this leg belongs to (used to group legs from the same trip, e.g. for interlining).
+
+ TimedLeg:
+ allOf:
+ - $ref: '#/components/schemas/Leg'
+ - type: object
+ additionalProperties: false
+ description: TIMED LEG (INPUT) — a leg on a fixed timetabled service.
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: timed
+ serviceJourneyRef:
+ type: string
+ description: Reference to the NeTEx SERVICE JOURNEY for this leg.
+ operatingDate:
+ type: string
+ format: date
+ description: The operating date of the service.
+ lineNumber:
+ type: string
+ description: Commercial line number or designator.
+ brand:
+ type: string
+ description: Commercial brand or product name of the service.
+ start:
+ description: Boarding point for this leg.
+ $ref: '#/components/schemas/LegBoard'
+ end:
+ description: Alighting point for this leg.
+ $ref: '#/components/schemas/LegAlight'
+ intermediateStops:
+ type: array
+ description: Intermediate stops passed during this leg (not boarded/alighted). Each value is a reference to a NeTEx STOP PLACE or SCHEDULED STOP POINT.
+ items:
+ type: string
+
+ ContinuousLeg:
+ allOf:
+ - $ref: '#/components/schemas/Leg'
+ - type: object
+ additionalProperties: false
+ description: CONTINUOUS LEG (INPUT) — a leg without fixed timetabled stops (e.g. walk, cycle, taxi).
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: continuous
+ startTime:
+ type: string
+ format: date-time
+ description: Scheduled start time of this leg.
+ endTime:
+ type: string
+ format: date-time
+ description: Scheduled end time of this leg.
+ startLocation:
+ description: Departure location for this continuous leg.
+ $ref: '#/components/schemas/Place'
+ endLocation:
+ description: Arrival location for this continuous leg.
+ $ref: '#/components/schemas/Place'
+
+ TransferLeg:
+ allOf:
+ - $ref: '#/components/schemas/Leg'
+ - type: object
+ additionalProperties: false
+ description: TRANSFER LEG — a leg representing a transfer between services (e.g. platform change, interchange).
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: transfer
+
+ LegBoard:
+ type: object
+ additionalProperties: false
+ description: LEG BOARD — the boarding event at the start of a timed leg.
+ required:
+ - stopPlaceRef
+ - plannedDepartureTime
+ properties:
+ stopPlaceRef:
+ type: string
+ description: Reference to the NeTEx SCHEDULED STOP POINT or STOP PLACE where boarding occurs.
+ plannedDepartureTime:
+ type: string
+ format: date-time
+ description: Scheduled departure time at the boarding stop.
+ pickupLocation:
+ type: string
+ description: Reference to a specific platform, bay, or pick-up zone within the stop place.
+ trainNumbers:
+ type: array
+ description: Commercial train numbers for this departure.
+ items:
+ type: string
+
+ LegAlight:
+ type: object
+ additionalProperties: false
+ description: LEG ALIGHT — the alighting event at the end of a timed leg.
+ required:
+ - stopPlaceRef
+ - plannedArrivalTime
+ properties:
+ stopPlaceRef:
+ type: string
+ description: Reference to the NeTEx SCHEDULED STOP POINT or STOP PLACE where alighting occurs.
+ plannedArrivalTime:
+ type: string
+ format: date-time
+ description: Scheduled arrival time at the alighting stop.
+ setDownLocation:
+ type: string
+ description: Reference to a specific platform, bay, or set-down zone within the stop place.
+
+
+
+ # ─── PLACE HIERARCHY ──────────────────────────────────────────────────────
+
+ Place:
+ type: object
+ description: PLACE (INPUT) — a geographic location referenced in the trip context. Use the placeType discriminator to select the concrete sub-type.
+ required:
+ - placeType
+ properties:
+ placeId:
+ type: string
+ description: Caller-assigned identifier for this place. Used to cross-reference from legs or sections.
+ placeType:
+ type: string
+ description: Discriminator identifying the concrete place type.
+ location:
+ description: Geodetic position of this place.
+ $ref: '#/components/schemas/GeoPosition'
+
+ StopPlaceInput:
+ allOf:
+ - $ref: '#/components/schemas/Place'
+ - type: object
+ additionalProperties: false
+ description: STOP PLACE (INPUT) — a stop place or scheduled stop point identified by reference.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: stopPlace
+ placeRef:
+ type: string
+ description: Reference to a NeTEx STOP PLACE or SCHEDULED STOP POINT.
+
+ AddressInput:
+ allOf:
+ - $ref: '#/components/schemas/Place'
+ - type: object
+ additionalProperties: false
+ description: ADDRESS (INPUT) — a postal address as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: address
+ addressLine1:
+ type: string
+ description: Primary address line (street name and number).
+ addressLine2:
+ type: string
+ description: Secondary address line (apartment, floor, etc.).
+
+ PointOfInterest:
+ allOf:
+ - $ref: '#/components/schemas/Place'
+ - type: object
+ additionalProperties: false
+ description: POINT OF INTEREST (INPUT) — a named point of interest as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: pointOfInterest
+ name:
+ type: string
+ description: Name of the point of interest.
+
+ TopologicalPlace:
+ allOf:
+ - $ref: '#/components/schemas/Place'
+ - type: object
+ additionalProperties: false
+ description: TOPOLOGICAL PLACE (INPUT) — a geographic area or zone as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: topologicalPlace
+ area:
+ type: string
+ description: GeoJSON Polygon geometry defining the area (serialised as string).
+ range:
+ type: integer
+ minimum: 0
+ description: Search radius in metres around the area centroid.
+
+ GeoPosition:
+ type: object
+ additionalProperties: false
+ description: A geodetic position (WGS-84).
+ required:
+ - longitude
+ - latitude
+ properties:
+ longitude:
+ type: number
+ format: double
+ description: Longitude in decimal degrees (WGS-84).
+ latitude:
+ type: number
+ format: double
+ description: Latitude in decimal degrees (WGS-84).
+
+ # ─── OFFER RESPONSE ───────────────────────────────────────────────────────────────
+
+ SearchOfferDelivery:
+ type: object
+ additionalProperties: false
+ description: SEARCH OFFER DELIVERY — the root response object containing all offers matching the search request, together with the echoed travelling entities and trip patterns.
+ properties:
+ offers:
+ type: array
+ description: The offers returned by the server for the requested trip and travelling entities.
+ items:
+ $ref: '#/components/schemas/Offer'
+ travellers:
+ type: array
+ description: The travelling entities echoed from the request (travellers, vehicles, animals, luggage).
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/Traveller'
+ - $ref: '#/components/schemas/PassengerVehicle'
+ - $ref: '#/components/schemas/Animal'
+ - $ref: '#/components/schemas/Luggage'
+ discriminator:
+ propertyName: entityType
+ mapping:
+ traveller: '#/components/schemas/Traveller'
+ vehicle: '#/components/schemas/PassengerVehicle'
+ animal: '#/components/schemas/Animal'
+ luggage: '#/components/schemas/Luggage'
+ tripPatterns:
+ type: array
+ description: The trip patterns echoed from the request.
+ items:
+ $ref: '#/components/schemas/TripPattern'
+ links:
+ type: array
+ description: Hypermedia links for further actions (e.g. pagination).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ Offer:
+ type: object
+ additionalProperties: false
+ description: OFFER — a purchasable combination of offer elements for the requested trip.
+ required:
+ - offerId
+ - elements
+ properties:
+ offerId:
+ type: string
+ description: Server-assigned unique identifier for this offer.
+ name:
+ type: string
+ description: Human-readable name of this offer (e.g. product or service name).
+ summary:
+ type: string
+ description: Short human-readable summary of the offer (e.g. route, date, class).
+ matching:
+ type: string
+ description: Indicates how well this offer matches the original request.
+ x-extensible-enum:
+ - exact
+ - partial
+ - none
+ status:
+ type: string
+ description: Current availability status of this offer.
+ enum:
+ - open
+ - closed
+ - expired
+ afterSalesFlexibility:
+ type: array
+ description: After-sales flexibility options applicable to this offer.
+ items:
+ type: string
+ enum:
+ - refundable
+ - exchangeable
+ - nonRefundable
+ - nonExchangeable
+ personalInformationRequired:
+ type: boolean
+ description: Whether personal information (e.g. name, date of birth) is required to purchase this offer.
+ elements:
+ type: array
+ minItems: 1
+ description: The offer elements (travel rights, ancillaries, allocations) that make up this offer.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/TravelRight'
+ - $ref: '#/components/schemas/Ancillary'
+ - $ref: '#/components/schemas/SpotAllocation'
+ - $ref: '#/components/schemas/AssetAllocation'
+ discriminator:
+ propertyName: offerElementType
+ mapping:
+ travelRight: '#/components/schemas/TravelRight'
+ ancillary: '#/components/schemas/Ancillary'
+ spotAllocation: '#/components/schemas/SpotAllocation'
+ assetAllocation: '#/components/schemas/AssetAllocation'
+ minimumPrice:
+ description: Minimum total price of this offer (e.g. before optional ancillaries).
+ $ref: '#/components/schemas/Price'
+ summaryDetails:
+ type: array
+ description: Human-readable summaries of the journey geometry and temporal span covered by this offer.
+ items:
+ $ref: '#/components/schemas/SummaryDetail'
+ providedSections:
+ type: array
+ description: The journey sections covered by this offer.
+ items:
+ $ref: '#/components/schemas/ProvidedSections'
+ guarantees:
+ type: array
+ description: Guarantees associated with this offer (e.g. connection guarantee, seat guarantee).
+ items:
+ $ref: '#/components/schemas/Guarantee'
+ links:
+ type: array
+ description: Hypermedia links for further actions (e.g. lock-offers).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ OfferElement:
+ type: object
+ description: OFFER ELEMENT — base class for all purchasable elements within an offer. Use the offerElementType discriminator to select the concrete sub-type.
+ required:
+ - offerElementType
+ - offerElementId
+ properties:
+ offerElementId:
+ type: string
+ description: Server-assigned unique identifier for this offer element.
+ offerElementType:
+ type: string
+ description: Discriminator identifying the concrete offer element type.
+ travellingEntities:
+ type: array
+ description: References (travellingEntityId values) to the travelling entities this element applies to.
+ items:
+ type: string
+ matching:
+ type: string
+ description: Indicates how well this offer element matches the original request.
+ x-extensible-enum:
+ - exact
+ - partial
+ - none
+ price:
+ description: Price of this individual offer element.
+ $ref: '#/components/schemas/Price'
+ fareProduct:
+ type: string
+ description: Reference to the fare product associated with this offer element (operator-defined code).
+ providedSections:
+ type: array
+ description: The journey sections covered by this offer element.
+ items:
+ $ref: '#/components/schemas/ProvidedSections'
+ guarantees:
+ type: array
+ description: Guarantees associated with this offer element.
+ items:
+ $ref: '#/components/schemas/Guarantee'
+ requiredInformation:
+ description: Personal information required for this offer element before purchase. Detail TBD.
+ $ref: '#/components/schemas/RequiredInformation'
+
+ TravelRight:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ additionalProperties: false
+ description: TRAVEL RIGHT — an offer element conferring the right to travel on a specific section of the journey.
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: travelRight
+ requiredAllocations:
+ type: array
+ description: Seat or space allocations required for this travel right (e.g. mandatory seat reservation).
+ items:
+ $ref: '#/components/schemas/RequiredAllocation'
+ requiredAncillaries:
+ type: array
+ description: Ancillaries that can or must be added to this travel right (e.g. bicycle transport, cabin).
+ items:
+ $ref: '#/components/schemas/RequiredAncillary'
+
+ Ancillary:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ additionalProperties: false
+ description: ANCILLARY — an offer element for an optional or required ancillary service (e.g. bike transport, cabin, meal).
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: ancillary
+ ancillaryId:
+ type: string
+ description: Server-assigned identifier for this ancillary.
+ type:
+ type: string
+ description: Type of ancillary service (operator-defined lookup value).
+
+ Allocation:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ description: ALLOCATION — base class for seat or space allocations within an offer. Use the offerElementType discriminator to select the concrete sub-type (spotAllocation or assetAllocation).
+ required:
+ - offerElementType
+ properties:
+ legRef:
+ type: string
+ description: Reference to the leg on which this allocation applies.
+ startPlaceRef:
+ type: string
+ description: Reference to the stop point where this allocation begins (boarding).
+ endPlaceRef:
+ type: string
+ description: Reference to the stop point where this allocation ends (alighting).
+
+ SpotAllocation:
+ allOf:
+ - $ref: '#/components/schemas/Allocation'
+ - type: object
+ additionalProperties: false
+ description: SPOT ALLOCATION — an allocation to a specific spot (e.g. seat, berth, parking space).
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: spotAllocation
+ typeOfSpot:
+ type: string
+ description: Category of the allocated spot.
+ x-extensible-enum:
+ - seat
+ - berth
+ - compartment
+ - wheelchairSpace
+ - parkingSpace
+ - other
+
+ AssetAllocation:
+ allOf:
+ - $ref: '#/components/schemas/Allocation'
+ - type: object
+ additionalProperties: false
+ description: ASSET ALLOCATION — an allocation to a named asset (e.g. a specific vehicle slot or named cabin).
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: assetAllocation
+ assetRef:
+ type: string
+ description: Reference to the named asset being allocated.
+ typeOfAsset:
+ type: string
+ description: Category of the asset (operator-defined extensible value).
+ x-extensible-enum:
+ - vehicleSlot
+ - cabin
+ - locker
+ - other
+
+ RequiredAllocation:
+ type: object
+ additionalProperties: false
+ description: REQUIRED ALLOCATION — specifies which allocations (seat or space reservations) are available or required for a travel right on a given leg.
+ properties:
+ legRef:
+ type: string
+ description: Reference to the leg (legId) to which these allocations apply.
+ minimum:
+ type: integer
+ description: Minimum number of allocations that must be selected.
+ maximum:
+ type: integer
+ description: Maximum number of allocations that may be selected.
+ allocations:
+ type: array
+ minItems: 1
+ description: The available allocation options for this leg.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/SpotAllocation'
+ - $ref: '#/components/schemas/AssetAllocation'
+ discriminator:
+ propertyName: offerElementType
+ mapping:
+ spotAllocation: '#/components/schemas/SpotAllocation'
+ assetAllocation: '#/components/schemas/AssetAllocation'
+
+ RequiredAncillary:
+ type: object
+ additionalProperties: false
+ description: REQUIRED ANCILLARY — specifies which ancillary services are available or required for a travel right on a given leg.
+ properties:
+ legRef:
+ type: string
+ description: Reference to the leg (legId) to which these ancillaries apply.
+ minimum:
+ type: integer
+ description: Minimum number of ancillaries that must be selected (0 = optional).
+ maximum:
+ type: integer
+ description: Maximum number of ancillaries that may be selected.
+ ancillaries:
+ type: array
+ minItems: 1
+ description: The available ancillary options for this leg.
+ items:
+ $ref: '#/components/schemas/Ancillary'
+
+
+ Price:
+ type: object
+ additionalProperties: false
+ description: PRICE — a monetary amount in a specific currency.
+ required:
+ - currencyCode
+ - amount
+ properties:
+ currencyCode:
+ type: string
+ description: ISO 4217 currency code (e.g. EUR, GBP, SEK).
+ amount:
+ type: number
+ format: double
+ description: Monetary amount in the specified currency.
+ vat:
+ type: array
+ description: VAT breakdown applicable to this price.
+ items:
+ $ref: '#/components/schemas/Vat'
+
+ Vat:
+ type: object
+ additionalProperties: false
+ description: VAT — a VAT component of a price, broken down by country and percentage.
+ required:
+ - amount
+ - currencyCode
+ - country
+ - percentage
+ properties:
+ amount:
+ type: number
+ format: double
+ description: VAT amount in the specified currency.
+ currencyCode:
+ type: string
+ description: ISO 4217 currency code for this VAT component.
+ country:
+ type: string
+ description: ISO 3166-1 alpha-2 country code for which this VAT rate applies.
+ percentage:
+ type: number
+ format: double
+ description: VAT percentage rate (e.g. 21.0 for 21%).
+
+ ProvidedSections:
+ type: object
+ additionalProperties: false
+ description: PROVIDED SECTIONS — identifies the journey section (from–to legs) covered by an offer or offer element.
+ properties:
+ startLegRef:
+ type: string
+ description: Reference to the first leg in this section.
+ endLegRef:
+ type: string
+ description: Reference to the last leg in this section.
+ startPlaceRef:
+ type: string
+ description: Reference to the departure place of this section.
+ endPlaceRef:
+ type: string
+ description: Reference to the arrival place of this section.
+ tripPatternRef:
+ type: string
+ description: Reference to the trip pattern this section belongs to.
+ sectionId:
+ type: string
+ description: Server-assigned identifier for this provided section.
+
+ SummaryDetail:
+ type: object
+ additionalProperties: false
+ description: SUMMARY DETAIL — a human-readable summary of the journey geometry and temporal span covered by an offer.
+ properties:
+ geometry:
+ type: string
+ description: Geometric description of the journey (e.g. origin–destination name pair).
+ temporal:
+ type: string
+ description: Temporal description of the journey (e.g. departure–arrival date-time range).
+ conditions:
+ type: string
+ description: Human-readable summary of the applicable fare conditions.
+
+
+ Guarantee:
+ type: object
+ additionalProperties: false
+ description: GUARANTEE — a guarantee associated with an offer or offer element (e.g. connection guarantee, seat guarantee).
+ properties:
+ guaranteeId:
+ type: string
+ description: Server-assigned identifier for this guarantee.
+ type:
+ type: string
+ description: Category of guarantee (operator-defined extensible value).
+ x-extensible-enum:
+ - connectionGuarantee
+ - seatGuarantee
+ - priceGuarantee
+ - other
+
+ RequiredInformation:
+ type: object
+ additionalProperties: false
+ description: REQUIRED INFORMATION — personal information that must be provided for an offer element before purchase.
+ properties:
+ requiredInformationId:
+ type: string
+ description: Server-assigned identifier for this required information item.
+ validation:
+ type: string
+ description: JSONPath expression defining the expected data structure or validation rule.
+ travellerRef:
+ type: string
+ description: Reference to the travelling entity for whom this information is required.
+
+ # ─── SHARED ───────────────────────────────────────────────────────────────
+
+ Link:
+ type: object
+ additionalProperties: false
+ x-externalDocs:
+ url: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
+ required:
+ - href
+ - rel
+ properties:
+ rel:
+ type: string
+ description: the action that can be performed OR part of the URI allowed values include the 'processId's, prefixes
+ for the referenced data sources, prefixes for deeplinks ('apple' and 'android'), OGC compliant ones (alternative,
+ next, etc)
+ description:
+ type: string
+ description: the description of the external data source
+ method:
+ type: string
+ description: to indicate the http method.
+ default: GET
+ enum:
+ - POST
+ - GET
+ - DELETE
+ - PATCH
+ type:
+ type: string
+ description: allowed values are described by IANA, ("application/geo+json")
+ href:
+ $ref: '#/components/schemas/url'
+ availableFrom:
+ $ref: '#/components/schemas/dateTime'
+ body:
+ type: object
+ description: the body template for the request. Replace $parametername$ in the body.
+ example:
+ packageId: $packageId$
+ expires:
+ $ref: '#/components/schemas/dateTime'
+ headers:
+ additionalProperties:
+ type: string
+
+ # ─── PRIMITIVES ───────────────────────────────────────────────────────────
+
+ dateTime:
+ type: string
+ format: date-time
+ x-pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$
+ description: https://www.rfc-editor.org/rfc/rfc3339#section-5.6, date-time (2019-10-12T07:20:50.52Z)
+
+ url:
+ type: string
+ description: valid URL
+ format: uri
+
+ httpDate:
+ type: string
+ description: A HTTP date string
+ x-format: http-date
+ x-externalDocs:
+ url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires
+ description: http-date
+
+ headers:
+ contentLanguage:
+ description: The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag (nl-NL)
+ schema:
+ type: string
+ pattern: ^[a-zA-Z]+-[a-zA-Z]+$
+ required: true
+ expires:
+ description: the offer expires at this timestamp
+ schema:
+ $ref: '#/components/schemas/httpDate'
+ required: false
+ version:
+ description: the version used to format the response
+ schema:
+ type: string
+ required: true
+
+ parameters:
+ requestor:
+ name: Requestor
+ in: header
+ description: The requestor header contains detailed information about who is calling the API. It can include information
+ such as channel, organization, sales unit or workstation id and be used to configure e.g. the fare range provided
+ to the caller. The content of the string is part of a bilateral contract by the two parties and not standardized by
+ OSDM. It is recommend to encrypt the information transferred.
+ schema:
+ type: string
+ traceState:
+ name: tracestate
+ in: header
+ description: 'The tracestate extends traceparent with vendor-specific data represented by a set of name/value pairs.
+
+ Storing information in tracestate is optional (see W3C Trace Context).'
+ schema:
+ type: string
+ acceptLanguage:
+ name: Accept-Language
+ in: header
+ description: 'Describes the set of natural languages that are preferred for localized text in the response
+
+ to the request (see RFC9110). Supporting English (en) is a must.'
+ schema:
+ type: string
diff --git a/deliverables/1 search offers/test cases/test-cases.md b/deliverables/1 search offers/test cases/test-cases.md
new file mode 100644
index 0000000..565b9c6
--- /dev/null
+++ b/deliverables/1 search offers/test cases/test-cases.md
@@ -0,0 +1,233 @@
+# Search Offers — Test Cases for Request Bodies
+
+---
+
+## Generic Test Cases
+
+These cases cover the core request model and apply regardless of which endpoint or standard is used.
+
+**TODO:** WT 1 should supply additional test cases.
+
+---
+
+### TC-001 — Single traveller, single timed leg (simple OJP outcome)
+
+**Purpose:** the most basic possible request: just one traveller.
+
+**Scenario:**
+An adult traveller wants to travel by train from Amsterdam Centraal to Utrecht Centraal on
+15 September 2025, departing at 09:12. No special requirements or discounts apply.
+The system must return a list of available offers for this trip.
+
+---
+
+### TC-002 — Family group, two adults and two children
+
+**Purpose:** processes multiple travellers with different ages.
+
+**Scenario:**
+A family of four wants to travel from Den Haag Centraal to Rotterdam Centraal on 20 October 2025,
+departing at 14:00. The travel party consists of two adults and two children aged 8 and 12.
+The system must be able to compose a suitable offer for each member of the family.
+
+---
+
+### TC-003 — Traveller with a discount card
+
+**Purpose:** an entitlement right (e.g. a rail discount subscription or Railcard) can be specified.
+
+**Scenario:**
+A traveller holds an off-peak discount subscription (40% reduction outside peak hours).
+The journey is from Utrecht Centraal to Eindhoven on 3 November 2025, departing at 11:30
+(off-peak). The system must take the entitlement into account when determining offers.
+
+---
+
+### TC-004 — Traveller with accessibility need (PRM)
+
+**Purpose:** wheelchair-related personal can be specified, so the operator can supply suitable offers.
+
+**Scenario:**
+A traveller uses a motorised wheelchair. The journey is from Leiden Centraal to Schiphol on
+5 December 2025, departing at 07:45. The system must transmit the personal need so that the
+operator returns only wheelchair-accessible offers and seat assignments.
+
+---
+
+### TC-005 — Traveller with a passenger vehicle (ferry)
+
+**Purpose:** a normal car can be specified, as part of the travelling party, for a ferry crossing.
+
+**Scenario:**
+A traveller wants to cross from Harwich to Hoek van Holland with their car on 10 January 2026,
+sailing at 23:00. The car is 430 cm long, 180 cm wide, and 155 cm tall. In addition to the
+vehicle transport, the traveller expects the server to return a cabin as an ancillary offer.
+
+---
+
+### TC-006 — Traveller with a bicycle
+
+**Purpose:** a bicycle can be included as a part of the travelling party, enabling the operator to return a bicycle ticket or reservation alongside the passenger offer.
+
+**Scenario:**
+A traveller takes their road bicycle on the train from Amsterdam to Zwolle on 22 March 2026,
+departing at 08:30. The bicycle weighs 8 kg. The API should return offers for both the
+traveller and the bicycle transport.
+
+---
+
+### TC-007 — Return journey with two trip patterns
+
+**Purpose:** request return tickets in a single offer request (OJP outcome).
+
+**Scenario:**
+A traveller wants to book a day return from Breda to Amsterdam Centraal. Outbound on 14 April 2026
+at 08:00, returning the same day at 18:30. The API must return offers for both trip patterns,
+potentially combined as a return fare.
+
+---
+
+### TC-008 — Filter on travel class and media type
+
+**Purpose:** specify the travel class and media type as filter.
+
+**Scenario:**
+A business traveller wants to receive only first-class offers available as a mobile ticket.
+The journey is from Rotterdam Centraal to Amsterdam Centraal on 2 June 2026, departing at 07:15.
+
+---
+
+### TC-009 — Request trips before/after a requested (departure) time
+
+**Purpose:** request a few offers before and after the requested time.
+
+**Scenario:**
+A traveller wants to take the train from Amsterdam to Berlin on 25 July 2026, preferably
+departing around 10:00. The caller wants at most 2 alternatives before and 5 after this time,
+with prices expressed in euros.
+
+---
+
+### TC-010 — Traveller with an assistance animal
+
+**Purpose:** verify that a guide dog or assistance animal can be included as a separate travelling
+entity (animal), so it can be offered free of charge.
+
+**Scenario:**
+A visually impaired traveller travels with their guide dog from Groningen to Leeuwarden on
+8 August 2026, departing at 13:20. The guide dog travels free of charge; the system must
+recognise the animal as an assistance animal and return only offers that permit it.
+
+---
+
+### TC-011 — International multi-operator rail journey
+
+**Purpose:** express an international journey spanning services from multiple operators
+(e.g. Eurostar + SNCF), as a multi-leg trip pattern, with each operator's
+service journey identified separately (OJP outcome).
+
+**Scenario:**
+A traveller wants to travel from Amsterdam Centraal to Paris Gare du Nord on 10 March 2026.
+The journey consists of a Thalys/Eurostar high-speed service with a single through service
+journey. The traveller holds a standard second-class ticket. No entitlement rights apply.
+The server is expected to return cross-border fare combinations from all participating operators.
+
+---
+
+### TC-012 — Promotional code as entitlement right
+
+**Purpose:** verify that a promotional discount code is correctly transmitted as an entitlement
+right so that the server can apply campaign pricing where applicable.
+
+**Scenario:**
+A traveller has received a promotional discount code (`PROMO25`) from a campaign run by an
+operator. The traveller wants to travel from Brussels-Midi to Cologne on 15 May 2026, departing
+at 11:07. The server should recognise the code and include discounted offers where the promotion
+applies, alongside full-price offers.
+
+---
+
+### TC-013 — Large group booking
+
+**Purpose:** verify that a large travel party (10 travellers) is correctly processed and that
+the server can return group fares where applicable, which typically require a minimum party size.
+
+**Scenario:**
+A group of 10 adults (e.g. a corporate team) wants to travel from Paris Gare de Lyon to Lyon
+Part-Dieu by TGV on 22 June 2026, departing at 07:00. The server should detect the group size
+and return group-rate offers alongside individual offers where available.
+
+---
+
+### TC-014 — search with mode filter
+
+**Purpose:** express an origin–destination pair without a fixed service journey reference combined with a mode filter.
+
+**Scenario:**
+A traveller wants to travel from Den Haag Centraal to Delft on any rail or bus service on
+18 September 2026, arriving before 09:00. The caller does not know the exact service; the server
+must search for all matching departures and return offers. Only bus and rail modes are accepted.
+
+--
+
+### TC-015 — Requested sections on a through journey
+
+**Purpose:** verify that the `requestedSections` filter correctly limits the offer search to a
+specific portion of a longer through journey (e.g. boarding mid-route or alighting early).
+
+**Scenario:**
+A traveller is already on a through train from Amsterdam to Eindhoven but wants to purchase
+a ticket only for the Utrecht–Eindhoven section. The request includes the full trip pattern
+but a `requestedSections` entry restricts the offer search to the segment starting at Utrecht.
+
+---
+
+### TC-016 — Traveller with mandatory information (nationality/residency)
+
+**Purpose:** verify that nationality and country of residency, which determine eligibility for
+domestic vs. international fares.
+
+**Scenario:**
+A traveller with Belgian nationality and French residency wants to travel from Paris to Brussels
+on 5 October 2026. The traveller's qualifying characteristics must be transmitted so that the
+server can determine eligibility for domestic Belgian fares, domestic French fares, or full
+international pricing.
+
+---
+
+### TC-017 — Multi-modal journey: timed leg + continuous leg (walk)
+
+**Purpose:** verify that a trip pattern combining a timed public transport leg with a
+continuous leg (taxi) is correctly expressed.
+
+**Scenario:**
+A traveller wants to go from Rotterdam Centraal to a hotel near Beurs square. The trip consists
+of a Metro leg (timed) followed by a 7-minute taxi ride (continuous).
+
+---
+
+### TC-018 — Place specified by geo-coordinates - Non trip based
+
+**Purpose:** on-demand ride or last-mile service can specify its origin and destination
+as geo-coordinate–based places rather than stop references.
+
+**Scenario:**
+A traveller wants to book a taxi or shared-ride from their current geo-location (52.3667°N,
+4.9041°E — near Amsterdam Sloterdijk) to Amsterdam Centraal on 12 November 2026 around 08:00.
+The leg is continuous (no fixed timetable). The server must accept the coordinate-based
+`Place` objects and return mobility offers.
+
+---
+
+### TC-019 — Multi-leg journey with an explicit transfer leg
+
+**Purpose:** verify that a trip pattern containing an explicit transfer leg between two timed
+services is correctly expressed, and that the server does not attempt to price the transfer
+itself but correctly associates offers with the surrounding timed legs.
+
+**Scenario:**
+A traveller travels from Antwerp-Centraal to Amsterdam Centraal, requiring a change at
+Rotterdam Centraal. The trip pattern contains three legs: a timed Thalys/IC service
+(Antwerp→Rotterdam), an explicit transfer leg (platform change at Rotterdam), and a second
+timed IC service (Rotterdam→Amsterdam). The TOMP server must return separate offers for each
+timed leg and handle the transfer gracefully.
diff --git a/deliverables/1 search offers/to do.md b/deliverables/1 search offers/to do.md
new file mode 100644
index 0000000..8a73b62
--- /dev/null
+++ b/deliverables/1 search offers/to do.md
@@ -0,0 +1,44 @@
+## Things to do
+
+* cope with the group id / fare zones / networks / geospatial filters / custom filter in the request offer filters
+
+* add sorting, limit/offset in search offer policy
+
+* find other name of 'ENTITLEMENT RIGHT'. It must also be used for reduction purposes like mediatype, distribution channel, payment types, ...
+
+* errors/warnings on offers
+
+* status on offer elements (to discuss)
+
+* document the process of versioning (of locked offers)
+
+* Find out how taxIds work. Where should this be administered?
+
+*****
+- how to limit the amount of offers? => functional,
+- temporal & spatial validity (on the offer)
+- name & description
+-
+
+[ {
+ id: 1
+ objectType: seat allocation,
+ seatType: BERTH
+ },
+ {
+ id: 2,
+ objectType: seat allocation,
+ seatType: BERTH
+ },
+ {
+ id: 3,
+ objectType: seat allocation,
+ seatType: COUCHETTE
+ },
+ {
+ id: 4,
+ objectType: travel right,
+ providedSections: [ { legRef: 1, legRef: 2 } ] // or trip pattern
+ reqSpotAlloc: [ { legRef: 1, min: 1, max: 2, chooseFrom: [ 1, 2 ] } } ]
+ }
+]
\ No newline at end of file
diff --git a/deliverables/2 lock offer/lock-offer-model.qea b/deliverables/2 lock offer/lock-offer-model.qea
new file mode 100644
index 0000000..9393b3a
Binary files /dev/null and b/deliverables/2 lock offer/lock-offer-model.qea differ
diff --git a/deliverables/2 lock offer/lock-offer.html b/deliverables/2 lock offer/lock-offer.html
new file mode 100644
index 0000000..1b6d577
--- /dev/null
+++ b/deliverables/2 lock offer/lock-offer.html
@@ -0,0 +1,41 @@
+
+
+
+
+
+ OpenAPI Preview — lock-offer.yaml
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deliverables/2 lock offer/lock-offer.yaml b/deliverables/2 lock offer/lock-offer.yaml
new file mode 100644
index 0000000..f89423b
--- /dev/null
+++ b/deliverables/2 lock offer/lock-offer.yaml
@@ -0,0 +1,698 @@
+openapi: 3.1.0
+info:
+ title: OTI — Lock offer
+ version: 0.1.0-draft
+ description: Locks a selected SALES OFFER PACKAGE and returns a LOCKED OFFER with a time-limited hold. A second endpoint retrieves the full detail of a locked offer.
+paths:
+
+ # ── Endpoint 1: Lock offer ────────────────────────────────────────────
+
+ /lock-offers:
+ post:
+ summary: 'OSDM 3.7.1: POST /lock-offers'
+ operationId: lock_offer_post_lock_offers
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferDelivery'
+
+ /processes/lock-offers/execute:
+ post:
+ summary: 'OMSA 0.1.0: POST /processes/lock-offers/execute'
+ operationId: omsa_lock_offer_post_processes_lock_offers_execute
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferDelivery'
+
+ /processes/select-offer/execution:
+ post:
+ summary: 'TOMP-API 2.0.0: POST /processes/select-offer/execution'
+ operationId: lock_offer_post_processes_select_offer_execution
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferRequest'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ Expiry-date:
+ $ref: '#/components/headers/expires'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockOfferDelivery'
+
+ # ── Endpoint 2: Locked offer detail ──────────────────────────────────────
+
+ /locked-offers/{lockedOfferId}:
+ get:
+ summary: 'OSDM 3.7.1: GET /locked-offers/{lockedOfferId}'
+ operationId: lock_offer_get_locked_offers_lockedOfferId
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - name: lockedOfferId
+ in: path
+ required: true
+ description: Identifier of the locked offer to retrieve, as returned by the lock-offer operation.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockedOffer'
+
+ /collections/locked-offer-details/items:
+ get:
+ summary: 'OMSA 0.1.0: GET /collections/locked-offer-details/items'
+ operationId: omsa_lock_offer_get_collections_locked_offer_details_items
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - name: lockedOfferId
+ in: query
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockedOffer'
+
+ /collections/offer-details/items:
+ get:
+ summary: 'TOMP-API 2.0.0: GET /collections/offer-details/items'
+ operationId: lock_offer_get_collections_offer_details_items
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - name: lockedOfferId
+ in: query
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: Success
+ headers:
+ Version:
+ $ref: '#/components/headers/version'
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LockedOffer'
+
+components:
+ schemas:
+
+ # ─── REQUEST ───────────────────────────────────────────────────────────────────────────
+
+ LockOfferRequest:
+ type: object
+ additionalProperties: false
+ description: LOCK OFFER REQUEST — locks a specific offer from the search result, optionally selecting allocations (e.g. seat reservations) and ancillaries.
+ required:
+ - offerReference
+ properties:
+ offerReference:
+ type: string
+ description: Reference to the offer (offerId) returned by the search-offers operation that is to be locked.
+ aftersalesByRetailerOnly:
+ type: boolean
+ description: When true, after-sales operations on this offer may only be performed by the retailer, not the passenger directly.
+ externalRef:
+ type: string
+ description: Caller-assigned external reference for this lock request, for correlation with the caller's own booking system.
+ allocations:
+ type: array
+ description: Specific allocations (e.g. seat or space reservations) requested alongside the lock.
+ items:
+ $ref: '#/components/schemas/AllocationSelection'
+ ancillaries:
+ type: array
+ description: Ancillary services requested alongside the lock.
+ items:
+ $ref: '#/components/schemas/AncillarySelection'
+
+ AllocationSelection:
+ type: object
+ additionalProperties: false
+ description: ALLOCATION SELECTION — a reference to a specific allocation offer element the traveller wishes to select as part of the lock request.
+ required:
+ - allocationReference
+ properties:
+ allocationReference:
+ type: string
+ description: Reference to the allocation offer element (offerElementId) to be selected.
+
+ AncillarySelection:
+ type: object
+ additionalProperties: false
+ description: ANCILLARY SELECTION — a reference to a specific ancillary offer element the traveller wishes to include in the lock request.
+ required:
+ - ancillaryReference
+ properties:
+ ancillaryReference:
+ type: string
+ description: Reference to the ancillary offer element (offerElementId) to be included.
+
+ # ─── LOCK OFFER DELIVERY ─────────────────────────────────────────────────────────────
+
+ LockOfferDelivery:
+ type: object
+ additionalProperties: false
+ description: LOCK OFFER DELIVERY — the server's response to a lock-offer request. Contains the locked-offer identifier, expiry time, and optionally the full locked offer detail.
+ required:
+ - lockedOfferId
+ - expiryTime
+ - offerRef
+ properties:
+ lockedOfferId:
+ type: string
+ description: Server-assigned unique identifier for the locked offer. Use this to retrieve full detail via the locked-offer-detail endpoint.
+ expiryTime:
+ $ref: '#/components/schemas/dateTime'
+ description: Date-time at which the lock expires and the offer is released.
+ offerRef:
+ type: string
+ description: Reference to the original offer (offerId) that was locked.
+ lockedOffer:
+ description: Full detail of the locked offer, if the server includes it immediately. May be absent when the detail must be fetched via a separate request.
+ $ref: '#/components/schemas/LockedOffer'
+ warnings:
+ type: array
+ description: Non-fatal warnings about the lock operation (e.g. partial availability, changed conditions).
+ items:
+ $ref: '#/components/schemas/Warning'
+ links:
+ type: array
+ description: Hypermedia links for further actions (e.g. confirm, release, get detail).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ # ─── LOCKED OFFER ─────────────────────────────────────────────────────────────────────────────
+
+ LockedOffer:
+ type: object
+ additionalProperties: false
+ description: LOCKED OFFER — a time-limited hold on a purchasable combination of offer elements, with full pricing and condition detail.
+ required:
+ - lockedOfferId
+ - status
+ properties:
+ lockedOfferId:
+ type: string
+ description: Server-assigned unique identifier for this locked offer.
+ name:
+ type: string
+ description: Human-readable name of the locked offer.
+ summary:
+ type: string
+ description: Short human-readable summary of the locked offer.
+ matching:
+ type: string
+ description: Indicates how well this locked offer matches the original request.
+ x-extensible-enum:
+ - exact
+ - partial
+ - none
+ status:
+ type: string
+ description: Current status of the locked offer.
+ enum:
+ - locked
+ - expired
+ - cancelled
+ - confirmed
+ afterSalesFlexibility:
+ type: array
+ description: After-sales conditions applicable to this locked offer (e.g. refundable, exchangeable).
+ items:
+ type: string
+ x-extensible-enum:
+ - refundable
+ - exchangeable
+ - nonRefundable
+ - nonExchangeable
+ personalInformationRequired:
+ type: boolean
+ description: When true, personal traveller information (e.g. name, date of birth) must be supplied before confirmation.
+ externalRef:
+ type: string
+ description: Echo of the caller-assigned external reference from the lock request.
+ elements:
+ type: array
+ minItems: 1
+ description: The offer elements (travel rights, ancillaries, allocations) that make up this locked offer.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/TravelRight'
+ - $ref: '#/components/schemas/Ancillary'
+ - $ref: '#/components/schemas/SpotAllocation'
+ - $ref: '#/components/schemas/AssetAllocation'
+ discriminator:
+ propertyName: offerElementType
+ mapping:
+ travelRight: '#/components/schemas/TravelRight'
+ ancillary: '#/components/schemas/Ancillary'
+ spotAllocation: '#/components/schemas/SpotAllocation'
+ assetAllocation: '#/components/schemas/AssetAllocation'
+ minimumPrice:
+ description: Minimum total price of this locked offer (e.g. before optional ancillaries).
+ $ref: '#/components/schemas/Price'
+ summaryDetails:
+ type: array
+ description: Summaries of the journey geometry and temporal details covered by this locked offer.
+ items:
+ $ref: '#/components/schemas/SummaryDetail'
+ providedSections:
+ type: array
+ description: The journey sections covered by this locked offer.
+ items:
+ $ref: '#/components/schemas/ProvidedSections'
+ guarantees:
+ type: array
+ description: Guarantees associated with this locked offer (e.g. connection guarantee, seat guarantee).
+ items:
+ $ref: '#/components/schemas/Guarantee'
+ links:
+ type: array
+ description: Hypermedia links for further actions (e.g. confirm, release, add ancillary).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ # ─── OFFER ELEMENTS ──────────────────────────────────────────────────────────────────────────
+
+ OfferElement:
+ type: object
+ description: OFFER ELEMENT — base class for all elements within a locked offer. Use the offerElementType discriminator to select the concrete sub-type.
+ required:
+ - offerElementType
+ - offerElementId
+ properties:
+ offerElementId:
+ type: string
+ description: Server-assigned unique identifier for this offer element.
+ offerElementType:
+ type: string
+ description: Discriminator identifying the concrete offer element type.
+ travellingEntities:
+ type: array
+ description: References (travellingEntityId) to the travelling entities this element applies to.
+ items:
+ type: string
+ matching:
+ type: string
+ description: Indicates how well this offer element matches the original request.
+ x-extensible-enum:
+ - exact
+ - partial
+ - none
+ requiredInformation:
+ description: Personal information required for this offer element before confirmation. Detail TBD.
+ $ref: '#/components/schemas/RequiredInformation'
+ price:
+ description: Price of this individual offer element.
+ $ref: '#/components/schemas/Price'
+ fareProduct:
+ type: string
+ description: Reference to the fare product associated with this offer element (productRef).
+ guarantees:
+ type: array
+ description: Guarantees associated with this offer element.
+ items:
+ $ref: '#/components/schemas/Guarantee'
+ providedSections:
+ type: array
+ description: The journey sections covered by this offer element.
+ items:
+ $ref: '#/components/schemas/ProvidedSections'
+
+ TravelRight:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ additionalProperties: false
+ description: TRAVEL RIGHT — an offer element conferring the right to travel on a specific section of the journey.
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: travelRight
+ ancillaries:
+ type: array
+ description: Ancillaries included in or associated with this travel right.
+ items:
+ $ref: '#/components/schemas/Ancillary'
+ allocations:
+ type: array
+ minItems: 1
+ description: Allocations (seat or space reservations) associated with this travel right.
+ items:
+ oneOf:
+ - $ref: '#/components/schemas/SpotAllocation'
+ - $ref: '#/components/schemas/AssetAllocation'
+ discriminator:
+ propertyName: offerElementType
+ mapping:
+ spotAllocation: '#/components/schemas/SpotAllocation'
+ assetAllocation: '#/components/schemas/AssetAllocation'
+
+ Ancillary:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ additionalProperties: false
+ description: ANCILLARY — an offer element for an optional ancillary service (e.g. meal, extra luggage, bike transport).
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: ancillary
+ ancillaryId:
+ type: string
+ description: Server-assigned identifier for this ancillary.
+ type:
+ type: string
+ description: Type of ancillary service (operator-defined lookup value).
+
+ Allocation:
+ allOf:
+ - $ref: '#/components/schemas/OfferElement'
+ - type: object
+ description: ALLOCATION — base class for seat or space allocations within a locked offer. Use the offerElementType discriminator to select the concrete sub-type (spotAllocation or assetAllocation).
+ required:
+ - offerElementType
+
+ SpotAllocation:
+ allOf:
+ - $ref: '#/components/schemas/Allocation'
+ - type: object
+ additionalProperties: false
+ description: SPOT ALLOCATION — an allocation to a specific spot (e.g. seat, berth, parking space) identified by leg and place references.
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: spotAllocation
+ legId:
+ type: string
+ description: Reference to the leg (legId) on which this allocation applies.
+ startPlace:
+ type: string
+ description: Reference to the stop point where this allocation begins (boarding).
+ endPlace:
+ type: string
+ description: Reference to the stop point where this allocation ends (alighting).
+ typeOfSpot:
+ type: string
+ description: Category of the allocated spot.
+ x-extensible-enum:
+ - seat
+ - berth
+ - compartment
+ - parkingSpace
+ - other
+
+ AssetAllocation:
+ allOf:
+ - $ref: '#/components/schemas/Allocation'
+ - type: object
+ additionalProperties: false
+ description: ASSET ALLOCATION — an allocation to a named asset (e.g. a specific vehicle slot, a named cabin). Detail TBD.
+ required:
+ - offerElementType
+ properties:
+ offerElementType:
+ type: string
+ const: assetAllocation
+
+ # ─── SUPPORTING TYPES ───────────────────────────────────────────────────────────────────────
+
+ Price:
+ type: object
+ additionalProperties: false
+ description: PRICE — a monetary amount in a specific currency.
+ required:
+ - currencyCode
+ - amount
+ properties:
+ currencyCode:
+ type: string
+ description: ISO 4217 currency code (e.g. EUR, GBP, SEK).
+ amount:
+ type: number
+ format: double
+ description: Monetary amount in the specified currency.
+ vat:
+ type: array
+ description: VAT breakdown applicable to this price.
+ items:
+ $ref: '#/components/schemas/Vat'
+
+ Vat:
+ type: object
+ additionalProperties: false
+ description: VAT — a VAT component of a price, broken down by country and percentage.
+ required:
+ - amount
+ - currencyCode
+ - country
+ - percentage
+ properties:
+ amount:
+ type: number
+ format: double
+ description: VAT amount in the specified currency.
+ currencyCode:
+ type: string
+ description: ISO 4217 currency code for this VAT component.
+ country:
+ type: string
+ description: ISO 3166-1 alpha-2 country code for which this VAT rate applies.
+ percentage:
+ type: number
+ format: double
+ description: VAT percentage rate (e.g. 21.0 for 21%).
+
+ ProvidedSections:
+ type: object
+ additionalProperties: false
+ description: PROVIDED SECTIONS — identifies the journey section (from–to legs) covered by an offer or offer element.
+ properties:
+ startLegId:
+ type: string
+ description: Identifier of the first leg in this section.
+ endLegId:
+ type: string
+ description: Identifier of the last leg in this section.
+ startPlace:
+ type: string
+ description: Reference to the departure place of this section.
+ endPlace:
+ type: string
+ description: Reference to the arrival place of this section.
+ tripPatternRef:
+ type: string
+ description: Reference to the trip pattern this section belongs to.
+
+ SummaryDetail:
+ type: object
+ additionalProperties: false
+ description: SUMMARY DETAIL — a human-readable summary of the journey geometry and temporal span covered by a locked offer.
+ properties:
+ geometry:
+ type: string
+ description: Geometric description of the journey (e.g. origin–destination name pair or GeoJSON). Detail TBD.
+ temporal:
+ type: string
+ description: Temporal description of the journey (e.g. departure–arrival date-time range). Detail TBD.
+ conditions:
+ type: string
+ description: Human-readable summary of the applicable fare conditions.
+
+ Guarantee:
+ type: object
+ additionalProperties: false
+ description: GUARANTEE — a guarantee associated with an offer or offer element (e.g. connection guarantee, seat guarantee). Detail TBD.
+
+ RequiredInformation:
+ type: object
+ additionalProperties: false
+ description: REQUIRED INFORMATION — personal information that must be provided for an offer element before confirmation. Detail TBD.
+
+ Warning:
+ type: object
+ additionalProperties: false
+ description: WARNING — a non-fatal condition raised during the lock operation (e.g. partial availability, changed price). Detail TBD.
+
+ # ─── SHARED ───────────────────────────────────────────────────────────────────────────────────
+
+ Link:
+ type: object
+ additionalProperties: false
+ x-externalDocs:
+ url: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
+ required:
+ - href
+ - rel
+ properties:
+ rel:
+ type: string
+ description: the action that can be performed OR part of the URI allowed values include the 'processId's, prefixes
+ for the referenced data sources, prefixes for deeplinks ('apple' and 'android'), OGC compliant ones (alternative,
+ next, etc)
+ description:
+ type: string
+ description: the description of the external data source
+ method:
+ type: string
+ description: to indicate the http method.
+ default: GET
+ enum:
+ - POST
+ - GET
+ - DELETE
+ - PATCH
+ type:
+ type: string
+ description: allowed values are described by IANA, ("application/geo+json")
+ href:
+ $ref: '#/components/schemas/url'
+ availableFrom:
+ $ref: '#/components/schemas/dateTime'
+ body:
+ type: object
+ description: the body template for the request. Replace $parametername$ in the body.
+ example:
+ packageId: $packageId$
+ expires:
+ $ref: '#/components/schemas/dateTime'
+ headers:
+ additionalProperties:
+ type: string
+
+ # ─── PRIMITIVES ────────────────────────────────────────────────────────────────────────────────
+
+ dateTime:
+ type: string
+ format: date-time
+ x-pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$
+ description: https://www.rfc-editor.org/rfc/rfc3339#section-5.6, date-time (2019-10-12T07:20:50.52Z)
+
+ url:
+ type: string
+ description: valid URL
+ format: uri
+
+ httpDate:
+ type: string
+ description: A HTTP date string
+ x-format: http-date
+ x-externalDocs:
+ url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires
+ description: http-date
+
+ headers:
+ contentLanguage:
+ description: The language/localization of user-facing content, One IETF BCP 47 (RFC 5646) language tag (nl-NL)
+ schema:
+ type: string
+ pattern: ^[a-zA-Z]+-[a-zA-Z]+$
+ required: true
+ expires:
+ description: the offer expires at this timestamp
+ schema:
+ $ref: '#/components/schemas/httpDate'
+ required: false
+ version:
+ description: the version used to format the response
+ schema:
+ type: string
+ required: true
+
+ parameters:
+ requestor:
+ name: Requestor
+ in: header
+ description: The requestor header contains detailed information about who is calling the API. It can include information
+ such as channel, organization, sales unit or workstation id and be used to configure e.g. the fare range provided
+ to the caller. The content of the string is part of a bilateral contract by the two parties and not standardized by
+ OSDM. It is recommend to encrypt the information transferred.
+ schema:
+ type: string
+ traceState:
+ name: tracestate
+ in: header
+ description: 'The tracestate extends traceparent with vendor-specific data represented by a set of name/value pairs.
+
+ Storing information in tracestate is optional (see W3C Trace Context).'
+ schema:
+ type: string
+ acceptLanguage:
+ name: Accept-Language
+ in: header
+ description: 'Describes the set of natural languages that are preferred for localized text in the response
+
+ to the request (see RFC9110). Supporting English (en) is a must.'
+ schema:
+ type: string
diff --git a/deliverables/2 lock offer/lookup.html b/deliverables/2 lock offer/lookup.html
new file mode 100644
index 0000000..585bed4
--- /dev/null
+++ b/deliverables/2 lock offer/lookup.html
@@ -0,0 +1,41 @@
+
+
+
+
+
+ OpenAPI Preview — lookup.yaml
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deliverables/2 lock offer/lookup.yaml b/deliverables/2 lock offer/lookup.yaml
new file mode 100644
index 0000000..27c4c83
--- /dev/null
+++ b/deliverables/2 lock offer/lookup.yaml
@@ -0,0 +1,391 @@
+openapi: 3.1.0
+info:
+ title: OTI — Lookup tables (Lock Offer)
+ version: 0.1.0-draft
+ description: >
+ Provides read-only access to the operator-defined lookup tables (code lists) used in the
+ OTI Lock Offer API. Each lookup table is accessible via two path patterns:
+
+ - **REST style** — `GET /{lookup-type}` — returns all items of a given code list.
+ - **OGC Records API style** — `GET /collections/{lookup-type}/items` — returns the same
+ items conforming to the OGC API - Records (Part 1) item-collection response structure.
+
+ The three lookup tables correspond to the attributes marked as `lookup` in the OTI model:
+
+ | Path segment | Used by |
+ |---|---|
+ | `personal-needs` | `OfferRequest.travellers[].personalNeeds[]` (echoed from search) |
+ | `ancillary-types` | `Ancillary.type` in locked offer responses |
+ | `entitlement-types` | `EntitlementRight.entitlementType` (echoed from search) |
+
+paths:
+
+ # ─── PERSONAL NEEDS ────────────────────────────────────────────────────────
+
+ /personal-needs:
+ get:
+ summary: List all personal need types
+ operationId: list_personal_needs
+ description: >
+ Returns all valid values for `personalNeeds[]` on a travelling entity.
+ These are operator-defined accessibility and mobility need codes
+ (e.g. motorizedWheelchair, visualImpairment, accompanyingDog).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/personal-needs/items:
+ get:
+ summary: 'OGC Records API: list personal need types'
+ operationId: ogc_list_personal_needs
+ description: >
+ Returns all valid values for `personalNeeds[]` on a travelling entity,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+ # ─── ANCILLARY TYPES ───────────────────────────────────────────────────────
+
+ /ancillary-types:
+ get:
+ summary: List all ancillary types
+ operationId: list_ancillary_types
+ description: >
+ Returns all valid values for `Ancillary.type` in locked offer responses.
+ These are operator-defined ancillary service codes
+ (e.g. bicycleTransport, vehicleTransport, cabin, meal, extraLuggage).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/ancillary-types/items:
+ get:
+ summary: 'OGC Records API: list ancillary types'
+ operationId: ogc_list_ancillary_types
+ description: >
+ Returns all valid values for `Ancillary.type` in locked offer responses,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+ # ─── ENTITLEMENT TYPES ─────────────────────────────────────────────────────
+
+ /entitlement-types:
+ get:
+ summary: List all entitlement right types
+ operationId: list_entitlement_types
+ description: >
+ Returns all valid values for `EntitlementRight.entitlementType` on a travelling entity.
+ These are operator-defined entitlement codes
+ (e.g. discountSubscription, loyaltyCard, concession, promotionCode, railcard).
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LookupCollection'
+
+ /collections/entitlement-types/items:
+ get:
+ summary: 'OGC Records API: list entitlement right types'
+ operationId: ogc_list_entitlement_types
+ description: >
+ Returns all valid values for `EntitlementRight.entitlementType` on a travelling entity,
+ conforming to the OGC API - Records (Part 1) item-collection response structure.
+ parameters:
+ - $ref: '#/components/parameters/acceptLanguage'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/ogcBbox'
+ - $ref: '#/components/parameters/ogcDatetime'
+ responses:
+ '200':
+ description: Success
+ headers:
+ Content-Language:
+ $ref: '#/components/headers/contentLanguage'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/OgcItemCollection'
+
+components:
+ schemas:
+
+ # ─── REST RESPONSE ─────────────────────────────────────────────────────────
+
+ LookupCollection:
+ type: object
+ additionalProperties: false
+ description: A paginated collection of lookup items returned by the REST-style endpoints.
+ required:
+ - items
+ properties:
+ items:
+ type: array
+ description: The lookup items on this page.
+ items:
+ $ref: '#/components/schemas/LookupItem'
+ totalCount:
+ type: integer
+ description: Total number of items in the code list (across all pages).
+ offset:
+ type: integer
+ description: Zero-based offset of the first item on this page.
+ limit:
+ type: integer
+ description: Maximum number of items returned per page.
+ links:
+ type: array
+ description: Pagination links (next, prev, self).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ LookupItem:
+ type: object
+ additionalProperties: false
+ description: A single entry in a lookup table (code list).
+ required:
+ - code
+ - name
+ properties:
+ code:
+ type: string
+ description: The machine-readable code value used in API requests and responses.
+ name:
+ type: string
+ description: Human-readable short label for this code (language follows Accept-Language).
+ description:
+ type: string
+ description: Optional longer description of what this code means.
+ validFrom:
+ type: string
+ format: date
+ description: Date from which this code is valid (inclusive). Omitted if always valid.
+ validTo:
+ type: string
+ format: date
+ description: Date until which this code is valid (inclusive). Omitted if open-ended.
+
+ # ─── OGC RECORDS RESPONSE ──────────────────────────────────────────────────
+
+ OgcItemCollection:
+ type: object
+ additionalProperties: false
+ description: >
+ An OGC API - Records (Part 1) item-collection response.
+ Conforms to the FeatureCollection-like envelope used by OGC Records.
+ required:
+ - type
+ - items
+ properties:
+ type:
+ type: string
+ const: ItemCollection
+ description: Fixed GeoJSON-compatible collection type identifier.
+ items:
+ type: array
+ description: The lookup items on this page, each wrapped in an OGC Record Item envelope.
+ items:
+ $ref: '#/components/schemas/OgcItem'
+ numberMatched:
+ type: integer
+ description: Total number of items matching the query (across all pages).
+ numberReturned:
+ type: integer
+ description: Number of items included in this response page.
+ links:
+ type: array
+ description: Pagination and self-description links (next, prev, self, collection).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ OgcItem:
+ type: object
+ additionalProperties: false
+ description: >
+ An OGC API - Records item envelope wrapping a single lookup entry.
+ Conforms to the OGC Records Item schema.
+ required:
+ - type
+ - id
+ - properties
+ properties:
+ type:
+ type: string
+ const: Feature
+ description: Fixed GeoJSON Feature type identifier (required by OGC Records).
+ id:
+ type: string
+ description: Unique identifier of this record — equal to the lookup code.
+ properties:
+ $ref: '#/components/schemas/LookupItem'
+ links:
+ type: array
+ description: Links related to this item (e.g. self, collection).
+ items:
+ $ref: '#/components/schemas/Link'
+
+ # ─── SHARED ────────────────────────────────────────────────────────────────
+
+ Link:
+ type: object
+ additionalProperties: false
+ x-externalDocs:
+ url: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
+ required:
+ - href
+ - rel
+ properties:
+ rel:
+ type: string
+ description: Link relation type (e.g. self, next, prev, collection, alternate).
+ href:
+ type: string
+ format: uri
+ description: The URL of the linked resource.
+ type:
+ type: string
+ description: Media type of the linked resource (e.g. application/json).
+ title:
+ type: string
+ description: Human-readable label for this link.
+ method:
+ type: string
+ enum:
+ - GET
+ - POST
+ - PUT
+ - PATCH
+ - DELETE
+ default: GET
+ description: HTTP method to use for this link.
+
+ # ─── PRIMITIVES ────────────────────────────────────────────────────────────
+
+ dateTime:
+ type: string
+ format: date-time
+ x-pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$
+ description: https://www.rfc-editor.org/rfc/rfc3339#section-5.6
+
+ parameters:
+ acceptLanguage:
+ name: Accept-Language
+ in: header
+ description: >
+ Preferred language for human-readable fields (name, description).
+ Supporting English (en) is mandatory (see RFC 9110).
+ schema:
+ type: string
+
+ limit:
+ name: limit
+ in: query
+ description: Maximum number of items to return per page (default 100).
+ required: false
+ schema:
+ type: integer
+ minimum: 1
+ maximum: 1000
+ default: 100
+
+ offset:
+ name: offset
+ in: query
+ description: Zero-based index of the first item to return (for pagination).
+ required: false
+ schema:
+ type: integer
+ minimum: 0
+ default: 0
+
+ ogcBbox:
+ name: bbox
+ in: query
+ description: >
+ OGC API bounding box filter (minLon,minLat,maxLon,maxLat).
+ Not applicable to lookup tables but included for OGC Records conformance.
+ required: false
+ schema:
+ type: array
+ items:
+ type: number
+ minItems: 4
+ maxItems: 6
+
+ ogcDatetime:
+ name: datetime
+ in: query
+ description: >
+ OGC API temporal filter (RFC 3339 instant or interval).
+ Filters items by their validFrom/validTo range when provided.
+ required: false
+ schema:
+ type: string
+
+ headers:
+ contentLanguage:
+ description: Language of human-readable content in the response (IETF BCP 47 tag, e.g. nl-NL).
+ schema:
+ type: string
+ pattern: ^[a-zA-Z]+-[a-zA-Z]+$
+ required: true
diff --git a/deliverables/2 lock offer/mappings/mapping-bob.md b/deliverables/2 lock offer/mappings/mapping-bob.md
new file mode 100644
index 0000000..4ae3148
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-bob.md
@@ -0,0 +1,238 @@
+# Mapping: Lock Offer → BoB Product API v3.4.0
+
+Maps each EUDIT **Lock Offer** concept to the corresponding concept/property in the **BoB Product API v3.4.0**.
+
+- **Endpoint 1**: `POST /reservations` (lock) — or `POST /order` in some BoB profiles
+- **Endpoint 2**: `GET /reservations/{reservationId}` (detail)
+- **EUDIT concept / Property** — as defined in `lock-offer.yaml`
+- **BoB concept** — the matching schema object in BoB Product API
+- **BoB property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+**Important scope note**: BoB Product API v3.4.0 operates at the product/reservation layer. A "lock" in EUDIT terms corresponds to a **provisional reservation** (`POST /reservations`) that holds a product before final purchase. BoB does not expose a generic "offer reference" flow; instead, the product to reserve is identified by `productId` and traveller categories. Several EUDIT fields have no BoB equivalent because BoB abstracts traveller and after-sales details.
+
+---
+
+## LockOfferRequest
+
+> Root request body for the lock operation.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `reservationRequest` | `productId` | The EUDIT offer reference must be translated to a BoB `productId` by the integrating system; BoB does not carry a generic offer-session token. |
+| aftersalesByRetailerOnly | boolean | 0..1 | — | — | No equivalent in BoB v3.4.0. After-sales channel restriction is not a reservation parameter. |
+| externalRef | string | 0..1 | `reservationRequest` | `externalReference` | Caller-assigned reference for correlation purposes. |
+| allocations | AllocationSelection | 0..* | `reservationRequest` | `seatPreferences[]` | BoB supports seat preferences as part of the reservation request; specific seat selection maps to `seatPreferences[].seatId`. |
+| ancillaries | AncillarySelection | 0..* | `reservationRequest` | `ancillaryIds[]` | BoB ancillary selection uses `ancillaryIds[]` referencing products from the BoB product catalogue. |
+
+---
+
+## AllocationSelection
+
+> Selection of a specific allocation offer element.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| allocationReference | string | 1..1 | `reservationRequest` | `seatPreferences[].seatId` | The `allocationReference` maps to a seat or space identifier in the BoB seat-map or allocation catalogue. |
+
+---
+
+## AncillarySelection
+
+> Selection of a specific ancillary offer element.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| ancillaryReference | string | 1..1 | `reservationRequest` | `ancillaryIds[]` | The `ancillaryReference` maps to a BoB ancillary product ID from the product catalogue. |
+
+---
+
+## LockedOfferDetailRequest
+
+> Request to retrieve the full detail of a locked offer.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `reservation` | `reservationId` | EUDIT `offerReference` (= `lockedOfferId`) maps to BoB `reservationId`; detail retrieved via `GET /reservations/{reservationId}`. |
+
+---
+
+## LockOfferDelivery
+
+> Server response to the lock-offer request.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `reservation` | `reservationId` | Server-assigned BoB reservation identifier. |
+| expiryTime | dateTime | 1..1 | `reservation` | `expirationDateTime` | BoB `expirationDateTime` — ISO 8601 date-time after which the provisional reservation lapses. |
+| offerRef | string | 1..1 | `reservation` | `productId` | Echo of the source product identifier. |
+| lockedOffer | LockedOffer | 0..1 | `reservation` | (full reservation body) | BoB returns a `reservation` object inline; `lockedOffer` corresponds to this object. |
+| warnings | Warning | 0..* | — | — | BoB v3.4.0 does not define a `warnings[]` field on reservation responses; non-fatal conditions are conveyed through HTTP status codes or error payloads. |
+| links | Link | 0..* | — | — | BoB uses REST resource URIs rather than HATEOAS `links[]` arrays. |
+
+---
+
+## LockedOffer
+
+> The time-limited held offer with full detail.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `reservation` | `reservationId` | |
+| name | string | 0..1 | — | — | No name field on BoB reservation. Product name derivable via `GET /product/{productId}`. |
+| summary | string | 0..1 | `reservation` | `description` | BoB `description` (if present) is the closest equivalent. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| status | string | 1..1 | `reservation` | `status` | BoB reservation statuses: `PROVISIONAL` (= locked), `CONFIRMED`, `CANCELLED`, `EXPIRED`. |
+| afterSalesFlexibility | string | 0..* | — | — | No equivalent field on BoB reservation. After-sales conditions are embedded in the product definition (`GET /product/{productId}`). |
+| personalInformationRequired | boolean | 0..1 | — | — | No equivalent Boolean flag in BoB. Passenger data requirements are defined at product level. |
+| externalRef | string | 0..1 | `reservation` | `externalReference` | Echo of the caller's external reference. |
+| elements | OfferElement | 1..* | `reservation` | `products[]` | Each BoB product within the reservation corresponds to a travel-right or ancillary offer element. |
+| minimumPrice | Price | 0..1 | `reservation` | `totalPrice { amount, currency }` | BoB returns a `totalPrice` at reservation level. |
+| summaryDetails | SummaryDetail | 0..* | — | — | No structured summary in BoB; derivable from product route/validity fields. |
+| providedSections | ProvidedSections | 0..* | `reservation` | `route { from, to }` | BoB expresses the covered section as an origin–destination route reference. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent in BoB Product API v3.4.0. |
+| links | Link | 0..* | — | — | No HATEOAS links in BoB reservation response. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements within the locked offer.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `product` | `productId` | BoB `productId` is the closest equivalent to an offer-element identifier. |
+| offerElementType | string | 1..1 | — | — | Discriminator only; BoB uses product categories instead. |
+| travellingEntities | TravellingEntityReference | 0..* | `reservationRequest` | `travellers[{ categoryId, quantity }]` | BoB associates travellers at reservation level using category codes, not per element. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| requiredInformation | RequiredInformation | 0..1 | — | — | No equivalent per-element required-information structure in BoB. |
+| price | Price | 0..1 | `product` | `price { amount, currency }` | Per-product price as returned by BoB. |
+| fareProduct | FareProduct | 0..1 | `product` | `fareId` | BoB `fareId` references the fare that applies to the product. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent in BoB v3.4.0. |
+| providedSections | ProvidedSections | 0..* | `product` | `route { from, to }` | Origin–destination scope of the product. |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific section.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| offerElementType (travelRight) | — | — | `product` | `fareId` | A travel right is implicit in the BoB fare product; `fareId` links to the applicable fare conditions. |
+| ancillaries | Ancillary | 0..* | `reservation` | `ancillaryIds[]` | Ancillaries are listed as separate ancillary product IDs on the reservation. |
+| allocations | Allocation | 1..* | `reservation` | `seatPreferences[]` | Seat/space allocations are expressed as seat preferences on the reservation. |
+
+---
+
+## Ancillary
+
+> Optional ancillary service.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | `ancillaryProduct` | `ancillaryId` | BoB ancillary product identifier from the product catalogue. |
+| type | string | 0..1 | `ancillaryProduct` | `type` | BoB ancillary type code (e.g. `MEAL`, `BICYCLE`, `LUGGAGE`). |
+
+---
+
+## SpotAllocation
+
+> Allocation to a specific physical spot.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| legId | string | 0..1 | — | — | BoB does not reference allocations by leg ID; allocation scope is implicit from the product/service journey. |
+| startPlace | string | 0..1 | `seatPreference` | `from` | Origin stop for the allocated spot (if directional). |
+| endPlace | string | 0..1 | `seatPreference` | `to` | Destination stop for the allocated spot (if directional). |
+| typeOfSpot | string | 0..1 | `seatPreference` | `type` | Seat/berth type code (e.g. `WINDOW`, `AISLE`, `LOWER_BERTH`). |
+
+---
+
+## AssetAllocation
+
+> Allocation to a named asset.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| (no additional properties) | — | — | `seatPreference` | `seatId` | BoB uses `seatId` to identify a named/specific allocated seat or space. |
+
+---
+
+## TravellingEntityReference
+
+> Reference to a travelling entity.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityRef | integer | 1..1 | `traveller` | `categoryId` | BoB aggregates travellers by category; there is no per-traveller identifier within a reservation. |
+
+---
+
+## Price
+
+> Monetary amount in a currency.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| currencyCode | string | 1..1 | `price` | `currency` | |
+| amount | number | 1..1 | `price` | `amount` | BoB `price.amount` at product or reservation level. |
+| vat | Vat | 0..* | — | — | BoB v3.4.0 does not return a structured VAT breakdown. |
+
+---
+
+## Vat
+
+> VAT component of a price. **No equivalent in BoB Product API v3.4.0.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| amount / currencyCode / country / percentage | various | — | — | — | Not part of BoB reservation response. |
+
+---
+
+## ProvidedSections
+
+> Journey section covered by an offer or element.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | — | — | No leg-level identifier in BoB; scope expressed as route origin. |
+| endLegId | string | 0..1 | — | — | No leg-level identifier in BoB; scope expressed as route destination. |
+| startPlace | string | 0..1 | `route` | `from` | Origin station/stop code (e.g. UIC). |
+| endPlace | string | 0..1 | `route` | `to` | Destination station/stop code (e.g. UIC). |
+| tripPatternRef | string | 0..1 | — | — | No trip-pattern reference in BoB; the reservation is the trip context. |
+
+---
+
+## SummaryDetail
+
+> Human-readable journey summary. **No direct equivalent in BoB Product API v3.4.0.**
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| geometry | string | 0..1 | — | — | Derivable from product route `from`/`to`. |
+| temporal | string | 0..1 | — | — | Derivable from product validity dates/times. |
+| conditions | string | 0..1 | `product` | `conditions[].description` | Product conditions carry after-sales and validity descriptions. |
+
+---
+
+## FareProduct
+
+> Fare product reference.
+
+| Property | Type | Mult. | BoB concept | BoB property | Notes |
+|---|---|---|---|---|---|
+| productRef | string | 0..1 | `product` | `fareId` | BoB `fareId` is the fare-level product reference. |
+
+---
+
+## Guarantee / RequiredInformation / Warning
+
+> Stub types.
+
+| EUDIT concept | BoB concept | BoB property | Notes |
+|---|---|---|---|
+| Guarantee | — | — | No equivalent in BoB Product API v3.4.0. |
+| RequiredInformation | — | — | Passenger data requirements are defined in product configuration, not returned per element. |
+| Warning | — | — | No `warnings[]` array on BoB reservation response. |
diff --git a/deliverables/2 lock offer/mappings/mapping-fgw.md b/deliverables/2 lock offer/mappings/mapping-fgw.md
new file mode 100644
index 0000000..9b8671e
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-fgw.md
@@ -0,0 +1,194 @@
+# Mapping: Lock Offer → FerryGateway 1.3.1
+
+Maps each EUDIT **Lock Offer** concept to the corresponding concept/property in **FerryGateway 1.3.1**.
+
+- **EUDIT concept / Property** — as defined in `lock-offer.yaml`
+- **FerryGateway concept** — the matching XML message / element in FerryGateway 1.3.1
+- **FerryGateway element** — the matching element/attribute name
+- **Notes** — mapping remarks, gaps, or open questions
+
+**Important scope note**: FerryGateway 1.3.1 uses XML request/response messages (not REST/JSON).
+Locking an offer (time-limited hold before payment) maps to the **`CreateReservationRequest`** /
+**`CreateReservationResponse`** message flow. FerryGateway does not have a two-phase lock/confirm
+split identical to OTI; a reservation in FerryGateway is already a committed hold and may require
+payment immediately or within a configurable time window.
+
+This mapping covers:
+
+1. **`CreateReservationRequest`** — the closest equivalent to a lock-offer request
+2. **`CreateReservationResponse`** — the closest equivalent to the lock-offer delivery / locked offer
+
+---
+
+## LockOfferRequest
+
+> Root request body — selects an offer and optionally specifies allocations and ancillaries to include.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `CreateReservationRequest` | `QuoteId` / `PriceId` | The previously retrieved price-quote reference is passed back to identify the offer to book. |
+| aftersalesByRetailerOnly | boolean | 0..1 | — | — | No equivalent; after-sales permissions are operator policy, not a request flag. |
+| externalRef | string | 0..1 | `CreateReservationRequest` | `AgentReference` | Caller's own booking reference. |
+| allocations | AllocationSelection | 0..* | `CreateReservationRequest` | `ServiceItems[]` | Seat/cabin/vehicle-deck allocation; FerryGateway uses service codes to select specific accommodation types. No direct spot-reference mechanism. |
+| ancillaries | AncillarySelection | 0..* | `CreateReservationRequest` | `ServiceItems[]` | Optional services (meals, pets, etc.) passed as service code items. |
+
+---
+
+## AllocationSelection
+
+> Selects a specific allocation offer element.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| allocationReference | string | 1..1 | `CreateReservationRequest` | `ServiceCode` | FerryGateway identifies accommodation by service code (e.g. cabin grade), not by a server-assigned allocation reference. |
+
+---
+
+## AncillarySelection
+
+> Selects a specific ancillary offer element.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| ancillaryReference | string | 1..1 | `CreateReservationRequest` | `ServiceCode` | Same as allocation — ancillaries selected by service code. |
+
+---
+
+## LockOfferDelivery
+
+> Server response to a lock-offer request — contains the locked-offer identifier and expiry.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `CreateReservationResponse` | `ReservationId` | FerryGateway assigns a `ReservationId` that identifies the hold. |
+| expiryTime | dateTime | 1..1 | `CreateReservationResponse` | `ExpiryDateTime` | Time by which payment must be made before the reservation is released. |
+| offerRef | string | 1..1 | `CreateReservationResponse` | `QuoteId` | Echo of the price-quote reference used in the request. |
+| lockedOffer | LockedOffer | 0..1 | `CreateReservationResponse` | (inline details) | FerryGateway typically returns full reservation details in the same response. |
+| warnings | Warning | 0..* | `CreateReservationResponse` | `Warnings[]` | Non-fatal conditions (e.g. accommodation changed, price adjusted). |
+| links | Link | 0..* | — | — | No hypermedia links in FerryGateway XML. |
+
+---
+
+## LockedOffer
+
+> Full detail of the time-limited hold.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `CreateReservationResponse` | `ReservationId` | |
+| name | string | 0..1 | — | — | No equivalent; a human-readable name is not part of the reservation response. |
+| summary | string | 0..1 | — | — | No equivalent. |
+| matching | string (x-enum) | 0..1 | — | — | No equivalent; FerryGateway either fulfils the request or returns an error. |
+| status | string (enum) | 1..1 | `CreateReservationResponse` | `ReservationStatus` | FerryGateway statuses: `Confirmed`, `Cancelled`, `AwaitingPayment`. Mapped to OTI `locked` / `expired` / `cancelled` / `confirmed`. |
+| afterSalesFlexibility | string[] | 0..* | `CreateReservationResponse` | `TicketConditions` | Conditions describing refundability / exchangeability returned as coded values. |
+| personalInformationRequired | boolean | 0..1 | — | — | Not a flag in FerryGateway; passenger details (name, passport) may be required depending on route/operator configuration. |
+| externalRef | string | 0..1 | `CreateReservationResponse` | `AgentReference` | Echo of caller's reference. |
+| elements | OfferElement | 1..* | `CreateReservationResponse` | `ReservationItems[]` | See offer-element mapping below. |
+| minimumPrice | Price | 0..1 | `CreateReservationResponse` | `TotalPrice { Amount, Currency }` | |
+| summaryDetails | SummaryDetail | 0..* | — | — | No equivalent. |
+| providedSections | ProvidedSections | 0..* | `CreateReservationResponse` | `SailingId`, `RouteCode` | Sailing identity echoed in the response. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent in FerryGateway. |
+| links | Link | 0..* | — | — | No hypermedia links. |
+
+---
+
+## OfferElement (base)
+
+> Base class for all elements within the locked offer.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `ReservationItem` | `ItemId` | |
+| offerElementType | string | 1..1 | — | — | Discriminator only; not present in FerryGateway. |
+| travellingEntities | string[] | 0..* | `ReservationItem` | `PassengerRef` / `VehicleRef` | FerryGateway links items to passengers/vehicles by reference. |
+| matching | string (x-enum) | 0..1 | — | — | No equivalent. |
+| requiredInformation | RequiredInformation | 0..1 | — | — | No equivalent at this stage; passenger data collected separately. |
+| price | Price | 1..1 | `ReservationItem` | `Amount`, `Currency` | Per-item price. |
+| fareProduct | string | 0..1 | `ReservationItem` | `ServiceCode` | Service or product code identifying the fare product. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent. |
+| providedSections | ProvidedSections | 0..* | `ReservationItem` | `SailingId` | Sailing reference per item. |
+
+---
+
+## TravelRight
+
+> Offer element conferring the right to travel on a section.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (OfferElement properties) | — | — | `ReservationItem` | — | See OfferElement above. |
+| ancillaries | Ancillary | 0..* | `ReservationItem` | `ServiceItems[]` | Included ancillaries returned as child service items. |
+| allocations | SpotAllocation / AssetAllocation | 0..* | `ReservationItem` | `CabinGrade`, `DeckLevel` | Accommodation details returned per item; no individual seat reference at this level. |
+
+---
+
+## Ancillary
+
+> Optional service element.
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | `ServiceItem` | `ServiceCode` | |
+| type | string (lookup) | 0..1 | `ServiceItem` | `ServiceCode` | The ancillary type (e.g. `meal`, `petTransport`) maps to a FerryGateway service code. |
+
+---
+
+## SpotAllocation
+
+> Allocation to a specific spot (seat, berth, parking space).
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| legId | string | 0..1 | `ReservationItem` | `SailingId` | FerryGateway allocation is per sailing, not per NeTEx leg reference. |
+| startPlace | string | 0..1 | — | — | Not applicable; boarding/alighting ports are at sailing level. |
+| endPlace | string | 0..1 | — | — | Not applicable. |
+| typeOfSpot | string (x-enum) | 0..1 | `AccommodationType` | `CabinGrade` / `DeckType` | FerryGateway uses cabin grade codes; exact `seat` / `berth` mapping depends on operator. |
+
+---
+
+## AssetAllocation
+
+> Allocation to a named asset. **No direct equivalent in FerryGateway.**
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| (OfferElement properties) | — | — | — | — | Named asset allocations have no equivalent in FerryGateway 1.3.1. |
+
+---
+
+## Price
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| currencyCode | string | 1..1 | `Amount` | `Currency` | ISO 4217. |
+| amount | number | 1..1 | `Amount` | `Value` | |
+| vat | Vat | 0..* | — | — | No VAT breakdown in FerryGateway 1.3.1; price is typically inclusive. |
+
+---
+
+## ProvidedSections
+
+| Property | Type | Mult. | FerryGateway concept | FerryGateway element | Notes |
+|---|---|---|---|---|---|
+| startLegId / endLegId | string | 0..1 | `ReservationItem` | `SailingId` | Single sailing per item in FerryGateway; no multi-leg section concept. |
+| startPlace / endPlace | string | 0..1 | `CreateReservationResponse` | `RouteCode` (port parts) | Origin/destination ports in UN/LOCODE format. |
+| tripPatternRef | string | 0..1 | — | — | No trip pattern concept in FerryGateway. |
+
+---
+
+## SummaryDetail / Guarantee / RequiredInformation / Warning
+
+| EUDIT concept | FerryGateway concept | Notes |
+|---|---|---|
+| SummaryDetail | — | No equivalent; journey summary not included in FerryGateway reservation response. |
+| Guarantee | — | No equivalent. |
+| RequiredInformation | — | Personal data requirements communicated out-of-band or via operator configuration. |
+| Warning | `CreateReservationResponse` `Warnings[]` | Non-fatal conditions returned as coded warning messages. |
+
+---
+
+## Link
+
+| EUDIT concept | FerryGateway concept | Notes |
+|---|---|---|
+| Link | — | FerryGateway uses a request/response XML model; no hypermedia links. Follow-up operations (payment, cancellation) use dedicated message types (`ConfirmReservationRequest`, `CancelReservationRequest`). |
diff --git a/deliverables/2 lock offer/mappings/mapping-omsa.md b/deliverables/2 lock offer/mappings/mapping-omsa.md
new file mode 100644
index 0000000..937a007
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-omsa.md
@@ -0,0 +1,238 @@
+# Mapping: Lock Offer → OMSA 0.1.0
+
+Maps each EUDIT **Lock Offer** concept to the corresponding concept/property in **OMSA 0.1.0**.
+
+- **Endpoint 1**: `POST /processes/lock-offers/execute`
+- **Endpoint 2**: `POST /processes/locked-offer-details/execute`
+- **EUDIT concept / Property** — as defined in `lock-offer.yaml`
+- **OMSA concept** — the matching schema object in OMSA 0.1.0
+- **OMSA property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+OMSA follows the OGC API Processes pattern: both endpoints use a `POST .../execute` call with a typed input object, returning a synchronous result. OMSA 0.1.0 does not define a dedicated *lock-offer* process; the closest equivalent is creating a **provisional booking** (`bookingInput` / `bookingResult`) from a previously returned offer. Key differences compared to OSDM are noted below.
+
+---
+
+## LockOfferRequest
+
+> Root request body for the lock operation.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `bookingInput` | `offerId` | The OMSA `bookingInput.offerId` references the offer to be booked/locked. |
+| aftersalesByRetailerOnly | boolean | 0..1 | — | — | No equivalent in OMSA 0.1.0. After-sales channel restriction is not a parameter in the OMSA booking input. |
+| externalRef | string | 0..1 | `bookingInput` | `externalId` | Caller-assigned reference for correlation. |
+| allocations | AllocationSelection | 0..* | `bookingInput` | `selectedOptions[].optionId` | OMSA represents seat or space selection as generic `selectedOptions[]` within the booking input; no separate allocation type. |
+| ancillaries | AncillarySelection | 0..* | `bookingInput` | `selectedOptions[].optionId` | Same `selectedOptions[]` pattern; the `optionId` identifies whether the selected option is a seat reservation or ancillary. |
+
+---
+
+## AllocationSelection
+
+> Selection of a specific allocation offer element.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| allocationReference | string | 1..1 | `bookingInput` | `selectedOptions[].optionId` | The `allocationReference` maps to an `optionId` from the preceding offer's `options[]` array. |
+
+---
+
+## AncillarySelection
+
+> Selection of a specific ancillary offer element.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| ancillaryReference | string | 1..1 | `bookingInput` | `selectedOptions[].optionId` | Same pattern as allocation; `ancillaryReference` maps to an `optionId`. |
+
+---
+
+## LockedOfferDetailRequest
+
+> Request to retrieve the full detail of a locked offer.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `bookingDetailInput` | `bookingId` | The `offerReference` (which is the `lockedOfferId`) maps to the OMSA `bookingId` supplied in the process input to retrieve booking detail. |
+
+---
+
+## LockOfferDelivery
+
+> Server response to the lock-offer request.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `bookingResult` | `bookingId` | Server-assigned booking identifier. |
+| expiryTime | dateTime | 1..1 | `bookingResult` | `validUntil` | Date-time by which the booking must be confirmed or it lapses. |
+| offerRef | string | 1..1 | `bookingResult` | `offerId` | Echo of the source offer identifier. |
+| lockedOffer | LockedOffer | 0..1 | `bookingResult` | (full `bookingResult` body) | OMSA typically returns the full booking result inline in the process execution response. |
+| warnings | Warning | 0..* | `bookingResult` | `warnings[]` | OMSA may return a `warnings[]` array for non-fatal conditions (e.g. availability change). |
+| links | Link | 0..* | — | — | No hypermedia links in the OMSA process result body; next steps are standard process endpoints. |
+
+---
+
+## LockedOffer
+
+> The time-limited held offer with full detail.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `bookingResult` | `bookingId` | |
+| name | string | 0..1 | — | — | No name field on OMSA booking result; derivable from offer description. |
+| summary | string | 0..1 | `bookingResult` | `description` | OMSA `description` is the closest equivalent to a human-readable summary. |
+| matching | string | 0..1 | — | — | No equivalent; OMSA booking always reflects the selected offer exactly. |
+| status | string | 1..1 | `bookingResult` | `state` | OMSA `state` values: `PENDING` (= locked), `CONFIRMED`, `CANCELLED`. EUDIT adds `expired`. |
+| afterSalesFlexibility | string | 0..* | `bookingResult` | `conditions[].type` | OMSA conditions array describes after-sales rules; types include `REFUNDABLE`, `EXCHANGEABLE`. |
+| personalInformationRequired | boolean | 0..1 | `bookingResult` | `personalDataRequired` | OMSA flag indicating whether passenger personal data must be supplied before confirmation. |
+| externalRef | string | 0..1 | `bookingResult` | `externalId` | Echo of the caller's external reference. |
+| elements | OfferElement | 1..* | `bookingResult` | `legs[].pricing[]` | OMSA booking legs carry pricing per leg, similar to the offer-search response structure. |
+| minimumPrice | Price | 0..1 | `bookingResult` | `totalPrice { amount, currencyCode }` | |
+| summaryDetails | SummaryDetail | 0..* | — | — | No equivalent; summary is derivable from the `legs[]` data. |
+| providedSections | ProvidedSections | 0..* | `bookingResult` | `legs[]` (start/end stop references) | OMSA `legs[]` implicitly define the covered sections via their origin/destination references. |
+| guarantees | Guarantee | 0..* | — | — | No structured guarantee in OMSA 0.1.0 booking result. |
+| links | Link | 0..* | `bookingResult` | `links[]` | OMSA process results may include OGC-style `links[]` for follow-up actions. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements within the locked offer.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `leg` | `id` | OMSA does not return discrete offer-element IDs; the closest anchor is the leg `id`. |
+| offerElementType | string | 1..1 | — | — | Discriminator only; OMSA does not use a typed element hierarchy. |
+| travellingEntities | TravellingEntityReference | 0..* | `traveller` | `id` | OMSA booking associates travellers via the `travellers[]` array at booking level, not per element. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| requiredInformation | RequiredInformation | 0..1 | `bookingResult` | `requiredPassengerData[]` | OMSA lists required passenger data fields at booking level. |
+| price | Price | 0..1 | `leg` | `pricing.parts[{ amount, currencyCode }]` | |
+| fareProduct | FareProduct | 0..1 | `leg` | `id` | Leg identifier serves as an implicit product reference in OMSA. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent. |
+| providedSections | ProvidedSections | 0..* | `leg` | `from`, `to` | Origin/destination stop references of the leg. |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific section.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| offerElementType (travelRight) | — | — | `leg` | `pricing[]` | In OMSA a travel right is implicit per leg; pricing is attached to the leg object. |
+| ancillaries | Ancillary | 0..* | — | — | Ancillaries are not nested under legs in OMSA; they are separate booking line items if present. |
+| allocations | Allocation | 1..* | `leg` | `assetType` | OMSA `assetType` describes the type of asset allocated (seat, berth, etc.). |
+
+---
+
+## Ancillary
+
+> Optional ancillary service.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | — | — | No discrete ancillary ID in OMSA booking result. |
+| type | string | 0..1 | `leg` | `assetType.subType` | OMSA `assetType.subType` can encode ancillary service categories in some implementations. |
+
+---
+
+## SpotAllocation
+
+> Allocation to a specific physical spot.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| legId | string | 0..1 | `leg` | `id` | OMSA spot allocation is tied to a specific leg. |
+| startPlace | string | 0..1 | `leg` | `from.stopReference.id` | |
+| endPlace | string | 0..1 | `leg` | `to.stopReference.id` | |
+| typeOfSpot | string | 0..1 | `leg` | `assetType.assetClass` | OMSA `assetClass` (e.g. `SEAT`, `BERTH`). |
+
+---
+
+## AssetAllocation
+
+> Allocation to a named asset.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| (no additional properties) | — | — | `leg` | `assetType` | OMSA models all allocations via `assetType`; a named asset maps to `assetType.assetClass` with an asset descriptor. |
+
+---
+
+## TravellingEntityReference
+
+> Reference to a travelling entity.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityRef | integer | 1..1 | `traveller` | `id` | OMSA `traveller.id` is the per-traveller correlation identifier within the booking. |
+
+---
+
+## Price
+
+> Monetary amount in a currency.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| currencyCode | string | 1..1 | `pricing` | `currencyCode` | |
+| amount | number | 1..1 | `pricing` | `amount` | OMSA `pricing.parts[].amount` (individual fare element) or `totalPrice.amount` (booking total). |
+| vat | Vat | 0..* | — | — | OMSA 0.1.0 does not return a structured VAT breakdown. |
+
+---
+
+## Vat
+
+> VAT component of a price. **No equivalent in OMSA 0.1.0.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| amount / currencyCode / country / percentage | various | — | — | — | Not part of OMSA booking response. |
+
+---
+
+## ProvidedSections
+
+> Journey section covered by an offer or element.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | `leg` | `id` (first leg) | |
+| endLegId | string | 0..1 | `leg` | `id` (last leg) | |
+| startPlace | string | 0..1 | `leg` | `from.stopReference.id` | |
+| endPlace | string | 0..1 | `leg` | `to.stopReference.id` | |
+| tripPatternRef | string | 0..1 | — | — | No trip-pattern reference in OMSA booking; the booking itself is the trip context. |
+
+---
+
+## SummaryDetail
+
+> Human-readable journey summary. **No direct equivalent in OMSA 0.1.0.**
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| geometry | string | 0..1 | — | — | Derivable from `legs[].from`/`to` place references. |
+| temporal | string | 0..1 | — | — | Derivable from `legs[].startTime`/`endTime`. |
+| conditions | string | 0..1 | `bookingResult` | `conditions[].description` | OMSA condition descriptions are the closest equivalent. |
+
+---
+
+## FareProduct
+
+> Fare product reference.
+
+| Property | Type | Mult. | OMSA concept | OMSA property | Notes |
+|---|---|---|---|---|---|
+| productRef | string | 0..1 | `leg` | `id` | OMSA does not have an explicit fare product reference; the leg ID serves as the implicit product anchor. |
+
+---
+
+## Guarantee / RequiredInformation / Warning
+
+> Stub types.
+
+| EUDIT concept | OMSA concept | OMSA property | Notes |
+|---|---|---|---|
+| Guarantee | — | — | No structured guarantee in OMSA 0.1.0. |
+| RequiredInformation | `bookingResult` | `requiredPassengerData[]` | OMSA lists required passenger data fields at booking level. |
+| Warning | `bookingResult` | `warnings[]` | OMSA `warnings[]` array carries non-fatal booking warnings. |
diff --git a/deliverables/2 lock offer/mappings/mapping-osdm.md b/deliverables/2 lock offer/mappings/mapping-osdm.md
new file mode 100644
index 0000000..f9bf640
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-osdm.md
@@ -0,0 +1,236 @@
+# Mapping: Lock Offer → OSDM 3.7.1
+
+Maps each EUDIT **Lock Offer** concept to the corresponding concept/property in **OSDM 3.7.1**.
+
+- **Endpoint 1**: `POST /bookings` (lock / create a provisional booking)
+- **Endpoint 2**: `GET /bookings/{bookingId}` (retrieve booking detail)
+- **EUDIT concept / Property** — as defined in `lock-offer.yaml`
+- **OSDM concept** — the matching schema object in OSDM 3.7.1
+- **OSDM property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+In OSDM 3.7.1 the *lock offer* step corresponds to `POST /bookings`, which creates an **unconfirmed booking** from one or more offer parts. The booking has a `confirmationLimit` (= lock expiry) and a `state` that starts as `UNCONFIRMED`. The booking detail is retrieved via `GET /bookings/{bookingId}`.
+
+---
+
+## LockOfferRequest
+
+> Root request body for the lock operation.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `booking` | `offerParts[].offerId` | Each OSDM offer part references the offer it is derived from. A single EUDIT `offerReference` typically maps to one `offerParts[]` entry. |
+| aftersalesByRetailerOnly | boolean | 0..1 | — | — | No direct equivalent in OSDM 3.7.1. After-sales channel restrictions are typically governed by bilateral operator/retailer agreements encoded in the fare conditions, not in the booking request. |
+| externalRef | string | 0..1 | `booking` | `externalId` | OSDM `externalId` is a caller-assigned reference for correlation with the retailer's system. |
+| allocations | AllocationSelection | 0..* | `booking` | `offerParts[].reservationOptions[].reservationOptionId` | In OSDM, seat/space reservations are selected by referencing a `reservationOptionId` returned in the offer's `offerParts[].reservationOptions[]`. |
+| ancillaries | AncillarySelection | 0..* | `booking` | `offerParts[].ancillaryOptions[].ancillaryOptionId` | Ancillary selections reference an `ancillaryOptionId` from the offer's `ancillaryOptions[]`. |
+
+---
+
+## AllocationSelection
+
+> Selection of a specific allocation offer element.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| allocationReference | string | 1..1 | `offerPart` | `reservationOptions[].reservationOptionId` | Direct mapping: the EUDIT `allocationReference` is the OSDM `reservationOptionId`. |
+
+---
+
+## AncillarySelection
+
+> Selection of a specific ancillary offer element.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| ancillaryReference | string | 1..1 | `offerPart` | `ancillaryOptions[].ancillaryOptionId` | Direct mapping: the EUDIT `ancillaryReference` is the OSDM `ancillaryOptionId`. |
+
+---
+
+## LockedOfferDetailRequest
+
+> Request to retrieve the full detail of a locked offer.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `booking` | `bookingId` (path parameter) | For the OSDM `GET /bookings/{bookingId}` endpoint the identifier is passed as a path parameter, not in a request body. This EUDIT field maps to that path parameter. |
+
+---
+
+## LockOfferDelivery
+
+> Server response to the lock-offer request.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `booking` | `bookingId` | Server-assigned booking identifier. |
+| expiryTime | dateTime | 1..1 | `booking` | `confirmationLimit` | Date-time by which the booking must be confirmed before the hold is released. |
+| offerRef | string | 1..1 | `booking` | `offerParts[].offerId` | Reference back to the source offer. |
+| lockedOffer | LockedOffer | 0..1 | `booking` | (full `booking` response body) | OSDM always returns the full booking object in the `POST /bookings` response; no separate detail fetch is required. This field echoes that inline detail. |
+| warnings | Warning | 0..* | — | — | No structured warning array in OSDM 3.7.1 booking response; informational messages may appear in `notes`. |
+| links | Link | 0..* | — | — | No hypermedia links in OSDM booking response. Subsequent operations (confirm, cancel) are inferred from standard OSDM endpoints. |
+
+---
+
+## LockedOffer
+
+> The time-limited held offer with full detail.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `booking` | `bookingId` | |
+| name | string | 0..1 | — | — | No name field on OSDM booking. Human-readable name derived from fare product descriptions. |
+| summary | string | 0..1 | — | — | No summary field. |
+| matching | string | 0..1 | — | — | No equivalent. OSDM booking is always an exact match to the selected offer. |
+| status | string | 1..1 | `booking` | `state` | OSDM `state` values: `UNCONFIRMED` (= locked), `CONFIRMED`, `CANCELLED`. EUDIT adds `expired` as a distinct state. |
+| afterSalesFlexibility | string | 0..* | `fareProduct` | `afterSalesConditions[]` | OSDM after-sales conditions describe refund and exchange rules per fare product element. |
+| personalInformationRequired | boolean | 0..1 | `booking` | `passengerSpecificationRequired` | OSDM indicates whether passenger personal data must be provided before confirmation. |
+| externalRef | string | 0..1 | `booking` | `externalId` | Echo of the caller-assigned external reference. |
+| elements | OfferElement | 1..* | `booking` | `offerParts[]` | Each OSDM `offerPart` groups fare products, reservations, and ancillaries. See **OfferElement** below. |
+| minimumPrice | Price | 0..1 | `booking` | `price` | OSDM `booking.price` is the total booking price (equivalent to EUDIT minimum price). |
+| summaryDetails | SummaryDetail | 0..* | — | — | No equivalent. Journey summary is derived from the trip specification in the offer. |
+| providedSections | ProvidedSections | 0..* | `booking` | `offerParts[].tripCoverage` | OSDM `tripCoverage` indicates which legs an offer part covers. |
+| guarantees | Guarantee | 0..* | — | — | No structured guarantee array in OSDM 3.7.1. Connection guarantees are operator policy, not returned in booking response. |
+| links | Link | 0..* | — | — | No hypermedia links in OSDM booking response. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements within the locked offer.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `fareProduct` / `reservation` / `ancillaryProduct` | `fareProductId` / `reservationId` / `ancillaryProductId` | OSDM uses separate ID fields per element type. |
+| offerElementType | string | 1..1 | — | — | Discriminator only; OSDM distinguishes element types by array placement. |
+| travellingEntities | TravellingEntityReference | 0..* | `offerPart` | `passengerRef` | Each OSDM offer part references the passenger(s) it applies to via `passengerRef`. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| requiredInformation | RequiredInformation | 0..1 | `offerPart` | `requiredPassengerSpecification` | OSDM indicates per offer part which passenger data fields are required. |
+| price | Price | 0..1 | `offerPart` | `price { amount, currency }` | |
+| fareProduct | FareProduct | 0..1 | `offerPart` | `fareProducts[].fareProductRef` | |
+| guarantees | Guarantee | 0..* | — | — | No equivalent at offer-part level. |
+| providedSections | ProvidedSections | 0..* | `offerPart` | `tripCoverage` | |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific section.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| offerElementType (travelRight) | — | — | `offerPart` | `fareProducts[]` | OSDM encodes travel rights as fare products within an offer part. |
+| ancillaries | Ancillary | 0..* | `offerPart` | `ancillaryProducts[]` | Ancillaries co-located in the same OSDM offer part. |
+| allocations | Allocation | 1..* | `offerPart` | `reservations[]` | OSDM reservations are co-located in the same offer part as the travel right. |
+
+---
+
+## Ancillary
+
+> Optional ancillary service.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | `ancillaryProduct` | `ancillaryProductId` | |
+| type | string | 0..1 | `ancillaryProduct` | `type` | |
+
+---
+
+## SpotAllocation
+
+> Allocation to a specific physical spot.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| legId | string | 0..1 | `reservation` | `serviceJourneyRef` | OSDM reservation references the service journey the seat is on. |
+| startPlace | string | 0..1 | `reservation` | `boardingStopPlaceRef` | |
+| endPlace | string | 0..1 | `reservation` | `alightingStopPlaceRef` | |
+| typeOfSpot | string | 0..1 | `reservation` | `seatInformation.placeType` | OSDM `placeType` (e.g. `SEAT`, `BERTH`, `COUCHETTE`). |
+
+---
+
+## AssetAllocation
+
+> Allocation to a named asset. **Partial equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| (no additional properties) | — | — | `reservation` | `seatInformation.placeType` | OSDM does not have a dedicated named-asset allocation concept; vehicle slot or cabin reservations are modelled as reservations with an appropriate `placeType`. |
+
+---
+
+## TravellingEntityReference
+
+> Reference to a travelling entity.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityRef | integer | 1..1 | `offerPart` | `passengerRef` | OSDM `passengerRef` links an offer part to the passenger it applies to. |
+
+---
+
+## Price
+
+> Monetary amount in a currency.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| currencyCode | string | 1..1 | `price` | `currency` | ISO 4217. |
+| amount | number | 1..1 | `price` | `amount` | |
+| vat | Vat | 0..* | — | — | OSDM 3.7.1 does not return a structured VAT breakdown; gross price only. |
+
+---
+
+## Vat
+
+> VAT component of a price. **No equivalent in OSDM 3.7.1.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| amount / currencyCode / country / percentage | various | — | — | — | OSDM returns gross prices only; VAT breakdown is not part of the booking response. |
+
+---
+
+## ProvidedSections
+
+> Journey section covered by an offer or element.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | `tripCoverage` | `legs[].legId` (first) | OSDM `tripCoverage` lists the specific legs covered by an offer part. |
+| endLegId | string | 0..1 | `tripCoverage` | `legs[].legId` (last) | |
+| startPlace | string | 0..1 | `tripCoverage` | `originStopPlaceRef` | |
+| endPlace | string | 0..1 | `tripCoverage` | `destinationStopPlaceRef` | |
+| tripPatternRef | string | 0..1 | — | — | No equivalent; OSDM offer parts reference legs directly. |
+
+---
+
+## SummaryDetail
+
+> Human-readable journey summary. **No equivalent in OSDM.**
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| geometry / temporal / conditions | string | 0..1 | — | — | Derivable from the trip specification and fare product conditions; not returned as a discrete summary object. |
+
+---
+
+## FareProduct
+
+> Fare product reference.
+
+| Property | Type | Mult. | OSDM concept | OSDM property | Notes |
+|---|---|---|---|---|---|
+| productRef | string | 0..1 | `fareProduct` | `fareProductRef` | Reference to the immutable fare product in the operator's fare catalogue. |
+
+---
+
+## Guarantee / RequiredInformation / Warning
+
+> Stub types.
+
+| EUDIT concept | OSDM concept | OSDM property | Notes |
+|---|---|---|---|
+| Guarantee | — | — | No structured guarantee in OSDM 3.7.1 booking response. |
+| RequiredInformation | `offerPart` | `requiredPassengerSpecification` | OSDM lists required passenger data fields per offer part. |
+| Warning | — | — | No structured warning type in OSDM booking response. |
diff --git a/deliverables/2 lock offer/mappings/mapping-tm.md b/deliverables/2 lock offer/mappings/mapping-tm.md
new file mode 100644
index 0000000..8308379
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-tm.md
@@ -0,0 +1,258 @@
+# Mapping: Lock Offer → Transmodel v6.2
+
+This file maps each EUDIT **Lock Offer** concept to the **Transmodel v6.2** concept(s) it realises.
+Unlike the other mapping files, this is not a standard-to-standard API mapping but a conceptual anchor:
+it shows which Transmodel concepts underpin each EUDIT schema.
+
+- **EUDIT concept** — as defined in `lock-offer.yaml`
+- **Transmodel concept** — the TM v6.2 concept(s) realised
+- **TM package** — the Transmodel part / package
+- **Notes** — alignment remarks
+
+---
+
+## Request-side concepts
+
+### LockOfferRequest
+
+| EUDIT concept | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LockOfferRequest | PRE-BOOKING REQUEST | Part 6 — Fare management | TM PRE-BOOKING REQUEST — the request to reserve a SALES OFFER PACKAGE instance before final purchase. Initiates the provisional-hold lifecycle. |
+
+---
+
+### LockOfferRequest properties
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| offerReference | SALES OFFER PACKAGE | Part 6 | Reference to the SALES OFFER PACKAGE instance to be locked. |
+| aftersalesByRetailerOnly | SELLING CONDITION | Part 6 | Constrains after-sales operations to the originating retailer; relates to TM SELLING CONDITION and RESPONSIBILITY SET. |
+| externalRef | CUSTOMER ACCOUNT | Part 6 | External identifier linking the request to the customer's account in the origin system. |
+| allocations | SEAT RESERVATION (selection) | Part 6 | Requested seat or space allocation within the SALES OFFER PACKAGE; TM SEAT RESERVATION or PLACE ASSIGNMENT. |
+| ancillaries | SUPPLEMENTARY PRODUCT (selection) | Part 6 | Selection of an optional ancillary product; TM SUPPLEMENTARY PRODUCT (add-on service). |
+
+---
+
+### AllocationSelection
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| AllocationSelection (class) | SEAT RESERVATION REQUEST | Part 6 | The act of selecting a specific physical spot; TM SEAT RESERVATION is the realised assignment. |
+| allocationReference | VEHICLE JOURNEY EQUIPMENT PLACE ASSIGNMENT | Part 6 | Reference to the specific PLACE (seat, berth, bicycle space) being requested within the vehicle. |
+
+---
+
+### AncillarySelection
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| AncillarySelection (class) | SUPPLEMENTARY PRODUCT | Part 6 | The act of selecting an optional ancillary; TM SUPPLEMENTARY PRODUCT captures the chosen add-on. |
+| ancillaryReference | SUPPLEMENTARY PRODUCT | Part 6 | Reference to the specific SUPPLEMENTARY PRODUCT instance selected. |
+
+---
+
+### LockedOfferDetailRequest
+
+| EUDIT concept | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LockedOfferDetailRequest | PRE-BOOKING REQUEST (detail retrieval) | Part 6 | A query against an existing PRE-BOOKING / PROVISIONAL BOOKING to retrieve its full content. |
+| offerReference | PROVISIONAL BOOKING | Part 6 | Identifier of the PROVISIONAL BOOKING whose detail is being requested. |
+
+---
+
+## Response-side concepts
+
+### LockOfferDelivery
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LockOfferDelivery (class) | PRE-BOOKING / PROVISIONAL BOOKING | Part 6 | TM PROVISIONAL BOOKING — the time-limited hold on a SALES OFFER PACKAGE created in response to a PRE-BOOKING REQUEST. |
+| lockedOfferId | PROVISIONAL BOOKING | Part 6 | Server-assigned identifier for the PROVISIONAL BOOKING instance. |
+| expiryTime | PROVISIONAL BOOKING | Part 6 | Time limit after which the PROVISIONAL BOOKING lapses if not confirmed; TM validity window attribute. |
+| offerRef | SALES OFFER PACKAGE | Part 6 | Back-reference to the source SALES OFFER PACKAGE that was locked. |
+| lockedOffer | PROVISIONAL BOOKING (detail) | Part 6 | The full PROVISIONAL BOOKING content; see LockedOffer below. |
+| warnings | — | — | Non-modelled in Transmodel core; operational message concept. |
+| links | — | — | Hypermedia navigation; not a TM concept. |
+
+---
+
+### LockedOffer
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| LockedOffer (class) | PROVISIONAL BOOKING | Part 6 | TM PROVISIONAL BOOKING — the held instance of a SALES OFFER PACKAGE pending confirmation. |
+| lockedOfferId | PROVISIONAL BOOKING | Part 6 | Identifier of the PROVISIONAL BOOKING. |
+| name | SALES OFFER PACKAGE | Part 6 | Human-readable label derivable from the referenced SALES OFFER PACKAGE name. |
+| summary | SALES OFFER PACKAGE | Part 6 | Summary text derivable from SALES OFFER PACKAGE description and trip context. |
+| matching | — | — | Not modelled in TM; conformance-matching is an implementation concept. |
+| status | BOOKING STATUS | Part 6 | TM BOOKING STATUS — the lifecycle state of the booking (PROVISIONAL, CONFIRMED, CANCELLED, EXPIRED). |
+| afterSalesFlexibility | AFTER SALES CONDITION | Part 6 | TM AFTER SALES CONDITION — rules governing exchange (EXCHANGING) and refund (REFUNDING) of the booking. |
+| personalInformationRequired | — | — | Not modelled in TM; data-collection requirement is an implementation concern. |
+| externalRef | CUSTOMER ACCOUNT | Part 6 | External identifier for the customer's account in the origin system. |
+| elements | SALES OFFER PACKAGE ELEMENT | Part 6 | Components of the locked SALES OFFER PACKAGE; see OfferElement below. |
+| minimumPrice | FARE PRICE | Part 6 | TM FARE PRICE — the monetary value assigned to the locked offer. |
+| summaryDetails | TRIP PATTERN | Part 3 | Journey summary derivable from the TRIP PATTERN and LEGs covered by the offer. |
+| providedSections | SECTION | Part 2 | TM SECTION — the subset of the journey covered by this offer or element. |
+| guarantees | GUARANTEE | Part 6 | TM GUARANTEE — a contractual commitment (connection guarantee, seat guarantee) associated with the booking. |
+| links | — | — | Hypermedia navigation; not a TM concept. |
+
+---
+
+### OfferElement
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| OfferElement (class) | SALES OFFER PACKAGE ELEMENT | Part 6 | TM SALES OFFER PACKAGE ELEMENT — a component within a SALES OFFER PACKAGE (§6.5.2). |
+| offerElementId | SALES OFFER PACKAGE ELEMENT | Part 6 | Server-assigned identifier for the element. |
+| offerElementType | (discriminator) | — | Discriminator over TM sub-types (ACCESS RIGHT ASSIGNMENT, SUPPLEMENTARY PRODUCT, SEAT RESERVATION). |
+| travellingEntities | TRAVELLING ENTITY | Part 6 | The TRAVELLING ENTITYs to whom this element applies. |
+| matching | — | — | Not modelled in TM. |
+| requiredInformation | — | — | Data-collection requirement; not a TM core concept. |
+| price | FARE PRICE | Part 6 | TM FARE PRICE — the monetary value of the element. |
+| fareProduct | FARE PRODUCT | Part 6 | TM FARE PRODUCT — the immutable element in the fare structure that defines the access right (§6.5.1). |
+| guarantees | GUARANTEE | Part 6 | TM GUARANTEE — contractual commitment associated with the element. |
+| providedSections | SECTION | Part 2 | Journey section covered by this element. |
+
+---
+
+### TravelRight
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| TravelRight (class) | ACCESS RIGHT ASSIGNMENT | Part 6 | TM ACCESS RIGHT ASSIGNMENT — assigns a right to travel to a specific passenger on a specific leg or zone (§6.5.3). |
+| ancillaries | SUPPLEMENTARY PRODUCT | Part 6 | Optional add-on services included with or adjacent to the travel right. |
+| allocations | SEAT RESERVATION | Part 6 | Seat or space reservations associated with the travel right. |
+
+---
+
+### Ancillary
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Ancillary (class) | SUPPLEMENTARY PRODUCT | Part 6 | TM SUPPLEMENTARY PRODUCT — an optional add-on service (meal, bicycle transport, lounge access) (§6.5.4). |
+| ancillaryId | SUPPLEMENTARY PRODUCT | Part 6 | Identifier of the ancillary SUPPLEMENTARY PRODUCT instance. |
+| type | SUPPLEMENTARY PRODUCT TYPE | Part 6 | Category of the ancillary (meal, bicycle, luggage, lounge, etc.). |
+
+---
+
+### Allocation (response)
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Allocation (class) | SEAT RESERVATION | Part 6 | TM SEAT RESERVATION — a confirmed allocation of a specific space within a vehicle. |
+
+---
+
+### SpotAllocation
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| SpotAllocation (class) | SEAT RESERVATION | Part 6 | TM SEAT RESERVATION for a specific physical spot (seat, berth, bicycle rack). |
+| legId | SERVICE JOURNEY | Part 3 | The SERVICE JOURNEY (leg) on which the spot is allocated. |
+| startPlace | SCHEDULED STOP POINT | Part 2 | Boarding stop for the allocation scope. |
+| endPlace | SCHEDULED STOP POINT | Part 2 | Alighting stop for the allocation scope. |
+| typeOfSpot | VEHICLE EQUIPMENT PLACE | Part 1 | TM VEHICLE EQUIPMENT PLACE — the type of physical location within the vehicle (seat, berth, cycle hook). |
+
+---
+
+### AssetAllocation
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| AssetAllocation (class) | VEHICLE JOURNEY EQUIPMENT PLACE ASSIGNMENT | Part 6 | TM VEHICLE JOURNEY EQUIPMENT PLACE ASSIGNMENT — assignment of a named asset to a specific VEHICLE JOURNEY, extending SEAT RESERVATION to cover non-seat spaces (bicycle storage, car-loader bay). |
+
+---
+
+### TravellingEntityReference
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| travellingEntityRef | TRAVELLING ENTITY | Part 6 | Reference to a TM TRAVELLING ENTITY (passenger, animal, vehicle, luggage item) associated with an offer element. |
+
+---
+
+### Price
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Price (class) | FARE PRICE | Part 6 | TM FARE PRICE — monetary value expressed in a currency (§6.4.5). |
+| currencyCode | CURRENCY TYPE | Part 6 | ISO 4217 currency; TM CURRENCY TYPE. |
+| amount | FARE PRICE | Part 6 | Numeric monetary amount. |
+| vat | FARE PRICE (VAT breakdown) | Part 6 | TM FARE PRICE may include VAT-related attributes; a structured VAT breakdown is an extension of the base TM model. |
+
+---
+
+### Vat
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Vat (class) | FARE PRICE (VAT component) | Part 6 | Tax component of a FARE PRICE; TM v6.2 models VAT as an attribute group on FARE PRICE. |
+| amount | FARE PRICE | Part 6 | VAT amount. |
+| currencyCode | CURRENCY TYPE | Part 6 | Currency of the VAT amount. |
+| country | — | Part 6 | Country of VAT jurisdiction; not explicitly modelled in TM core. |
+| percentage | FARE PRICE | Part 6 | VAT rate percentage. |
+
+---
+
+### ProvidedSections
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| ProvidedSections (class) | SECTION | Part 2 | TM SECTION — a defined part of a route between two points, scoping the offer element. |
+| startLegId | SERVICE JOURNEY | Part 3 | The first SERVICE JOURNEY (leg) in the covered section. |
+| endLegId | SERVICE JOURNEY | Part 3 | The last SERVICE JOURNEY (leg) in the covered section. |
+| startPlace | SCHEDULED STOP POINT / PLACE | Part 2 | TM SCHEDULED STOP POINT or PLACE — origin of the covered section. |
+| endPlace | SCHEDULED STOP POINT / PLACE | Part 2 | TM SCHEDULED STOP POINT or PLACE — destination of the covered section. |
+| tripPatternRef | TRIP PATTERN | Part 3 | Reference to the TM TRIP PATTERN that this section belongs to. |
+
+---
+
+### SummaryDetail
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| SummaryDetail (class) | — | — | No direct TM equivalent; human-readable summary derivable from TRIP PATTERN + FARE PRODUCT attributes. |
+| geometry | SECTION / ROUTE | Part 2 | Route geometry derivable from TM SECTION or ROUTE points. |
+| temporal | CALL (departure/arrival) | Part 3 | Temporal summary derivable from TM CALL departure/arrival times at origin/destination. |
+| conditions | AFTER SALES CONDITION | Part 6 | Human-readable condition text derivable from TM AFTER SALES CONDITION descriptions. |
+
+---
+
+### FareProduct
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| FareProduct (class) | FARE PRODUCT | Part 6 | TM FARE PRODUCT — an immutable element in a fare structure representing a type of access right (§6.5.1). |
+| productRef | FARE PRODUCT | Part 6 | Reference to the specific FARE PRODUCT included in this offer element. |
+
+---
+
+### Guarantee
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Guarantee (class) | GUARANTEE | Part 6 | TM GUARANTEE — a contractual commitment associated with an offer element (connection guarantee, seat guarantee, price guarantee). |
+
+---
+
+### RequiredInformation
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| RequiredInformation (class) | — | — | No dedicated TM concept; relates to TRANSPORT CUSTOMER and CUSTOMER ACCOUNT data requirements. |
+
+---
+
+### Warning
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Warning (class) | — | — | Non-modelled in Transmodel core; an operational/informational message concept outside TM scope. |
+
+---
+
+### Link
+
+| EUDIT property | Transmodel concept | TM package | Notes |
+|---|---|---|---|
+| Link (class) | — | — | Hypermedia navigation concept; not part of Transmodel data model. |
diff --git a/deliverables/2 lock offer/mappings/mapping-tomp.md b/deliverables/2 lock offer/mappings/mapping-tomp.md
new file mode 100644
index 0000000..2ba66fc
--- /dev/null
+++ b/deliverables/2 lock offer/mappings/mapping-tomp.md
@@ -0,0 +1,238 @@
+# Mapping: Lock Offer → TOMP-API 2.0.0
+
+Maps each EUDIT **Lock Offer** concept to the corresponding concept/property in **TOMP-API 2.0.0**.
+
+- **Endpoint 1**: `POST /processes/select-offer/execution`
+- **Endpoint 2**: `GET /bookings/{bookingId}` (or `POST /processes/locked-offer-details/execution`)
+- **EUDIT concept / Property** — as defined in `lock-offer.yaml`
+- **TOMP concept** — the matching schema object in TOMP-API
+- **TOMP property** — the matching field name
+- **Notes** — mapping remarks, gaps, or open questions
+
+In TOMP-API 2.0.0 a "lock" corresponds to creating a **booking** in state `PENDING`. The client selects a leg/option and the operator holds it before confirmation. Seat and ancillary selections are expressed through `legs[].assetType` and related sub-objects. TOMP has no dedicated "lock offer" process; the closest lifecycle event is `POST /legs/{legId}/events` with `eventType: PREPARE` or `POST /bookings` returning `state: PENDING`.
+
+---
+
+## LockOfferRequest
+
+> Root request body for the lock operation.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `booking` | `id` (of the offer/leg being locked) | TOMP identifies the offer as a leg reference. The `offerReference` is passed as the leg or offer ID in the booking body. |
+| aftersalesByRetailerOnly | boolean | 0..1 | — | — | No equivalent in TOMP 2.0.0. After-sales channel control is not a booking input parameter. |
+| externalRef | string | 0..1 | `booking` | `customerReference` | Caller-assigned external reference carried on the booking. |
+| allocations | AllocationSelection | 0..* | `leg` | `assetType` (selected seat/berth) | Seat/space selection supplied as `assetType` on the relevant leg. |
+| ancillaries | AncillarySelection | 0..* | `leg` | `subAssets[]` | Ancillary services expressed as sub-assets on the leg (e.g. meal, bicycle). |
+
+---
+
+## AllocationSelection
+
+> Selection of a specific allocation offer element.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| allocationReference | string | 1..1 | `leg` | `assetType.assetClass` / `assetType.assetSubClass` | The allocation reference maps to the asset type descriptor that identifies the selected spot. |
+
+---
+
+## AncillarySelection
+
+> Selection of a specific ancillary offer element.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| ancillaryReference | string | 1..1 | `leg` | `subAssets[].assetType.assetClass` | TOMP sub-assets on a leg carry ancillary service references; the `ancillaryReference` maps to a sub-asset asset class. |
+
+---
+
+## LockedOfferDetailRequest
+
+> Request to retrieve the full detail of a locked offer.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerReference | string | 1..1 | `booking` | `id` | TOMP retrieves booking detail via `GET /bookings/{id}`; the `offerReference` (= `lockedOfferId`) maps to the TOMP booking `id`. |
+
+---
+
+## LockOfferDelivery
+
+> Server response to the lock-offer request.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `booking` | `id` | TOMP server-assigned booking identifier returned in `POST /bookings` response. |
+| expiryTime | dateTime | 1..1 | `booking` | `expiresBefore` | TOMP `expiresBefore` (ISO 8601) — the time by which the booking must be confirmed or it expires. |
+| offerRef | string | 1..1 | `booking` | `legs[].id` | Echo of the source offer/leg identifier. |
+| lockedOffer | LockedOffer | 0..1 | `booking` | (full booking body) | TOMP returns the full booking inline; `lockedOffer` corresponds to the booking object itself. |
+| warnings | Warning | 0..* | — | — | TOMP 2.0.0 does not define a `warnings[]` array on the booking response; non-fatal conditions may appear in operator-specific extensions. |
+| links | Link | 0..* | `booking` | `links[]` | TOMP booking objects carry HATEOAS `links[]` for follow-up actions (e.g. confirm, cancel). |
+
+---
+
+## LockedOffer
+
+> The time-limited held offer with full detail.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| lockedOfferId | string | 1..1 | `booking` | `id` | |
+| name | string | 0..1 | — | — | No name field on TOMP booking; derivable from leg descriptions. |
+| summary | string | 0..1 | `booking` | `legs[0].departureTime` + `legs[-1].arrivalTime` | TOMP does not return a free-text summary; a summary can be constructed from leg origin/destination and times. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| status | string | 1..1 | `booking` | `state` | TOMP `state` values: `PENDING` (= locked), `CONFIRMED`, `CANCELLED`, `EXPIRED`. Maps directly. |
+| afterSalesFlexibility | string | 0..* | `booking` | `conditions[].conditionType` | TOMP condition types include `CONDITIONAL_REFUND`, `NO_REFUND`, `EXCHANGE`. |
+| personalInformationRequired | boolean | 0..1 | — | — | No equivalent Boolean flag. TOMP uses required customer-data schemas in the booking flow but does not expose a dedicated flag. |
+| externalRef | string | 0..1 | `booking` | `customerReference` | Echo of the caller's external reference. |
+| elements | OfferElement | 1..* | `booking` | `legs[]` | Each TOMP leg corresponds to a travel-right or ancillary offer element. |
+| minimumPrice | Price | 0..1 | `booking` | `pricing.estimated` / `pricing.parts[]` | TOMP booking pricing is expressed per leg; an aggregate must be computed by the client. |
+| summaryDetails | SummaryDetail | 0..* | — | — | No equivalent; derivable from `legs[]` departure/arrival times and stop references. |
+| providedSections | ProvidedSections | 0..* | `booking` | `legs[]` (from/to stop references) | TOMP legs implicitly define covered sections via their `from` and `to` place references. |
+| guarantees | Guarantee | 0..* | — | — | No structured guarantee concept in TOMP 2.0.0 booking. |
+| links | Link | 0..* | `booking` | `links[]` | TOMP HATEOAS links for booking actions. |
+
+---
+
+## OfferElement
+
+> Base class for purchasable elements within the locked offer.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerElementId | string | 1..1 | `leg` | `id` | TOMP `leg.id` is the closest equivalent to an offer-element identifier. |
+| offerElementType | string | 1..1 | — | — | Discriminator only; TOMP does not use a typed element hierarchy at this level. |
+| travellingEntities | TravellingEntityReference | 0..* | `booking` | `customers[]` | TOMP associates travellers at booking level via `customers[]`, not per leg element. |
+| matching | string | 0..1 | — | — | No equivalent. |
+| requiredInformation | RequiredInformation | 0..1 | `booking` | `requiredUserInfo` | TOMP booking may specify required user-info fields; see operator configuration. |
+| price | Price | 0..1 | `leg` | `pricing.parts[{ amount, currencyCode }]` | |
+| fareProduct | FareProduct | 0..1 | `leg` | `id` | Leg ID serves as implicit product reference. |
+| guarantees | Guarantee | 0..* | — | — | No equivalent in TOMP 2.0.0. |
+| providedSections | ProvidedSections | 0..* | `leg` | `from`, `to` | Origin and destination stop references of the leg. |
+
+---
+
+## TravelRight
+
+> Right to travel on a specific section.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| offerElementType (travelRight) | — | — | `leg` | `pricing[]` | A travel right is implicit per TOMP leg; pricing is attached to the leg object. |
+| ancillaries | Ancillary | 0..* | `leg` | `subAssets[]` | Ancillary services are modelled as sub-assets of the leg in TOMP. |
+| allocations | Allocation | 1..* | `leg` | `assetType` | TOMP `assetType` describes the allocated asset (seat, berth, bicycle space, etc.). |
+
+---
+
+## Ancillary
+
+> Optional ancillary service.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| ancillaryId | string | 0..1 | `leg.subAssets[]` | `id` | TOMP sub-asset `id` identifies the ancillary item. |
+| type | string | 0..1 | `leg.subAssets[].assetType` | `assetClass` | TOMP `assetClass` encodes the ancillary category (e.g. `MEAL`, `BICYCLE_STORAGE`). |
+
+---
+
+## SpotAllocation
+
+> Allocation to a specific physical spot.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| legId | string | 0..1 | `leg` | `id` | TOMP spot allocation is tied to a specific leg by `id`. |
+| startPlace | string | 0..1 | `leg` | `from.stopReference.id` | |
+| endPlace | string | 0..1 | `leg` | `to.stopReference.id` | |
+| typeOfSpot | string | 0..1 | `leg.assetType` | `assetClass` | TOMP `assetClass` (e.g. `SEAT`, `BERTH`, `BICYCLE_STORAGE`). |
+
+---
+
+## AssetAllocation
+
+> Allocation to a named asset.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| (no additional properties) | — | — | `leg` | `assetType` | TOMP models all allocations via `assetType`; a named asset maps to `assetType.assetClass` with an asset descriptor in `assetType.assetSubClass`. |
+
+---
+
+## TravellingEntityReference
+
+> Reference to a travelling entity.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| travellingEntityRef | integer | 1..1 | `customer` | `id` | TOMP `customers[].id` is the per-traveller correlation identifier within the booking. |
+
+---
+
+## Price
+
+> Monetary amount in a currency.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| currencyCode | string | 1..1 | `pricing` | `currencyCode` | |
+| amount | number | 1..1 | `pricing` | `amount` | TOMP `pricing.parts[].amount` (per element) or booking-level total. |
+| vat | Vat | 0..* | — | — | TOMP 2.0.0 does not return a structured VAT breakdown. |
+
+---
+
+## Vat
+
+> VAT component of a price. **No equivalent in TOMP-API 2.0.0.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| amount / currencyCode / country / percentage | various | — | — | — | Not part of TOMP booking response. |
+
+---
+
+## ProvidedSections
+
+> Journey section covered by an offer or element.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| startLegId | string | 0..1 | `leg` | `id` (first leg) | |
+| endLegId | string | 0..1 | `leg` | `id` (last leg) | |
+| startPlace | string | 0..1 | `leg` | `from.stopReference.id` | |
+| endPlace | string | 0..1 | `leg` | `to.stopReference.id` | |
+| tripPatternRef | string | 0..1 | — | — | No trip-pattern reference in TOMP booking; the booking ID is the trip context. |
+
+---
+
+## SummaryDetail
+
+> Human-readable journey summary. **No direct equivalent in TOMP-API 2.0.0.**
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| geometry | string | 0..1 | — | — | Derivable from `legs[].from`/`to` place references. |
+| temporal | string | 0..1 | — | — | Derivable from `legs[].departureTime`/`arrivalTime`. |
+| conditions | string | 0..1 | `booking` | `conditions[].description` | TOMP condition descriptions are the closest equivalent. |
+
+---
+
+## FareProduct
+
+> Fare product reference.
+
+| Property | Type | Mult. | TOMP concept | TOMP property | Notes |
+|---|---|---|---|---|---|
+| productRef | string | 0..1 | `leg` | `id` | TOMP does not have an explicit fare product reference; the leg ID serves as the implicit product anchor. |
+
+---
+
+## Guarantee / RequiredInformation / Warning
+
+> Stub types.
+
+| EUDIT concept | TOMP concept | TOMP property | Notes |
+|---|---|---|---|
+| Guarantee | — | — | No structured guarantee concept in TOMP 2.0.0. |
+| RequiredInformation | `booking` | `requiredUserInfo` | TOMP may specify required user-info fields via operator configuration. |
+| Warning | — | — | No `warnings[]` array on TOMP booking response; non-fatal conditions are operator-specific. |
diff --git a/deliverables/2 lock offer/test cases/test-cases.md b/deliverables/2 lock offer/test cases/test-cases.md
new file mode 100644
index 0000000..30cd005
--- /dev/null
+++ b/deliverables/2 lock offer/test cases/test-cases.md
@@ -0,0 +1,218 @@
+# Lock Offer — Test Cases for Request Bodies
+
+This document describes the test cases for the lock-offer endpoints of the *OTI Lock Offer* API.
+
+The two request schemas covered are:
+
+- **`LockOfferRequest`** — used by `POST /lock-offers`, `POST /processes/lock-offers/execute`, and `POST /processes/lock-offers/execution`.
+- **`LockedOfferDetailRequest`** — used by `POST /processes/locked-offer-details/execute` and `POST /processes/locked-offer-details/execution`. (The OSDM `GET /lock-offers/{lockedOfferId}` endpoint uses a path parameter instead and requires no request body.)
+
+The test cases are organised in two sections:
+
+1. **Generic test cases (TC-001 – TC-005)** — applicable to all three `lock-offers` endpoints.
+2. **Standard-specific test cases**:
+ - **TC-006**: OSDM 3.7.1 (`POST /lock-offers`)
+ - **TC-007**: OMSA 0.1.0 (`POST /processes/lock-offers/execute`)
+ - **TC-008**: TOMP-API 2.0.0 (`POST /processes/lock-offers/execution`)
+3. **Locked offer detail (TC-009)** — for the two POST detail endpoints (OMSA and TOMP-API).
+
+---
+
+## Generic Test Cases (`LockOfferRequest`)
+
+These cases cover the core request model and apply regardless of which endpoint or standard is used.
+The `offerReference` values are representative server-assigned UUIDs as they would appear in a real `LockOfferDelivery`.
+
+---
+
+### TC-001 — Minimal lock
+
+**Purpose:** the most basic possible request: lock an offer identified solely by its reference.
+No extra selections, no external reference, no flags.
+
+**Scenario:**
+A traveller has received a list of offers from a search-offers call and selects one to lock.
+The caller sends only the mandatory `offerReference` and relies on the server to apply defaults for
+all other options.
+
+**Key characteristics:**
+- `offerReference` only — all other fields absent
+- No allocations, no ancillaries, no external reference, no flag
+
+**Example file:** `TC-001-minimal-lock.json`
+
+---
+
+### TC-002 — Lock with external reference
+
+**Purpose:** verify that the optional `externalRef` field is correctly transmitted, enabling the
+caller's booking system to correlate the locked offer with its own internal booking record.
+
+**Scenario:**
+A retailer's backend system locks an offer and attaches its own internal booking reference
+(`booking-ref-NL-20260315-00042`) for later correlation during confirmation and fulfilment.
+
+**Key characteristics:**
+- `offerReference` + `externalRef`
+- No allocations, no ancillaries, no flag
+
+**Example file:** `TC-002-external-reference.json`
+
+---
+
+### TC-003 — After-sales restricted to retailer only
+
+**Purpose:** verify that the `aftersalesByRetailerOnly` flag is correctly transmitted, instructing
+the server that the passenger must not be able to perform after-sales operations (refund, exchange)
+directly — only the retailer may do so.
+
+**Scenario:**
+A corporate travel management company locks an offer on behalf of an employee. Company policy
+requires that all post-purchase changes go through the TMC, not through the passenger-facing
+channel. The TMC sets `aftersalesByRetailerOnly: true` and attaches its internal reference.
+
+**Key characteristics:**
+- `offerReference` + `aftersalesByRetailerOnly: true` + `externalRef`
+- No allocations, no ancillaries
+
+**Example file:** `TC-003-aftersales-retailer-only.json`
+
+---
+
+### TC-004 — Lock with one allocation selection
+
+**Purpose:** verify that a specific allocation offer element (e.g. a seat reservation returned by
+the search) can be selected by reference as part of the lock request.
+
+**Scenario:**
+A traveller searches for offers and receives a travel right together with a seat reservation offer
+element. The traveller selects a specific seat (`offer-element-seat-001`) to include in the lock.
+The `allocationReference` points to the `offerElementId` of that reservation as returned by the
+search-offers response.
+
+**Key characteristics:**
+- `offerReference` + 1 allocation selection
+- `allocationReference` references an `offerElementId` from the preceding search result
+- No ancillaries, no external reference, no flag
+
+**Example file:** `TC-004-allocation-selection.json`
+
+---
+
+### TC-005 — Lock with one ancillary selection
+
+**Purpose:** verify that a specific ancillary offer element (e.g. a bicycle transport ticket) can
+be selected by reference and included in the lock alongside the base travel right.
+
+**Scenario:**
+A traveller takes a bicycle on the train. The search returned a bicycle transport ancillary offer
+element. The traveller selects it (`offer-element-bicycle-001`) to be locked together with
+the base travel offer.
+
+**Key characteristics:**
+- `offerReference` + 1 ancillary selection
+- `ancillaryReference` references an `offerElementId` from the preceding search result
+- No allocations, no external reference, no flag
+
+**Example file:** `TC-005-ancillary-selection.json`
+
+---
+
+## OSDM-Specific Test Cases (`POST /lock-offers`)
+
+---
+
+### TC-006 — Two seat reservations and a meal ancillary (international rail)
+
+**Purpose:** verify that multiple allocation selections and an ancillary can be combined in a
+single lock request, as is typical for international rail sales where seat reservations and
+on-board catering are selected alongside the fare.
+
+**Scenario:**
+Two travellers are travelling from Amsterdam to Paris on a high-speed service. They have
+received an offer from a prior OSDM search. Both travellers select adjacent seats in coach 4
+(seats 32A and 32B) and add a standard meal ancillary. The lock request references all three
+offer elements by their `offerElementId`s, plus the retailer's PNR as `externalRef`.
+
+**Key characteristics:**
+- `offerReference` + `externalRef` (PNR)
+- 2 allocation selections (`allocationReference`: coach4/32A, coach4/32B)
+- 1 ancillary selection (`ancillaryReference`: meal)
+
+**Example file:** `TC-006-osdm-seat-reservations-and-meal.json`
+
+---
+
+## OMSA-Specific Test Cases (`POST /processes/lock-offers/execute`)
+
+---
+
+### TC-007 — Lock with ancillary (OV-fiets) and OMSA external reference
+
+**Purpose:** verify that an OMSA lock request can select a shared-mobility ancillary offer element
+(e.g. an OV-fiets bicycle rental included in a combined offer) alongside the base travel right.
+
+**Scenario:**
+A traveller books a combined train + OV-fiets offer from Den Haag Centraal to Delft via OMSA.
+The search returned a travel right and a bicycle rental ancillary. The caller attaches its own
+OMSA-style trip reference as `externalRef`.
+
+**Key characteristics:**
+- `offerReference` + `externalRef` (OMSA trip ID)
+- 1 ancillary selection (OV-fiets rental offer element)
+- No allocations, no flag
+
+**Example file:** `TC-007-omsa-lock-with-ancillary.json`
+
+---
+
+## TOMP-Specific Test Cases (`POST /processes/lock-offers/execution`)
+
+---
+
+### TC-008 — Retailer-only after-sales + luggage storage ancillary (MaaS)
+
+**Purpose:** verify that a TOMP lock request can combine the `aftersalesByRetailerOnly` flag
+with an ancillary selection (e.g. left-luggage storage as part of a MaaS journey), while
+attaching a MaaS-platform booking reference as `externalRef`.
+
+**Scenario:**
+A MaaS platform locks a combined transit + luggage-storage offer for a traveller arriving at
+Rotterdam Centraal. The platform sets `aftersalesByRetailerOnly: true` so that the MaaS operator
+retains sole control over any post-purchase operations. A luggage storage slot ancillary is
+selected alongside the transit element.
+
+**Key characteristics:**
+- `offerReference` + `aftersalesByRetailerOnly: true` + `externalRef` (MaaS booking ID)
+- 1 ancillary selection (luggage storage offer element)
+- No allocation selections
+
+**Example file:** `TC-008-tomp-retailer-only-lock.json`
+
+---
+
+## Locked Offer Detail Test Cases (`LockedOfferDetailRequest`)
+
+These cases apply to `POST /processes/locked-offer-details/execute` (OMSA) and
+`POST /processes/locked-offer-details/execution` (TOMP-API).
+
+> **Note:** the OSDM `GET /lock-offers/{lockedOfferId}` endpoint does not use a request body —
+> the locked offer identifier is passed as a path parameter.
+
+---
+
+### TC-009 — Basic locked offer detail request
+
+**Purpose:** verify the minimal `LockedOfferDetailRequest`: retrieve the full detail of a
+previously locked offer using the `lockedOfferId` returned in the `LockOfferDelivery`.
+
+**Scenario:**
+Following a successful lock, the caller received a `LockOfferDelivery` containing a
+`lockedOfferId`. The caller now requests the full locked offer detail via the OMSA or TOMP
+POST endpoint, supplying the `lockedOfferId` as `offerReference`.
+
+**Key characteristics:**
+- `offerReference` = the `lockedOfferId` from the preceding `LockOfferDelivery`
+- No other fields (schema has no other properties)
+
+**Example file:** `TC-009-locked-offer-detail-basic.json`
diff --git a/deliverables/2b amend offer/possibilities.md b/deliverables/2b amend offer/possibilities.md
new file mode 100644
index 0000000..8bee4b4
--- /dev/null
+++ b/deliverables/2b amend offer/possibilities.md
@@ -0,0 +1,157 @@
+# Possible amend offer operations
+
+* spot availability/allocate spots accomodation
+* anc. availibility/allocate ancillary
+* supply information ( personal, vehicle, payment method (voucher, promo), bearer of the ticket (device/token), language of the ticket ) [ per offer element ]
+* remove offer element
+* get additional travel right/(add travelling entity/leg)
+* get offer (on ID)
+
+Pre-condition: An offer is searched for, and locked.
+It is now time to modify the offer, make it tailor-made for the travelling party.
+
+## Add offer element
+
+You can add new elements to the offer, or replace offer element (like seat allocations) for others. When adding/replacing element,
+it will be likely that there will be financial consequences.
+
+### Seat/spot allocation
+
+This functionality will consist of 2 parts:
+- request available seats/spots, including additional fees per seat. Optionally including a seat/spot to 'exchange'
+- add the allocation of a (replacing) seat/spot
+
+Removal of allocated spots/seats can be done using the 'remove not-mandatory offer elements'.
+
+#### Get availability
+
+__GET /available-spots__ or __GET /collections/available-spots/items__
+will return information about the available spots, referring to the (external) deck specification. Including additional fees/reductions per seat (related to the offered product).
+
+**Question**: should it also supply a deck-overview (to show to the customer (SVG?))
+
+Filters: product(s), seat state(s), selected seat(s)
+Policy: auto select
+
+#### Allocate seat/spot
+
+__POST /spot-allocation__ or __POST /processes/allocate-spot/execution__
++ offerRef
++ spotId[]
+
+After executing this function, the complete, updated offer (list) will be returned.
+
+**Question**: should we introduce a policy 'updatesOnly'? Default false, returning the complete offer (list). If true, only delivering the added/exchanged allocation(s), but in the same structure.
+
+### Asset allocation
+
+This functionality will consist of 2 parts:
+- request available assets, including additional fees per asset. Optionally including an asset to 'exchange'
+- add the allocation of a (replacing) asset
+
+Removal of allocated assets can be done using the 'remove not-mandatory offer elements'.
+
+**Remark** it is possible that in the offer is already an allocated asset, but only with a product related.
+
+#### Get availability
+
+__GET /available-assets__ or __GET /collections/available-assets/items__
+will return information about the available assets, referring to the (external) asset locations. Including additional fees/reductions per asset (related to the offered product).
+
+**Question**: should we rely on e.g. GBFS or NeTEx to publish the locations of the available assets?
+
+Filters: product(s), bbox, station(s)
+
+#### Allocate asset
+
+__POST /asset-allocation__ or __POST /processes/allocate-asset/execution__
++ offerRef
++ offerElementRef (travelRight)
++ assetId
+
+After executing this function, the complete, updated offer (list) will be returned.
+
+**Question**: should we introduce a policy 'updatesOnly'? Default false, returning the complete offer (list). If true, only delivering the added/exchanged allocation(s), but in the same structure.
+
+### Ancillary allocation (upselling, cross-selling)
+
+This functionality will consist of 2 parts:
+- request available/applicable ancillaries, including additional fees per ancillary. Optionally including an ancillary to 'exchange'
+- add the allocation of a (replacing) ancillaries
+
+Removal of allocated ancillaries can be done using the 'remove not-mandatory offer elements'.
+
+**Remark** it is possible that in the offer is already an allocated ancillary, but only with a product related.
+
+#### Get availability
+
+__GET /available-ancillaries__ or __GET /collections/available-ancillaries/items__
+will return information about the available ancillaries, referring to the (external) specifications. Including additional fees/reductions per ancillary (related to the offered product).
+
+**Question**: should we rely on e.g. NeTEx to publish the definition of available ancillaries?
+
+Filters: product(s)
+
+#### Allocate ancillary
+
+__POST /ancillary-allocation__ or __POST /processes/allocate-ancillary/execution__
++ offerRef
++ offerElementRef (travel right)
++ ancillaryId
+
+After executing this function, the complete, updated offer (list) will be returned.
+
+**Question**: should we introduce a policy 'updatesOnly'? Default false, returning the complete offer (list). If true, only delivering the added/exchanged allocation(s), but in the same structure.
+
+### Add additional travelling entity (travel right)
+
+This is a function to extend the travelling party. It must be possible to supply a travelling entity. The locked resources will remain locked during the process. It will not contain the (mandatory) information for this travelling entity. Use 'Supply information' for this.
+
+After executing this function, the complete, updated offer (list) will be returned.
+
+__POST /travelling-entity__ or __POST /processes/add-travelling-entity/execution__
++ offerRef
++ traveller details
+
+### Add additional leg (travel right)
+
+This functionality will consist of 2 parts:
+- search for offers, and include the existing offer as input
+- add one of the offers to the locked offer collection.
+
+This function should also cover the use case to start with locking a product offer, and add a trip offer
+
+__POST /search-offers__ or __POST /processes/search-offers/execution__
++ offerToExtend = offerRef
+... returns offers
+
+__POST /travel-right__ or __POST /processes/add-travel-right/execution__
++ offerRef
++ offerToExtend
+
+## Supply information
+
+The retailer should be able to submit information that is required, see the search-offer response.
+
+__POST /offer-information__ or __POST /processes/add-offer-information/execution__
++ offerRef
++ travellingEntityData : [ { data-element, travellingEntityRef, value } ]
++ optionalReductionItems : [ { issuer, reductionType, code } ]
+
+The information supplied here CANNOT be retrieved in the API, to avoid GDPR conflicts.
+
+## Retrieve offer details
+
+This is a simple request to return the offer object.
+
+__GET /offers__ or __GET /collections/offers/items__
++ offerRef
+
+## Remove not-mandatory offer element (allocation, ancillary, travel right)
+
+This requist should referring an offer & offer element(s) to remove. Removal of offer elements bundled by guarantees will be rejected,
+or the guarantee will be removed. Mandatory offer elements cannot be removed.
+
+__DELETE /offer-element__ or __POST /processes/remove-offer-element/execution__
++ offerRef
++ offerElementRef
\ No newline at end of file
diff --git a/deliverables/3 purchase offer/purchase-offer-model.qea b/deliverables/3 purchase offer/purchase-offer-model.qea
new file mode 100644
index 0000000..bf7a7ae
Binary files /dev/null and b/deliverables/3 purchase offer/purchase-offer-model.qea differ
diff --git a/deliverables/5 refund/refund-offer-model.qea b/deliverables/5 refund/refund-offer-model.qea
new file mode 100644
index 0000000..6d986f5
Binary files /dev/null and b/deliverables/5 refund/refund-offer-model.qea differ
diff --git a/deliverables/6 after sales/after-sales-model.qea b/deliverables/6 after sales/after-sales-model.qea
new file mode 100644
index 0000000..f4cd6bf
Binary files /dev/null and b/deliverables/6 after sales/after-sales-model.qea differ
diff --git a/deliverables/6 after sales/possibilities.md b/deliverables/6 after sales/possibilities.md
new file mode 100644
index 0000000..72a31a0
--- /dev/null
+++ b/deliverables/6 after sales/possibilities.md
@@ -0,0 +1,21 @@
+
+* Cancel : ROLLBACK of the purchase without a fee
+* Refund : Refund of unused travel right(s), when the customer/traveller has changed their mind
+* Reimbursed : Traveller is not able to use the travel right(s) due to unforseen circumstances for the Traveller (requires proof)
+* Redress of guarantee : Refund of broken guarantee(s)
+ * Complaint : Traveller is not able to use the travel right due to the fault of the Carrier (financial compensation)
+ * Redress: all the other redress options.
+* Release : Postponed refund, first addressed to the carrier.
+* Exchange : exchange package element(s) for other package element(s)
+* Transfer : hand over of travel rights to another traveller or device
+* Suspend / resume : start/stop usability of a purchase package
+* Revoke travel document :
+* Revoke travel right :
+* Renew package : retailer's task.
+* Reissue travel document :
+
+* Addition : ADDING additional package elements.
+ * available spots / allocate spots
+ * available ancillaries / allocate ancillaries
+ * additional travel right / travel right (adding persons/legs)
+ * Cross-sell
diff --git a/deliverables/guide-lines/enums.md b/deliverables/guide-lines/enums.md
new file mode 100644
index 0000000..6537d65
--- /dev/null
+++ b/deliverables/guide-lines/enums.md
@@ -0,0 +1,184 @@
+
+# Guidelines on the use of enums, extensible enums and lookup data
+
+These guidelines must be respected when implementing/designing the OTI, when using enums, x-enums or lookup lists.
+
+## Enum
+
+Enums define a _final_ list of values for an API version.
+_Deleting a value is a mayor verion change_ and _adding an enum a minor version change_.
+In case an additional value should be used with older API versions patch versions are needed for the older versions.
+
+__Values of an enum cannot be deprecated.__
+
+Use an Enum only if:
+* The values will not change within the next years until the next mayor version
+* The values are assumed to be exhaustive in the context of the API version
+
+*Example*
+```json
+ type: string
+ description: |
+ VALUE_1 : English description of what this value means
+ VALUE_2 : English description of what this value means
+ enum:
+ - VALUE_1
+ - VALUE_2
+ default: VALUE_2
+```
+
+> __NOTE!__
+> Enums like these must be described in the OTI specification, and should be taken 'as is'; they are inmutable.
+
+## Extensible Enum
+
+Extensible enums are used to specify a list of values not bound to an API version.
+New values can be added to the list at any time by the governing body of the API.
+The list needs to be documented separately from the API, but it is not bound to an API version.
+Implementers must be able to handle new values. A documentation on the expected implementations should be added in the comment on the enumeration. In general, the behaviour will be to ignore the unknown values.
+
+Extensible enums might be used as new values are defined frequentely or because they are open for bilateraly or unilateraly defined values. It must be documented whether bilateral or unilateral additional values are allowed.
+
+*Example*
+```json
+ someExtendibleEnum:
+ type: string
+ externalDocs:
+ description: This url refers to the definition of the code list 'someExtendibleEnum'
+ url: https:/..../oti/codelists?#someExtendibleEnum
+ description: |
+ VALUE_3 : Only for uni- or bilateral values
+ x-extensible-enum:
+ - VALUE_1
+ - VALUE_2
+ - VALUE_3
+```
+> __NOTE!__
+> Avoid extending these list as much as possible (interoperability).
+> If it is not avoidable, reach out to the governing body to request the addition of a new value.
+> In the meantime, you can add it as a uni- or bilateral value.
+
+*Usage conditions*
+> * If, and only if, you have uni- or bilateral values, you MAY extend this list. Notify the governing body.
+> * only codelist values must be accepted by requestors (Retailer),
+> * unknown (to the requestor) values should be ignored
+
+*Useful instructions*
+> * Use the pipe ("|") in the description, this means that linefeeds will be taken literally.
+> * Use 2 spaces in the description to specify a line feed:
+> VALUE_1 : English description of what this value means <-- ADDED TO SPACES HERE
+
+## Lookup lists
+
+This refers to an API endpoint to get possible selectable items, instead of specifying them in the specification. It is not included in the API messages themselfes due to:
+* operator/distributor-specific
+* frequent updates
+
+_Some example scenarios_
+If the information is needed before the API message flow starts:
+* the reduction cards accepted by a provider so they can be used in a customer account prior to the sales process
+* product search options needed to setup the search UI prior to a product based search.
+
+If the information might require some preprocessing to be adopted to sales channels:
+* Layouts for a graphical selection of seats
+
+If supportive information is needed for use cases:
+* Detailed definition of zones to be displayed graphically.
+
+*Example without ETag*
+This is an EXAMPLE. It is not likely that the statusses will need a flexible list.
+
+> Request
+```http
+GET /statusses
+Accept: application/json
+```
+> Response 1: small datasets
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+ETag: "ETag1"
+Cache-Control: max-age=0, must-revalidate
+{
+ "new": {
+ "nl": "Nieuw",
+ "en": "New",
+ "de": "Neu"
+ },
+ "pending": {
+ "nl": "Wachtend",
+ "en": "Pending",
+ "de": "Ausstehend"
+ }
+}
+```
+> Response 2: large datasets
+```http
+HTTP/1.1 303 See Other
+Location: https://.../statusses_v1
+ETag: "ETag1"
+Cache-Control: max-age=0, must-revalidate
+```
+The data can be fetched directly from the 'Location' (rerouting).
+
+*Example using the ETag*
+
+The initial retrieval of the data is the same as without using the ETag. But now it is possible to
+use the ETag header field, to check if it is possible to reuse data retrieved earlier, to reduce the
+amount of transmitted data.
+
+> ETag enabled request
+```http
+GET /statusses
+Accept: application/json
+If-None-Match: "eTag1"
+```
+> Response 1: data is not modified, the ETag remains the same
+```http
+HTTP/1.1 304 Not Modified
+ETag: "ETag1"
+```
+> Response 2: data is modified, the ETag is different, for small datasets
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+ETag: "ETag2"
+
+{
+ "new": {
+ "nl": "Nieuw",
+ "en": "New",
+ "de": "Neu"
+ },
+ "pending": {
+ "nl": "In afwachting",
+ "en": "Pending",
+ "de": "Ausstehend"
+ }
+}
+
+```
+> Response 2: data is modified, the ETag is different, for large datasets
+```http
+HTTP/1.1 303 See Other
+Location: https://.../statusses_v2
+ETag: "ETag2"
+Cache-Control: max-age=0, must-revalidate
+```
+
+*Usage conditions*
+> Lookup endpoints MUST provide:
+> * multilanguage support for all text
+
+> Endpoints for larger data sets MUST support:
+> * cache control using a strong ETag as version tag
+ ETag = MD5, SHA-1 of SHA-256 hash of the result, between double quotes.
+> * http reply 303 with a download location
+
+> __NOTE!__
+> In the OTI, it will be prescribed per data lookup endpoint if it requires the 'large data set' regime.
+
+### ETag references
+* RFC 9110: HTTP Semantics - Section 8.8.3 (ETag)
+* RFC 9110: HTTP Semantics - Section 13.1.2 (If-None-Match)
+* RFC 9111: HTTP Caching
diff --git a/deliverables/openapi/components/headers/accept-language.yaml b/deliverables/openapi/components/headers/accept-language.yaml
new file mode 100644
index 0000000..e62c265
--- /dev/null
+++ b/deliverables/openapi/components/headers/accept-language.yaml
@@ -0,0 +1,10 @@
+in: header
+name: Accept-Language
+required: true
+schema:
+ type: string
+x-externalDocs:
+ description: >-
+ A comma-separated list of BCP 47 (RFC 5646) language tags and optional
+ weights as described in IETF RFC7231 section 5.3.5.
+ A list of the languages/localizations the user prefers.
\ No newline at end of file
diff --git a/deliverables/openapi/components/headers/authorization.yaml b/deliverables/openapi/components/headers/authorization.yaml
new file mode 100644
index 0000000..a078a29
--- /dev/null
+++ b/deliverables/openapi/components/headers/authorization.yaml
@@ -0,0 +1,6 @@
+in: header
+name: authorization
+required: true
+schema:
+ type: string
+description: Header field, JWT-bearer must be supplied
\ No newline at end of file
diff --git a/deliverables/openapi/components/headers/content-language.yaml b/deliverables/openapi/components/headers/content-language.yaml
new file mode 100644
index 0000000..497a3a2
--- /dev/null
+++ b/deliverables/openapi/components/headers/content-language.yaml
@@ -0,0 +1,9 @@
+in: header
+name: Content-Language
+required: true
+schema:
+ type: string
+x-externalDocs:
+ description: >-
+ A comma-separated list of BCP 47 (RFC 5646) language tags and optional
+ weights as described in IETF RFC7231 section 5.3.5.
diff --git a/deliverables/openapi/components/headers/expires.yaml b/deliverables/openapi/components/headers/expires.yaml
new file mode 100644
index 0000000..8cfd31c
--- /dev/null
+++ b/deliverables/openapi/components/headers/expires.yaml
@@ -0,0 +1,10 @@
+in: header
+name: expires
+required: true
+description: A HTTP date string
+schema:
+ type: string
+ format: http-date
+x-externalDocs:
+ url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires
+ description: http-date format as defined in RFC7231, section 7.1.1.1
\ No newline at end of file
diff --git a/deliverables/openapi/components/headers/version.yaml b/deliverables/openapi/components/headers/version.yaml
new file mode 100644
index 0000000..91bf309
--- /dev/null
+++ b/deliverables/openapi/components/headers/version.yaml
@@ -0,0 +1 @@
+type: object
diff --git a/deliverables/openapi/components/requestBodies/LockOfferRequest.yaml b/deliverables/openapi/components/requestBodies/LockOfferRequest.yaml
new file mode 100644
index 0000000..5cc5224
--- /dev/null
+++ b/deliverables/openapi/components/requestBodies/LockOfferRequest.yaml
@@ -0,0 +1,23 @@
+content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ offerReference:
+ description: >
+ The reference of the offer to be locked. This reference is obtained from the offer search response.
+ type: string
+
+ allocationRefs:
+ type: array
+ description: >
+ The references of the offer allocations to be locked. These references are obtained from the offer search response.
+ items:
+ type: string
+
+ ancillaryRefs:
+ type: array
+ description: >
+ The references of the ancillary services to be locked. These references are obtained from the offer search response.
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/requestBodies/SearchOfferRequest.yaml b/deliverables/openapi/components/requestBodies/SearchOfferRequest.yaml
new file mode 100644
index 0000000..db2d5ef
--- /dev/null
+++ b/deliverables/openapi/components/requestBodies/SearchOfferRequest.yaml
@@ -0,0 +1,96 @@
+ searchOfferRequest:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ travellers:
+ type: array
+ minItems: 1
+ description: >
+ The travelling entities (travellers, vehicles, animals, luggage) for whom offers are sought.
+ items:
+ oneOf:
+ - $ref: ../schemas/Traveller.yaml
+ - $ref: ../schemas/PassengerVehicle.yaml
+ - $ref: ../schemas/Animal.yaml
+ - $ref: ../schemas/Luggage.yaml
+ discriminator:
+ propertyName: entityType
+ mapping:
+ traveller: ../schemas/Traveller.yaml
+ vehicle: ../schemas/PassengerVehicle.yaml
+ animal: ../schemas/Animal.yaml
+ luggage: ../schemas/Luggage.yaml
+ tripPatterns:
+ type: array
+ items:
+ $ref: ../schemas/TripPattern.yaml
+ products:
+ type: array
+ items:
+ $ref: ../schemas/Product.yaml
+ policy:
+ type: object
+ properties:
+ # result constraints
+ requestedCurrency:
+ description: >
+ The currency in which the offer prices should be returned. This is relevant for offers that include prices.
+ ISO 4217 currency code, e.g. "EUR", "USD", "GBP", etc.
+ type: string
+
+ requestedLanguage:
+ description: >
+ The language in which the offer should be returned. This is relevant for offers that include human-readable descriptions,
+ such as the offer summary or the description of the offer elements.
+ RFC 5646 language tag, e.g. "en", "de", "fr", etc.
+ type: string
+
+ exactMatch:
+ description: >
+ Whether the search should return only offers that exactly match the specified criteria (true)
+ or if it can also return offers that partially match the criteria (false).
+ TBD: (recommended) remove this field. If the retailer want to have also alternatives, it must
+ request e.g. additional classes of use, modes, etc. in the filters.
+ type: boolean
+ filters:
+ type: object
+ properties:
+ # travellers constraints (=> trip planner)
+ # maxTransfers:
+ # type: integer
+ # maxTravelTime:
+ # type: integer
+ # maxWalkingTime:
+ # type: integer
+ # maxTransferWalkingTime:
+ # type: integer
+ # maxTransferDistance:
+ # type: integer
+
+ # media/distribution constraints
+ mediaTypes:
+ type: array
+ items:
+ type: string
+ distributionChannels:
+ type: array
+ items:
+ type: string
+
+ # mode constraints
+ modes:
+ type: array
+ items:
+ type: string
+ classOfUse:
+ type: array
+ items:
+ type: string
+
+ # leg constraints (for trip pattern-based search)
+ sections:
+ type: array
+ items:
+ $ref: ../schemas/Section.yaml
diff --git a/deliverables/openapi/components/responses/LockOfferDelivery.yaml b/deliverables/openapi/components/responses/LockOfferDelivery.yaml
new file mode 100644
index 0000000..45fdb82
--- /dev/null
+++ b/deliverables/openapi/components/responses/LockOfferDelivery.yaml
@@ -0,0 +1,12 @@
+description: The reponse of the lock offer request, or the details of the locked offer.
+headers:
+ Version:
+ $ref: ../headers/version.yaml
+ Content-Language:
+ $ref: ../headers/contentLanguage.yaml
+ Expires:
+ $ref: ../headers/expires.yaml
+content:
+ application/json:
+ schema:
+ $ref: ../schemas/LockedOffer.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/responses/LockOfferDetailsDelivery.yaml b/deliverables/openapi/components/responses/LockOfferDetailsDelivery.yaml
new file mode 100644
index 0000000..f81b88b
--- /dev/null
+++ b/deliverables/openapi/components/responses/LockOfferDetailsDelivery.yaml
@@ -0,0 +1 @@
+$ref: LockOfferDelivery.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/responses/SearchOfferDelivery.yaml b/deliverables/openapi/components/responses/SearchOfferDelivery.yaml
new file mode 100644
index 0000000..c7725da
--- /dev/null
+++ b/deliverables/openapi/components/responses/SearchOfferDelivery.yaml
@@ -0,0 +1,12 @@
+type: object
+properties:
+ offers:
+ type: array
+ items:
+ $ref: ../schemas/Offer.yaml
+
+ links:
+ type: array
+ description: Hypermedia links for further actions (e.g. pagination).
+ items:
+ $ref: ../schemas/Link.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/AddresInput.yaml b/deliverables/openapi/components/schemas/AddresInput.yaml
new file mode 100644
index 0000000..cdcac20
--- /dev/null
+++ b/deliverables/openapi/components/schemas/AddresInput.yaml
@@ -0,0 +1,20 @@
+allOf:
+ - $ref: Place.yaml
+ - type: object
+ additionalProperties: false
+ description: ADDRESS (INPUT) — a postal address as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: address
+ addressLine1:
+ type: string
+ description: Primary address line (street name and number).
+ addressLine2:
+ type: string
+ description: Secondary address line (postalcode, city, state, nation)
+ addressLine3:
+ type: string
+ description: Tertiary address line (additional address information, if needed)
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/AllocationPlaceHolder.yaml b/deliverables/openapi/components/schemas/AllocationPlaceHolder.yaml
new file mode 100644
index 0000000..1f7607b
--- /dev/null
+++ b/deliverables/openapi/components/schemas/AllocationPlaceHolder.yaml
@@ -0,0 +1,11 @@
+allOf:
+- $ref: ./PlaceHolder.yaml
+- type: object
+ properties:
+ travelRightRef:
+ type: string
+ selectableAllocationRefs:
+ type: array
+ description: the offer elements associated to this placeholder (e.g. seat allocation, asset allocation).
+ items:
+ type: string
diff --git a/deliverables/openapi/components/schemas/Ancillary.yaml b/deliverables/openapi/components/schemas/Ancillary.yaml
new file mode 100644
index 0000000..a018755
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Ancillary.yaml
@@ -0,0 +1,8 @@
+allOf:
+ - $ref: ./OfferElement.yaml
+ - type: object
+ description: ANCILLARY — an ancillary offer element, which can be added to an offer
+ properties:
+ ancillaryType:
+ type: string
+ description: the type of ancillary (e.g. baggage, meal, lounge access). Lookup
diff --git a/deliverables/openapi/components/schemas/AncillaryPlaceHolder.yaml b/deliverables/openapi/components/schemas/AncillaryPlaceHolder.yaml
new file mode 100644
index 0000000..8e547b2
--- /dev/null
+++ b/deliverables/openapi/components/schemas/AncillaryPlaceHolder.yaml
@@ -0,0 +1,13 @@
+allOf:
+- $ref: ./PlaceHolder.yaml
+- type: object
+ properties:
+- type: object
+ properties:
+ travelRightRef:
+ type: string
+ selectableAncillaryRefs:
+ type: array
+ description: the offer elements associated to this placeholder (e.g. seat allocation, asset allocation).
+ items:
+ type: string
diff --git a/deliverables/openapi/components/schemas/Animal.yaml b/deliverables/openapi/components/schemas/Animal.yaml
new file mode 100644
index 0000000..7260039
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Animal.yaml
@@ -0,0 +1,22 @@
+allOf:
+ - $ref: TravellingEntity.yaml
+ - type: object
+ additionalProperties: false
+ description: ANIMAL — an animal travelling alongside its owner.
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: animal
+ type:
+ type: string
+ description: Category of animal.
+ x-extensible-enum:
+ - dog
+ - cat
+ - other
+ assistant:
+ type: boolean
+ description: Whether this animal is a registered assistance animal.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/AssetAllocation.yaml b/deliverables/openapi/components/schemas/AssetAllocation.yaml
new file mode 100644
index 0000000..f01b055
--- /dev/null
+++ b/deliverables/openapi/components/schemas/AssetAllocation.yaml
@@ -0,0 +1,12 @@
+allOf:
+ - $ref: ./PriceableObject.yaml
+ - type: object
+ description: ASSET ALLOCATION — an asset allocation offer element, which can be added to an offer
+ properties:
+ #assetType:
+ # type: string
+ # description: the type of asset (e.g. vehicle, equipment). Lookup / x-enum to be defined.
+ # => product of the asset can be used to determine the type of asset, so assetType is not needed as a separate property
+ assetId:
+ type: string
+ description: the identifier of the allocated asset
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/ContinuousLeg.yaml b/deliverables/openapi/components/schemas/ContinuousLeg.yaml
new file mode 100644
index 0000000..1f235fe
--- /dev/null
+++ b/deliverables/openapi/components/schemas/ContinuousLeg.yaml
@@ -0,0 +1,25 @@
+allOf:
+ - $ref: .\Leg.yaml
+ - type: object
+ additionalProperties: false
+ description: CONTINUOUS LEG (INPUT) — a leg without fixed timetabled stops (e.g. walk, cycle, taxi).
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: continuous
+ startTime:
+ type: string
+ format: date-time
+ description: Scheduled start time of this leg.
+ endTime:
+ type: string
+ format: date-time
+ description: Scheduled end time of this leg.
+ startLocation:
+ description: Departure location for this continuous leg.
+ $ref: .\Place.yaml
+ endLocation:
+ description: Arrival location for this continuous leg.
+ $ref: .\Place.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/EntitlementRight.yaml b/deliverables/openapi/components/schemas/EntitlementRight.yaml
new file mode 100644
index 0000000..b37e363
--- /dev/null
+++ b/deliverables/openapi/components/schemas/EntitlementRight.yaml
@@ -0,0 +1,19 @@
+type: object
+additionalProperties: false
+description: >
+ ENTITLEMENT RIGHT — a credential held by a travelling entity that may
+ qualify for reduced fares or special conditions (loyalty card, discount
+ card, concession, etc.).
+required:
+ - entitlementType
+properties:
+ issuer:
+ type: string
+ description: Issuing authority or scheme name.
+ entitlementType:
+ type: string
+ description: >
+ Type of entitlement (operator-defined lookup value).
+ code:
+ type: string
+ description: Instance identifier such as a card number or voucher code.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Fee.yaml b/deliverables/openapi/components/schemas/Fee.yaml
new file mode 100644
index 0000000..1aa5d20
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Fee.yaml
@@ -0,0 +1,10 @@
+type: object
+properties:
+ feeType:
+ type: string
+ description: The type of fee being applied (e.g., service fee, booking fee, cancellation fee).
+ offerElementRefs:
+ type: array
+ description: The related offer elements that this fee is covering. This can include specific services, products, or other components of the offer.
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Fulfillment.yaml b/deliverables/openapi/components/schemas/Fulfillment.yaml
new file mode 100644
index 0000000..6e7c520
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Fulfillment.yaml
@@ -0,0 +1,31 @@
+type: object
+description: FULFILLMENT — the fulfillment details of a booked offer
+properties:
+ fulfillmentId:
+ type: string
+ description: the identifier of the fulfillment
+ travellingEntityRefs:
+ type: array
+ description: the travelling entities associated to the fulfillment (e.g. passenger, driver).
+ This can be used to determine for whom the fulfillment is.
+ items:
+ type: string
+ travelDocuments:
+ type: array
+ description: the travel documents associated to the fulfillment (e.g. ticket, boarding pass)
+ items:
+ $ref: './TravelDocument.yaml'
+ packageElementRefs:
+ type: array
+ description: the package elements associated to the fulfillment (e.g. travel right, ancillary, seat allocation).
+ This can be used to determine what is fulfilled.
+ items:
+ type: object
+ properties:
+ packageElementRef:
+ type: string
+ description: the reference to the package element (e.g. travel right, ancillary, seat allocation)
+ sectionRef:
+ type: string
+ description: the reference to the section of the trip for which the package element is fulfilled.
+ This can be used to determine when the fulfillment is valid based on the itinerary of the trip.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/GeoPosition.yaml b/deliverables/openapi/components/schemas/GeoPosition.yaml
new file mode 100644
index 0000000..2fbb363
--- /dev/null
+++ b/deliverables/openapi/components/schemas/GeoPosition.yaml
@@ -0,0 +1,15 @@
+type: object
+additionalProperties: false
+description: A geodetic position (WGS-84).
+required:
+- longitude
+- latitude
+properties:
+ longitude:
+ type: number
+ format: double
+ description: Longitude in decimal degrees (WGS-84).
+ latitude:
+ type: number
+ format: double
+ description: Latitude in decimal degrees (WGS-84).
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Guarantee.yaml b/deliverables/openapi/components/schemas/Guarantee.yaml
new file mode 100644
index 0000000..f777ae5
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Guarantee.yaml
@@ -0,0 +1,29 @@
+type: object
+description: GUARANTEE — a guarantee associated to package elements
+properties:
+
+ guaranteeType:
+ type: string
+ description: the type of guarantee (e.g. refund, exchange, cancel)
+ enum:
+ - refund
+ - exchange
+ - cancel
+ - travel_through
+
+ description:
+ type: string
+ description: a human readable description of the guarantee
+
+ packageElementRefs:
+ type: array
+ description: the package element(s) to which the guarantee applies
+ items:
+ type: string
+
+ redresses:
+ type: array
+ description: the redresses associated to the guarantee
+ items:
+ $ref: ./Redress.yaml
+
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Leg.yaml b/deliverables/openapi/components/schemas/Leg.yaml
new file mode 100644
index 0000000..978d31f
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Leg.yaml
@@ -0,0 +1,30 @@
+type: object
+description: LEG (INPUT) — a single leg within a trip. Use the legType discriminator to select the concrete sub-type.
+required:
+- legId
+- legType
+properties:
+ legId:
+ type: string
+ description: Caller-assigned identifier for this leg.
+ sequenceNumber:
+ type: integer
+ description: Position of this leg within the trip.
+ mode:
+ type: string
+ description: Transport mode for this leg.
+ enum:
+ - rail
+ - coach
+ - bus
+ - ferry
+ - metro
+ - tram
+ - air
+ - other
+ legType:
+ type: string
+ description: Discriminator identifying the concrete leg type.
+ trip:
+ type: string
+ description: Caller-assigned identifier for the trip this leg belongs to (used to group legs from the same trip, e.g. for interlining).
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/LegAlight.yaml b/deliverables/openapi/components/schemas/LegAlight.yaml
new file mode 100644
index 0000000..e6a6035
--- /dev/null
+++ b/deliverables/openapi/components/schemas/LegAlight.yaml
@@ -0,0 +1,17 @@
+type: object
+additionalProperties: false
+description: LEG ALIGHT — the alighting event at the end of a timed leg.
+required:
+- stopPlaceRef
+- plannedArrivalTime
+properties:
+ stopPlaceRef:
+ type: string
+ description: Reference to the NeTEx SCHEDULED STOP POINT or STOP PLACE where alighting occurs.
+ plannedArrivalTime:
+ type: string
+ format: date-time
+ description: Scheduled arrival time at the alighting stop.
+ setDownLocation:
+ type: string
+ description: Reference to a specific platform, bay, or set-down zone within the stop place.
diff --git a/deliverables/openapi/components/schemas/LegBoard.yaml b/deliverables/openapi/components/schemas/LegBoard.yaml
new file mode 100644
index 0000000..34d7cdd
--- /dev/null
+++ b/deliverables/openapi/components/schemas/LegBoard.yaml
@@ -0,0 +1,22 @@
+type: object
+additionalProperties: false
+description: LEG BOARD — the boarding event at the start of a timed leg.
+required:
+- stopPlaceRef
+- plannedDepartureTime
+properties:
+ stopPlaceRef:
+ type: string
+ description: Reference to the NeTEx SCHEDULED STOP POINT or STOP PLACE where boarding occurs.
+ plannedDepartureTime:
+ type: string
+ format: date-time
+ description: Scheduled departure time at the boarding stop.
+ pickupLocation:
+ type: string
+ description: Reference to a specific platform, bay, or pick-up zone within the stop place.
+ trainNumbers:
+ type: array
+ description: Commercial train numbers for this departure.
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Link.yaml b/deliverables/openapi/components/schemas/Link.yaml
new file mode 100644
index 0000000..3415ea0
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Link.yaml
@@ -0,0 +1,43 @@
+type: object
+description: Link object
+properties:
+ href:
+ type: string
+ description: the URL of the linked resource
+ rel:
+ type: string
+ description: the relationship between the current resource and the linked resource
+ type:
+ type: string
+ description: >-
+ the media type of the linked resource (recommended: use IANA MIME type)
+ title:
+ type: string
+ description: a human-readable title for the linked resource
+
+ method:
+ type: string
+ description: to indicate the HTTP method.
+ default: GET
+ enum:
+ - POST
+ - GET
+ - DELETE
+ - PATCH
+ body:
+ type: object
+ description: the (prefilled) body for the request
+ headers:
+ type: object
+ additionalProperties:
+ type: string
+ mandatory:
+ description: is this link informative, or must it be used?
+ type: boolean
+ availableFrom:
+ type: string
+ format: date-time
+ expires:
+ type: string
+ format: date-time
+
diff --git a/deliverables/openapi/components/schemas/LockedOffer.yaml b/deliverables/openapi/components/schemas/LockedOffer.yaml
new file mode 100644
index 0000000..5f4a16e
--- /dev/null
+++ b/deliverables/openapi/components/schemas/LockedOffer.yaml
@@ -0,0 +1 @@
+$ref: ./Offer.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Luggage.yaml b/deliverables/openapi/components/schemas/Luggage.yaml
new file mode 100644
index 0000000..f14559e
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Luggage.yaml
@@ -0,0 +1,42 @@
+allOf:
+ - $ref: TravellingEntity.yaml
+ - type: object
+ additionalProperties: false
+ description: >
+ LUGGAGE — a bulky item a traveller brings that may affect offer
+ availability, space allocation, or price.
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: luggage
+ type:
+ type: string
+ description: Category of item.
+ x-extensible-enum:
+ - bicycle
+ - pram
+ - luggage
+ - wheelchair
+ - skis
+ - snowboard
+ - musicalInstrument
+ - other
+ length:
+ type: integer
+ minimum: 0
+ description: Length in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width in centimetres.
+ height:
+ type: integer
+ minimum: 0
+ description: Height in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Weight in kilograms.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Offer.yaml b/deliverables/openapi/components/schemas/Offer.yaml
new file mode 100644
index 0000000..6311609
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Offer.yaml
@@ -0,0 +1,27 @@
+allOf:
+- $ref: ./Package.yaml
+- type: object
+ required:
+ - minimumPrice
+
+ properties:
+ matching:
+ type: string
+ enum:
+ - exact
+ - partial
+
+ minimumPrice:
+ $ref: ./Price.yaml
+
+ personalInformationRequired:
+ type: boolean
+
+ placeHolders:
+ type: array
+ description: .
+ items:
+ oneOf:
+ - $ref: ./TravellingEntityPlaceHolder.yaml
+ - $ref: ./AllocationPlaceHolder.yaml
+ - $ref: ./AncillaryPlaceHolder.yaml
diff --git a/deliverables/openapi/components/schemas/OfferElement.yaml b/deliverables/openapi/components/schemas/OfferElement.yaml
new file mode 100644
index 0000000..29c8fce
--- /dev/null
+++ b/deliverables/openapi/components/schemas/OfferElement.yaml
@@ -0,0 +1,10 @@
+allOf:
+ - $ref: ./PackageElement.yaml
+ - type: object
+ description: OFFER ELEMENT — a priceable part of an offer, like a travel right, an allocation (seat/asset), or an ancillary
+ properties:
+ matching:
+ type: string
+ enum:
+ - exact
+ - partial
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Package.html b/deliverables/openapi/components/schemas/Package.html
new file mode 100644
index 0000000..dba9223
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Package.html
@@ -0,0 +1,166 @@
+
+
+
+
+
+ OpenAPI Preview — Package.yaml
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Package.yaml b/deliverables/openapi/components/schemas/Package.yaml
new file mode 100644
index 0000000..f11c3a2
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Package.yaml
@@ -0,0 +1,109 @@
+type: object
+description: >-
+ a package, containing all information to travel, which can be offered to customers. A package is composed of:
+ - the 'who' (the travelling entities associated to the package, e.g. travellers, luggage, vehicles, animals)
+ - the 'what' (the trip patterns and sections associated to the package)
+ - the 'how' (the offer elements associated to the package, e.g. travel rights, seat allocations, ancillaries)
+ - the guarantees associated to the package
+required:
+ - packageId
+ - version
+
+properties:
+ ## machine identification
+ packageId:
+ type: string
+ description: the identifier of the package
+ version:
+ type: string
+ description: the version of the package
+ status:
+ type: string
+ description: the status of the package
+ enum:
+ - offered
+ - locked
+ - released
+ - confirmed
+ - rollbacked
+ - expired
+ - fulfilled
+ - cancelled
+ - in_progress
+ - executed
+
+ ## human readable information
+ name:
+ type: string
+ summary:
+ type: string
+ summaryDetails:
+ type: array
+ items:
+ $ref: ./SummaryDetail.yaml
+
+ afterSalesFlexibility:
+ type: string
+ description: >-
+ The flexibility of the offer after the sale has been made.
+ TBD: Define the possible values for this field. Should we include here the allowed 'after sales operations'
+ (e.g. exchange, cancel, refund) instead of flexible, semiFlexible, nonFlexible?
+ enum:
+ - flexible
+ - semiFlexible
+ - nonFlexible
+
+ ## the 'who'
+ travellingEntities:
+ type: array
+ description: the traveling entities associated to the package, which can be used for display purposes
+ items:
+ oneOf:
+ - $ref: ./Traveller.yaml
+ - $ref: ./Luggage.yaml
+ - $ref: ./PassengerVehicle.yaml
+ - $ref: ./Animal.yaml
+
+ ## the 'what'
+ tripPatterns:
+ type: array
+ description: the trip patterns associated to the package, which can be used for display purposes
+ items:
+ $ref: ./TripPattern.yaml
+
+ sections:
+ type: array
+ description: the sections of the package
+ items:
+ $ref: ./Section.yaml
+
+ ## the 'how'
+ elements:
+ type: array
+ minItems: 1
+ items:
+ oneOf:
+ - $ref: ./Ancillary.yaml
+ - $ref: ./SeatAllocation.yaml
+ - $ref: ./AssetAllocation.yaml
+ - $ref: ./TravelRight.yaml
+ - $ref: ./Fee.yaml
+
+ guarantees:
+ type: array
+ description: the guarantees associated to the package, which can be used for display purposes
+ items:
+ $ref: ./Guarantee.yaml
+
+ ## warnings and links
+ warnings:
+ type: array
+ description: the warnings associated to the package, which can be used for display purposes
+ items:
+ $ref: ./Warning.yaml
+
+ links:
+ type: array
+ description: the links associated to the package, which can be used for navigation purposes ( 'find the next technical steps' ).
+ items:
+ $ref: ./Link.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PackageElement.yaml b/deliverables/openapi/components/schemas/PackageElement.yaml
new file mode 100644
index 0000000..6168f19
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PackageElement.yaml
@@ -0,0 +1,31 @@
+allOf:
+ - $ref: ./PriceableObject.yaml
+ - type: object
+ description: PACKAGE ELEMENT — a package element offer element, which can be added to an offer
+ properties:
+ packageElementType:
+ type: string
+ description: the type of package element
+ enum:
+ - travelRight
+ - seatAllocation
+ - assetAllocation
+ - ancillary
+
+ sectionRefs:
+ type: array
+ description: the sections of the offer to which this element belongs
+ items:
+ type: string
+
+ travellingEntityRefs:
+ type: array
+ description: the travelling entities (e.g. travellers) associated to this offer element
+ items:
+ type: string
+
+ mandatory:
+ type: boolean
+ description: Indicates if the package element is mandatory in the offer/package.
+ If true, the package element cannot be removed from the offer/package by the customer.
+ It might be possible to exchange this package element with another one.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PassengerVehicle.yaml b/deliverables/openapi/components/schemas/PassengerVehicle.yaml
new file mode 100644
index 0000000..df55fd8
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PassengerVehicle.yaml
@@ -0,0 +1,54 @@
+allOf:
+ - $ref: TravellingEntity.yaml
+ - type: object
+ additionalProperties: false
+ description: >
+ PASSENGER VEHICLE — a traveller-owned vehicle to be transported
+ (e.g. on a train, a ferry or car-train).
+ required:
+ - entityType
+ - type
+ properties:
+ entityType:
+ type: string
+ const: vehicle
+ type:
+ type: string
+ description: Vehicle category.
+ x-extensible-enum:
+ - car
+ - motorhome
+ - caravan
+ - trailer
+ - motorbike
+ - bicycle
+ - scooter
+ - other
+ height:
+ type: integer
+ minimum: 0
+ description: Height of the vehicle in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width of the vehicle in centimetres.
+ length:
+ type: integer
+ minimum: 0
+ description: Total length of the vehicle in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Total weight of the vehicle in kilograms.
+ licensePlate:
+ type: string
+ description: Vehicle license plate number.
+ trailer:
+ description: Details of a towed trailer, if applicable.
+ $ref: PassengerVehicle.yaml
+ vehicleRacks:
+ type: array
+ maxItems: 2
+ description: Vehicle racks or carriers mounted on the vehicle.
+ items:
+ $ref: VehicleRack.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Place.yaml b/deliverables/openapi/components/schemas/Place.yaml
new file mode 100644
index 0000000..04eb0f9
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Place.yaml
@@ -0,0 +1,18 @@
+type: object
+description: PLACE (INPUT) — a geographic location referenced in the trip context. Use the placeType discriminator to select the concrete sub-type.
+required:
+- placeId
+- placeType
+properties:
+ placeId:
+ type: string
+ description: Caller-assigned identifier for this place. Used to cross-reference from legs or sections.
+ placeType:
+ type: string
+ description: Discriminator identifying the concrete place type.
+ name:
+ type: string
+ description: Name of the place.
+ location:
+ description: Geodetic position of this place.
+ $ref: .\GeoPosition.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PlaceHolder.yaml b/deliverables/openapi/components/schemas/PlaceHolder.yaml
new file mode 100644
index 0000000..9049473
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PlaceHolder.yaml
@@ -0,0 +1,23 @@
+type: object
+properties:
+ placeHolderType:
+ type: string
+ description: the type of placeholder (e.g. traveller, allocation, ancillary).
+ enum:
+ - traveller
+ - allocation
+ - ancillary
+ description:
+ type: string
+ description: a human readable description of the placeholder
+ validationRule:
+ type: object
+ description: rules for validating the placeholder value (JSONPath expression)
+
+examples:
+ - placeHolderType: traveller
+ description: Age must be supplied
+ validationRule: "$.travellingEntities[(@.type=='traveller' && @.travellingEntityId=='23' && @.age != null && @.age != '')]"
+ - placeHolderType: passengerVehicle
+ description: Vehicle license plate must be supplied
+ validationRule: "$.travellingEntities[(@.type=='passengerVehicle' && @.travellingEntityId=='342' && @.licensePlate != null && @.licensePlate != '')]"
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PointOfInterest.yaml b/deliverables/openapi/components/schemas/PointOfInterest.yaml
new file mode 100644
index 0000000..431a075
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PointOfInterest.yaml
@@ -0,0 +1,11 @@
+allOf:
+ - $ref: Place.yaml
+ - type: object
+ additionalProperties: false
+ description: POINT OF INTEREST (INPUT) — a named point of interest as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: pointOfInterest
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Price.yaml b/deliverables/openapi/components/schemas/Price.yaml
new file mode 100644
index 0000000..af2758a
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Price.yaml
@@ -0,0 +1,42 @@
+type: object
+required:
+ - amount
+ - currency
+properties:
+ amount:
+ type: number
+ format: double
+ description: The price amount.
+ currency:
+ type: string
+ description: The currency of the price, in ISO 4217 format (e.g., "USD", "EUR").
+ description:
+ type: string
+ description: An optional description of the price.
+ type:
+ type: string
+ description: An optional type of the price (e.g., "fee").
+ enum:
+ - fee
+ - deposit
+ - fine
+ - refund
+ - reimbursement
+ - other
+ discounts:
+ type: array
+ description: An optional list of discounts APPLIED to the price.
+ items:
+ type: number
+ format: double
+ surcharges:
+ type: array
+ description: An optional list of surcharges APPLIED to the price.
+ items:
+ type: number
+ format: double
+ taxes:
+ type: array
+ description: An optional list of taxes INCLUDED in the price.
+ items:
+ $ref: .\Tax.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PriceableObject.yaml b/deliverables/openapi/components/schemas/PriceableObject.yaml
new file mode 100644
index 0000000..ab0239c
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PriceableObject.yaml
@@ -0,0 +1,21 @@
+type: object
+description: PRICEABLE OBJECT — an object of a trip that can be priced
+properties:
+ priceableObjectId:
+ type: string
+ description: the identifier of the priceable object
+
+ description:
+ type: string
+ description: a description of the priceable object
+
+ fareProductRef:
+ type: string
+ description: the reference to the fare product associated to the priceable object.
+ This can be used to determine the type of the priceable object based on the type of the associated fare product.
+
+ priceElements:
+ type: array
+ description: the price of the priceable object, which can be composed of multiple price elements
+ items:
+ $ref: .\Price.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Product.yaml b/deliverables/openapi/components/schemas/Product.yaml
new file mode 100644
index 0000000..d73ddd1
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Product.yaml
@@ -0,0 +1 @@
+type: object
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/PurchasedPackage.yaml b/deliverables/openapi/components/schemas/PurchasedPackage.yaml
new file mode 100644
index 0000000..8b2e945
--- /dev/null
+++ b/deliverables/openapi/components/schemas/PurchasedPackage.yaml
@@ -0,0 +1,8 @@
+allOf:
+- $ref: ./Package.yaml
+- type: object
+ properties:
+ fulfillments:
+ type: array
+ items:
+ $ref: ./Fulfillment.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Redress.yaml b/deliverables/openapi/components/schemas/Redress.yaml
new file mode 100644
index 0000000..0480f71
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Redress.yaml
@@ -0,0 +1,2 @@
+type: object
+# TBD: add fields
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/SeatAllocation.yaml b/deliverables/openapi/components/schemas/SeatAllocation.yaml
new file mode 100644
index 0000000..f706e5c
--- /dev/null
+++ b/deliverables/openapi/components/schemas/SeatAllocation.yaml
@@ -0,0 +1,34 @@
+allOf:
+ - $ref: ./PriceableObject.yaml
+ - type: object
+ description: SEAT ALLOCATION — a seat allocation offer element, which can be added to an offer
+ properties:
+ spotType:
+ type: string
+ description: the type of allocation (e.g. seat, berth). Lookup / x-enum to be defined.
+ coach:
+ type: string
+ description: the coach of the allocated seat (if applicable)
+ deck:
+ type: string
+ description: the deck of the allocated seat (if applicable)
+ row:
+ type: string
+ description: the row of the allocated seat (if applicable)
+ seatNumber:
+ type: string
+ description: the number of the allocated seat (if applicable)
+
+ # additional properties to specify the validity
+ legRef:
+ type: string
+ description: the reference to the leg of the trip for which the seat is allocated.
+ This can be used to determine the validity of the seat allocation based on the itinerary of the trip.
+ startPlaceRef:
+ type: string
+ description: the reference to the place from which the seat allocation starts to be valid.
+ This can be used to determine the validity of the seat allocation based on the itinerary of the trip.
+ endPlaceRef:
+ type: string
+ description: the reference to the place at which the seat allocation stops being valid.
+ This can be used to determine the validity of the seat allocation based on the itinerary of the trip.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Section.yaml b/deliverables/openapi/components/schemas/Section.yaml
new file mode 100644
index 0000000..248c68f
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Section.yaml
@@ -0,0 +1,25 @@
+type: object
+description: >-
+ A section is a leg-based constraint for trip pattern-based search.
+ It allows to specify constraints on a specific leg of the trip, identified by its start and end leg references.
+required:
+ - sectionId
+ - startLegRef
+ - endLegRef
+properties:
+ sectionId:
+ type: string
+
+ tripPatternRef:
+ description: to refer to a specific trip pattern, if needed.
+ type: string
+
+ startLegRef:
+ type: string
+ endLegRef:
+ type: string
+
+ startPlaceRef:
+ type: string
+ endPlaceRef:
+ type: string
diff --git a/deliverables/openapi/components/schemas/StopPlaceInput.yaml b/deliverables/openapi/components/schemas/StopPlaceInput.yaml
new file mode 100644
index 0000000..cbf3573
--- /dev/null
+++ b/deliverables/openapi/components/schemas/StopPlaceInput.yaml
@@ -0,0 +1,15 @@
+allOf:
+- $ref: '#/components/schemas/Place'
+- type: object
+ additionalProperties: false
+ description: STOP PLACE (INPUT) — a stop place or scheduled stop point identified by reference.
+ required:
+ - placeType
+ - placeRef
+ properties:
+ placeType:
+ type: string
+ const: stopPlace
+ placeRef:
+ type: string
+ description: Reference to a NeTEx STOP PLACE or SCHEDULED STOP POINT.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/SummaryDetail.yaml b/deliverables/openapi/components/schemas/SummaryDetail.yaml
new file mode 100644
index 0000000..3cd8403
--- /dev/null
+++ b/deliverables/openapi/components/schemas/SummaryDetail.yaml
@@ -0,0 +1,36 @@
+type: object
+description: SummaryDetail — a summary of the details of an offer, which can be used for display purposes
+properties:
+ conditions:
+ type: array
+ description: the conditions associated to the offer
+ items:
+ type: string
+ temporalRestrictions:
+ type: string
+ description: the temporal restrictions associated to the offer, RFC 8601 time range
+ pattern: '^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?\/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?)|(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?)$'
+ geographicalRestrictions:
+ type: array
+ description: the geographical restrictions associated to the offer
+ items:
+ description: the geographical restriction, which can be used for display purposes. GeoJSON feature.
+ type: object
+ properties:
+ type:
+ type: string
+ description: the type of the GeoJSON feature (e.g. Point, Polygon)
+ geometry:
+ type: object
+ description: the geometry of the GeoJSON feature
+ properties:
+ type:
+ type: string
+ description: the type of the geometry (e.g. Point, Polygon)
+ coordinates:
+ type: array
+ description: the coordinates of the geometry
+ items:
+ oneOf:
+ - type: number
+ - $ref: '#/components/schemas/GeoJSONGeometry'
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Tax.yaml b/deliverables/openapi/components/schemas/Tax.yaml
new file mode 100644
index 0000000..79b05b9
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Tax.yaml
@@ -0,0 +1,33 @@
+type: object
+required:
+ - amount
+ - currency
+properties:
+ amount:
+ type: number
+ description: The price amount.
+ currency:
+ type: string
+ description: The currency of the price, in ISO 4217 format (e.g., "USD", "EUR").
+ country:
+ type: string
+ description: The country code (ISO 3166-1 alpha-2) where the tax is applied.
+ percentage:
+ type: number
+ format: double
+ description: The tax percentage rate (e.g., 20 for 20%).
+ taxNumber:
+ type: string
+ description: An optional tax identification number or code.
+ type:
+ type: string
+ description: A type of the tax.
+ x-enum:
+ - VAT
+ - GST
+ - sales_tax
+ - service_tax
+ - other
+ description:
+ type: string
+ description: An optional description of the tax.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TimedLeg.yaml b/deliverables/openapi/components/schemas/TimedLeg.yaml
new file mode 100644
index 0000000..743bd8b
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TimedLeg.yaml
@@ -0,0 +1,35 @@
+allOf:
+ - $ref: Leg.yaml
+ - type: object
+ additionalProperties: false
+ description: TIMED LEG (INPUT) — a leg on a fixed timetabled service.
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: timed
+ serviceJourneyRef:
+ type: string
+ description: Reference to the NeTEx SERVICE JOURNEY for this leg.
+ operatingDate:
+ type: string
+ format: date
+ description: The operating date of the service.
+ lineNumber:
+ type: string
+ description: Commercial line number or designator.
+ brand:
+ type: string
+ description: Commercial brand or product name of the service.
+ start:
+ description: Boarding point for this leg.
+ $ref: .\LegBoard.yaml
+ end:
+ description: Alighting point for this leg.
+ $ref: .\LegAlight.yaml
+ intermediateStops:
+ type: array
+ description: Intermediate stops passed during this leg (not boarded/alighted). Each value is a reference to a NeTEx STOP PLACE or SCHEDULED STOP POINT.
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TopologicalPlaceInput.yaml b/deliverables/openapi/components/schemas/TopologicalPlaceInput.yaml
new file mode 100644
index 0000000..d1e4ed8
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TopologicalPlaceInput.yaml
@@ -0,0 +1,18 @@
+allOf:
+ - $ref: .\Place.yaml
+ - type: object
+ additionalProperties: false
+ description: TOPOLOGICAL PLACE (INPUT) — a geographic area or zone as a place.
+ required:
+ - placeType
+ properties:
+ placeType:
+ type: string
+ const: topologicalPlace
+ area:
+ type: object
+ description: GeoJSON Polygon geometry defining the area.
+ range:
+ type: integer
+ minimum: 0
+ description: Search radius in metres around the area centroid.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TransferLeg.yaml b/deliverables/openapi/components/schemas/TransferLeg.yaml
new file mode 100644
index 0000000..29624fe
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TransferLeg.yaml
@@ -0,0 +1,11 @@
+allOf:
+ - $ref: .\Leg.yaml
+ - type: object
+ additionalProperties: false
+ description: TRANSFER LEG — a leg representing a transfer between services (e.g. platform change, interchange).
+ required:
+ - legType
+ properties:
+ legType:
+ type: string
+ const: transfer
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravelDocument.yaml b/deliverables/openapi/components/schemas/TravelDocument.yaml
new file mode 100644
index 0000000..492cd69
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravelDocument.yaml
@@ -0,0 +1,26 @@
+type: object
+required:
+ - travelDocumentId
+ - type
+properties:
+ travelDocumentId:
+ type: string
+
+ type:
+ type: string
+ description: the type of travel document (e.g. QR code, barcode, image, token). Lookup / x-enum to be defined.
+ enum:
+ - QR_CODE
+ - BARCODE
+ - IMAGE
+ - TOKEN
+
+ mediaType:
+ type: string
+ description: the media type of the travel document (e.g. PDF, image/jpeg, etc., IANA media type).
+ This can be used to determine how to process or display the travel document.
+
+ issuingCarrier:
+ type: string
+ description: the carrier that issued the travel document (if applicable)
+
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravelRight.yaml b/deliverables/openapi/components/schemas/TravelRight.yaml
new file mode 100644
index 0000000..8a0eeb8
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravelRight.yaml
@@ -0,0 +1,17 @@
+allOf:
+ - $ref: ./PackageElement.yaml
+ - type: object
+ description: TRAVEL RIGHT — a travel right offer element, which can be added to an offer
+ properties:
+
+ ancillaryRefs:
+ type: array
+ description: the ancillaries associated to this travel right
+ items:
+ type: string
+
+ allocationRefs:
+ type: array
+ description: the seat or asset allocations associated to this travel right
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Traveller.yaml b/deliverables/openapi/components/schemas/Traveller.yaml
new file mode 100644
index 0000000..8d4b68a
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Traveller.yaml
@@ -0,0 +1,51 @@
+allOf:
+ - $ref: TravellingEntity.yaml
+ - type: object
+ additionalProperties: false
+ description: TRAVELLER — a human traveller for whom offers are sought.
+ required:
+ - entityType
+ properties:
+ entityType:
+ type: string
+ const: traveller
+ age:
+ type: integer
+ minimum: 0
+ description: Age in years at the time of travel.
+ assistant:
+ type: boolean
+ description: >
+ Whether this traveller acts as an assistant to another traveller
+ in the same travel party.
+ dateOfBirth:
+ type: string
+ format: date
+ description: >
+ Date of birth. Enables age-band fare calculation.
+ TBD: is is needed, since we do have an 'age'?
+ TBD: if it is, should it be in the traveller, or in its QualifyingCharacteristics?
+ externalReference:
+ type: string
+ description: Caller-assigned external reference for this traveller.
+ personalNeeds:
+ type: array
+ description: >
+ Accessibility or personal needs of this traveller.
+ Values are operator-defined; see the /personal-needs lookup endpoint.
+ For standardisation needs, there will be a list of needs within OTI.
+ The described needs in the list CANNOT be modified, but it is allowed to remove unsupported needs,
+ or to add new ones, but ALWAYS with an unique code. If you want to add this new one to the standard,
+ create an issue on GitHub.
+ items:
+ type: string
+ qualifyingCharacteristics:
+ description: >
+ Additional qualifying characteristics used for eligibility determination.
+ May contain GDPR-sensitive personal data.
+ $ref: TravellerQualifyingCharacteristics.yaml
+ travellingParty:
+ description: >
+ The travel party this traveller belongs to. A travel party is a group of travellers that are travelling together,
+ and for which the same offer(s) should be returned. A travel party may consist of one or more travellers.
+ $ref: TravellingParty.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravellerQualifyingCharacteristics.yaml b/deliverables/openapi/components/schemas/TravellerQualifyingCharacteristics.yaml
new file mode 100644
index 0000000..12672e4
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravellerQualifyingCharacteristics.yaml
@@ -0,0 +1,43 @@
+type: object
+additionalProperties: false
+description: >
+ TRAVELLER QUALIFYING CHARACTERISTICS — demographic and eligibility data
+ used for fare calculation. May contain GDPR-sensitive personal data.
+properties:
+ fullName:
+ type: string
+ description: Full name of the traveller.
+ nationality:
+ type: string
+ description: Nationality (ISO 3166-1 alpha-2 country code).
+ residency:
+ type: string
+ description: >
+ City, state and nation. Like 'Houston, Texas, USA'
+ dateOfBirth:
+ type: string
+ format: date
+ description: Date of birth. (TBD — should it be included)
+ licenseTypes:
+ type: array
+ description: >
+ License types held by this traveller that may affect offer
+ availability (e.g. EU driving licence categories).
+ items:
+ type: string
+ x-enum:
+ - AM
+ - A1
+ - A2
+ - A
+ - B1
+ - B
+ - BE
+ - C1
+ - C1E
+ - C
+ - CE
+ - D1
+ - D1E
+ - D
+ - DE
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravellingEntity.yaml b/deliverables/openapi/components/schemas/TravellingEntity.yaml
new file mode 100644
index 0000000..4f993bd
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravellingEntity.yaml
@@ -0,0 +1,25 @@
+type: object
+description: >
+ TRAVELLING ENTITY — base class for all entities taking part in a journey.
+ Use the entityType discriminator to select the concrete sub-type.
+required:
+ - entityType
+ - travellingEntityId
+properties:
+ travellingEntityId:
+ type: string
+ description: >
+ Stable caller-assigned identifier for this entity.
+ Must be unique, throughout the complete process. Referenced in responses to
+ indicate which offer elements apply to which TRAVELLING ENTITY.
+ entityType:
+ type: string
+ enum: [traveller, vehicle, animal, luggage]
+ description: Discriminator identifying the concrete type of this entity.
+ entitlementRights:
+ type: array
+ description: >
+ ENTITLEMENT RIGHTs held by this entity that may qualify for reduced
+ fares or special conditions.
+ items:
+ $ref: EntitlementRight.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravellingEntityPlaceHolder.yaml b/deliverables/openapi/components/schemas/TravellingEntityPlaceHolder.yaml
new file mode 100644
index 0000000..e47623c
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravellingEntityPlaceHolder.yaml
@@ -0,0 +1,19 @@
+allOf:
+- $ref: ./PlaceHolder.yaml
+- type: object
+ properties:
+ field:
+ type: string
+ description: the type of placeholder, which determines the kind of information that is expected to be filled in.
+ For example, if the type is "fullName", then the value of the placeholder should be a full name. The type can be used to determine how to validate the value of the placeholder and how to use it in the offer.
+ enum:
+ - fullName
+ - passportNumber
+ - age
+ - driverLicenseNumber
+ - vehicleRegistrationNumber
+ travellingEntityRefs:
+ description: the travelling entities associated to this placeholder (e.g. passenger, vehicle, etc). This can be used to determine for whom the placeholder is.
+ type: array
+ items:
+ type: string
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TravellingParty.yaml b/deliverables/openapi/components/schemas/TravellingParty.yaml
new file mode 100644
index 0000000..561f862
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TravellingParty.yaml
@@ -0,0 +1,12 @@
+type: object
+properties:
+ travellingPartyId:
+ type: string
+ description: Caller-assigned identifier for this travel party.
+ travellingPartyType:
+ type: string
+ description: >
+ The type of travel party.
+ enum:
+ - family
+ - group
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/TripPattern.yaml b/deliverables/openapi/components/schemas/TripPattern.yaml
new file mode 100644
index 0000000..35a8d3b
--- /dev/null
+++ b/deliverables/openapi/components/schemas/TripPattern.yaml
@@ -0,0 +1,24 @@
+type: object
+additionalProperties: false
+description: TRIP PATTERN (INPUT) — a proposed trip the traveller wants to undertake, consisting of one or more legs.
+required:
+- legs
+properties:
+ tripPatternId:
+ type: string
+ description: Caller-assigned identifier for this trip pattern.
+ legs:
+ type: array
+ minItems: 1
+ description: The legs that make up this trip pattern.
+ items:
+ oneOf:
+ - $ref: .\TimedLeg.yaml
+ - $ref: .\ContinuousLeg.yaml
+ - $ref: .\TransferLeg.yaml
+ discriminator:
+ propertyName: legType
+ mapping:
+ timed: .\TimedLeg.yaml
+ continuous: .\ContinuousLeg.yaml
+ transfer: .\TransferLeg.yaml
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/VehicleRack.yaml b/deliverables/openapi/components/schemas/VehicleRack.yaml
new file mode 100644
index 0000000..4babaf0
--- /dev/null
+++ b/deliverables/openapi/components/schemas/VehicleRack.yaml
@@ -0,0 +1,35 @@
+type: object
+additionalProperties: false
+description: >
+ VEHICLE RACK — a rack or carrier mounted on a passenger vehicle
+ (e.g. roof rack, bike carrier).
+properties:
+ type:
+ type: string
+ description: Type of rack.
+ x-extensible-enum:
+ - roofRack
+ - bikeCarrier
+ - skiCarrier
+ - towbarCarrier
+ - other
+ mounting:
+ type: string
+ description: How the rack is mounted on the vehicle.
+ enum: [roof, towbar, rear]
+ height:
+ type: integer
+ minimum: 0
+ description: Height of the rack in centimetres.
+ width:
+ type: integer
+ minimum: 0
+ description: Width of the rack in centimetres.
+ length:
+ type: integer
+ minimum: 0
+ description: Length of the rack in centimetres.
+ weight:
+ type: integer
+ minimum: 0
+ description: Weight of the rack including load in kilograms.
\ No newline at end of file
diff --git a/deliverables/openapi/components/schemas/Warning.yaml b/deliverables/openapi/components/schemas/Warning.yaml
new file mode 100644
index 0000000..12b9896
--- /dev/null
+++ b/deliverables/openapi/components/schemas/Warning.yaml
@@ -0,0 +1,33 @@
+type: object
+description: errors/warning, RFC 7807 compliant
+required:
+ - type
+ - title
+properties:
+ type:
+ type: string
+ format: uri
+ description: >-
+ A URI reference that identifies the problem type. This specification encourages that, when dereferenced,
+ it provide human-readable documentation for the problem type (e.g., using HTML). When this member is not present, its value is assumed to be "about:blank".
+ example: "https://example.com/probs/out-of-credit"
+ default: "about:blank"
+ title:
+ type: string
+ description: A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem.
+ example: "You have insufficient balance."
+ status:
+ type: integer
+ format: int32
+ description: The HTTP status code for this specific error.
+ example: 403
+ detail:
+ type: string
+ description: A human-readable explanation specific to this situation. Helps to resolve the error.
+ example: "Your current balance is €30, but the order costs €50."
+ instance:
+ type: string
+ format: uri
+ description: A URI reference that uniquely identifies this specific error (e.g., a transaction or log ID).
+ example: "/transactions/abc-12345"
+additionalProperties: true
\ No newline at end of file
diff --git a/deliverables/openapi/oti.yaml b/deliverables/openapi/oti.yaml
new file mode 100644
index 0000000..1d793f5
--- /dev/null
+++ b/deliverables/openapi/oti.yaml
@@ -0,0 +1,42 @@
+openapi: 3.1.0
+info:
+ title: OpenAPI Specification for OTI
+ version: 0.0.1
+ description: >-
+ This is the OpenAPI specification for the OTI. It defines the request and response formats for the OTI (compliant) API specifications.
+
+servers: []
+paths: {}
+components:
+ requestBodies:
+ $ref: ./requestBodies/SearchOfferRequest.yaml
+ responses:
+ $ref: ./responses/SearchOfferResponse.yaml
+ schemas:
+ TravellingEntity:
+ $ref: ./schemas/TravellingEntity.yaml
+
+ # Traveller
+ Traveller:
+ $ref: ./schemas/Traveller.yaml
+ TravellerQualifyingCharacteristics:
+ $ref: ./schemas/TravellerQualifyingCharacteristics.yaml
+ TravellingParty:
+ $ref: ./schemas/TravellingParty.yaml
+
+ # Vehicles
+ PassengerVehicle:
+ $ref: ./schemas/PassengerVehicle.yaml
+ VehicleRack:
+ $ref: ./schemas/VehicleRack.yaml
+
+ # Luggage
+ Luggage:
+ $ref: ./schemas/Luggage.yaml
+
+ # Animal
+ Animal:
+ $ref: ./schemas/Animal.yaml
+
+
+
diff --git a/deliverables/usecases-to-endpoints.md b/deliverables/usecases-to-endpoints.md
new file mode 100644
index 0000000..9bb3623
--- /dev/null
+++ b/deliverables/usecases-to-endpoints.md
@@ -0,0 +1,151 @@
+# Relationship between Business Use Cases and API Endpoints
+
+This document explains how the **Business Use Cases (BUC-A through BUC-J)** relate to the **API endpoints** defined in the YAML files in this `deliverables` folder.
+
+---
+
+## Overview
+
+The BUC files describe the complete business process of a journey, from inspiration to post-trip aftersales. The YAML files contain the concrete API specifications (OpenAPI 3.1.0) that technically support this process. At this point, **two of the seven phases** have an API specification; the remaining phases are still in preparation.
+
+```
+BUC-A Inspire & Plan ──► 1 search offers/search-offers.yaml ✓
+BUC-B Shop & Price ──► 2 lock offer/lock-offer.yaml ✓ (partial)
+BUC-C Order & Book ──► (not yet available)
+BUC-D Pay ──► (not yet available)
+BUC-E Ticketing ──► (not yet available)
+BUC-F Pre-Trip Aftersales ──► (not yet available)
+BUC-J Post-Trip Aftersales ──► (not yet available)
+
+Lookup tables (supporting BUC-A and BUC-B):
+ ──► 1 search offers/lookup.yaml ✓
+ ──► 2 lock offer/lookup.yaml ✓
+```
+
+---
+
+## BUC-A — Plan your trip / Inspire & Plan
+
+**File:** `wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan.md`
+**Status:** In review — version 3
+
+### Goal
+The traveller defines selection criteria (origin, destination, time, passenger profile) and receives a list of matching offers with price, travel guarantees, and sales conditions.
+
+### Corresponding API specification
+**File:** `deliverables/1 search offers/search-offers.yaml`
+
+| Method | Path | Mapped standard | Description |
+|--------|------|-----------------|-------------|
+| `POST` | `/offers` | OSDM 3.7.1 | Search offers based on trip pattern and passengers |
+| `POST` | `/processes/search-offers/execute` | OMSA 0.1.0 | Same function, OMSA-style |
+| `POST` | `/processes/search-offers/execution` | TOMP-API 2.0.0 | Same function, TOMP-style |
+
+All three endpoints share the same request/response schema, making the API compatible with multiple existing interoperability standards simultaneously.
+
+### How BUC-A shapes the endpoint structure
+
+| BUC-A step | Technical translation in the endpoint |
+|------------|---------------------------------------|
+| Traveller provides selection criteria (origin, destination, time) | `tripPatterns[]` in `OfferRequest` — `TimedLeg`, `ContinuousLeg` or `TransferLeg` |
+| Passenger profile: age, special needs, assisted travel | `travellers[]` — `Traveller`, `PassengerVehicle`, `Animal`, `Luggage` (discriminator `entityType`) |
+| Special needs (PRM, wheelchair, etc.) | `travellers[].personalNeeds[]` — codes from the `/personal-needs` lookup |
+| Filter by transport mode, class of use, media type | `filter` object — `SearchOfferFilter` |
+| Result policy: number of results before/after requested departure, currency | `policy` object — `SearchOfferPolicy` |
+| Retailer consolidates offers with price, guarantees and conditions | `SearchOfferDelivery.offers[]` — each `Offer` contains `elements[]`, `minimumPrice`, `guarantees`, `afterSalesFlexibility` |
+| Customer selects a candidate offer | `Offer.offerId` is passed on to BUC-B (Lock Offer) |
+
+---
+
+## BUC-B — Shop and Price / Basket management
+
+**File:** `wiki/use-cases/business-use-cases/BUC-B-shop-and-price.md`
+**Status:** In review — version 3
+
+### Goal
+The customer builds a shopping basket with selected offers and keeps each element up to date (price, validity, dependencies) until deciding to proceed to reservation and payment.
+
+### Corresponding API specification
+**File:** `deliverables/2 lock offer/lock-offer.yaml`
+
+Locking an offer (offer hold / pre-reservation) is the technical counterpart of the step in BUC-B where the retailer temporarily secures the availability of an offer for the customer.
+
+| Method | Path | Mapped standard | Description |
+|--------|------|-----------------|-------------|
+| `POST` | `/lock-offers` | OSDM 3.7.1 | Lock a selected offer |
+| `POST` | `/processes/lock-offers/execute` | OMSA 0.1.0 | Same function, OMSA-style |
+| `POST` | `/processes/select-offer/execution` | TOMP-API 2.0.0 | Same function, TOMP-style |
+| `GET` | `/locked-offers/{lockedOfferId}` | OSDM 3.7.1 | Retrieve details of a locked offer |
+| `GET` | `/collections/locked-offer-details/items` | OMSA 0.1.0 | Same function, OMSA-style |
+| `GET` | `/collections/offer-details/items` | TOMP-API 2.0.0 | Same function, TOMP-style |
+
+### How BUC-B shapes the endpoint structure
+
+| BUC-B step | Technical translation in the endpoint |
+|------------|---------------------------------------|
+| Customer adds an offer to the basket | `LockOfferRequest.offerReference` — references `Offer.offerId` from BUC-A |
+| Selection of a specific seat or berth | `allocations[]` — `AllocationSelection` with `allocationReference` |
+| Selection of ancillary services (meal, luggage, upgrade) | `ancillaries[]` — `AncillarySelection` with `ancillaryReference` |
+| Offer is temporarily held with a time limit | `LockOfferDelivery.lockedOfferId` + `expiryTime` |
+| Track the status of the lock | `LockedOffer.status` — `locked`, `expired`, `cancelled`, `confirmed` |
+| Non-fatal changes in availability or conditions | `LockOfferDelivery.warnings[]` |
+| After-sales restricted to the retailer only | `LockOfferRequest.aftersalesByRetailerOnly` |
+| Hypermedia navigation to the next step (confirm, release) | `LockOfferDelivery.links[]` |
+
+> **Note:** The full basket management logic (adding, removing, repricing, dependency evaluation) as described in BUC-B falls outside the scope of the current lock-offer API. That API covers only the moment at which an offer is held after selection by the customer.
+
+---
+
+## Lookup tables (supporting BUC-A and BUC-B)
+
+**Files:**
+- `deliverables/1 search offers/lookup.yaml`
+- `deliverables/2 lock offer/lookup.yaml`
+
+Both lookup YAMLs are identical in structure and provide read-only access to operator-defined code lists. They support both BUC-A and BUC-B.
+
+| Method | Path | Purpose in the BUCs |
+|--------|------|----------------------|
+| `GET` | `/personal-needs` | Valid values for `travellers[].personalNeeds[]` (BUC-A: PRM traveller, wheelchair user, etc.) |
+| `GET` | `/collections/personal-needs/items` | Same, OGC Records API style |
+| `GET` | `/ancillary-types` | Valid values for `Ancillary.type` (BUC-A/B: meal, luggage, upgrade, etc.) |
+| `GET` | `/collections/ancillary-types/items` | Same, OGC Records API style |
+| `GET` | `/entitlement-types` | Valid values for `EntitlementRight.entitlementType` (BUC-A: discount right, subscription, etc.) |
+| `GET` | `/collections/entitlement-types/items` | Same, OGC Records API style |
+
+Each endpoint is available in two patterns:
+- **REST style** — simple GET on the resource path
+- **OGC Records API style** — via `/collections/{name}/items`, for interoperability with geodata ecosystems
+
+---
+
+## Business Use Cases not yet covered
+
+The following BUCs are described in the wiki but do not yet have a corresponding API specification in `deliverables`:
+
+| BUC | Title | Expected API scope |
+|-----|-------|--------------------|
+| **BUC-C** | Order & Book | Reservation confirmation, collection of personal data, preliminary and final booking |
+| **BUC-D** | Pay | Payment execution (retailer-side, distributor-side, shared, third-party PSP) |
+| **BUC-E** | Ticketing & Fulfilment | Creation of travel rights, issuance of travel documents (PDF, QR, NFC, wallet) |
+| **BUC-F** | Pre-Trip Aftersales | Cancellation, exchange, cross-sell, operator-initiated changes before travel |
+| **BUC-J** | Post-Trip Aftersales | Vouchers, claims, no-show, urban transport lifecycle |
+
+---
+
+## Summary: coverage per phase
+
+```
+Phase BUC API status
+──────────────────────────────────────────────────────────────
+Inspire BUC-A ✓ search-offers.yaml (3 endpoints)
+Basket BUC-B ✓ lock-offer.yaml (6 endpoints)
+ ✓ lookup.yaml (6 endpoints, supporting)
+Reservation BUC-C ○ not yet available
+Payment BUC-D ○ not yet available
+Fulfilment BUC-E ○ not yet available
+Pre-trip BUC-F ○ not yet available
+Post-trip BUC-J ○ not yet available
+```
+
+All existing API specifications follow **OpenAPI 3.1.0**, version `0.1.0-draft`, and are each available in three interoperability variants: **OSDM 3.7.1**, **OMSA 0.1.0**, and **TOMP-API 2.0.0**.
diff --git a/wiki/use-cases/business-use-cases/ARCHIVE/buc-a-inspire-and-plan.md b/wiki/use-cases/business-use-cases/ARCHIVE/buc-a-inspire-and-plan.md
new file mode 100644
index 0000000..8610046
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/ARCHIVE/buc-a-inspire-and-plan.md
@@ -0,0 +1,117 @@
+
+## Use Case Overview
+
+- **Business Use Case ID & Name:** BUC-A — Plan your trip and choose your means of travel and/or your FARE PRODUCT
+- **Goal (Objective):** Enable the Transport Customer to select the most suitable mobility offer (transport mode, product, package, price, and guarantees) for his TRAVEL.
+- **Scope:** Offer discovery (journey planner proposals) / catalogue consultation (FARE PRODUCT catalogue) / PRICE calculation / CUSTOMER OFFER PACKAGE constitution
+---
+
+## Actors & Context
+
+- **Primary Actor:** **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** needs to purchase products suited to his travel needs. He can be the manager of a group, a PRM, the purchaser for a minor traveler or other with specific needs or none.
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** supports the customer and initiates catalogue consultation.
+ - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** provides the FARE PRODUCT catalogue, prices, availability, and guarantees.
+
+- **Assumptions (context at start):**
+ - The retailer is authorised to consult the distributor’s FARE PRODUCT catalogue.
+ - The catalogue and related pricing/guarantee information are available (online service or accessible dataset).
+ - The TRANSPORT CUSTOMER can provide the additional information required to compute/confirm the best offer.
+
+---
+
+## Preconditions & Postconditions
+
+- **Preconditions (must be true before start):**
+ - Access to the distributor’s FARE PRODUCT catalogues is available to the retailer and/or TRANSPORT CUSTOMER.
+ - The relevant catalogue (for the distributor/network/area) is identified.
+ - Basic travel intent is known (at minimum: the customer wants to travel; optionally: zone/route/date/passenger profile).
+
+- **Postconditions — Success guarantees:**
+ - One or more candidate offers are identified, including:
+ - selected **FARE PRODUCT(s)** and **SALES OFFER PACKAGE(s)** (if applicable)
+ - the associated **Price**
+ - applicable **TRAVEL GUARANTEEs and aftersales conditions**
+ - **availability** information (where applicable)
+ - The selected option (or shortlist) is available for the next step (e.g., purchase/booking).
+
+- **Postconditions — Minimal guarantees:**
+ - If no suitable solution is found, the customer receives a clear “no matching offer” outcome (with a reason where possible).
+ - The consultation outcome can be logged/audited (if required by the system).
+
+---
+
+## Scenarios
+
+### Main scenario
+- **Retrieving product list**
+1. The TRANSPORT CUSTOMER is planning his TRAVEL, which can be composed of one or more TRIPs, each consisting of one or more LEGs. He wants to go from TRIP ORIGIN PLACE to his TRIP DESTINATION PLACE using public transport and, optionally, return to the origin PLACE (can be a POINT, a SECTION or a ZONE).
+
+2. The TRANSPORT CUSTOMER may or may not connect to a CUSTOMER ACCOUNT on a digital platform. The TRANSPORT CUSTOMER may (if he wishes) prove eligibility for a particular USER PROFILE (under 25 years old, PRM indications, corporate participation). The TRANSPORT CUSTOMER can apply for a particular COMMERCIAL PROFILE. He can have his USER PROFILE(s) and/or COMMERCIAL PROFILE(s) already registered with his CUSTOMER ACCOUNT. He may wish to use specific features of his CUSTOMER ACCOUNT (TRAVEL DOCUMENTs, reduction cards, entitlements, vehicle plate, driving licence).
+
+3.
+ a. **If the TRAVEL is complex** (multi-LEGs, multi-TRIPs), and/or if the TRANSPORT CUSTOMER does not know how to make his travel, he can use a journey planner whether or not it is populated with the information from CUSTOMER ACCOUNT. It gives one or more results with detailed TRIP PATTERNs: schedule, transport mode, lines, stops, and connections.
+ b. The journey planner can be associated with a fare calculator: the TRANSPORT CUSTOMER can provide required details on travellers (date of birth, name, reduction cards, disabilities, PRM services needed, companion, bike spot) or remain, by default, with a basic COMMERCIAL PROFILE (anonymous adult - for only one trip - without reduction). The TRANSPORT CUSTOMER can indicate that he wants to include THIRD-PARTY PRODUCT in the solution (example: museum entry)
+ c. At least, the TRANSPORT CUSTOMER has a web link to the website of each distributor on each LEG/JOURNEY to browse their catalogue (equivalent to the next step).
+ d. If available, a fare calculator can provide FARE PRODUCTs that are suitable for the TRIP(s), from one basic solution on each origin-destination LEG (default values used like : "for today", "anonymous", "single-trip ticket on the network") to many more elaborate solutions (for the travel specified day, combined ticket, multimodal offers, with reduction and guarantees, including passes already purchased). The availability of some assets or mandatory reservations can also be displayed.
+ e. The retailer can manage the displayed results with additional indicators, ranking, filtering (operator, line, categories, product name), comparing: price, duration, number of interchanges, mode mix, GHG/CO₂ impact, comfort, accessibility or operator.
+
+5.
+ a. **If the TRAVEL is easy to plan**, the TRANSPORT CUSTOMER can browse a digital platform, go to a travel agency, a distributor desk, or a ticket vending machine in a station to choose mobility tickets. He wants to choose by himself between tickets, choosing himself the transport modes and the prices he is willing to pay. He can also include THIRD-PARTY PRODUCTs in his search.
+ b. Either the TRANSPORT CUSTOMER or the retailer on behalf of the TRANSPORT CUSTOMER starts the catalogue consultation. The retailer browses the catalogue to retrieve an initial set of candidate FARE PRODUCT(s) and SALES OFFER PACKAGE(s). This catalogue can be statically built with an aggregation and rework of one or many distributor catalogues, themselves built based on fare owner catalogues. This catalogue can be partially or totally dynamically built using real-time requests to distributors.
+ c. The TRANSPORT CUSTOMER reviews the initial results and may filter or order the results. If he cannot finalise his selection, he can refine the catalogue to narrow the displayed FARE PRODUCT(s) and SALES OFFER PACKAGE(s) according to the consultation context and the data he provides (new or modified data and/or data coming from journey planner requirements).
+
+- **Asking for product-based offers**
+5. One or more times, the TRANSPORT CUSTOMER selects one candidate SALES OFFER PACKAGE of one or more distributors (multiple transport modes, multiple operators). He requests details so that he can consult the detailed contents, conditions, guarantees, and optional parts of the selected SALES OFFER PACKAGE. This consultation can be done for more than one SALES OFFER PACKAGE at the same time, as long as they can be displayed on the same screen at the same time.
+
+6. If the selected SALES OFFER PACKAGE is not yet fully defined, the TRANSPORT CUSTOMER enters additional customer parameters by providing the required information, such as the traveller profile, eligibility, accessibility needs, class, date, zone, quantity, or extras. Once the required information is filled in, the retailer checks the entries and provides a price with the applicable commercial and travel conditions (aftersales including exchange or refund, specific restrictions, guarantees, passenger rights) for the selected SALES OFFER PACKAGE. It may be composed of several products.
+
+7.
+ a. If this PRICE is an indicative price depending on mandatory reservation (for example, a seat), or if the TRANSPORT CUSTOMER wishes to check availability and the system allows it, the TRANSPORT CUSTOMER checks availability and, on some distributor's systems, may start the reservation process: the retailer checks availability and may start a temporary hold for the selected SALES OFFER PACKAGE.
+ b. If the final price is a yield price, at this moment, the retailer requests a final price (valid for a limited period)
+ c. If availability is also confirmed, the retailer retrieves the final price and returns it with the final conditions for the selected SALES OFFER PACKAGE.
+
+- **Selection of offers**
+
+8. Before making a final choice, the TRANSPORT CUSTOMER may change options to modify class, extras, or other defining elements, and if needed the retailer refreshes the offer and recalculates the corresponding conditions and price.
+9. One by one, the TRANSPORT CUSTOMER can consult, select, or discard FARE PRODUCT(s) to build a final complete solution. At each step, for each selected product requiring a reservation, the retailer can start the reservation process with the distributor in order to ensure coherent multiple reservations (transaction management with multiple distributors).
+10. The TRANSPORT CUSTOMER chooses the preferred solution, and the retailer can keep the selected option in a "wish list" so that the CUSTOMER OFFER PACKAGE is ready for the next reservation and purchase step. The retailer can inform the TRANSPORT CUSTOMER that all or part of the offer has expired and propose a new price and availabiltiy calculation.
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+- **Specific trip**
+1. The TRANSPORT CUSTOMER chooses his origin station and his destination station on the ticket vending machine with the option "around the stations : x kilometers".
+2. The TRANSPORT CUSTOMER enters required data (customer account, reduction card).
+3. The TRANSPORT CUSTOMER chooses between a few SALES OFFER PACKAGEs displayed with their PRICE, on different JOURNEYs with different stations (radius-based).
+
+- **Single anonymous travel**
+1. The TRANSPORT CUSTOMER starts his mobile application; the home page displays a shortcut for single-trip purchase in one action.
+2. He chooses an anonymous single-trip ticket by clicking on this shortcut.
+
+- **PRM journey**
+1. The TRANSPORT CUSTOMER has specific needs that must be guaranted to be met during his TRAVEL (on the LEG and between LEGs). The journey planner gives solutions that meet the TRAVEL SPECIFICATION with mobility services even on the first LEG (from house/postal address to first STOP POINT), during interchange and on the last LEG (from last STOP POINT to final destination).
+2. If the journey planner is associated with a fare calculator, the TRANSPORT CUSTOMER receives a fare offer compliant with USER PROFILE and with TRAVEL SPECIFICATION, including continuous additional services and travel guarantees from house to destination.
+3. If the journey planner only provides basic mobility solutions, the TRANSPORT CUSTOMER must browse the catalogue to select one by one the tickets, services and guaranteees he needs. When his selection fulfills his complete TRAVEL, he has a satisfactory solution.
+
+- **Return trip**
+1. The TRANSPORT CUSTOMER plans a TRAVEL composed of an outward journey and the corresponding return journey. The journey planner can manage the full TRAVEL, requesting only minimal criteria for the return trip (return time and reversing origin-destination).
+2. If the journey planner is associated with a fare calculator, the TRANSPORT CUSTOMER can receive a fare offer that takes into account the whole TRAVEL (for example, a daily pass less expensive than two separate tickets).
+3. If the journey planner only proposes basic mobility solutions, the TRANSPORT CUSTOMER must browse the catalogue to select one by one the tickets, looking for a solution that includes the two TRIPs.
+
+- **Bank card as TRAVEL DOCUMENT**
+1. The TRANSPORT CUSTOMER plans a TRAVEL and consults the catalogue: he checks that his bank card is accepted as a TRAVEL DOCUMENT on the selected JOURNEYs. The validity conditions, guarantees and PRICEs (including fees and VAT rates) are displayed. The TRANSPORT CUSTOMER is fully informed.
+2. The TRANSPORT CUSTOMER does not need to select a product himself : the FARE PRODUCT selection is done by the system when the traveller taps on the validator equipment (date and time, place, line, stop, operator, bank contract and answer, customer account).
+
+
+### Diagram
+UML activity diagram
+
+
+
+
+### Links with use cases
+
+Link to (https://github.com/TransmodelEcosystem/EUDIT/discussions/36#discussioncomment-16183779)
+To be completed
+
diff --git a/wiki/use-cases/business-use-cases/ARCHIVE/buc-b-shop-and-price.md b/wiki/use-cases/business-use-cases/ARCHIVE/buc-b-shop-and-price.md
new file mode 100644
index 0000000..c1e8665
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/ARCHIVE/buc-b-shop-and-price.md
@@ -0,0 +1,212 @@
+## Use Case Overview
+
+- **Business Use Case ID & Name:** BUC-B — Shop your FARE PRODUCT(s) and manage your TRAVEL BASKET with PRICE calculation at any time
+- **Goal (Objective):** Enable the TRANSPORT CUSTOMER to build, review, modify and validate a logical TRAVEL BASKET containing one or more CUSTOMER OFFER PACKAGE(s), with updated PRICE information available at any time before the next use case dealing with reservation initiation and payment.
+- **Scope:** TRAVEL BASKET creation and management / CUSTOMER OFFER PACKAGE completion / PRICE calculation and recalculation / dependency management between basket elements / basket consistency across possible retailer-side and/or distributor-side basket implementations / preparation of a ready basket for the next use case
+---
+
+## Actors & Context
+
+- **Primary Actor:** **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wants to prepare a consistent basket suited to his TRAVEL, for himself and/or for other travellers. He can be the manager of a group, a PRM, the purchaser for a minor traveler or other with specific needs or none.
+
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** manages the shopping flow and customer interaction, presents the TRAVEL BASKET to the TRANSPORT CUSTOMER and may manage a logical and/or technical basket (basket consistency, requests sent to one or more distributors).
+ - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** provides offer completion rules, PRICE information, commercial conditions, after-sales conditions, guarantees, and dependency rules affecting basket elements. May manage a technical basket for one or more basket elements.
+
+- **Assumptions (context at start):**
+ - The TRANSPORT CUSTOMER has already selected one or more candidate CUSTOMER OFFER PACKAGE(s) in the previous use case.
+ - The TRANSPORT CUSTOMER can provide the additional information required to complete and price the selected offer(s).
+ - The TRAVEL BASKET is a logical business object from the customer perspective; its technical implementation may reside with the retailer, with one or more distributors, or be distributed across both.
+ - Depending on the implementation, "basket" operations may be executed:
+ - only in a retailer "basket";
+ - only in a distributor "basket"; or
+ - in a retailer "basket" and in one or more distributor "baskets" that must remain aligned.
+ - The use case is implementation-neutral and therefore specifies the required business result, not the internal technical ownership of the "basket".
+
+---
+
+## Preconditions & Postconditions
+
+- **Preconditions (must be true before start):**
+ - Access to the distributor’s selling system is available/authorized to the retailer and/or TRANSPORT CUSTOMER.
+ - The relevant distributor(s) of the selected offer elements are identified.
+ - The distributor’s selling system and related pricing, guarantee, after-sales and dependency information are available (online service or accessible dataset).
+ - At least one FARE PRODUCT is selected by the CUSTOMER (at minimum: the customer wants to purchase one FARE PRODUCT; optionally: many CUSTOMER OFFER PACKAGEs).
+ - The TRANSPORT CUSTOMER context needed to continue the purchase is available or can be entered, including traveller data, rights, options, delivery data, invoicing data or VAT context where required.
+
+- **Postconditions — Success guarantees:**
+ - A TRAVEL BASKET exists and contains one or more completed and consistent TRAVEL BASKET ELEMENTs according to the TRANSPORT CUSTOMER’s actions.
+ - Each TRAVEL BASKET ELEMENT contains one CUSTOMER OFFER PACKAGE and the information needed for continuation :
+ - selected **CUSTOMER OFFER PACKAGE(s)**, including quantity
+ - the associated current **PRICE**
+ - applicable **reductions, TRAVEL GUARANTEEs and aftersales conditions**
+ - any dependency information linking it to other TRAVEL BASKET ELEMENTs
+ - optional protection or guarantee services selected during shopping, where applicable
+ - group-specific quotation results, where applicable
+ - approval-hold status, where applicable
+ - identified reservation-related constraints or intermediate reservation results, where applicable
+ - The whole TRAVEL BASKET has a calculated total **PRICE** (can be zero or less).
+ - The basket state presented to the customer is consistent, regardless of whether the underlying implementation relies on a retailer basket, a distributor basket, or coordinated baskets across both.
+ - This use case ends when the TRAVEL BASKET is ready for the next step; reservation initiation and payment are out of scope and belong to the following use case.
+
+- **Postconditions — Minimal guarantees:**
+ - If the TRANSPORT CUSTOMER abandons the process or no suitable solution is found, the TRAVEL BASKET remains empty. The purchase process is suspended or ended.
+ - After any TRAVEL BASKET operation, the retailer and/or distributor shall ensure that no TRAVEL BASKET ELEMENT remains with an outdated PRICE, an invalid status, or an unresolved dependency with another TRAVEL BASKET ELEMENT. The TRAVEL BASKET shall remain internally consistent after any operation.
+ - If synchronisation between retailer-side and distributor-side basket states is required, the system detects any divergence and prevents continuation until the customer basket state is made consistent again.
+ - The TRANSPORT CUSTOMER actions can be logged/audited (if required by the system).
+
+---
+
+## Scenarios
+
+### Main scenario
+Note : In Transmodel improved with COROM project proposals, a CUSTOMER OFFER PACKAGE is created when a SALES OFFER PACKAGE has been selected and parameterised for a specific customer context; it is then inserted into the TRAVEL BASKET as part of a TRAVEL BASKET ELEMENT.
+
+#### TRAVEL BASKET management
+1. The TRANSPORT CUSTOMER shall start this use case after having selected one or more candidate FARE PRODUCT(s) and their corresponding SALES OFFER PACKAGE(s); fulfilling at least one CUSTOMER OFFER PACKAGE in the previous use case.
+2. The retailer shall open, identify or initialise to the TRANSPORT CUSTOMER a logical TRAVEL BASKET, regardless of whether the underlying technical basket is managed by the retailer, by one or more distributor(s), or by both. The logical TRAVEL BASKET may be created explicitly at the TRANSPORT CUSTOMER’s request or implicitly when the first CUSTOMER OFFER PACKAGE is added associated with the current shopping session. This TRAVEL BASKET can be transparent for the TRANSPORT CUSTOMER and not requested for a basic purchase.
+- **Display TRAVEL BASKET**
+3. At each step, the retailer shall present to the TRANSPORT CUSTOMER the current shopping context and so, the TRANSPORT CUSTOMER can see a representation/summary of what he is purchasing (current state of TRAVEL BASKET if already exists) including the details of each operation:
+ - the list of TRAVEL BASKET ELEMENTs;
+ - the CUSTOMER OFFER PACKAGE contained in each TRAVEL BASKET ELEMENT;
+ - the detailed PRICE of each TRAVEL BASKET ELEMENT;
+ - the total PRICE of the TRAVEL BASKET;
+ - the quotation validity period applicable to each concerned CUSTOMER OFFER PACKAGE; and
+ - the main conditions attached to each TRAVEL BASKET ELEMENT and to the basket as a whole.
+- **Creation of an empty TRAVEL BASKET (optional)**
+4. If the TRANSPORT CUSTOMER requests the creation of an empty TRAVEL BASKET, the retailer shall create or request creation of the corresponding basket state in the relevant basket implementation(s), retrieve the resulting basket state where applicable, and present the empty logical TRAVEL BASKET to the TRANSPORT CUSTOMER.
+- **Addition of one or many TRAVEL BASKET ELEMENT(s)**
+5. The TRANSPORT CUSTOMER may add a CUSTOMER OFFER PACKAGE (selected and defined in previous use case) to his TRAVEL BASKET as a TRAVEL BASKET ELEMENT either :
+ - one selected CUSTOMER OFFER PACKAGE in a single action; or
+ - several selected CUSTOMER OFFER PACKAGE(s) in one action, including for a multimodal, multi-leg or multi-operator TRAVEL with protection or guarantee option related to connections.
+The addition is the only operation that the TRANSPORT CUSTOMER can start the process with. This operation can be the only one available for the TRANSPORT CUSTOMER on the selling system.
+If the TRANSPORT CUSTOMER is shopping for a group larger than the standard instant-shopping scope, the retailer may interrupt this flow : the retailer sends a specific request to the relevant distributor(s), including the group-related constraints, and resumes the present use case when the quotation is returned.
+6. For each addition, the retailer shall create one TRAVEL BASKET ELEMENT corresponding to the shopping intention of the TRANSPORT CUSTOMER for the concerned part of the TRAVEL. Each TRAVEL BASKET ELEMENT shall contain one CUSTOMER OFFER PACKAGE representing the customer-specific shopping component derived from the selected SALES OFFER PACKAGE and its customer parameterisation. On each addtion, the retailer shall :
+ - identify the relevant distributor for the selected SALES OFFER PACKAGE;
+ - confirm (and ends the collect if required) the data required to build thne corresponding CUSTOMER OFFER PACKAGE;
+ - send the relevant request to the distributor (including retailer's TRAVEL BASKET if required), where distributor-side processing is required;
+ - create or update the corresponding TRAVEL BASKET ELEMENT in the relevant basket implementation(s);
+ - (if required) evaluate dependencies between TRAVEL BASKET ELEMENT to assure the consistency of the TRAVEL BASKET and inform the TRANSPORT CUSTOMER of the consequences; and
+ - retrieve the resulting PRICE, validity period and applicable conditions for presentation to the TRANSPORT CUSTOMER.
+Several CUSTOMER OFFER PACKAGE(s) added in one action may correspond to one multimodal, multi-leg or multi-operator TRAVEL and may be processed either as one combined basket update or recursively element by element.
+Pre-reservation step can be started at this moment. The retailer may temporarily interrupt the present use case, start the relevant reservation initiation process with the concerned distributor(s), and then resume the shopping process with the updated TRAVEL BASKET state. This reservation initiation is managed in next use case.
+- **Modification of one existing TRAVEL BASKET ELEMENT**
+7. The TRANSPORT CUSTOMER may request modification of one existing TRAVEL BASKET ELEMENT. It can be on, when applicable : quantity, date and time, validity options, eligibility data, traveller assignment, customer account context (including fare contracts and travel documents), reduction rights, class or comfort option (seat preference), ancillary selections, delivery preferences, invoicing order, VAT context. It can be on any other mandatory parameter required by the distributor.
+8. On a modification request, the retailer shall :
+ - identify the TRAVEL BASKET ELEMENT concerned and the permitted characteristics that may be changed;
+ - request from the TRANSPORT CUSTOMER any additional data required to perform the modification;
+ - send the relevant update request to the concerned distributor, where applicable;
+ - retrieve the updated CUSTOMER OFFER PACKAGE, PRICE, validity period and other applicable conditions; and
+ - (if required) evaluate dependencies between TRAVEL BASKET ELEMENT to assure the consistency of the TRAVEL BASKET and inform the TRANSPORT CUSTOMER of the consequences; and
+ - retrieve the resulting PRICE, validity period and applicable conditions for presentation to the TRANSPORT CUSTOMER.
+- **Removal of one or many existing TRAVEL BASKET ELEMENT(s)**
+9. The TRANSPORT CUSTOMER may request removal of one existing TRAVEL BASKET ELEMENT. He may do it by selecting it in the TRAVEL BASKET display or down the quantity to zero or with any other displayed option.
+10. For each removal, the retailer shall :
+ - identify the TRAVEL BASKET ELEMENT concerned;
+ - send the relevant deletion request to the concerned distributor, where applicable;
+ - update the relevant TRAVEL BASKET implementation(s);
+ - determine whether the removal affects any other TRAVEL BASKET ELEMENT, any combined pricing rule, any pass condition, any ancillary condition, or any other basket dependency; and
+ - retrieve the resulting TRAVEL BASKET state for presentation to the TRANSPORT CUSTOMER.
+Severeal removals in one step for the TRANSPORT CUSTOMER can be managed as only one operation or recursively, one by one in order to manage element's dependencies.
+- **Clearing the whole TRAVEL BASKET**
+11. The TRANSPORT CUSTOMER may request clearing of the whole TRAVEL BAKSET. He may do it by selecting the TRAVEL BASKET or, on some systems, downing the last element quantity to zero or with any other displayed option. A additional confirmation can be required.
+12. To execute this demand, the retailer shall :
+ - request deletion or resetting of all TRAVEL BASKET content in the relevant basket implementation(s);
+ - retrieve confirmation of the resulting empty basket state, where applicable; and
+ - display the resulting empty logical TRAVEL BASKET to the TRANSPORT CUSTOMER.
+On some systems, this operation is managed as a TRAVEL BASKET removeal.
+
+#### Final price calculation
+- **Change management**
+13. If required, after any operation listed above and before displaying the operation result, the retailer and/or the concerned distributor(s) in interaction with the TRANSPORT CUSTOMER shall evaluate the impact of the operation on:
+ - the affected TRAVEL BASKET ELEMENT;
+ - any other TRAVEL BASKET ELEMENT;
+ - the PRICE of one or more basket elements;
+ - the total PRICE of the TRAVEL BASKET;
+ - quotation validity;
+ - fare combinability;
+ - through-fare eligibility;
+ - ancillary applicability;
+ - pass validity conditions;
+ - bundle conditions; and
+ - any other dependency between TRAVEL BASKET ELEMENTs.
+During each evaluation, the retailer shall send to the relevant request to the concerned distributor and each of them shall return the updated shopping result for the relevant CUSTOMER OFFER PACKAGE(s), including the applicable PRICE, validity period, conditions, restrictions and any detected consequence affecting other TRAVEL BASKET ELEMENTs.
+14. The retailer shall consolidate all relevant distributor responses, together with any retailer-side basket processing result, into one updated logical TRAVEL BASKET state. If one or more quotations cannot continue without recalculation (expired), the retailer shall request a mandatory refresh of the CUSTOMER OFFER PACKAGE(s) before the logical TRAVEL BASKET can continue unchanged.
+If the requested operation has consequences on one or more other TRAVEL BASKET ELEMENTs, the retailer shall present those consequences to the TRANSPORT CUSTOMER before finalising the TRAVEL BASKET state :
+ - repricing of one or more TRAVEL BASKET ELEMENTs;
+ - refresh or expiry of a quotation;
+ - loss, addition or modification of a reduction, negotiated fare, entitlement or pass condition;
+ - invalidation or activation of a combined offer (fare combination evaluation);
+ - change in ancillary eligibility or ancillary PRICE;
+ - invalidation of one or more CUSTOMER OFFER PACKAGE(s);
+ - deletion or replacement of dependent TRAVEL BASKET ELEMENTs; or
+ - modification of the overall basket consistency.
+15. The TRANSPORT CUSTOMER shall either accept the proposed consequences and confirm the TRAVEL BASKET update, or reject the proposed consequences and cancel the operation. If the TRANSPORT CUSTOMER rejects the proposed consequences, the retailer shall preserve the previously consistent logical TRAVEL BASKET state. If the TRANSPORT CUSTOMER accepts the proposed consequences, the retailer shall confirm and apply the resulting basket state across the relevant basket implementation(s).
+16. In any case,the retailer shall inform the TRANSPORT CUSTOMER with the result and present the updated logical TRAVEL BASKET, including:
+ - all current TRAVEL BASKET ELEMENTs;
+ - the CUSTOMER OFFER PACKAGE contained in each element;
+ - the PRICE of each element, reduction amount, VAT;
+ - the total PRICE of the TRAVEL BASKET, reduction amount, VATs; and
+ - the main applicable conditions and validity constraints.
+- **Pricing**
+17. The TRANSPORT CUSTOMER may also provide a promotion code, discount code, entitlement reference, reduction right, corporate identifier (and agreements) or pass-related information applicable to one or more basket elements. The promotion or discount code may be accepted, rejected, or only partially applicable depending on distributor and retailer commercial rules. If the TRANSPORT CUSTOMER, or a corporate booker acting on his behalf, requires an internal approval before continuing, he or the retailer may request that the quotation or the TRAVEL BASKET remains valid for a defined period.
+18. The retailer shall send the relevant pricing or validation request to the concerned distributor(s), and/or apply the relevant retailer-side rules, in order to update the affected CUSTOMER OFFER PACKAGE(s), TRAVEL BASKET ELEMENT(s), PRICE(s) and basket conditions. The distributor(s) shall return the updated pricing and conditions. If a holding mechanism is required, the shopping process is temporarily suspended until approval is obtained, rejected or expired.
+19. The retailer shall present the resulting updated logical TRAVEL BASKET to the TRANSPORT CUSTOMER and ensure that the logical TRAVEL BASKET remains consistent and up to date, so that no TRAVEL BASKET ELEMENT remains with:
+ - an outdated PRICE;
+ - an expired quotation without being identified as such;
+ - an invalid CUSTOMER OFFER PACKAGE;
+ - an unresolved dependency; or
+ - incomplete data required for the next use case.
+20. The TRANSPORT CUSTOMER may repeat any basket operation until he decides to stop modifying the TRAVEL BASKET.
+
+#### TRAVEL BASKET finalization
+21. The retailer calculates the final price of the whole TRAVEL BASKET and shall present the final state of the TRAVEL BASKET to the TRANSPORT CUSTOMER, including the current contents, the applicable conditions, the current total PRICE, and any remaining validity constraints relevant for continuation.
+23. When the TRANSPORT CUSTOMER decides to stop modifying the basket, the TRANSPORT CUSTOMER shall validate the selected TRAVEL BASKET as the intended purchase solution and request continuation to the next step. The use case shall end when the TRAVEL BASKET is complete, consistent and ready for the next use case dealing with reservation initiation (if not started yet) and payment.
+24. Upon this validation, the retailer and/or the relevant distributor(s) shall ensure that the TRAVEL BASKET enters a locked state (frozen) in which no operation may alter the TRAVEL BASKET content, the CUSTOMER OFFER PACKAGE(s), the applicable PRICE(s), or the associated conditions (fozen maximal duration) and dependencies.
+25. The locked TRAVEL BASKET shall constitute the stable input for the next use case dealing with reservation initiation and payment.
+
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+- **Direct purchase**
+1. The TRANSPORT CUSTOMER has selected a basic FARE PRODUCT which is immedialtly a CUSTOMER OFFER PACKAGE. He selects the "Purchase in one-clic" option.
+2. The TRANSPORT CUSTOEMR does not see the TRAVEL BASKET : he directly arrives on payment interface. This scenario is a shortcut to main scenario.
+
+- **Offer hold for approval**
+1. The TRANSPORT CUSTOMER, or a corporate booker acting on his behalf, is willing to keep the TRAVEL BASKET stable for a period (longer than the automatic system does) before validating it, because an internal approval is required.
+2. The retailer sends a request to the relevant distributor(s) to maintain the quotation or the basket content valid for a defined period, according to the applicable conditions. The purchase process is put on hold during this approval period.
+3. The distributor(s) return the validity period and the applicable holding conditions. The retailer informs the TRANSPORT CUSTOMER of the approval deadline and of any constraint linked to this temporary hold.
+4. If the approval is obtained in time, the purchase process continues with the validated TRAVEL BASKET. If the approval is not obtained in time, the TRAVEL BASKET must be refreshed, repriced, or abandoned.
+
+- **Group quotation with dedicated group process**
+1. The TRANSPORT CUSTOMER is welling to purchase for a group of travellers, larger than what it is proposed in the catalogue. He submits a specific group offer request, for example, by email for a group quotation (specific channel).
+2. The retailer sends the request to relevant distributor(s), including group-related contraints. The purchase process is put on hold while awaiting the quotation (step 6).
+3. An agent or several agents prepare the quotation and reply, for example, by email to the request. The purchase process then continues.
+
+- **Effective reservation during shopping**
+1. The TRANSPORT CUSTOMER adds in his TRAVEL BASKET a CUSTOMER OFFER PACKAGE with a reservation. For this reservation a reservation-related process must be started in order to continue shopping on a consistent basis.
+2. The retailer temporary leaves the the current use case and start reservation process as described in next use case with the relevant distribtor(s) using the current state of the affected CUSTOMER OFFER PACKAGE(s).
+3. When the reservation is executed; only to secure the TRAVEL BASKET content for continuation of the shopping process, the retailer returns to the shopping process and updates the logical TRAVEL BASKET accordingly.
+7. The retailer presents the updated TRAVEL BASKET state to the TRANSPORT CUSTOMER, including the consequences of the reservation-related process on the concerned TRAVEL BASKET ELEMENT(s) and on the basket as a whole.
+8. The TRANSPORT CUSTOMER may then continue the shopping process, following presetn use case.
+
+- **Mandatory Co-sale**
+1. The TRANSPORT CUSTOMER adds, modifies or removes one TRAVEL BASKET ELEMENT, but this operation affects another TRAVEL BASKET ELEMENT because of a dependency rule, a bundle rule, or a mandatory co-sale condition.
+2. The retailer sends the relevant update request to the concerned distributor(s) and asks for the consequences of this operation on the other TRAVEL BASKET ELEMENT(s). The purchase process is temporarily blocked while awaiting the dependency evaluation.
+3. The distributor(s) return the consequences of the operation, for example repricing, invalidation, deletion, replacement or the need to add another element.The retailer informs the TRANSPORT CUSTOMER of these consequences and asks for confirmation.
+5. If the TRANSPORT CUSTOMER accepts the consequences, the basket is updated and the purchase process continues. If he rejects them, the previous basket state is preserved.
+
+
+### Diagram
+UML activity diagram
+
+
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx
+wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+To be completed
+
+
diff --git a/wiki/use-cases/business-use-cases/ARCHIVE/buc-d-pay.md b/wiki/use-cases/business-use-cases/ARCHIVE/buc-d-pay.md
new file mode 100644
index 0000000..95f81a5
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/ARCHIVE/buc-d-pay.md
@@ -0,0 +1,245 @@
+## Use Case Overview
+
+- **Business Use Case ID & Name:** BUC-D — Pay your CUSTOMER PURCHASE PACKAGE(s)
+- **Goal (Objective):** Enable the TRANSPORT CUSTOMER to pay one or more CUSTOMER PURCHASE PACKAGE(s), possibly provided by several DISTRIBUTOR(s), through a coherent customer-facing payment process, while allowing different payment architectures: retailer-side payment, distributor-side payment, shared payment, or payment through a PAYMENT PROVIDER.
+
+- **Scope:** CUSTOMER OFFER PACKAGE completion with CHARGING MOMENT and PAYMENT METHOD confirmation/ PRICE update is necessary / dependency management between TRAVEL BASKET ELEMENTs / PAYMENT METHOD update / coordination between Retailer, Distributor and Payment Provider / payment result consolidation / payment proof and billing information / ready for next use case (fulfilment).
+
+---
+
+## Terminology note — TRAVEL BASKET, TRAVEL BASKET ELEMENT, SALES TRANSACTION and order
+
+At the beginning of this use case, the TRANSPORT CUSTOMER may still manage a **locked TRAVEL BASKET** containing one or more **TRAVEL BASKET ELEMENT(s)**, still part of the shopping/purchase preparation state. Each TRAVEL BASKET ELEMENT contains one CUSTOMER PURCHASE PACKAGE, as defined in BUC-B.
+
+The term **order** is not defined as a reference business concept in Transmodel. It may be implemented from the moment the purchase has been confirmed sufficiently (and "order" may be already pre-created at the beginning of the use-case). It may be explicitly used by a local implementation or by an external retailing system.
+Instead, the appropriate Transmodel concept to use when the purchase is confirmed is **SALES TRANSACTION**. A SALES TRANSACTION should be used from the moment the customer has validated the basket and the sale is sufficiently confirmed to be recorded by the Retailer :
+ - the TRAVEL BASKET becomes the purchase input;
+ - each TRAVEL BASKET ELEMENT contributes to the confirmed purchase;
+ - each CUSTOMER PURCHASE PACKAGE remains traceable;
+ - the confirmed sale is represented by a SALES TRANSACTION;
+ - payment may be associated with the SALES TRANSACTION and/or the CUSTOMER PURCHASE PACKAGE(s).
+
+In this use case, **TRAVEL BASKET / TRAVEL BASKET ELEMENT** is used when describing the payment process until payment validation, and **SALES TRANSACTION** is used after the payment validation. However, this may vary depending on the system. The confirmed sale should be represented by SALES TRANSACTION, created or confirmed only when the purchase has reached a sufficiently binding state, typically after successful payment validation.
+
+## Actors & Context
+
+- **Primary Actors:**
+ - **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wants to pay with his chosen PAYMENT METHOD(s) a consistent basket suited to his TRAVEL, for himself and/or for other travellers and receive all proofs of payment.
+ - **Payment Service Provider (PSP) (PAYMENT PROVIDER ROLE (API not managed by EUDIT project)):** Executes or supports the payment transaction. The PSP :
+ - authorises, captures, rejects, secures, schedules or confirms payment;
+ - may manage card payment, account debit, voucher, wallet, loyalty redemption, travel account debit or other payment instruments;
+ - returns the payment transaction result to the responsible Retailer and/or Distributor.
+
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** manages the shopping flow and customer interaction, presents the payable TRAVEL BASKET to the TRANSPORT CUSTOMER and may manage a logical and/or technical basket (basket consistency, requests sent to one or more distributors). He can manage the interface with the bank (Payment Provider), coordinates the payment and keeps coherent the purchase process during payment.
+ - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** Provides or confirms the business data needed for payment of the CUSTOMER PURCHASE PACKAGE(s). The Distributor confirms payable amount (based on PRICE(s) calculation) and CHARGING MOMENT(s) with time limit(s), confirms accepted PAYMENT METHOD(s) from a business point of view and confirms reservation, holding, ancillary or guarantee status (next use case). He - indicates whether payment must be completed before final confirmation and applies business consequences of payment success, failure or expiry.
+
+
+- **Assumptions (context at start):**
+ - The TRANSPORT CUSTOMER can provide the additional information required to pay for the selected offer(s).
+ - The PAYMENT PROVIDER ROLE may be performed, for each CUSTOMER PURCHASE PACKAGE, by:
+ - the Retailer or the Distributor;
+ - a third-party PSP (can be a bank, a travel account provider, a voucher provider, a loyalty provider,...)
+ - or another delegated payment system.
+ - The interfaces with the banks and the Payment Service Provider equipment(s) are available.
+ - Depending on the implementation, each payment operation may be executed:
+ - only in a retailer side;
+ - only in a distributor side; or
+ - in a third-party system.
+ - The use case is PSP implementation-neutral and therefore specifies the required business entries and results, not the internal technical bank exchange.
+
+---
+
+## Preconditions & Postconditions
+
+- **Preconditions (must be true before start):**
+ - The TRANSPORT CUSTOMER has already completed one or more CUSTOMER PURCHASE PACKAGE(s) in the previous use case. They are ready for payment.
+ - The relevant payment processing system(s) of each TRAVEL BASKET ELEMENT are identified and can be accessed.
+ - The Distributor’s selling system and related pricing rules (with time limits) with dependency information are available (online service or accessible dataset).
+ - The TRANSPORT CUSTOMER context needed to continue the purchase is available or can be entered, including traveller data, rights, options, delivery data, invoicing data or VAT context where required.
+ - Refunds, compensation, voucher issuance after refund and other after-sales processes are out of scope of present BUC and are handled in use cases **F** and **J** dedicated to after-sales. But they refers to the same PSP interactions and APIs.
+
+- **Postconditions — Success guarantees:**
+ - Each CUSTOMER PURCHASE PACKAGE has a payment status, consolidated and given to TRANSPORT CUSTOMER by the Retailer.
+ - The basket state presented to the customer is consistent, regardless of whether the underlying implementation relies on a retailer basket, a distributor basket, or coordinated baskets across both.
+ - This use case ends when the TRAVEL BASKET is ready for the next step; payment status is known.
+ - Reservation, option, seat, ancillary, service or guarantee depending on payment will be finalized according to Distributor rules in Business Use Case E.
+ - The TRANSPORT CUSTOMER receives the appropriate proof(s): receipt, invoice, payment terms, payment schedule, confirmation. Fulfilment is managed in Business Use Case E (access to TRAVEL DOCUMENT(s)).
+
+- **Postconditions — Minimal guarantees:**
+ - If the TRANSPORT CUSTOMER abandons the process or no suitable payment solution is found, the TRAVEL BASKET may remain as it is for a delay. The purchase process is suspended or ended.
+ - The Distributor indicates which payment part remains held, is released, is cancelled, is partially cancelled or requires revalidation.
+ - The Retailer consolidates the TRAVEL BASKET state and prevents fulfilment if a required payment condition is not met.
+ - If funds or accounting information must be distributed, cleared or reconciled between the Retailer and one or more Distributor(s) are described in Business Use Case K.
+ - The TRANSPORT CUSTOMER actions can be logged/audited (if required by the system).
+ - If many CUSTOMER PURCHASE PACKAGE(s) are involved, allocation remains traceable per Distributor, SALES TRANSACTION, payment instrument and settlement rule.
+
+---
+
+
+## Scenarios
+
+### Main scenario
+1. The TRANSPORT CUSTOMER shall start this use case after the preceding shopping and reservation phases, when one or more CUSTOMER PURCHASE PACKAGE(s) have been selected, parameterised, inserted into a TRAVEL BASKET and locked or stabilized for payment. At this moment, it may remain elements that modify the final payment : shipping costs, payment method fees, CHARGING MOMENT, Retailer platform feees or promotions and operation fees (by example : after-sales fees).
+
+- **Payment options choice**
+2. The Retailer presents to the TRANSPORT CUSTOMER a summarized payable view :
+ - CUSTOMER PURCHASE PACKAGE(s) to be paid;
+ - PRICE of each and total amount for the current options;
+ - selected or available PAYMENT METHOD(s);
+ - CHARGING MOMENT(s);
+ - payment deadline(s) or milestones for group purchase;
+ - fees, taxes and currency(s) information including available shipping possibilities and operation fees;
+ - any deferred amount or future instalment amount, where applicable;
+ - main conditions attached to payment, linked to deferred payment, B2B invoicing or corporate approval;
+ - main consequences of payment failure or expiry.
+
+3. The TRANSPORT CUSTOMER selects and/or confirms the PAYMENT METHOD(s) and options.
+4. If required, the Retailer and/or Distributor shall refresh the final payable PRICE before payment confirmation and present the updated state to TRANSPORT CUSTOMER, especially if:
+ - the locked validity period is close to expiry or one or more component deadlines are close to expiry;
+ - one or many options changes the final amount to pay. (PAYMENT METHOD, taxes, invoicing, delivery, corporate rules or currency conversion affect the payable amount).
+
+- **Distributor and PSP contraints synchonization**
+5. For each concerned Distributor, the Retailer verifies and confirms:
+ - CUSTOMER PURCHASE PACKAGE identifier;
+ - final PRICE and currency;
+ - taxes and invoicing constraints;
+ - CHARGING MOMENT(s);
+ - accepted PAYMENT METHOD(s);
+ - payment time limits;
+ - holding or reservation status;
+ - rule in case of payment success;
+ - rule in case of payment pending, failure or expiry;
+ - whether the Distributor requires payment execution by a specific Payment Provider.
+
+6. Each Distributor returns the payable state and any payment-related constraints.
+7. The Retailer consolidates all Distributor responses into one coherent payment proposal for the TRANSPORT CUSTOMER. The Retailer also determines and manages the payment architecture : he identifies, for each CUSTOMER PURCHASE PACKAGE, which entity performs the PAYMENT PROVIDER ROLE:
+ - Retailer-side Payment Provider;
+ - Distributor-side Payment Provider;
+ - third-party Payment Provider;
+ - shared or mixed architecture.
+
+8. The TRANSPORT CUSTOMER may select one or mixed PAYMENT METHOD(s) that may include, when applicable :
+ - bank card or other card-based payment;
+ - SEPA direct debit or similar mandate-based debit;
+ - wallet or account-based payment (can be on Retailer's system);
+ - travel account debit;
+ - voucher or travel credit;
+ - miles, points or loyalty redemption;
+ - corporate account or B2B invoicing arrangement;
+ - cash or point-of-sale payment;
+ - split payment across several means of payment; or
+ - scheduled payment for deferred charging or instalments.
+ Depending on the business rules, payment (and additional data) may be:
+ - immediate, with direct authorisation and capture or delayed, with deferred capture or later debit;
+ - split into several CHARGING MOMENT(s);
+ - made by instalments according to a payment plan;
+ - made by one single payment for several CUSTOMER PURCHASE PACKAGE(s);
+ - verifies for particular PAYMENT METHOD (voucher, loyalty points, B2B, travel credit) with the relevant provider a particular confirmation process;
+ - made by travel account debit or B2B invoice/settlement arrangement; or
+ - combined with voucher, loyalty redemption or other PAYMENT METHOD(s).
+
+9. The retailer shall verify, with the relevant PSP, that the selected PAYMENT METHOD(s) are accepted for:
+ - the concerned CUSTOMER PURCHASE PACKAGE(s);
+ - the concerned distributor(s);
+ - the TRANSPORT CUSTOMER context;
+ - the country, currency and tax context;
+ - the amount and charging rule;
+ - the requested CHARGING MOMENT; and
+ - the applicable payment deadline.
+ And request to TRANSPORT CUSTOMER additional information (payer identity, billing address, invoice data, VAT number or corporate identifier, travel account identifier, voucher or travel credit reference, loyalty identifier, mandate consent, card or account credentials, strong customer authentication data, instalment acceptance conditions). The TRANSPORT CUSTOMER may see only one unique mayment (MarketPlace case) and later, the Retailer distributes, settles or reconciles the corresponding amounts with several distributor(s) according to commercial agreements (see Business Use Case K).
+
+- **Architecture Retailer-side payment**
+
+10. The Retailer, acting directly or through its Payment Provider, initiates payment for one or more CUSTOMER PURCHASE PACKAGE(s) and receivess the transaction result.
+11. The Retailer sends each concerned Distributor a payment confirmation or payment status notification including:
+ - paid amount;
+ - payment status, timestamp and reference;
+ - CUSTOMER PURCHASE PACKAGE(s);
+ - allocation amount and currency;
+ - payment instrument type where required for audit, invoicing or after-sales.
+12. Each Distributor verifies that the payment status satisfies its business rule and returns the component result (confirmed / pending / rejected / expired / revalidation required).
+13. The Retailer consolidates Distributor responses and updates the TRAVEL BASKET.
+
+- **Architecture Distributor-side payment**
+
+14. The Distributor indicates that payment must be executed through its own Payment Provider or delegated payment process. The Retailer sends the required payment initiation context to the Distributor.
+15. The Distributor, acting with its PSP, initiates payment, receives the transaction result from the Payment Provider.
+16. The Distributor returns the payment result and status to the Retailer:
+ - paid and confirmed;
+ - paid but fulfilment pending;
+ - payment pending / refused / expired / cancelled;
+ - revalidation required.
+17. The Retailer consolidates Distributor responses and updates the TRAVEL BASKET.
+
+- **Architecture Shared Retailer-Distributor payment**
+
+20. Some parts should be paid through the Retailer PSP (arhictecture Retailer-side payment) and others through one or more Distributor PSP(s) (architecture Architecture Distributor-side payment). The Retailer and Distributor(s) have agreements on:
+ - which CUSTOMER PURCHASE PACKAGE(s) are paid by which Payment Provider;
+ - whether the TRANSPORT CUSTOMER sees one payment step or several coordinated payment steps;
+ - how mixed PAYMENT METHODs are allocated;
+ - how partial success is handled;
+ - how payment deadlines are enforced.
+ following the architecure of the paiment part, each, Retailer or Distributor, requests for the payment part.
+21. Each PSP returns the transaction result to its requestor. If necessary, each Distributor returns the business status of its paiment part to the Retailer.
+22. The Retailer consolidates all results and updates the TRAVEL BASKET.
+
+- **Architecture Third-party Payment Provider**
+
+23. The Retailer and/or Distributor sends the payment initiation data to a third-party Payment Provider. The Payment is executed or scheduled and the transaction result is returned to his requestor.
+24. The Retailer and Distributor(s) exchange the necessary payment result information so that:
+ - every CUSTOMER PURCHASE PACKAGE has a clear payment state;
+ - any reservation or holding can be finalized or released;
+ - billing and settlement data remain traceable;
+ - the TRAVEL BASKET status remains coherent.
+
+ - **Payment result**
+25. If mixed payment is used, the Retailer coordinates the authorization and allocation of each part of the payment while preserving one coherent TRAVEL BASKET. Depending on the result, the Distributor may confirms or release reservation elements (see Business Use Case E).
+26. The Retailer consolidates all payment part statuses and informs the TRANSPORT CUSTOMER of the final payment result.
+27. The Retailer and/or Distributor provides the relevant proof of payment (receipt with legal data following rule of each state), invoice, payment terms with installments, and fulfilment trigger. It can be document(s) and/or TRANSPORT CUSTOMER account update or other format.
+28. The Retailer may inform the Distributor(s) with each CUSTOMER PURCHASE PACKAGE data to create/update SALES TRANSACTION(s).
+
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+## Payment failure
+1. One payment part fails or expires.
+2. The Retailer receives the failure or expiry status from the Distributor or PSP.
+3. The Distributor indicates the consequence for the impacted CUSTOMER PURCHASE PACKAGE.
+4. The Retailer either asks for another PAYMENT METHOD, requests revalidation, or informs the TRANSPORT CUSTOMER that the purchase cannot continue.
+
+## Negative amount
+1. The resulting financial amount is negative.
+2. No TRANSOPRT CUSTOMER payment is collected in BUC-D.
+3. The Retailer redirects the case to Business Use Case F or J for refund, compensation, credit note or voucher handling.
+
+## Payment after approval
+1. A corporate or group purchase requires approval before payment.
+2. The Retailer asks the Distributor(s) whether the quotation can remain valid until approval.
+3. Once approval is obtained, the Retailer restarts the payment coordination flow.
+4. If the deadline has expired, the Distributor requires refresh, revalidation or repricing.
+
+## Zero amount to pay
+1. If the payable amount for the current CHARGING MOMENT is equal to zero, the payment use case shall still be executed as a zero-payment confirmation flow.
+No monetary transaction is initiated with a Payment Provider, unless a technical payment authorization is required by implementation rules.
+2. The Retailer shall confirm with each concerned Distributor that:
+ - the total amount due is zero (not necessary the Distributor part => see settlement in Business Use Case K);
+ - no PAYMENT METHOD is required, or the required PAYMENT METHOD has already covered the amount;
+ - the CUSTOMER PURCHASE PACKAGE can be confirmed without payment;
+ - any reservation, ancillary, guarantee or service depending on payment can be finalized.
+3. The Retailer consolidates the statuses and informs the TRANSPORT CUSTOMER that no payment is due.
+4. The Retailer and/or Distributor provides the relevant proof of purchase, zero-amount receipt, invoice if legally required, confirmation and fulfilment trigger.
+
+
+### Diagram
+UML activity diagram
+
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx
+wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+To be completed
+
+
diff --git a/wiki/use-cases/business-use-cases/buc-e-fulfilment.md b/wiki/use-cases/business-use-cases/ARCHIVE/buc-e-fulfilment.md
similarity index 100%
rename from wiki/use-cases/business-use-cases/buc-e-fulfilment.md
rename to wiki/use-cases/business-use-cases/ARCHIVE/buc-e-fulfilment.md
diff --git a/wiki/use-cases/business-use-cases/business_use-case_format.md b/wiki/use-cases/business-use-cases/ARCHIVE/business_use-case_format.md
similarity index 100%
rename from wiki/use-cases/business-use-cases/business_use-case_format.md
rename to wiki/use-cases/business-use-cases/ARCHIVE/business_use-case_format.md
diff --git a/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image1.png b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image1.png
new file mode 100644
index 0000000..9c8fee4
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image1.png differ
diff --git a/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image2.png b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image2.png
new file mode 100644
index 0000000..d37d180
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan-images/image2.png differ
diff --git a/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan.docx b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan.docx
new file mode 100644
index 0000000..70bdc51
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-A-inspire-and-plan.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-B-shop-and-price-images/image1.png b/wiki/use-cases/business-use-cases/BUC-B-shop-and-price-images/image1.png
new file mode 100644
index 0000000..92b9159
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-B-shop-and-price-images/image1.png differ
diff --git a/wiki/use-cases/business-use-cases/BUC-B-shop-and-price.docx b/wiki/use-cases/business-use-cases/BUC-B-shop-and-price.docx
new file mode 100644
index 0000000..b804a32
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-B-shop-and-price.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.docx b/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.docx
new file mode 100644
index 0000000..f4826b3
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.md b/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.md
new file mode 100644
index 0000000..5dbe2b2
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/BUC-C-Order-and-Book.md
@@ -0,0 +1,385 @@
+**Use Case Overview**
+- **Business Use Case ID & Name:** BUC-C — Order & Book (+ begin of reservation)
+- **Goal (Objective):** preparing the TRAVEL BASKET (BUC-B ) the Transport Customer selected, to make sure it is available before Retailer – Distributor payment takes place
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Add the 2 steps between the basket and the payment : Secure inventory/options with a time limit and confirm the sales after the financial agreement
+- **Scope:** adding reservations and ancillaries to the Travel Basket, entering personal data, creating a provisional booking (+ beginning of reservation) and making it final
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> We could add here a terminology chapter to clarify "reservation / hold : a claim on a ressource" and "booking / finalisation : the action that make the sale definitive..."
+> Same for "preliminary booking" and "final booking" if you want to use these terms (...‘preliminary booking’ refers to a temporary hold/reservation of inventory (reservation), while ‘final booking’ is confirmed only once the Retailer confirms financial commitment )
+
+> **Comment (BIGEX Olivier, 2026-05-27):**
+> Could be great. Add freeze of the price in preliminary booking (to give the customer time to pay if dynamic pricing).
+**Actors & Context**
+- **Primary Actor:** **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wanting to finalize what is selected in the TRAVEL BASKET
+He/she can be the manager of a group, a PRM, the purchaser for a minor traveler or other with specific needs or none. A travel agent acting on behalf of a corporate client. A corporate travel manager. A multi-modal aggregator.
+
+> **Comment (Bourdelin, Sonia, 1900-01-01):**
+> Proposition : change for business word Customer
+
+- **Supporting Actors / Stakeholders:**
+- **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** supports the customer by making sure the selected CUSTOMER PURCHASE PACKAGE(s) is completely available, before payment process
+- **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** creates the provisional booking and creates the reservation.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> + manages time limit
+- **Assumptions (context at start):**
+- The TRANSPORT CUSTOMER can provide the additional information required to finalize the transaction (anonymous booking app; traveler information; driver license etc..)
+**Preconditions & Postconditions**
+- **Preconditions (must be true before start):**
+- TRANSPORT CUSTOMER has a TRAVEL BASKET containing at least one TRAVEL BASKET ELEMENT with one CUSTOMER OFFER PACKAGE
+
+> **Comment (Bourdelin, Sonia, 1900-01-01):**
+> offer that need a reservation: "at least one element that requires inventory/options securing (AVAILABILITY CONDITION)"
+- **Postconditions — Success guarantees :**
+- All items of the TRAVEL BASKET are confirmed / reserved so they will be available for fulfilment and Settlement between Retailer and Distributor and fulfilment.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> some element that require reservation. This BUC do not affect the others elements of the basket.
+
+> **Comment (BIGEX Olivier, 2026-05-27):**
+> The hypothesis here is that any offer is really bought on distributor side only if a confirmation of the purchase to the distributor is done. Thus all items shall be confirmed (and some of them reserved), in order to be ready for the fulfilment.
+- **Postconditions — Minimal guarantees:**
+- If one of the offer parts cannot be confirmed, the customer receives a clear “no offer bookable” outcome (with a reason where possible).
+
+> **Comment (Bourdelin, Sonia, 1900-01-01):**
+> And in some cases, new proposal and/or available actions (change option/leg/operator, refresh offer, restart selection in BUC-A/BUC-B)
+
+**Scenarios**
+**Main scenario**
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> I suppose that the first chapter "selecting..." and third 'customer details ...' are parts of pre-reservation ? Could be only 2 blocks in main scenario : pre-reservation and finalizing the booking ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> We have to choose where we set the Frozen/locked state of the basket : in BUC-B at the end or in BUC-C at the begining.
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> The backet elements need to be locked in case of dynamic pricing or of facilitiy/seat reservation. It is done in basket management (as soon as an offer is put in the basket). But it seems that the choice is to describ that here in BUC-C (Requesting preliminary booking).
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Add an explicit step here like that : "Retailer freezes the basket content for reservation securing (TRAVEL BASKET / TRAVEL BASKET ELEMENT). Changes after this point require restarting reservation securing for impacted elements. "
+- **Selecting reservation preferences and ancillaries**
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> To be added somewhere: an option can have a price ==> an option is a sub-offer and the selection of this kind of offer follow the same process than BUC-B (basket management), with an update of the final price each time an option is selected/deselected.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> add something like : "When an ancillary/option has a price, treat it like a selectable sub-offer: selecting/deselecting triggers repricing similarly to BUC-B (basket update)"
+
+> **Comment (Edwin van den Belt, 2026-05-20):**
+> Question: a reservation is not a booking, but a claim on a resource (seat, bike, etc). How about just requesting a travel right (without reservations)?
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> This question probably comes with the structure of this document. Each bullet point is optional (except the last one: finalizing the booking). Maybe point out that ?
+- The TRANSPORT CUSTOMER can request reservation and ancillary options if available. To do that Retailer asks Distributor(s) for all reservation and ancillary options
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> To securize the options (seat, bike spot, service) with a time limit (RESERVATION, AVAILABILITY CONDITION, SPOT ALLOCATION)
+- Distributor supplies all reservation and ncillary options with the price and all relevant details.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> I would add once here the list of the concepts : available reservation/facility options, constraints per leg/operator, price where applicable, and availability status
+- TRANSPORT CUSTOMER expresses seating preferences and constraints, including seat position, coach, deck, adjacency to another passenger, and mandatory vs preferred requirements, across operators and modes. The Retailer should know per leg what reservation possibilities are available. The Retailer should be able to assign seats or ancillaries per operator, ensuring consistency across the journey. The Retailer supports cases where not all the legs or operators or modes included in the journey can satisfy the requested preferences.
+
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Or based on:
+> - seat preferences stored in a customer account.
+> - customer profile: a PRM with wheelchair will be automaticaly placed in a dedicated seat (if available). Same for a companion of a PRM (placed near the PRM)
+
+> **Comment (Vinke, Bob BGH, 2026-05-15):**
+> I find this a retailer internal function. Does not change EUDIT specification.
+
+> **Comment (JUGELT Stefan, 2026-05-20):**
+> This knowledge comes from the distributor.
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> Indeed. How comes this information from the customer is an internal function of the retailer, based on possibilities provided by the distributor. But in that case, the sentence could be written the other way round: «the retailer collects seating preferences…»
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> each option can be bound to a CPP or to a CPP element.
+
+> **Comment (Vinke, Bob BGH, 2026-05-15):**
+> CPP is transmodel.. What would you add business wise to this line?
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> If we come back to business, language, then «leg» seems correct
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> and in some cases, Retailer or Distributor can propose alternatives
+- Customer can select seat preferences (window/aisle, facing direction, quiet zone, power socket, legroom) depending of each operator.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> can be a bike sport, ... larger than a seat
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> Could we use the generic wording «facility»?
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Yes, facility covers seat, bike space, etc.(RESERVATION / SPOT ALLOCATION).
+- Customer can choose his preferred seat if the operator supports seat map selection based on a graphical coach/deck layout, including available, reserved, and unavailable seat indicators. Retailer ensures consistent seat map representation despite heterogeneous seat models.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> many possibilities : chose one seat, let the operator chose the best seat for you with your criteria, let the operator chose the best seat corresponding to your offer
+- Retailer can support asset-specific ancillary services (helmet rental, child seat, cargo trailer, EV charging reservation; luggage; meals; seat upgrade) bookable alongside the leg. Ferry-specific extras: pet transport (IATA pet category), wheelchair-accessible cabins, dietary meal requests, and lounge access.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> is it link with the seat ? In some cases yes, in some cases no (bike spot in second class in french TER is not linked with a seat reservation)
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Enlarge to all transportables, facility,
+- Special PRM specifications can be taken into account at this stage in the process (…additional specific requirements?.)
+
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> That’s a tricky point. The station-based assistance is typically not provided by the operator but by the infrastructure provider. Thus out of scope of EUDIT ?
+
+> **Comment (Vinke, Bob BGH, 2026-05-15):**
+> How does the current PRM booking UIC work? Do you book ticket and assistandce at the same time? or is it a separate proces?
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> At least in France, 2 separated services, but the purchase of a ticket must be proven to the infrastructure manager (PNR/ticket ref)
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> You can mark ‘station-based assistance request’ as out-of-scope or separate service, while keeping operator-reserved facilities in scope
+- In case of reservation only, this step can take place based on trip only selection in use case A, where reservation only was selected.
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> To be developped here: the customer can resquest a reservation only, if he already has a valid fare contract (e.g. a pass or a single ticket). But to do that, he shall prove that he has a valid fare contract (or retrieved by the retailer)
+
+> **Comment (Vinke, Bob BGH, 2026-05-15):**
+> For what mode / standard is this proof needed? Currently OSDM supports seling reservation without proof.
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> Indeed. We could consider that this proof process is an internal process of the distributor/fare provider. But at least the related travel right could (not mandatory) be added as customer context (booking/ticket ref ?).
+It is possible this step is done as part of SALES OFFER PACKAGE selection in use case A
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> option of SOP
+- **Requesting preliminary booking**
+- The TRANSPORT CUSTOMER confirms the selections and confirms to want to proceed to finalizing the sale.
+
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Not necessarily. The preliminary booking can happen at the moment when a CPP is put in a Travel Basket, in order to secure the price and the seat availability.
+> Maybe delete simply this 4th point ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Or reformulate as the pre-booking can be, in some cases, triggered earlier (when an offer is added to basket) in the purchase process.
+
+> **Comment (BIGEX Olivier, 2026-05-27):**
+> Ok with this reformulation
+- The RETAILER requests for preliminary booking of the selected CUSTOMER OFFER PACKAGE(s) by requesting the SALES OFFER PARTS at all relevant DISTRIBUTOR(s)
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> SALES OFFER PACKAGE for the "offer". If you need to speak about a part of a SOP (= SALES OFFER PACKAGE ELEMENT if it is an association to a special TRAVEL DOCUMENT), you could use offer part for BUC. And explain if something is missing in Transmodel : we have in EUDIT to propose evolutions
+- The Distributor(s) check(s) the availability of the SALES OFFER PARTS at the operator(s) and creates a preliminary booking and reservation(s) if required. (The reservation is actually created). The created booking may include a defined payment time limit, after which the order or parts of it may be automatically cancelled or released according to the operator rules. This time limit can differ, depending on the time left till the time of departure.
+
+> **Comment (Vinke, Bob BGH, 2026-04-28):**
+> How does it work if an operator replies with a PENDING reply, where other operaters can provide direct or provisional confirmation?
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Or the operator needs technicaly more time to reply.
+> Asynchroneous booking is way more complexe and requests specific technical architecture. In scope ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Operator ‘PENDING’ / async confirmation should be moved to an alternative scenario (requires polling/callback/timeouts). Nominal path should remain synchronous confirmation of securing (RESERVATION).
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Not a payment time limit, but a booking (=finalization) time limit, which includes a payment step on retailer’s side
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> We have the both time limits : the one of payment is managed in BUC-D and the one on reservation is managed here. Please split in 2 and manage here reservation time limit
+The Distributor confirms the success of the preliminary booking to the Retailer. This confirmation consists of a time limit, the preliminary booking will be secured for this time limit. The Distributor assigns unique booking references (booking code, external reference) that can be used by Distributor, Retailer and operator systems.
+The Distributor requests the personal data requested by the operator(s). (Legal name (title, forename, surname; Nationality (ISO 3166-1 alpha-3; Identity documents (type, number, issue country, expiry date); Legal name (title, forename, surname); Nationality (ISO 3166-1 alpha-3); Identity documents (type, number, issue country, expiry date); Emergency contact (ICE phone, email); Place of birth, VISA/permit number (for international crossings); **Vehicle data** (registration plate) etc..
+
+> **Comment (Vinke, Bob BGH, 2026-04-28):**
+> should FR-BOOK-015 be part of this step” The booking confirmation response shall include a detailed payment breakdown showing each payment instrument used (card, voucher, loyalty points, corporate account), the amount applied per instrument, and per-operator settlement allocation, enabling transparent multi-method payment reconciliation.”
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Yes, but not here but for the finalization
+
+> **Comment (RECEVEUR Jean-Baptiste, 2026-05-28):**
+> If the reference is unique only on the Distributor side, it might be "not unique" on the retailer side. They both need to assign a reference which will be unique in each system.
+- **Providing relevant CUSTOMER details**
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> does the customer provide fulfilment preferences and data (NFC smartcard) as well or not at this step ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> Perhaps move the title just before peceeding sentence ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Traveller can be a group. Add refernces to this case and moreover, a group may require only capacity hold, not defined seats. Capacity hold can be also the only need for one traveller.
+- The TRANSPORT CUSTOMER supplies all relevant personal data needed by the operators for the selected offer. This concerns the data that is not needed to calculate an offer and is personal, so should only be collected if the offer needs to be finalized. And only that data needs to be collected needed for the selected offers. Data is only sent to those distributors that need it.
+
+
+> **Comment (JUGELT Stefan, 2026-05-20):**
+> Those data should be only provided if strictly needed for the contract execution.
+
+> **Comment (Vinke, Bob BGH, 2026-05-21):**
+> made a bit more specific.
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> to be conform with ....RGPD
+- When required by one or more operators, the gender passenger data is transmitted only when required by the operator for the specific service. Permissible values align with ERA/OSDM gender enumeration.
+
+- For a group booking the list of TRAVELERS might not be complete, to amend in later stage.
+
+
+> **Comment (JUGELT Stefan, 2026-05-20):**
+> This might be difficult as the amount of travellers and their type should be fix at this stage.
+
+> **Comment (Vinke, Bob BGH, 2026-05-21):**
+> but the amount of travelers and type is not related to GDPR. it can not be related to a specific individual. so i do not see the problem.
+- If relevant for one of related operators, the Retailer will assure licence type validation (driving licence category) as a precondition for reserving vehicle categories that require a licence.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> validity in general ?
+- 5. The TRANSPORT CUSTOMER confirms the final purchase of the TRAVEL BASKET. Confirming the responsibility for payment.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> remove number
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> basket
+- **Finalizing the booking**
+- The Retailer ensures the financial transaction with the TRANSPORT CUSTOMER. The Retailer confirms the booking to the Distributor after making sure the transaction will be payed by the TRANSPORT CUSTOMER.
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> The Customer wants to finalize the purchase after financial engagement in order to trigger the next step in BUC-E : receive the travel rights and documents (SALES OFFER PART(s), TRAVEL DOCUMENT(s))
+- The retailer takes care of a B2C payment before finalizing the booking
+
+- The Retailer has another payment arrangement with the customer (account based; invoice etc. )
+
+- the TRAVEL may be a Group TRAVEL with special payment conditions.
+
+
+> **Comment (Vinke, Bob BGH, 2026-04-28):**
+> Is this part of this step, or earlier before provisional booking?
+- The TRANSPORT CUSTOMER might have an operator specific voucher as a payment means for the operator specific offer part. INTERACTION alternative flow?
+
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> is this covered in use case D? or only, when Retailer - Distributor interaction is needed in case of 9-d voucher?
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Yes, BUC-D.
+> Coudl be reformulated by:
+> «Once the retailer has ensure the financial transaction with the TRANSPORT CUSTOMER (see BUC-D), the retailer confirms the booking»
+> that’s all
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> yes move payment execution details in BUC-D and add a reference here
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> Yes, in BUC-D is is explained also. Refers to BUC. But it is clearer to spoke about that in both cases for me
+- The Distributor finalizes the sale of all SALES OFFER PARTS with all operators and confirms the completed booking to the Retailer.
+The Distributor returns a full price breakdown including: base fare, applicable VAT per jurisdiction, other charges (booking fees, distribution fees), and the grand total. For journeys crossing international borders, the applicable VAT rate can differ from domestic VAT in one or more countries traversed.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> offers that need reservation
+
+> **Comment (BIGEX Olivier, 2026-05-27):**
+> Not only. The assumption is that any offer shall be confirmed to the distributor before fulfilment
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> Returns «through ticket» (according to PRR) final guarantee as well.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> + Final guarantees relevant even for 'though journey'
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> + in addition explicitly returning final guarantees relevant to ‘through journey’ when applicable (TRAVEL GUARANTEE(s))
+**Alternativesscenarios**
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> IS the Order splitting described in EUDIT.use.case... docx input is taken into account ?
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+- **Price change**
+4.a When during the pre booking step, the inventory is still available but the price of a previously returned SALES OFFER PART changes during booking confirmation. The Distributor response shall clearly indicate price change, provide the updated offer with new price and validity, and allow the Retailer to present the change to the customer before proceeding. Use case A can be used to select a new SALES OFFER PACKAGE or the customer can abandon the flow.
+
+> **Comment (JUGELT Stefan, 2026-05-20):**
+> Is my understanding correct that the price can change even if a valid pre-booking exists?
+
+> **Comment (Vinke, Bob BGH, 2026-05-21):**
+> no. the pre-booking step is meant to block the price and fysical inventory for a specific period for this customer.
+> This part reflects to the fact that during the step to achieve the pre-booking, the distributor can find out that in the meanwhile the current price or inventory is no longer available. This can be the fact, as the offer does not reserve. it is just a view on the current situation in the inventory.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> There is a case when once a reservation/hold is confirmed (RESERVATION), price/inventory should remain stable within the hold time limit; price change can occur during the securing attempt (if hold not yet confirmed). If you want you can precise this case
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> is it a reference to step 4?
+- **No complete preliminary booking**
+4.b The distributor cannot confirm one or more of the requested SALES OFFER PACKAGE PARTS. A failure message with reason and affected OFFER PART is sent.
+
+Retailer informs the customer of a booking failure and helps him to finalize an alternative offer selection, using BUC A and B.
+If the booking is aborted due to the partial failure, the Retailer performs a rollback to release locks on successfully locked legs, preventing customers from blocking partial journeys.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> even a total failure need a rollback to release any succesful holds to avoid blocking ressources
+- **Mand**a**tory seat selection/preference no longer available**
+If the seat selection / preference is no longer available this is returned by the Distributor, so Retailer can inform the TRANSPORT CUSTOMER. If the seat selection was a fixed (payable) choice, the TRANSPORT CUSTOMER can change his selection.
+- **Passenger blacklist**
+Retailer should know when one of the operators has a Passenger blacklist. If this is a case, the retailer must use the passenger data to check against this blacklist just before customer payment. The response returns an appropriate refusal reason without disclosing the specific blacklist reason to the end user.interaction with distributor
+
+> **Comment (JUGELT Stefan, 2026-05-20):**
+> Are we sure that this is part of the specification? Wouldn't it be the task for the Distributor in case of a ressource reservation?
+
+> **Comment (Vinke, Bob BGH, 2026-05-21):**
+> as the pre-booking fase is still anonimous AND as blacklist preferabely takes place bofore payment, a step between pre-booking and payment could be relevant. The PRE-booking reply could show that a blacklist check is manditory before payment. wiht a specifick API call in between. TO BE DISCUSSED.
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Yes it can be done but is it the retailer responsability ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Who is requesting that check ? To precise
+- **Inventory release at time limit exceed**
+If the time limit is exceeded, the Retailer can ask the TRANSPORT CUSTOMER if he still want to purchase. If so, the Retailer asks for a new time limit. If not the Retailer releases the preliminary booking.
+If the Retailer does not finalize the preliminary booked SALES OFFER PARTS within the time limit, the Distributor contacts all operators to release inventory.
+- **Single anonymous travel**
+If the TRANSPORT CUSTOMER has an anonymous travel profile, the Retailer uses this function for those operators that support this, making sure that anonymous travel is used where supported.
+- **Post- BookingAdd-On**
+The Retailer can add ancillary services, seat upgrades, or optional reservations to an existing confirmed booking without cancelling the original booking. The Distributor returns the updated order with new price and fulfillment details.
+- **Price calculation afterthe trip**
+
+> **Comment (Bourdelin, Sonia, 2026-05-26):**
+> Can we have a reservation and travel with an EMV card ? I think it is the case we must cover : reserve a bike space/ something and travel with ENV card or any other post-payment contract.
+In sales processes like Fairtiq BeIN-BeOUT or chipcard / EMV CheckIN-CheckOUT this process can be followed after the trip. The Retailer can collect all relevant TRIP and product information, during the TRAVEL. After the TRAVEL, the Retailer can finalize the transaction.
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> To me reviewed more deeply. With EMV or smart card post-payment, the retailer is not involved, but validating stakeholders: checkin/out events are directly sent to the operator.
+
+> **Comment (BIGEX Olivier, 2026-05-11):**
+> BUC-C could only deal with the (optional)subscription of a post-payment service. Another BUC could detailed waht happens after the Trip
+
+> **Comment (Vinke, Bob BGH, 2026-05-15):**
+> how does EMV work in relation to a sales proces of a multi model trip?
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> If multimodal trip I assume that the customer is simply informed that for that leg he will only need to checkin(/checkout). Or handle subscription if mandatory.
+- **Longer time limit for special Transport customer processes**
+Holding an offer beyond the standard offer lifetime can be a chargeable service defined unilaterally by the operator(s). The operator publishes the applicable hold fee, maximum hold duration (e.g. 24 hours), and the fee collection method. The Distributor returns the hold fee amount and currency in the offer response when an on-hold option is available; a hold requires explicit distributor acceptance of the fee before activating the hold by the Retailer. The distributor returns a hold reference, hold expiry timestamp, and confirmation of the amount that will be charged.
+The Retailer can release the hold before expiry with appropriate fee treatment per operator rules (e.g. fee forfeited or refunded). The consumer-facing price can be distinguishes the hold fee from the transport fare.
+
+**Diagram**
+UML activity diagram
+
+
+
+**Links with use cases**
+Link to (https://github.com/TransmodelEcosystem/EUDIT/discussions/36#discussioncomment-16183779)
+To be completed
diff --git a/wiki/use-cases/business-use-cases/BUC-D-pay.docx b/wiki/use-cases/business-use-cases/BUC-D-pay.docx
new file mode 100644
index 0000000..3a556fe
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-D-pay.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.docx b/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.docx
new file mode 100644
index 0000000..bda1875
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.md b/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.md
new file mode 100644
index 0000000..88b44a0
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/BUC-E-Ticketing-and-Fulfilment.md
@@ -0,0 +1,275 @@
+In writing stage – version 1
+## Use Case Overview
+
+- **Business Use Case ID & Name:** BUC-E— Ticketing and Fulfilment
+- **Goal (Objective):** Enable the Customer to obtain travel access rights resulting of what he purchased, reserved and paid. His mobility contract(s) must be created according to the confirmed offers. The customer may also receive the appropriate supports/media (can be inspected).
+- **Scope (Summary) :**
+ - Confirmation that selected offer(s) / basket element(s) are ready for fulfilment,
+ - Retailer request to Distributor for fulfilment constraints, supported fulfilment methods and required data
+ - Creation or confirmation of travel rights and contract(s),
+ - Issuing, generation, registration, retrieval or loading of travel evidence with Retailer-side, Distributor-side, shared or third-party fulfilment architectures,
+
+> **Comment (Bourdelin, Sonia, 2026-05-21):**
+> Add the management of Activation and deactivation of travel documents must be supported where relevant (e.g. BoB activate-ticket, TOMP activate-product).
+ - Distributor response with document, token, account/media update, retrieval reference, delivery reference, tele-distribution of all required media, or pending/failed status with management of delayed distributions,
+ - Coordination with reservation process (confirmation of contract creation and fulfilment, data exchange, failure management),
+ - Consolidation of fulfilment status by the Retailer and provision of the final fulfilment result to the Customer,
+ - Management of fulfilment failure, partial fulfilment, delayed fulfilment, reissue or cancellation before delivery
+ - Traceability for later validation, inspection, account consultation and after-sales use cases.
+
+## Terminology note —
+
+The **travel right** (FARE CONTRACT) represents the created travel access right. It is the contractual right allowing the TRANSPORT CUSTOMER or another entitled passenger to access the transport service under defined conditions. In some systems it may be explicit; in others it may be implicit or account-based.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Should be extended to all kinds of mobility contract, which are not sufficient to travel. Like reduction card, facility reservation...
+
+The **purchase record** (SALES TRANSACTION) is a record of the confirmed sale on Retailer side once the purchase has reached a sufficiently binding state.
+
+The ticket / travel evidence /**support** (TRAVEL DOCUMENT) is the medium or representation distributed to the TRANSPORT CUSTOMER or traveller to prove or use the right. It may be physical, digital, account-based, token-based, barcode-based, smartcard-based, mobile wallet-based, printed, dematerialised or retrievable later through a customer account.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Enum ==> not sure that the list is exhaustive. A deep analyse of possible enums for fulfilment methods and fulfilment media should be done, based on existing standards.
+> --> write here that these are exemples.
+
+A FARE CONTRACT may exist without an immediately distributed TRAVEL DOCUMENT if the access right is stored in an account, on a smart medium, or if the document is generated later. Conversely, a TRAVEL DOCUMENT should always refer to one or more underlying access rights, contracts or entitlement records.
+The **distribution channel** (DISTRIBUTION CHANNEL) is the channel through which the travel evidence is delivered or made available.
+The **fulfilment method** (FULFILMENT METHOD) is the way the travel right is made usable: online ticket, mobile ticket, smartcard loading, collection, account update, physical delivery, etc.: delivery of the proof of the access rights or the media support.
+
+The term **order** is not used as a normative EUDIT / Transmodel business object in this use case.
+A Retailer may internally manage an “order”, but this remains an implementation-specific retail object. In this BUC:
+- before confirmation, the business flow is described through the basket and basket elements (TRAVEL BASKET, TRAVEL BASKET ELEMENT);
+- the selected Distributor offer remains traceable as a CUSTOMER PURCHASE PACKAGE;
+- after confirmation, the sale is traceable through a purchase record (SALES TRANSACTION);
+- fulfilment creates or confirms the travel right (FARE CONTRACT) and the travel evidence (TRAVEL DOCUMENT) or equivalent account/media update.
+
+## Actors & Context
+
+- **Primary Actors:**
+ - **Customer (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wants to receive usable access rights, documents, media updates, account updates or retrieval information to travel and being inspected (proof of travel rights). He acts for himself/herself and/or for the travellers represented, including groups, PRM travellers, minors, corporate travellers or other travellers with specific needs.
+
+ - **Traveller** (PASSENGER ROLE): the person(s) who will actually travel and use the travel rights. The Traveller and the Customer can be the same person but not always.
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (**FARE PRODUCT RETAILER ROLE (API consumer)): manages the fulfilment process for the customer. He presents fulfilment choices and statuses, coordinates Distributor-side fulfilment when required, and may distribute directly when authorized.
+-
+ - **Distributor** (FARE PRODUCT DISTRIBUTOR ROLE (API provider)): may create, confirm or validate the travel access right(s) and contract(s). He may manage the ticketing constraints, coordinate or have ticketing issuer role(s), provides or enable access to the support(s) (TRAVEL DOCUMENT(s)).
+
+- **Other retailer/distributor-facing Actor :** where applicable
+ - **Media and Medium Application Provider** (MEDIA PROVIDER ROLE, MEDIUM APPLICATION PROVIDER ROLE) : May load or activate a physical or digital support, such as a smartcard, NFC mobile application, RFID token or wallet.
+ - **Fulfilment Provider** / Document Generator (FARE PRODUC ISSUER ROLE) : May generate a barcode, QR code, Aztec code, PDF, BoB BCT token, wallet pass, collection reference or other document artefact.
+
+## Preconditions & Postconditions
+
+- **Assumptions and Preconditions (must be true before start):**
+ - Payment phase has ended with a known payment or confirmation status for the concerned basket element(s) and even zero-amount basket element are ready for fulfilment.
+ - The Retailer knows which Distributor is responsible for each selected offer with its fulfilment rules (immediate fulfilment, delayed fulfilment, account update, media loading, collection, physical delivery, or no separate document because the right is account/media-based.)
+ - Distribution channel is chosen by customer and accessible, even asynchronously.
+
+> **Comment (Vinke, Bob BGH, 2026-05-18):**
+> one booking might even have different distribution chanals, if not all products support the same?
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Yes we manage it in the BUC
+ - Different architectures are known and associated with relevant contracts and the chosen distribution channel for the media. The contract creation and / or the support distribution can be done by : retailer-side fulfilment (under delegation), distributor-side fulfilment, shared fulfilment, third-party fulfilment (fulfilment provider or complete ticketing system).
+ - Different architectures are known and associated with relevant supports: The support can be delivered immediately after the payment, after a hold-on delay, after reservation finalization, after contract loading on contactless card, travel account, mobile application,… or delayed later to station equipment, travel agency,…
+ - The BUC-E is contract creation and fulfilment architecture neutral.
+ -
+ -
+-
+
+- **Postconditions — Success guarantees:**
+ - The contracts are created and ready to be used.
+ - The Customer has received appropriate:
+ - travel right (**FARE CONTRACT** or equivalent access right) is created, confirmed or updated,
+ - travel evidence (**TRAVEL DOCUMENT**) or equivalent, account/media/retrieval reference is created or made available
+ - The Retailer presents a coherent status to all parties:
+ - each fulfilled selected offer has a clear fulfilment status,
+ - each Distributor returns the identifiers and status needed for traceability,
+ - each Retailer consolidates the status across all Distributor(s),
+ - the Customer is informed of what is usable, what is pending, and any remaining action before travel.
+ - The fulfilment result remains traceable to the basket element, selected offer, purchase record, travel right and travel evidence.
+
+> **Comment (Vinke, Bob BGH, 2026-05-18):**
+> why is this relevant for this UC?
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> The references (support, contract, payment) must be recorded for after-sales validation inspection, ...
+-
+- **Postconditions — Minimal guarantees:**
+ - If fulfilment cannot be completed, the Customer is informed with status, consequences and next possible actions for each impacted travel right.
+ - The Retailer is responsible for the coherency between contract and supports : he prevents the Customer from misunderstanding.
+
+> **Comment (Vinke, Bob BGH, 2026-05-18):**
+> do you have a definition of suports?
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Added terminology chapter
+ - The Distributor returns a business status and next possible action: retry, alternative channel, pending notification, cancellation before distribution, reissue, manual support or transfer to after-sales.
+ - Actions are logged and can be audited.
+
+## Scenarios
+
+### Main scenario
+1. The use case starts when one or more selected offer(s) / basket element(s) are ready for fulfilment after BUC-D. The Retailer identifies, for each selected offer, the data required for fulfilment with at least: traveller(s), selected or available fulfilment method (FULFILMENT METHOD), delivery, account, medium or retrieval data (TYPE OF TRAVEL DOCUMENT).
+
+- **Fulfilment preparation**
+2. The Retailer checks the coherence of the selected offer(s) from a fulfilment point of view and coordinates: he prepares the fulfilment summary for the Customer and prepares the Distributor requests with:
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> «booked-offer» ?
+> To insist on the fact that the offer has been purchased ?
+ - selected offer(s) to fulfil and its Distributor responsible for each selected offer,
+ - requested fulfilment method(s),
+ - expected travel evidence type(s),
+ - whether fulfilment is immediate, delayed, account-based, media-based, collection-based or physically delivered,
+ - any remaining information needed before fulfilment.
+This summary is shown to Customer who can confirm or update fulfilment according to business rules.
+3. For each concerned Distributor, the Retailer requests fulfilment readiness and constraints with
+ - reservation / seat / ancillary / service references where applicable.
+ - traveller data required for ticketing;
+ - selected fulfilment method;
+ - requested type of travel evidence (TYPE OF TRAVEL DOCUMENT);
+ - delivery channel or retrieval channel;
+ - customer account or target medium reference;
+ - required timing;
+ - any customer-facing constraints already presented by the Retailer
+4. The Distributor returns whether fulfilment can proceed and under which conditions (revalidation required, missing data, who will generate the travel evidence and contract, security requirements, delays, medium or account constraints, rules in case of failure).
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> A 2-steps interaction with the distributor for fulfilment (prepare + fulfil) cannot be imposed. Let the forge decides the endpoints.
+> --> change step 3 with «the retailer checks fulfilment readyness and constraints, based on information provided by the distributor :» and remove step 4 ?
+
+- **Distributor constraints (depending on architecture)**
+5. The Retailer consolidates all Distributor responses to identify for each selected offer the fulfilment roles repartition and delegations, delayed (asynchronous) fulfilment and impossibilities.
+
+**Retailer-side fulfilment**
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Feedback of other BUC: add a small disclaimer just before telling that there could be several fulfilment process.
+> In order to make the reader understand that step 9 don’t follow step 8.
+6. This architecture applies when the Retailer is allowed to issue, generate, distribute or load the travel evidence using Distributor-provided rules, templates, identifiers, security material or registration rules. The Distributor provides the Retailer with the required fulfilment data.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Including security data (keys, algorithms…).
+7. The Retailer creates or prepares the travel evidence (TRAVEL DOCUMENT) or updates the account/medium where authorised.
+Examples:
+ - generate PDF / mobile ticket / barcode / QR code;
+ - generate wallet pass;
+ - prepare customer account update;
+ - perform NFC loading if delegated;
+ - create a collection reference;
+ - produce a customer-facing document combining several Distributor results.
+8. The Retailer sends a fulfilment notification or registration request to the Distributor (what has been done and status). The Distributor validates and records the fulfilment result. The Retailer informs the Customer with fulfilment status accordingly.
+
+**Distributor -side fulfilment**
+9. This architecture applies when the Distributor creates the travel right and travel evidence itself. The Retailer sends the fulfilment initiation request with traveller data, selected fulfilment method, delivery, account, medium data, requested document type and other constraints.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Could be plural. For SNCF, the retailer can get a pdf (a link to download it)+ encoded picture of the barcode with related data.
+10. The Distributor creates or confirms the travel right (FARE CONTRACT or equivalent). He may also:
+ - finalise the reservation : confirm seat or ancillary allocation;
+ - register the contract;
+ - generate the document;
+ - update an account;
+ - prepare a medium loading order.
+11. The Distributor returns the fulfilment result to the Retailer with confirmations/failures, status and references. The Retailer informs the Customer with fulfilment status accordingly.
+
+**Shared Retailer–Distributor fulfilment**
+12. This architecture applies when some fulfilment tasks are performed by the Retailer and others by the Distributor. The Retailer still coordinates fulfilment process. For each selected offer, the Retailer and Distributor identify who performs each fulfilment task:
+ - travel rights creation or confirmation,
+ - support generation,
+ - document registration,
+ - account update,
+ - media loading,
+ - Customer/Traveller distribution,
+ - status notification (and who is notified).
+13. Each party executes its fulfilment part and returns status and references. The Retailer consolidates the final status and ensures that the Customer receives a coherent result.
+
+**Third-party fulfilment provider**
+14. The Retailer and/or Distributor may use a third-party fulfilment provider, document generator, registrar, account provider, media provider, wallet provider or ticketing system. The BUC does not standardise the third-party internal API. It only requires that the Retailer and Distributor exchange enough data to keep traceability.
+15. The third party returns the result to its requestor. The Retailer and Distributor exchange the necessary references. The Retailer consolidates the final status and ensures that the Customer receives a coherent result.
+
+- **Fulfilment resultconsolidation**
+
+16. The Retailer consolidates all fulfilments status (Distributors, third-parties, …) and informs the Customer. The fulfilment can be: full, partial, pending, delayed, failed, cancelled, to be revalidated, need manual action.
+Partial, failed or blocked fulfilment is not handled as a separate alternative scenario. It is handled as a fulfilment status returned by the Distributor and consolidated by the Retailer. The Distributor must return the business consequence and the next possible action for each impacted selected offer.
+
+17. The Retailer and/or Distributor provides the support(s) or/and information.
+The Customer may receive:
+- downloadable document;
+- email attachment;
+- mobile ticket;
+- wallet pass;
+- barcode / QR code;
+- account update confirmation;
+- smartcard loading confirmation;
+- ticket collection reference;
+- delivery tracking information;
+- confirmation that the access right is already associated with an account or medium.
+
+18. The Retailer and Distributor record the fulfilment references needed for later processes
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+##### Immediate fulfilment
+- The Distributor confirms that the selected offer can be fulfilled immediately.
+- The Retailer or Distributor creates or confirms the travel right(s).
+- The support or equivalent account/media update is generated immediately.
+- The Distributor returns the final fulfilment status.
+- The Retailer informs the Customer that the travel right is usable.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> According to conditions of use (e.g. could be usable in 2 months).
+#####
+##### Delayed or asynchronous fulfilment
+- The Distributor accepts the fulfilment request but cannot immediately provide the final travel evidence / support.
+- The Distributor returns a pending or delayed status with expected availability time and references.
+- The Retailer informs the Customer that the travel right is not yet usable or is usable only under defined conditions.
+- When fulfilment becomes ready, the Distributor or fulfilment provider notifies the Retailer, or the Retailer retrieves the fulfilment result.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> Add here «teledistribution» process ?
+> --> «when fulfilment becomes ready or when the fulfilment has been performed by another retailer or validating provider»
+> Or add a dedicated scenario ?
+- The Retailer provides the final travel evidence / support, account update, media loading confirmation, collection reference or delivery information to the Customer.
+- If the delayed fulfilment fails, the Distributor returns the business consequence and next possible action.
+-
+**Cancellation before distribution**
+- A fulfilment operation must be cancelled before the travel evidence / support is distributed or before the travel right becomes usable. The Retailer requests cancellation before distribution from the Distributor.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> «immediate cancellation» ? To make the difference with the cancellation for aftersales
+- The Distributor checks whether the travel right or support has already been issued, distributed, loaded, activated or made usable. The Distributor returns the resulting status:
+ - cancelled before distribution;
+ - cannot cancel because already distributed;
+ - already usable;
+ - reissue required;
+ - transfer to after-sales required.
+- The Retailer updates the Customer-facing status.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> May cancel the payment process too
+- If cancellation before distribution is no longer possible, the case exits BUC-E and is transferred to the relevant after-sales use case.
+**Reissue before travel without changing the selected offer**
+- A travel evidence / support must be reissued before travel because of a technical issue, wrong format, delivery issue, failed loading, corrupted document or authorised correction. The Retailer requests reissue from the Distributor or performs reissue under Distributor delegation.
+
+> **Comment (BIGEX Olivier, 2026-05-22):**
+> or the customer has lost his document
+- The Distributor confirms whether reissue is allowed without changing the selected offer.
+- The previous support is marked as replaced, voided, blocked or blacklisted where required. The new support is issued and remains linked to the same:
+ - selected offer (CUSTOMER PURCHASE PACKAGE);
+ - purchase record (SALES TRANSACTION);
+ - travel right (FARE CONTRACT);
+ - original fulfilment reference.
+- The Retailer informs the Customer which support must now be used. If the reissue implies a commercial change, refund, exchange or compensation, the case exits BUC-E and is transferred to the relevant after-sales use case.
+
+### Diagram
+UML activity diagram to point out the flows between Retailer and Distributor
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+.....
+
+To be completed
diff --git a/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).docx b/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).docx
new file mode 100644
index 0000000..be76d33
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).md b/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).md
new file mode 100644
index 0000000..e54f72c
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/BUC-F-Pre-Trip (Services & Aftersales).md
@@ -0,0 +1,403 @@
+## Use Case Overview (draft)
+
+- **Business Use Case ID & Name:** BUC-F — Pre-Trip
+- **Goal (Objective):** The customer wants to check travel conditions and to modify his transport contract (ticket) before traveling. Or the customer wants to add offers to his trip. Or the customer is notified by the retailer that his trip has been modified by one or several operators. All other operations not directly related to a future travel are managed by BUC-J (voucher lifecycle, claims, no-show, account/support lifecycle actions, contract suspension/blacklist, ABT security invalidation, management of NFC smartcard…).
+
+> **Comment (BIGEX Olivier, 2026-05-15):**
+> Do we add here Cross-sell offers received / booked and update of the trip (addition of legs/passengers) after the initial finalization as well ?
+
+> **Comment (BIGEX Olivier, 2026-05-21):**
+> Yes. To be updated
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> I added the BUC-J to concentrate all the aftersales operations that are not in this BUC.
+> Could add a comment about that : BUC-F focuses on pre-trip servicing actions around existing transport contracts (cancel/exchange/cross-sell) and operator-initiated changes. All other after-sales types not explicitly covered here (voucher lifecycle, claims, no-show, account/support lifecycle actions, contract suspension/blacklist, ABT security invalidation, etc.) are handled in BUC-J.
+
+> **Comment (BIGEX Olivier, 2026-05-28):**
+> Ok, I had the same idea. Mention to BUC-J added.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> travel rights or documents
+
+> **Comment (BIGEX Olivier, 2026-05-28):**
+> My business language for «travel rights» is «transport contract». Let’s find the best wording in workshop.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Yes, we can align the vocabulary but the customer could want to modify his travel document without modifying the "contract" (if your contract does not include the support/media/travel document). It is the use case managed in the use case "Change before travel" in Corom report (document change process). Here, we have to decide what is managed here and what is managed in BUC-J
+
+- **Scope :** Disruption information / search of transport contract and related aftersales conditions / Upsell / Cross-sell / Release reserved facility / Cancel / Exchange / Notification of change made by the operator.
+
+> **Comment (Bourdelin, Sonia, 05/27/2026):**
+> disruption/redress end-to-end workflows and claim handling are out of scope for BUC-F and are covered in BUC-J
+> add : BUC-F focuses on pre-trip servicing actions around existing transport contracts: cancellation, exchange (including upsell), addition of offers/services (cross-sell), release of reserved facilities, and handling operator-initiated changes that impact the transport contract.
+
+## Terminology notes —
+
+Aftersales actions when available:
+- **Cancel** (1-step cancel): the transport contract (or part of it) is cancelled independently of any new wish of travel and customer who initially paid is refunded by the retailer in accordance with the fare conditions for that transport contract. In case of reservations on the original transport contract, the allocated seats/resources are released for reuse by other travellers.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> It is the travel rights that are cancelled.
+> Do you want to manage here also the cancellation of the travel document ?
+> My remark is the same for the others operation : exchange of travel rights, of travel document or both
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Refund/compensation instruments such as vouchers/credit notes, overpayment and their management are not detailed here; refer to BUC-J.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> The Distributor returns cancellation options/proposals (eligibility, fees, refundable amount) according to after-sales conditions. If reservation resources exist, their release is performed according to Distributor rules. Refund/compensation instruments are not detailed here; see BUC-D and BUC-J.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Is it part of cancellation that the contract must be pre-paid ? and the it must be refund (other possibilities ?)?
+- **Release** (2-steps cancel): before the departure the customer signals to a retailer, which is not the retailer that has done the original purchase (usually the sales office of the operator), that the allocated seats/resources may be released for reuse by other travellers. This action will preserve the fare conditions based on pre-trip conditions for subsequent assessment. It enables also the cancelation to be processed and approved after the trip, when the customer goes back to the retailer that has done the original purchase, in accordance with the fare conditions for that transport contract.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Release is covered here partially as a pre-trip operational action;
+> The end with any subsequent claim, eligibility assessment after travel, or dispute handling belongs to BUC-J.
+- **Exchange**: exchange operations (change date, time, route, or class) without requiring an independent cancelation + rebook process. For the exchange operation, the original transport contract is part of the initial context of the request for a new offer. Cancel conditions and Exchange conditions can be different. In case of reservation bound to the original transport contract, the reservation is released only when a new reservation on the new trip is secured.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> larger : facility, guarantees, ...
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Explicit that is is one customer demand with implication of 2 aftersales actions.
+> It is what will be done but in one transaction under the responsibility of who manages the exchange (retailer or distributor). The difference is who is taking the responsibility in case of failure somewhere in the process.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Do you want to manage here the travel document exchange or only the travel rights exchange, and as consequence, the exchange of travel document. Add reference to BUC-J for travle document exchange.
+- **Upsell**: kind of exchange where the travel intention is unchanged, but the customer wants to travel with higher comfort (e.g. 2nd class à 1st class in rail).
+- **Cross-sell**: addition of offers bound to the initial transport contract. Most of the time, the customer is suggested to purchase these additional offers by the retailer or the distributor or the operator. These booked offers are part of the trip.
+-
+## Actors & Context
+
+- **Primary Actors:**
+ - **Customer** (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)): has access to the real time content of his transport contract or wants to modify transport contracts (or part of them).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> and/or
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Limit here to what is managed in this BUC
+
+- **Supporting Actors / Stakeholders:**
+ - **Retailer** (FARE PRODUCT RETAILER ROLE (API consumer)): manages the search for the concerned transport contract and the related aftersales process, including the capture of customer new criteria, the aftersales flow with the distributor until the finalization of the aftersales, the refund in relationship with the PSP and the possible issuing of new travel documents. May suggest to the customer any additional offers or upgrades bound to his travel. May inform the customer that transport contracts have been changed by the operator.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> too restrictive (PSP managed in BUC-D): requests payable delta/refund amounts
+
+ - **Distributor** (FARE PRODUCT DISTRIBUTOR ROLE (API provider)): provides aftersales conditions and fare information to the retailer. Provides cancel / exchange /upsell / cross-sell offers and finalize the aftersales process or purchase of new offers process, including possible new reservations.
+- Provides an updated view of transport contracts to the retailer, including if a transport contract has been changed by the operator.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> If it is him who connects to custmer account
+
+## Preconditions & Postconditions
+
+- **Assumptions (context at start):**
+ - Depending on the architecture of the systems, the transport contract can be recorded on distributor side or underlying actors (ABT / server centric) or can be standalone (CBT / document centric).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> In urban transport, we have also a copy if the contactlesscard content on the system (in case of reconstitution, broken, ...)
+ - In case of change of the transport contract by the operator, this BUC doesn’t describe the railway’s duty imposed by the EU Passenger Rights Regulation (direct relationship between railway and traveller). What is described here is the information to the retailer by the distributor that a transport contract has been updated by the operator, and the retailer is free to use this event to notify also the customer. The important point is that based on the PRR, the operator must notify the passengers, whereas the retailer may notify the customer or any user of its front tools (e.g. retailer’s app).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Not sure it is at the right place in this BUC.
+> This BUC manages the case when the Customer (that is or not a traveler) has been informed of a change. The customer must receive the best information about change impacting his travel rights.
+ - Post-payment services are not concerned by this BUC, since no payment has been done so far in that case. The customer can change his mind without needing of doing anything.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> it is usual to request a first payment at the subscription moment
+
+> **Comment (BIGEX Olivier, 2026-05-18):**
+> Maybe still cancel the subscription of the post-payment service ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Yes, post-payment subscription cancellation and related servicing (stop mandate, settle outstanding amounts, unblock access) are not detailed in BUC-F; add a reference to BUC-J for post-payment service servicing.
+- **Preconditions (must be true before start):**
+ - Access to the distributor’s selling system is available/authorized to the retailer on behalf of the buyer.
+ - The relevant distributor(s) of the selected transport contract elements are identified.
+ - The distributor’s selling system and related pricing, guarantee, after-sales and dependency information are available (online service or accessible dataset).
+ - The customer has got a transport contract, issued as travel document.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> with or not relevant travel document(s)
+ - The customer is in possession of the travel documents, or the travel document can be retrieved from a customer account.
+
+> **Comment (Bourdelin, Sonia, 05/27/2026):**
+> In some cases, the travel document is issued only few days before he travel. The request here can be done before the issuing of the travel document;
+> In some cases, there is no document fulfilment (EMV)
+
+- **Postconditions — Success guarantees:**
+ - Cancel: the transport contracts are no longer active and cannot be used anymore. The seats/resources have been released. According to aftersales condition, the customer can be fully or partially refunded by the retailer. The settlement process will take this cancellation into account.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> or not
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> BUC-K
+ - Exchange (including upsell): the initial transport contracts are no longer active and cannot be used anymore. They have been replaced by new transport contracts, and the customer has received new travel documents. The initial seats/resources can have been released and replaced by new seats/resources assignment (if available). According to aftersales condition and to the payment balanced, the customer can be partially refunded by the retailer (negative balance) or must pay a supplement (positive balance). The settlement process will take this exchange into account.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> if required, updated
+ - Cross-sell: one or several new offers has been booked (including reservations is available) and fulfilled and are part of the customer’s initial travel.
+ - Change by the operator: the retailer is informed of the change of the transport contract and makes this information available to the customer.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> if it is relevant and according to customer rights
+
+- **Postconditions — Minimal guarantees:**
+ - If the customer abandons the process of Cancel/Exchange/Cross-sell or no suitable solution is found or no Cancel/Exchange can be done (not cancellable / not exchangeable), the initial transport contracts remain unchanged and valid. In case of reservations, they have not been released.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> depends...
+ - Depending on aftersales conditions, the exchange request can be rejected in case of substitutions that change the departure stop
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> it is an example of failure of the exchange. Can happen for many reasons
+-
+
+## Scenarios
+
+### Main scenario
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Add a precision : Primary object serviced here is the transport contract (travel rights). Travel documents may need to be re-issued/updated/invalidated as a consequence, according to Distributor rules and fulfilment processes (see BUC-E / BUC-J where applicable).
+
+- **Search for a transport contract**
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> The aftersales can be done on travel document also. Precise that here which case we manage
+- The customer consults his available transport contracts.
+ - The customer can show his travel documents to the retailer so that the retailer can read its content (barcode reader, NFC reader, direct entry by visual reading of the ticket media…) and collect references of the transport contracts and related retailer’s order and distributor’s booking. If the customer is connected to a customer account and if the initial purchase has been made by this retailer, this information can be directly retrieved in it.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Explicit if the retailer is the one who did the sale or another : can be both cases
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> If the sale has been done by another operator/retailer, the retailer only sees the data required for aftersales conditions application, not all the purchases, contracts history, ...
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> particular case : delegated rights to the retailer to connect to customer account (the customer account can be on the retailer system, on the distributor system or on a third-party system)
+> But how connexion to customer account is done is out of our scope.
+ - Optionally, based on one single travel document, if the retailer has managed an order, then it can collect the references of all multi-distributor fare contracts (and related bookings) of the trip.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> In anonymous case, the majority in urban transport
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> rights ?, authorizations ?
+> the retailer need at least keys to read the card or request the system (ABT) : security management
+ - Based on these references, the retailer requests the distributor to retrieve (if allowed) detailed information on the transport contract and on all transport contracts of the booking on distributor’s side, including aftersales conditions based on their current status.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> to reformulate : it is the aftersales conditions status known by the distributor ? But in media base system, it is the status of the contract on the media that is taken into account
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> depends on the architecture
+ - In case of change of a transport contract initiates by the (change of the vehicle configuration, planned route substitution, cancellation of the service journey…), the information about this change is made available to the retailer. It could be an update of the transport contract (e.g. update of the seat/resource assignment) or a new ticket transport contract which replaces the initial one. The customer can reissue his travel document with updated content. Depending to the reason of the change and the sales conditions, the customer can request a cancellation or exchange of the transport contract with bypass of the aftersales conditions.
+
+> **Comment (Bourdelin, Sonia, 05/27/2026):**
+> It is a second entry point of the use case. Not a d. point in contract search. Put this chapter at a highest level as a second trigger of the BUC.
+> Please clarify with assumptions and PRR
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> "operator" I suppose ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> and sometimes directly to the customer (mobile applicaition)
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> automatically proposed by R or D and with or without required C acceptance
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> if required
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> includes the reason of the change I think
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> may choose between different options. cancellation or exchange are managed in this BUC. Others are managed in BUC-J
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Unsupervised / mid-supervised aftersles operation are only done by authorized agents. Everything else is scheduled and parametrized.
+- Based on search transport contracts, the customer can:
+ - Stop the BUC here.
+ - Request a cancellation.
+ - Request an exchange.
+ - Add new offers to his travel.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> e. all possibilities manages in BUC-J
+
+- **Cancellation**
+- The customer requests a cancellation of all his trip, or of a part of it (selection of transport contracts, legs, passengers, services).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Do we cancel a whole or part of the pattern or also services, facilities, ...? Please clarify and we will manage what is not done here in BUC-J
+ - After having requested all concerned distributors, the retailer shows to the customer offers for cancellation, including price for refund and possible fees.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> It is not exactly in this way we use 'offer' in the project. Could you change by 'proposals', or another word ?
+ - The retailer can apply authorisation codes ('overrule codes') that waive or reduce fees for cancellation. It is up to the distributor to accept them or not.
+
+> **Comment (Bourdelin, Sonia, 05/27/2026):**
+> Please put the steps in the temporal order : add a step where the retailer request for the distributor for the cancellation conditions deleguated (to the retailer)
+> Add precision if the authorization is/must be requested in real-time (additional step) and if there is an overrule
+ - The customer is informed if transport contract cannot be partially cancelled.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Enlarge : cancellation possibilities : full, partila , not allowed, with fees, ..
+ - The customer is informed of all applicable rules of cancellation in full and in plain language so the customer can make an informed decision.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> c and d are the same step ? or it is done with 2 different ways and steps ?
+ - The customer confirms the cancellation. If the transport contracts are stored in system, they are cancelled by the concerned distributors, and the travel documents are useless (can be destroyed if disposable). If the transport contracts are stored in an NFC smartcard, the card content must be successfully updated on an eligible device. If the transport contracts are stored on secured (paper) travel documents, the travel documents must be returned to the retailer.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> confirms he wants to cancel
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Not of the travel document can be used for many contracts (ABt achitecture or contactless card with more than 1 contract)
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> MAny solutions depending on the D policy (see my comment below about travel document updates)
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> If it happens (the card is caught by a validator) but not necessary
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> or not
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Given examples help to understand but we need a global sentence : NFC, device are too restrictive : proof, reference, retieval method, travle document,...
+ - Depending on the cancellation balance and retailer’s fees, the customer is refunded.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> We should manage somewhere a 'refund' chapter : in BUC-D in alternatives scenario of payment ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> by the retailer
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Clarify between the customer desire (cancel trip) and the many ways of manage it by the retailer and the consequences (refund, ...). In most cases, it lets to a refund but can be many others consequences (voucher, redirect to Exchange, nothing happen, the group has a traveller less, my invoice will be recreased at th end of the month, ..
+ - The settlement process will take this cancellation into account (see next BUC).
+
+- **Exchange**
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> For the EUDIT project, it could be interesting to split a in basic actions : an exchange is : 1 - a search with criteria / 2- a new reservation / 3- a cancellation / 4 - payment management / 5 - confirmation of the full transaction / 6- fulfilment of travel rights and if necessary travel document. It will help us to identify
+- The customer requests an exchange of all his trip, or of a part of it (selection of transport contracts, legs, passengers, services). The exchange can be a reduction or addition of passengers, a change of trip (date, requested departure/arrival time, legs) or a change of level of comfort (potentially suggested by the retailer or the distributor).
+ - The customer follows BUC-A, except that the initial transport contract(s) are part of the context of the offer request.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> and critria for exchange are given : remain on same leg, same level of confort, same price, etc .... The seach engine must have which can be enlarged and which must be kept as a criteria.
+ - The retailer can apply authorisation codes ('overrule codes') that waive or reduce fees for exchange. It is up to the distributor to accept them or not.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Can you detail more the interactions between retailer and distributor as it si our subject in EUDIT ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> 2 cases : the retailer manages the exchange as the new solution is from another operator (in France from Paris to Marseille, with Trainline, you can change from SNCF to Renfe)
+> Or it is the distributor that manages the exchange as it is guaranteed is after sales conditions.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> two responsibility models
+ - The customer is informed of all applicable rules of exchange in full and in plain language so the customer can make an informed decision.
+ - The customer selects and confirms an exchange offer (BUC-C). The initial reservation(s) are released once the exchange confirmation is successful.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Confirmation is done in a second time : first the customer select a solution / the retailer-distributor tries to do it / the customer confirm with payment (zero, refund => see refund use case, new payment => BUC-D)
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> Please detail the interactions between R and D and in the 2 cases (who manages the exhcnage)
+ - Depending on the exchange balance and retailer’s fees, the customer can be partially refunded or must pay the difference (BUC-D).
+ - The costumer gets new transport contract(s) with travel document(s) (BUC E). If the initial transport contracts are stored in system, they are cancelled by the concerned distributors, and the initial travel documents are useless (can be destroyed if disposable). If the initial transport contracts are stored in an NFC smartcard, the card content must be successfully updated on an eligible device. If the initial transport contracts are stored on secured (paper) travel documents, the initial travel documents must be returned to the retailer.
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> can be or not (in Account base solution, change is done on the system, not on the document/ticket/QRCode)
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> add :on the retailer request
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> or erased (QRcode) or returned (smartcard) or others ways ... following ditributor policy
+
+> **Comment (Bourdelin, Sonia, 05/27/2026):**
+> UX dependant, too restrictive
+> Enlarge the travel document management with at least the 3 cases I see : the document embed the travel rights => must be updated (immediately, delayed) / the document security must be updated (key with validity period by example) / the travel document doesn't need to be updated (ABT architecture). It can be sum up with : the D informs the R with the travel document needs for update or change (or nothing).
+> After, the updates can be done by the retailer, by the distributor or by a third party (operator on validator equipement)
+ - The settlement process will take this exchange into account (see next BUC).
+-
+- **Addition of new offers**
+- The customer requests the addition of offers to his trip
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> offer(s) or service or ancilliary, ... to his contract
+ - The customer follows BUC-A, except that the initial transport contract(s) can be part of the context of the offer request (not mandatory, depending of the cross-sell product: adding an urban ticket is independent of any existing transport contract, whereas adding a seat reservation or a large luggage is bound to the initial admission).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> commercial agreements between distributor(s) and retailer(s). The dependencies between offers can be part of the D data sent to R (commercial profil required, etc ..). But it could be (urban transport) the distributor that calculates the cohabitation rules and the dependencies and the final acceptance (or not) of the new offer
+ - The distributor can apply support automatic journey continuation (AJC), re-pricing a journey when a customer extends travel beyond the originally booked destination. In that case, new transport contracts can concern the new offer and initial transport contracts.
+ - The customer selects, confirms new offer(s) (BUC-C) and pays (BUC-D).
+ - The costumer gets new transport contract(s) with travel document(s) (BUC E).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> or updated
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> relevant
+ - The new booked offers are included in the initial trip (depending of the booked offers, the aggregation is done by the retailer or the distributor).
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> or not in the initial contract
+
+> **Comment (Bourdelin, Sonia, 2026-05-27):**
+> refers to BUC-E for fulfilment
+ - The settlement process will take this exchange into account (see next BUC).
+
+### Alternatives scenarios
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Can we manage additional alternatives cases or integrate it in the main scenario ?
+> - Partial cancellation not allowed / constrained
+> - Cancellation or exchange requires revalidation because of time limits
+> - Exchange rejected after attempt : the retailer has to manage the failure and to restart a exchange process
+> - Multiple distributors in one trip: mixed outcomes
+Independent alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+- **Simple CBT / document centric ticket withaftersales conditions included in shared dataset**
+- After having retrieved transport contract information by reading the travel document, the retailer can inform directly the customer about aftersales conditions based on shared dataset of products. Then the customer can proceed to the Cancel/Exchange request, without asking the distributor previously for aftersales conditions on this transport contract.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Even if it is the retailer that does the exchange directly, he has been informed and authorized previously. In any case, the retailer knows the aftersales conditions but can receive this information in real-time or asynchroneously
+
+- **Release resources before departure**
+- before the departure the customer signals to a retailer, which is not the retailer that has done the original purchase (usually the sales office of the operator), that allocated seats/resources for a transport contract may be released for reuse by other travellers, because he no longer wishes to travel.
+- The customer is informed of all applicable rules of release offers in full and in plain language so the customer can make an informed decision.
+- The retailer notifies the distributor of this first step of a cancelation for this transport contract, which is no longer usable for travel, without confirming the cancellation.
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> + ressource release
+- The retailer informs the costumer that he must finalize the cancellation with his initial retailer to be refunded.
+- The customer goes back to the retailer that has done the initial purchase to confirm the cancellation and being refunded (see the end of a normal cancellation BUC-F-3-c).
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> one possibility among many
+
+- **Asynchronous cancellation**
+- In case of cancellation, the distributor can choose to delay the cancellation confirmation to the retailer (e.g. needs time to check if the contract has not been consumed).
+
+> **Comment (Bourdelin, Sonia, 2026-05-28):**
+> Yes, by example for contracts with amount to pay based on taps collection
+> True for many aftersales actions for this type of contract
+- The retailer is informed later by the distributor that the cancellation is confirmed and that the customer can be refunded.
+
+### Diagram
+UML activity diagram to point out the flows between Retailer and Distributor
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+.....
+
+To be completed
diff --git a/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).docx b/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).docx
new file mode 100644
index 0000000..0abf4f4
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).md b/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).md
new file mode 100644
index 0000000..08a76c1
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/BUC-J-After-Trip (Aftersales & Claims).md
@@ -0,0 +1,102 @@
+## Use Case Overview (draft)
+
+- **Business Use Case ID & Name:** BUC-J— Aftersales servicing and claims (non-covered by BUC-F)
+- **Goal (Objective):** Enable the Customer (or an assisted agent (Retailer)) to handle after-sales servicing cases that are not covered in BUC-F, including voucher/credit lifecycle, claims and disputes, no-show, and urban transport lifecycle operations on customer accounts, media/supports and contracts.
+- **Scope:** This BUC covers after-sales servicing actions that:
+- are triggered after purchase or before/after travel,
+- do not fit the pre-trip cancel/exchange/cross-sell flows of BUC-F,
+- require specific servicing processes (vouchers/credits, disputes/claims, no-show, security lists, lifecycle management of supports and contracts).
+
+
+## Terminology note —
+Optionnal – Business conceopts + Transmodel concepts (existintg, new, proposed) used in this BUC
+
+## Actors & Context
+
+- **Primary Actors:**
+ - **Customer (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** can identify the relevant item(s) concerned by the request (e.g., contract identifier, travel document, voucher reference, customer account, medium/support ID).
+
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)) :** captures the request, orchestrates servicing, consolidates responses and provides customer-facing information.
+-
+ - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)) :** validate eligibility, apply servicing rules and confirm business outcomes for their products/contracts.
+-
+
+## Preconditions & Postconditions
+
+- **Assumptions & Preconditions (must be true before start):**
+ - The Customer can identify the relevant item(s) concerned by the request (e.g., contract identifier, travel document, voucher reference, customer account, medium/support ID).
+ - The Retailer has authorised access to the relevant Distributor servicing capabilities.
+-
+
+- **Postconditions — Success guarantees:**
+ - The requested servicing action is completed or clearly rejected with reasons and next actions (refresh, provide missing data, contact responsible party).
+ - Where applicable, the corresponding object status is updated (voucher balance/status, contract state, support state, customer account linkage).
+
+- **Postconditions — Minimal guarantees:**
+ - What can be tested at least at the end (when everything goes wrong ) ?
+
+## Scenarios
+
+### Main scenario
+The main scenario of BUC-J is the selection and execution of one of the servicing use cases below.
+Hand-offs (references to other BUC)
+- Payment execution and payment-side constraints remain in BUC-D when a servicing case requires a new payment or a payment adjustment.
+- Settlement/reconciliation details remain in BUC-K where accounting allocation is required.
+- Fulfilment / issuance of updated travel documents remains in BUC-E when servicing produces new travel rights/documents.
+
+A) Voucher / credit / residual value servicing
+1. Voucher validation and eligibility check (value, status, eligible scope) before use.
+2. Apply voucher as a payment instrument; handle partial applicability and per-distributor eligibility.
+3. Residual value handling when voucher exceeds eligible amount:
+ - issue a new/updated voucher or credit,
+ - treat residual as a separate eligible item (when supported),
+ - record residual as an overpayment (“trop-perçu”) for later reconciliation/crediting.
+4. Voucher issuance / update / cancellation after servicing outcomes (e.g., refund-to-voucher, goodwill credit).
+
+B) Claims, disputes, passenger rights servicing
+5. Create and manage a customer claim/dispute (service incident, eligibility disagreement, “consumed vs not consumed”, amount contested).
+6. Provide “who to contact / servicing responsibility” information per leg/operator/contract.
+7. Support evidence collection and status tracking (decision pending, accepted, rejected, additional info required).
+8. Compensation decision outcomes (operator decision), including form of compensation (voucher/credit/other).
+
+C) No-show and post-trip entitlement consequences
+9. Handle no-show status and its consequences according to after-sales conditions (fees, loss of right, partial refund eligibility).
+10. Handle “release then assess after travel” outcomes (where release was done pre-trip and eligibility is evaluated post-trip).
+
+D) Customer account servicing
+11. Customer account closure request (data suppression/retention rules + suspension of associated contracts).
+12. Detach / attach a medium/support to another customer account.
+
+E) Medium / support servicing (urban transport)
+13. Renewal of a medium/support (new medium issued, same data/identifiers re-associated).
+14. Reconstitution after damage (restore encoded rights and associated access rights).
+15. Blacklisting of a medium/support (lost/stolen/compromised).
+16. Return / restitution of a medium/support and deposit handling.
+17. ABT medium invalidation (security key revoked; medium cannot be used again).
+18. Update encoded data on a medium/support (user type change, social status update).
+19. Lock/unlock of a digital credential or application instance (as defined in your glossary).
+
+F) Contract / access-right servicing (urban transport)
+20. Contract suspension list management (temporary / definitive / periodic).
+21. Regularisation of unpaid instalment and unblocking of the contract.
+22. Removal from “contracts to unblock” list once the blocking cause is resolved.
+23. Blacklisting of a contract/access right.
+24. Terminate a direct-debit subscription contract (stop payment terms and prevent further use as per rules).
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+##### Title
+1. Step 1
+2. The ....
+
+### Diagram
+UML activity diagram to point out the flows between Retailer and Distributor
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+.....
+
+To be completed
diff --git a/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.docx b/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.docx
new file mode 100644
index 0000000..5236d7d
Binary files /dev/null and b/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.docx differ
diff --git a/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.md b/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.md
new file mode 100644
index 0000000..a431887
--- /dev/null
+++ b/wiki/use-cases/business-use-cases/BUC-LETTER-main-feature-TEMPLATE.md
@@ -0,0 +1,63 @@
+## Use Case Overview (draft)
+
+- **Business Use Case ID & Name:** BUC-LETTER — MAIN feature
+- **Goal (Objective):** What the customer wants to do
+- **Scope:** All things done in this BUC
+
+## Terminology note —
+Optionnal – Business conceopts + Transmodel concepts (existintg, new, proposed) used in this BUC
+
+## Actors & Context
+
+- **Primary Actors:**
+ - **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** what is doing here
+
+- **Supporting Actors / Stakeholders:**
+ - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** what is doing here
+-
+ - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** what is doing here
+-
+
+- **Assumptions (context at start):**
+ - What is set up at the beginning ?
+
+## Preconditions & Postconditions
+
+- **Preconditions (must be true before start):**
+ - Hypothesis
+-
+
+- **Postconditions — Success guarantees:**
+ - What can be tested as true at the end in happy case ?
+
+- **Postconditions — Minimal guarantees:**
+ - What can be tested at least at the end (when everything goes wrong ) ?
+
+## Scenarios
+
+### Main scenario
+1. From where we start
+
+- **Step 1**
+2.
+....
+- **Last step**
+....
+28. Last thing to do
+
+### Alternatives scenarios
+Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
+
+##### Title
+1. Step 1
+2. The ....
+
+### Diagram
+UML activity diagram to point out the flows between Retailer and Distributor
+
+### Links with inputs
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+
+.....
+
+To be completed
diff --git a/wiki/use-cases/business-use-cases/buc-a-inspire-and-plan.md b/wiki/use-cases/business-use-cases/buc-a-inspire-and-plan.md
index 8610046..4f32a46 100644
--- a/wiki/use-cases/business-use-cases/buc-a-inspire-and-plan.md
+++ b/wiki/use-cases/business-use-cases/buc-a-inspire-and-plan.md
@@ -1,117 +1,148 @@
-
+In review – version 3
## Use Case Overview
+- **Business Use Case ID & Name:** BUC-A — Plan your trip by providing your selection criteria and choose the most suitable offer
+- **Goal (Objective):** Enable the traveller (or an assisted agent) to define clear selection criteria and then to choose the most suitable travel offer, with transparent pricing, sales conditions (exchange/refund rules) and travel guarantees.
+- **Scope (Summary) :**
+ - Capture the traveller’s **selection criteria** (modes, route preference, flexibility level, passenger needs).
+ - Retrieve and present **matching options**.
+ - Let the traveller **filter/compare** options.
+ - Provide **price** (indicative or final as needed).
+ - Show clearly: **sales conditions** (exchange/refund rules) **separately from travel guarantees**.
+ - Output: a **chosen option or shortlist**, or “no matching offer”. Offer discovery (journey planner proposals) / catalogue consultation (FARE PRODUCT catalogue) / PRICE calculation / CUSTOMER PURCHASE PACKAGE constitution
-- **Business Use Case ID & Name:** BUC-A — Plan your trip and choose your means of travel and/or your FARE PRODUCT
-- **Goal (Objective):** Enable the Transport Customer to select the most suitable mobility offer (transport mode, product, package, price, and guarantees) for his TRAVEL.
-- **Scope:** Offer discovery (journey planner proposals) / catalogue consultation (FARE PRODUCT catalogue) / PRICE calculation / CUSTOMER OFFER PACKAGE constitution
----
+## Roles (schema in Roles for Business Use cases_v1.pptx )
-## Actors & Context
+
-- **Primary Actor:** **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** needs to purchase products suited to his travel needs. He can be the manager of a group, a PRM, the purchaser for a minor traveler or other with specific needs or none.
-- **Supporting Actors / Stakeholders:**
- - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** supports the customer and initiates catalogue consultation.
- - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** provides the FARE PRODUCT catalogue, prices, availability, and guarantees.
+## Terminology notes —
+**Catalogue**: a customer-context proposal with a price, conditions and guarantees (not a list of individual products). In Transmodel terms, this corresponds to a (CUSTOMER OFFER PACKAGE), traceable to underlying components such as (FARE PRODUCT(s)) / (SALES OFFER PACKAGE(s)) when relevant.
-- **Assumptions (context at start):**
- - The retailer is authorised to consult the distributor’s FARE PRODUCT catalogue.
- - The catalogue and related pricing/guarantee information are available (online service or accessible dataset).
- - The TRANSPORT CUSTOMER can provide the additional information required to compute/confirm the best offer.
+**Fare calculator / pricing engine** (implementation note): In this document, “fare calculator” refers to an implementation component (often on the Distributor side) used to compute prices based on route and Customer parameters. It is not a standardised EUDIT component. In the EUDIT scope, the Retailer requests priced offers and the Distributor returns the priced offer options (price, conditions, and availability where applicable), regardless of the internal pricing engine used.
----
+**Offer**: a customer-context proposal with a price, conditions and guarantees (not a list of individual products). In Transmodel terms, this corresponds to a (CUSTOMER OFFER PACKAGE), traceable to underlying components such as (FARE PRODUCT(s)) / (SALES OFFER PACKAGE(s)) when relevant.
-## Preconditions & Postconditions
+**Travel guarantees** (aligning the wording with the Passenger Rights Regulations (PRR): Travel guarantees include the passenger-rights-related commitments applicable to the offer (e.g. re-routing/assistance/compensation principles when relevant), as well as any additional commercial guarantees provided by the Distributor/Retailer. The detailed legal obligations and jurisdiction-specific rules remain out of scope here; this BUC only requires that the applicable guarantees are made visible and selectable/comparable at offer selection time.
-- **Preconditions (must be true before start):**
- - Access to the distributor’s FARE PRODUCT catalogues is available to the retailer and/or TRANSPORT CUSTOMER.
- - The relevant catalogue (for the distributor/network/area) is identified.
- - Basic travel intent is known (at minimum: the customer wants to travel; optionally: zone/route/date/passenger profile).
+> **Comment (Bourdelin, Sonia, 2026-05-29):**
+> TO REVIEW
-- **Postconditions — Success guarantees:**
- - One or more candidate offers are identified, including:
- - selected **FARE PRODUCT(s)** and **SALES OFFER PACKAGE(s)** (if applicable)
- - the associated **Price**
- - applicable **TRAVEL GUARANTEEs and aftersales conditions**
- - **availability** information (where applicable)
- - The selected option (or shortlist) is available for the next step (e.g., purchase/booking).
+## Actors & Context
+- **Context**: This use case describes **the pre-purchase offer discovery** phase for ground transport. It focuses on how a **Retailer** helps a **Customer /Traveller** identify suitable travel options by interacting with one or more **Distributors/Operators** and presenting comparable results. It does **not describe the retailer’s end-customer user interface** in detail, and it does **not cover non-ground content** such as flights, hotels or car rental.
+- **Primary Actor: Customer** (end customer) (TRANSPORT CUSTOMER ROLE and PURCHASER ROLE**) :** the person who expresses the needs and makes choices to purchase offers suited to travel needs. He can act for one or several Travellers (be the manager of a group, a PRM, the purchaser for a minor traveller or other with specific needs or none). The Customer may also be the traveller (i.e. the person who will actually travel and use the entitlement) (PASSENGER ROLE).
+- **Supporting Actors:**
+ - **Retailer (**FARE PRODUCT RETAILER ROLE) (API consumer): supports the Customer queries, initiates catalogue consultation, aggregates and presents options and support comparison (ranking / filtering). See Role schema: orange rectangle on the right)
+ - **Distributor** (FARE PRODUCT DISTRIBUTOR ROLE) (API provider): provides the data and content to build timetable, fare catalogue, prices, availabilities, and guarantees.
+## Preconditions & Postconditions
+- **Assumptions and Preconditions (must be true before start):**
+ - Commercial agreements are in place: Access to the Distributor’s catalogues are available to the Retailer. Some offers may be restricted.
+ - The relevant content (for the distributor/network/area) sources are identified: the Retailer can determine which Distributor(s) to query for the requested trip (this may involve one or several sources depending on the journey).
+ - The catalogue exists and is available as a pre-loaded/static reference dataset; availability and final price confirmation (when required) are performed through the responsible Distributor systems.
+ - The Customer/Traveller can provide the minimum additional information required to propose relevant options (e.g. origin/destination or travel area, timing/frequency, passenger profile/eligibility, preferences) the best offer
+ - Basic travel intent is known (at minimum: the customer wants to travel; optionally: zone/route/date/passenger profile), focused on ground-transport distribution.
+ - **T**hird-party products may be included only when they are distributed through the same Distributor(s) in scope (i.e. provided as part of the Distributor’s content/offers). Third-party products delivered outside that distribution scope are not covered here.
+- **Postconditions — Success guarantees:**
+ - The Customer receives one or more candidate offers proposed by the Retailer and sourced from one or more Distributors (shortlist: CUSTOMER OFFER PACKAGE(s)).
+ - For each candidate offer, the Customer can see:
+ - offer content and his packaging (FARE PRODUCT(s), SALES OFFER PACKAGE(s))
+ - the associated price (PRICE), including any purchase validity/time limit.
+ - applicable travel guarantees (TRAVEL GUARANTEE(s)),
+ - the applicable conditions, including:
+ - validity constraints (e.g. zone, time window),
+ - eligibility requirements (e.g. reduction card, corporate entitlement),
+ - combination/combinability rules (e.g. outward must be part of a return trip),
+ - and after-sales conditions (exchange/refund/cancellation). (VALIDITY CONDITION(s), ENTITLEMENT(s), OFFER RULE(s), USAGE PARAMETER(s): EXCHANGING / REFUNDING / CANCELLING),
+ - availability information (where applicable) (e.g. mandatory reservation, remaining capacity). (AVAILABILITY CONDITION)
+ - The Customer selects a preferred offer or many (or shortlist of offers; available for the next step (e.g., purchase/booking) ().
- **Postconditions — Minimal guarantees:**
- - If no suitable solution is found, the customer receives a clear “no matching offer” outcome (with a reason where possible).
- - The consultation outcome can be logged/audited (if required by the system).
-
----
+ - If no suitable solution is found, the Customer receives a clear “no matching offer” outcome (with a reason where possible).
+ - If no suitable solution is found, the Retailer or Distributor may provide alternative offers.
## Scenarios
-
### Main scenario
-- **Retrieving product list**
-1. The TRANSPORT CUSTOMER is planning his TRAVEL, which can be composed of one or more TRIPs, each consisting of one or more LEGs. He wants to go from TRIP ORIGIN PLACE to his TRIP DESTINATION PLACE using public transport and, optionally, return to the origin PLACE (can be a POINT, a SECTION or a ZONE).
-
-2. The TRANSPORT CUSTOMER may or may not connect to a CUSTOMER ACCOUNT on a digital platform. The TRANSPORT CUSTOMER may (if he wishes) prove eligibility for a particular USER PROFILE (under 25 years old, PRM indications, corporate participation). The TRANSPORT CUSTOMER can apply for a particular COMMERCIAL PROFILE. He can have his USER PROFILE(s) and/or COMMERCIAL PROFILE(s) already registered with his CUSTOMER ACCOUNT. He may wish to use specific features of his CUSTOMER ACCOUNT (TRAVEL DOCUMENTs, reduction cards, entitlements, vehicle plate, driving licence).
-
-3.
- a. **If the TRAVEL is complex** (multi-LEGs, multi-TRIPs), and/or if the TRANSPORT CUSTOMER does not know how to make his travel, he can use a journey planner whether or not it is populated with the information from CUSTOMER ACCOUNT. It gives one or more results with detailed TRIP PATTERNs: schedule, transport mode, lines, stops, and connections.
- b. The journey planner can be associated with a fare calculator: the TRANSPORT CUSTOMER can provide required details on travellers (date of birth, name, reduction cards, disabilities, PRM services needed, companion, bike spot) or remain, by default, with a basic COMMERCIAL PROFILE (anonymous adult - for only one trip - without reduction). The TRANSPORT CUSTOMER can indicate that he wants to include THIRD-PARTY PRODUCT in the solution (example: museum entry)
- c. At least, the TRANSPORT CUSTOMER has a web link to the website of each distributor on each LEG/JOURNEY to browse their catalogue (equivalent to the next step).
- d. If available, a fare calculator can provide FARE PRODUCTs that are suitable for the TRIP(s), from one basic solution on each origin-destination LEG (default values used like : "for today", "anonymous", "single-trip ticket on the network") to many more elaborate solutions (for the travel specified day, combined ticket, multimodal offers, with reduction and guarantees, including passes already purchased). The availability of some assets or mandatory reservations can also be displayed.
- e. The retailer can manage the displayed results with additional indicators, ranking, filtering (operator, line, categories, product name), comparing: price, duration, number of interchanges, mode mix, GHG/CO₂ impact, comfort, accessibility or operator.
-
-5.
- a. **If the TRAVEL is easy to plan**, the TRANSPORT CUSTOMER can browse a digital platform, go to a travel agency, a distributor desk, or a ticket vending machine in a station to choose mobility tickets. He wants to choose by himself between tickets, choosing himself the transport modes and the prices he is willing to pay. He can also include THIRD-PARTY PRODUCTs in his search.
- b. Either the TRANSPORT CUSTOMER or the retailer on behalf of the TRANSPORT CUSTOMER starts the catalogue consultation. The retailer browses the catalogue to retrieve an initial set of candidate FARE PRODUCT(s) and SALES OFFER PACKAGE(s). This catalogue can be statically built with an aggregation and rework of one or many distributor catalogues, themselves built based on fare owner catalogues. This catalogue can be partially or totally dynamically built using real-time requests to distributors.
- c. The TRANSPORT CUSTOMER reviews the initial results and may filter or order the results. If he cannot finalise his selection, he can refine the catalogue to narrow the displayed FARE PRODUCT(s) and SALES OFFER PACKAGE(s) according to the consultation context and the data he provides (new or modified data and/or data coming from journey planner requirements).
+- **Express the need**
+1. The Customer is planning the travel (TRAVEL), which can be composed of one or more trips (TRIP(s)), each consisting of one or more legs (LEG(s)). The Customer wants to travel from an origin place (TRIP ORIGIN PLACE) to his destination place (TRIP DESTINATION PLACE) using public transport and, optionally, return to the origin place (PLACE can be a POINT, a SECTION or a ZONE). Any discontinuities (‘gaps’) between trips are not managed by this BUC by default; however, a Distributor may propose an end-to-end offer and/or a connection protection mechanism to cover such gaps (e.g. a combined offer or a travel guarantee for connections), in which case it is presented as part of the returned offer. The Customer provides selection criteria to the Retailer (for one or several Traveller**(s)**): timing/frequency, preferred modes, route preference (fastest/cheapest/greener), flexibility level (refund/exchange constraints), accessibility needs, and any other criteria needed to identify relevant options.
+2. The Customer may or may not connect to a customer account (CUSTOMER ACCOUNT) on digital platform of the Retailer, of a Distributor or another party. The Customer may request or prove eligibility for a particular passenger profile (USER PROFILE) (under 25 years old, PRM indications, corporate participation, companion, bike spot). The Customer may apply for a particular commercial profile (COMMERCIAL PROFILE). Relevant eligibility elements may already be registered or may be provided during the consultation (transport card, reduction cards, entitlements, vehicle plate, driving licence). The Customer can indicate that he wants to include associated offer (THIRD-PARTY PRODUCT) in the solution (example: museum entry)
+- **Select the right content sources**
+3. The Retailer determines which Distributor**(s)** to query (one or many), according to coverage (network/area/operators/commercial brand) and commercial/access rules. The Retailer then requests content to retrieve an initial set of candidate options.
-- **Asking for product-based offers**
-5. One or more times, the TRANSPORT CUSTOMER selects one candidate SALES OFFER PACKAGE of one or more distributors (multiple transport modes, multiple operators). He requests details so that he can consult the detailed contents, conditions, guarantees, and optional parts of the selected SALES OFFER PACKAGE. This consultation can be done for more than one SALES OFFER PACKAGE at the same time, as long as they can be displayed on the same screen at the same time.
+> **Comment (Bourdelin, Sonia, 2026-05-29):**
+> Ok
-6. If the selected SALES OFFER PACKAGE is not yet fully defined, the TRANSPORT CUSTOMER enters additional customer parameters by providing the required information, such as the traveller profile, eligibility, accessibility needs, class, date, zone, quantity, or extras. Once the required information is filled in, the retailer checks the entries and provides a price with the applicable commercial and travel conditions (aftersales including exchange or refund, specific restrictions, guarantees, passenger rights) for the selected SALES OFFER PACKAGE. It may be composed of several products.
+- **Retrieve candidate offers (two entry points)**
+Depending on the context, the Retailer may obtain candidate options through two entry points (the orchestration is the same; only the starting input differs):
+4. **Trip-based entry (journey planner result as input)**
+- When the travel is not straightforward or if the Customer does not know how to make his travel or wants route suggestions, he can use a journey planner to compute possible routes and connections whether or not it is populated with the information from an account (CUSTOMER ACCOUNT), such as passenger profile attributes (e.g. age band), eligibility/entitlements (e.g. reduction rights, corporate profile), accessibility needs, preferred fulfilment medium (when it impacts eligibility), and party composition (number and type of travellers). It gives one or more results with details: schedule, transport modes, lines, stops, and connections (TRIP PATTERN(s)).
-7.
- a. If this PRICE is an indicative price depending on mandatory reservation (for example, a seat), or if the TRANSPORT CUSTOMER wishes to check availability and the system allows it, the TRANSPORT CUSTOMER checks availability and, on some distributor's systems, may start the reservation process: the retailer checks availability and may start a temporary hold for the selected SALES OFFER PACKAGE.
- b. If the final price is a yield price, at this moment, the retailer requests a final price (valid for a limited period)
- c. If availability is also confirmed, the retailer retrieves the final price and returns it with the final conditions for the selected SALES OFFER PACKAGE.
-
-- **Selection of offers**
+- The journey planner may be associated with a fare calculator based on the selected route(s) and the Customer/Traveller parameters, the fare calculator returns priced offer/options for that route (PASSENGER FARE OPTION) (from basic default assumptions to more tailored results using eligibility, reductions, accessibility needs, corporate traveller profile/entitlements (when applicable), loyalty attributes (when applicable) and guarantees (TRAVEL GUARANTEE(s)). It may also indicate any availability constraints when relevant (AVAILABILITY CONDITION) (combined ticket, multimodal offers, with reduction and guarantees, including passes already purchased) and may display availability of some assets or mandatory reservations.
+
+- If the journey planner is not associated with a fare calculator, the Customer may be provided with a fallback to continue outside EUDIT (for example, redirecting the Customer to an external sales channel for the relevant segment), which is equivalent to the catalogue-based entry but outside the EUDIT flow.
+
+
+5. **Catalogue-based entry (catalogue browsing as input)**
+Catalogue consultation is a Retailer/Distributor sourcing mechanism used to retrieve candidate offers; it does not imply that the Customer is manually selecting individual fare products.
+- The Customer can browse one or more catalogues on a digital platform, go to a travel agency, a distributor desk, a ticket vending machine in a station or any distribution channel to request and compare offers proposed by the Retailer. The Customer may express preferences (e.g. mode, comfort, flexibility), but the Retailer presents priced offers returned by Distributor(s), and the Customer selects among those offers. He wants to choose by himself between offers, choosing himself the transport modes and the prices he is willing to pay. He can also include additional offers (THIRD-PARTY PRODUCTs) in his search when they are distributed through the same Distributor(s).
+
+- Either the Customer or the Retailer on behalf of the Customer ask the Retailer for offers matching their criteria. The Retailer browses one or more catalogue to retrieve an initial set of candidate offers and presents an initial list. This catalogue exists as a reference static dataset (which may result from aggregation and harmonisation of one or more Distributor catalogues). When needed, this reference catalogue may be complemented or refreshed through real-time requests to Distributor(s), for example to retrieve up-to-date content or to confirm pricing and availability constraints.
+
+- The Customer reviews the initial results and may filter or order the offers. When the Customer selects an item, the Retailer requests the priced option for the Customer’s specific context and parameters and receives the corresponding conditions and guarantees (TRAVEL GUARANTEE(s)).
+If the Customer cannot finalise the selection (e.g. distributor unreachable/timeout, partial content returned, eligibility evidence missing or rejected, quote validity/Time Limit expired, availability change during selection, inconsistent constraints across distributors), the Customer refines the search criteria, and the Retailer refreshes the catalogue results accordingly (e.g. by updating the context data and/or any constraints coming from the journey planning input). The updated results are then re-filtered and re-ranked to narrow down the list of candidate offers.
+- **Present an initial set of comparable offers**
+6. In both cases, the Retailer orchestrates the exchange with one or more Distributors and consolidates responses into a consistent list of comparable options, including price (PRICE), sales conditions and combination constraints (USAGE PARAMETER(s), VALIDITY CONDITION(s), ENTITLEMENT(s), OFFER RULE(s)), travel guarantees, and availability where applicable. The Retailer can manage (filter/rank/compare in a consistent comparison frame so the Customer can compare like-for-like) the displayed results with additional attributes provided by the Distributor(s) (operator, line, categories, product name) : fare/price, sales conditions (exchange/refund/cancellation), duration, number of interchanges, mode mix, GHG/CO₂ impact, comfort, accessibility or operator (CUSTOMER PURCHASE PACKAGE). The Retailer also supports comparison of corporate/private fares when eligibility is provided, and may display included/optional ancillaries and services (e.g. seats, luggage) as part of the option content. Where options involve multi-operator or multimodal pricing, the Retailer presents any validity, eligibility and combination/combinability constraints explicitly (e.g. outbound must be part of a return trip, zone validity, required reduction card) (PRICE/FARE PRICE, USAGE PARAMETER(s), VALIDITY CONDITION(s), ENTITLEMENT(s), OFFER RULE(s), TRAVEL GUARANTEE(s)).
+
+- **Consult offers details ( for a selected candidate offer )**
+7. The Customer selects one candidate offer and requests details so that he can consult the detailed contents, conditions, guarantees, and optional parts. This consultation can be done for more than one offer at the same time, if they can be displayed on the same screen at the same time. The Retailer retrieves the detailed information from the relevant Distributor(s) and presents it in a consistent way.
+8. If the selected offer cannot be confirmed for the specific customer context, the Customer enters additional customer parameters by providing the required information, such as the traveller profile, eligibility, accessibility needs, class, date, zone, quantity, or extras (ACCESS RIGHT PARAMETER(s), USER PROFILE, ENTITLEMENT(s), CLASS OF USE). Once the required information is filled in, the Retailer checks the entries, updates the customer context (adds the missing parameters) and requests confirmation from the relevant Distributor(s). The Distributor(s) then either confirm the offer (price/conditions/availability) or reject it if the provided inputs do not satisfy eligibility or other constraints. The Customer is informed with a price with the applicable commercial and travel conditions:
+- sales and aftersales conditions including exchange, cancellation or refund conditions (USAGE PARAMETER(s): EXCHANGING / REFUNDING / CANCELLING),
+- travel guarantees (TRAVEL GUARANTEE(s)) including passenger rights when applicable,
+- availability information (AVAILABILITY CONDITION),
+- third-party products only when included in the Distributor-provided content.
+It may be composed of several items.
+9. a. If this price is indicative and depends on mandatory reservation (for example, a seat (SPOT ALLOCATION)), or if the Customer wishes to check availability and the system allows it, or if confirming the chosen option requires locking capacity (seat/quota) or starting a time-limited hold/pre-reservation, this is handled in the Reservation BUC-C.
+- If the final price is a dynamic/yield price, the Distributor returns a price with a limited validity period (validity/TTL). The Retailer informs the Customer that this price may expire; if it expires before the Customer proceeds, the Retailer must request a refreshed price and updated conditions from the Distributor before continuation.
+- **Refine and re-evaluateoffers**
+10. If the Customer cannot finalise his selection, he adjusts the criteria and/or defining parameters to narrow/change the displayed offers according to the consultation context and the data he provides (new or modified data and/or data coming from journey planner requirements). The Retailer refreshes the option(s) by re-querying the relevant Distributor(s). This can iterate until the Customer is satisfied or no option matches. If the Customer wants to collect and manage several options/products together (iterate BUC-A several times, assemble a basket), this is handled in BUC-B (basket management) (TRAVEL BASKET / TRAVEL PACKAGE).
+- **Selection**
+11. The Customer chooses the preferred solution (or a shortlist). The Retailer records the consultation outcome as the selected option/shortlist (CUSTOMER OFFER PACKAGE) . The retailer can inform the Customer that all or part of the offer has expired and propose a new price and availability calculation when applicable.
-8. Before making a final choice, the TRANSPORT CUSTOMER may change options to modify class, extras, or other defining elements, and if needed the retailer refreshes the offer and recalculates the corresponding conditions and price.
-9. One by one, the TRANSPORT CUSTOMER can consult, select, or discard FARE PRODUCT(s) to build a final complete solution. At each step, for each selected product requiring a reservation, the retailer can start the reservation process with the distributor in order to ensure coherent multiple reservations (transaction management with multiple distributors).
-10. The TRANSPORT CUSTOMER chooses the preferred solution, and the retailer can keep the selected option in a "wish list" so that the CUSTOMER OFFER PACKAGE is ready for the next reservation and purchase step. The retailer can inform the TRANSPORT CUSTOMER that all or part of the offer has expired and propose a new price and availabiltiy calculation.
-
### Alternatives scenarios
Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
- **Specific trip**
-1. The TRANSPORT CUSTOMER chooses his origin station and his destination station on the ticket vending machine with the option "around the stations : x kilometers".
-2. The TRANSPORT CUSTOMER enters required data (customer account, reduction card).
-3. The TRANSPORT CUSTOMER chooses between a few SALES OFFER PACKAGEs displayed with their PRICE, on different JOURNEYs with different stations (radius-based).
+1. The Customer chooses his origin station and his destination station, optionally using a "around me/ the stations: x kilometres" (a nearby/radius option around the stations. (PLACE as POINT/SECTION/ZONE)).
+2. The Customer enters required data (customer account, reduction card) (CUSTOMER ACCOUNT optional, ENTITLEMENT(s)).
+3. The Customer chooses between a few offers displayed with their price, on different travel options with different stations (radius-based).
- **Single anonymous travel**
-1. The TRANSPORT CUSTOMER starts his mobile application; the home page displays a shortcut for single-trip purchase in one action.
-2. He chooses an anonymous single-trip ticket by clicking on this shortcut.
-
-- **PRM journey**
-1. The TRANSPORT CUSTOMER has specific needs that must be guaranted to be met during his TRAVEL (on the LEG and between LEGs). The journey planner gives solutions that meet the TRAVEL SPECIFICATION with mobility services even on the first LEG (from house/postal address to first STOP POINT), during interchange and on the last LEG (from last STOP POINT to final destination).
-2. If the journey planner is associated with a fare calculator, the TRANSPORT CUSTOMER receives a fare offer compliant with USER PROFILE and with TRAVEL SPECIFICATION, including continuous additional services and travel guarantees from house to destination.
-3. If the journey planner only provides basic mobility solutions, the TRANSPORT CUSTOMER must browse the catalogue to select one by one the tickets, services and guaranteees he needs. When his selection fulfills his complete TRAVEL, he has a satisfactory solution.
-
-- **Return trip**
-1. The TRANSPORT CUSTOMER plans a TRAVEL composed of an outward journey and the corresponding return journey. The journey planner can manage the full TRAVEL, requesting only minimal criteria for the return trip (return time and reversing origin-destination).
-2. If the journey planner is associated with a fare calculator, the TRANSPORT CUSTOMER can receive a fare offer that takes into account the whole TRAVEL (for example, a daily pass less expensive than two separate tickets).
-3. If the journey planner only proposes basic mobility solutions, the TRANSPORT CUSTOMER must browse the catalogue to select one by one the tickets, looking for a solution that includes the two TRIPs.
-
-- **Bank card as TRAVEL DOCUMENT**
-1. The TRANSPORT CUSTOMER plans a TRAVEL and consults the catalogue: he checks that his bank card is accepted as a TRAVEL DOCUMENT on the selected JOURNEYs. The validity conditions, guarantees and PRICEs (including fees and VAT rates) are displayed. The TRANSPORT CUSTOMER is fully informed.
-2. The TRANSPORT CUSTOMER does not need to select a product himself : the FARE PRODUCT selection is done by the system when the traveller taps on the validator equipment (date and time, place, line, stop, operator, bank contract and answer, customer account).
-
-
-### Diagram
+1. The Customer starts his mobile application/distribution channel; the entry point can display a shortcut for single-trip purchase “in one action” (i.e. with minimal input) (CUSTOMER ACCOUNT optional).
+2. The Customer chooses an anonymous single-trip ticket by using this shortcut (default assumptions may apply: anonymous adult, single trip, no reduction) (USER PROFILE default, TRAVEL SPECIFICATION minimal).
+3. The Retailer requests and displays the priced offer with sales conditions and travel guarantees (PASSENGER FARE OFFER, PRICE, USAGE PARAMETER(s), TRAVEL GUARANTEE(s)).
+4. If an availability check or a time-limited hold is required, it is handled in **BUC-C**. (AVAILABILITY CONDITION, SPOT RESERVATION / SPOT ALLOCATION)
+5. If the Customer purchases, it is handled in **BUC-D**. (PAYMENT)
+
+- **PRM journey**
+ 1. The Traveller(s) have specific needs that must be guaranteed to be met during the travel (on each leg and between legs, during connections). The journey planner gives solutions that meet the travel specification with mobility services even on the first leg (from house/postal address to first stop point), during interchange and on the last leg (from last stop point to final destination) (TRAVEL SPECIFICATION, LEG(s)).
+2. If the journey planner is associated with a fare calculator, the Customer receives an offer compliant with passenger profile and with the travel specification, including continuous additional services and travel guarantees from house to destination (USER PROFILE, PASSENGER FARE OFFER, TRAVEL GUARANTEE(s)).
+3. If the journey planner only provides basic mobility solutions, the Customer browses the catalogue to select one by one the required tickets/services/guarantees. When his selection fulfils his complete travel, he has a satisfactory solution. If this requires combining several items, it is handled in BUC-B (TRAVEL BASKET / TRAVEL PACKAGE).
+
+- **Return trip**
+ 1. The Customer plans a travel composed of an outward journey and the corresponding return journey. The journey planner can manage the full travel, requesting only minimal criteria for the return trip (return time and reversing origin-destination) (TRAVEL, TRIP(s)).
+2. If an integrated fare calculator is available, it may produce an initial indicative priced offer based on the result of the journey planner: , the Customer can receive an offer that considers the whole travel (for example, a daily pass less expensive than two separate tickets) (PASSENGER FARE OFFER, PRICE).
+3. If the journey planner only proposes basic mobility solutions, the Customer browses the catalogue to select one by one the tickets, looking for a solution that includes the two trips. If this requires assembling multiple selected items, it is handled in BUC-B (TRAVEL BASKET / TRAVEL PACKAGE).
+
+- **Bank card as TRAVEL DOCUMENT**
+ 1. The Customer plans a travel and consults the catalogue: he checks that his bank card is accepted as a travel credential on the selected journeys. The validity conditions, guarantees and prices (including fees and VAT rates) are displayed. The Customer is fully informed (TRAVEL DOCUMENT, VALIDITY CONDITION(s), TRAVEL GUARANTEE(s), PRICE).
+2. The Customer does not need to select a product himself: the offer selection is done by the system when the traveller taps on the validator equipment (date and time, place, line, stop, operator, bank contract and answer, customer account) (FARE PRODUCT, CUSTOMER ACCOUNT optional).
+3. This alternative may end at the information stage in BUC-A when no retailer-led purchase is performed.
+
+### Diagram
UML activity diagram
-
+
+> **Comment (Bourdelin, Sonia [2], 2026-04-30):**
+> To update
### Links with use cases
-
-Link to (https://github.com/TransmodelEcosystem/EUDIT/discussions/36#discussioncomment-16183779)
+Link to (https://github.com/TransmodelEcosystem/EUDIT/discussions/36#discussioncomment-16183779)
To be completed
-
diff --git a/wiki/use-cases/business-use-cases/buc-b-shop-and-price.md b/wiki/use-cases/business-use-cases/buc-b-shop-and-price.md
index c1e8665..2bd70f9 100644
--- a/wiki/use-cases/business-use-cases/buc-b-shop-and-price.md
+++ b/wiki/use-cases/business-use-cases/buc-b-shop-and-price.md
@@ -1,212 +1,266 @@
+In review – version 3
## Use Case Overview
-- **Business Use Case ID & Name:** BUC-B — Shop your FARE PRODUCT(s) and manage your TRAVEL BASKET with PRICE calculation at any time
-- **Goal (Objective):** Enable the TRANSPORT CUSTOMER to build, review, modify and validate a logical TRAVEL BASKET containing one or more CUSTOMER OFFER PACKAGE(s), with updated PRICE information available at any time before the next use case dealing with reservation initiation and payment.
-- **Scope:** TRAVEL BASKET creation and management / CUSTOMER OFFER PACKAGE completion / PRICE calculation and recalculation / dependency management between basket elements / basket consistency across possible retailer-side and/or distributor-side basket implementations / preparation of a ready basket for the next use case
----
+- **Business Use Case ID & Name:** BUC-B — Shop and manage your basket of selected offers with price updates at any time
+- **Goal (Objective):** Enable the Customer to build, review, modify and validate a shopping basket containing one or more selected offers, while keeping each element up to date (price, validity, conditions, dependencies) until the Customer decides to proceed (TRAVEL BASKET, TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE, PRICE).
+- **Scope (Summary) :**
+ - Basket creation and management (possibly implicit to the Customer),
+ - Completing any missing information needed to keep options priceable-valid,
+ - Price and totals calculation after each change,
+ - Handling dependency management between elements (bundles, combinability, mandatory co-sale),
+ - Basket consistency across possible retailer-side and/or distributor-side basket implementations with validity/time limits, refresh/expiry, and optional “hold for approval” cases,
+ - Preparation of a stable basket for purchase continuation (TRAVEL BASKET, TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE, PRICE, USAGE PARAMETER(s)),
## Actors & Context
-- **Primary Actor:** **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wants to prepare a consistent basket suited to his TRAVEL, for himself and/or for other travellers. He can be the manager of a group, a PRM, the purchaser for a minor traveler or other with specific needs or none.
-
+- **Context**: This use case starts after the Customer has identified one or more suitable offers and wants to manage them together as a shopping basket, including checks and repricing that may require interactions with one or more Distributors.
+- **Primary Actor:** Customer (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)): the person managing the shopping, for himself and/or for other travellers. He can be the manager of a group, a PRM, the purchaser for a minor traveller or other with specific needs or none. He decides what stays in the basket and when to proceed.
+ - Traveller**:** the person(s) who will actually travel and use the entitlement. The Traveller and the Customer can be the same person but not always.
- **Supporting Actors / Stakeholders:**
- - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** manages the shopping flow and customer interaction, presents the TRAVEL BASKET to the TRANSPORT CUSTOMER and may manage a logical and/or technical basket (basket consistency, requests sent to one or more distributors).
- - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** provides offer completion rules, PRICE information, commercial conditions, after-sales conditions, guarantees, and dependency rules affecting basket elements. May manage a technical basket for one or more basket elements.
+ - **Retailer** (FARE PRODUCT RETAILER ROLE (API consumer)): manages the shopping flow and customer interaction, presents the basket to the Customer and may manage a logical and/or technical basket (basket consistency, requests sent to one or more distributors, consolidates responses from Distributor(s)).
+ - **Distributor** (FARE PRODUCT DISTRIBUTOR ROLE (API provider)): provides offer completion rules, price information, commercial conditions, after-sales conditions, guarantees, and dependency rules affecting basket elements. May manage a technical basket for one or more basket elements.
-- **Assumptions (context at start):**
- - The TRANSPORT CUSTOMER has already selected one or more candidate CUSTOMER OFFER PACKAGE(s) in the previous use case.
- - The TRANSPORT CUSTOMER can provide the additional information required to complete and price the selected offer(s).
- - The TRAVEL BASKET is a logical business object from the customer perspective; its technical implementation may reside with the retailer, with one or more distributors, or be distributed across both.
- - Depending on the implementation, "basket" operations may be executed:
- - only in a retailer "basket";
- - only in a distributor "basket"; or
- - in a retailer "basket" and in one or more distributor "baskets" that must remain aligned.
- - The use case is implementation-neutral and therefore specifies the required business result, not the internal technical ownership of the "basket".
+> **Comment (BIGEX Olivier, 2026-05-06):**
+> As discussed, no need for basket on distributor side at this step, since it manages on its sides offers which are already consistent.
+>
+> In some cases, with NFC cards, cohabitations rules must be checked by the distributor (e.g. only one pass by card and by fare owner), but no need to write here that the distributor creates a basket (internal distributor solution).
+> --> To be removed and add somewhere a step where items in retailer’s basket are checked by the distributor (only items concerned by this distributor).
----
+> **Comment (Bourdelin, Sonia [2], 2026-05-06):**
+> Some systems need a TB on their side (urabn transport to check hat the contactless card can manage the new contracts)
## Preconditions & Postconditions
-- **Preconditions (must be true before start):**
- - Access to the distributor’s selling system is available/authorized to the retailer and/or TRANSPORT CUSTOMER.
- - The relevant distributor(s) of the selected offer elements are identified.
- - The distributor’s selling system and related pricing, guarantee, after-sales and dependency information are available (online service or accessible dataset).
- - At least one FARE PRODUCT is selected by the CUSTOMER (at minimum: the customer wants to purchase one FARE PRODUCT; optionally: many CUSTOMER OFFER PACKAGEs).
- - The TRANSPORT CUSTOMER context needed to continue the purchase is available or can be entered, including traveller data, rights, options, delivery data, invoicing data or VAT context where required.
+- **Assumptions and Preconditions (must be true before start):**
+
+ - The Customer has already selected one or more candidate offer(s) (CUSTOMER PURCHASE PACKAGE(s)) in the previous use case (BUC-A).
+ - The Customer can provide the additional information required to complete and price the selected offer(s) (traveller data, eligibility, options, invoicing/VAT context if relevant).
+ - The Retailer can identify the relevant Distributor(s) for each selected offer and access the required selling/pricing information, either via online services or accessible datasets.
+- The basket (TRAVEL BASKET) is a logical business object representing the shopping state (it may be explicit or implicit to the Customer); its technical implementation may reside with the retailer, with one or more distributors, or be distributed across both. The use case is implementation-neutral and therefore specifies the required business result, not the internal technical ownership of the "basket" (can be only in a retailer "basket", only in a distributor "basket"; or in a retailer "basket" and in one or more distributor "baskets" that must remain aligned).
+
+> **Comment (BIGEX Olivier, 2026-05-06):**
+> I disagree, not the same objects and functions. But I don’t see the impact in OTI, and I don’t want to enter in an architecture debate.
+> Maybe simply remove this sentence, which doesn’t bring anything to this BUC
+
+> **Comment (Bourdelin, Sonia [2], 2026-05-06):**
+> On OTI, we may manage API that coordinate the 2 TB.
+> **Comment (BIGEX Olivier, 2026-05-19):**
+> I still think that this is not the same business object, thus I am not confortable with this wording. BUT :
+> on retailer’s side, the retailer’s functions could be supported by a technical agregator (e.g. a B2B multimodal digital mobility service), which manages a basket. And it would be great if OTI support interactions between the retailer and the agregator as well.
+> A basket could be seen as a booking in a non confirmed status. On retailer’s side (= retailer’s order) and on distributor’s side.
+> ==> maybe we have both a similar thing in mind, but we don’t use the same wording in our architecture. Thus I still suggest to avoid writting implementation solutions and replace these wordings (here and above) by the needs for interactions between retailer and distributor. E.g. «the retailer may inform the distributor that an offer has been put/removed from the basket».
+
+> **Comment (Bourdelin, Sonia, 2026-05-31):**
+> Yes, we should concentrate on the exchanges between retailer and distributor.
+> Text modified + last point added
+- When needed to keep elements up to date (pricing, validity, constraints, dependencies), the Retailer may inform the relevant Distributor(s) that an offer has been added/updated/removed in the basket and request the corresponding checks/updates for the concerned element(s).
- **Postconditions — Success guarantees:**
- - A TRAVEL BASKET exists and contains one or more completed and consistent TRAVEL BASKET ELEMENTs according to the TRANSPORT CUSTOMER’s actions.
- - Each TRAVEL BASKET ELEMENT contains one CUSTOMER OFFER PACKAGE and the information needed for continuation :
- - selected **CUSTOMER OFFER PACKAGE(s)**, including quantity
- - the associated current **PRICE**
- - applicable **reductions, TRAVEL GUARANTEEs and aftersales conditions**
- - any dependency information linking it to other TRAVEL BASKET ELEMENTs
- - optional protection or guarantee services selected during shopping, where applicable
- - group-specific quotation results, where applicable
- - approval-hold status, where applicable
- - identified reservation-related constraints or intermediate reservation results, where applicable
- - The whole TRAVEL BASKET has a calculated total **PRICE** (can be zero or less).
- - The basket state presented to the customer is consistent, regardless of whether the underlying implementation relies on a retailer basket, a distributor basket, or coordinated baskets across both.
- - This use case ends when the TRAVEL BASKET is ready for the next step; reservation initiation and payment are out of scope and belong to the following use case.
+-
+ - A basket exists and contains one or more completed and consistent basket elements according to the Customer’s actions : ; any constraints required by the configuration of an offer (or combinations of offers) are identified and either satisfied or clearly flagged (TRAVEL BASKET, TRAVEL BASKET ELEMENT).
+ - Each basket element contains one selected offer and the information needed for continuation:
+ - selected **offer(s)** and quantity, including validity when applicable (CUSTOMER PURCHASE PACKAGE)
+ - the associated current price (PRICE),
+ - applicable reductions, guarantees and aftersales conditions (TRAVEL GUARANTEE(s), USAGE PARAMETER(s)),
+ - any dependency information linking it to other basket elements (bundles/co-sale/combinability),
+ - optional protection or guarantee services selected during shopping, where applicable,
+ - group-specific quotation results, where applicable,
+ - approval-hold status, where applicable,
+ - identified reservation-related constraints or intermediate reservation results, where applicable.
+ - The whole basket has a calculated total price (totals can be zero or less).
+ - The basket state presented to the customer is consistent reflects the latest known status of each element (valid/expired/needs refresh) and any constraints affecting continuation., not where the “basket” is technically stored.
+ - This use case ends when the basket is ready for the next step; reservation initiation or continuation and payment are out of scope and belong to the use cases BUC-C and BUC-D.
- **Postconditions — Minimal guarantees:**
- - If the TRANSPORT CUSTOMER abandons the process or no suitable solution is found, the TRAVEL BASKET remains empty. The purchase process is suspended or ended.
- - After any TRAVEL BASKET operation, the retailer and/or distributor shall ensure that no TRAVEL BASKET ELEMENT remains with an outdated PRICE, an invalid status, or an unresolved dependency with another TRAVEL BASKET ELEMENT. The TRAVEL BASKET shall remain internally consistent after any operation.
- - If synchronisation between retailer-side and distributor-side basket states is required, the system detects any divergence and prevents continuation until the customer basket state is made consistent again.
- - The TRANSPORT CUSTOMER actions can be logged/audited (if required by the system).
+-
+ - If the Customer abandons the process or no suitable solution is found, the basket remains empty or unchanged. Any time-limited elements are clearly marked as expired/not usable until refreshed.
+ - After any basket operation, the Retailer and/or Distributor shall ensure that no basket element remains with an outdated price, an invalid status, or an unresolved dependency with another basket element. The basket shall remain internally consistent after any operation.
+ - If synchronization between retailer-side and distributor-side basket states is required, the system detects any divergence and prevents continuation until the basket state is made consistent again. Divergence may occur for example after an expiry/refresh on Distributor side, an availability change, or a partial update failure; in such cases the Retailer requires a refresh and shows the updated state before proceeding.
+ - The Customer actions can be logged/audited (if required by the system).
+
+## Terminology –
+
+CUSTOMER PURCHASE PACKAGE : In Transmodel improved with COROM project proposals, a CUSTOMER PURCHASE PACKAGE is created when a SALES OFFER PACKAGE has been selected and parameterised for a specific customer context. Where basket management is required, this CUSTOMER PURCHASE PACKAGE may be inserted into the TRAVEL BASKET as part of a TRAVEL BASKET ELEMENT. However, for a simple purchase flow, the Retailer may present the CUSTOMER PURCHASE PACKAGE directly to the TRANSPORT CUSTOMER without exposing or explicitly managing a TRAVEL BASKET.
----
+**Basket** is the logical business object that represents the **current shopping state** of one customer session: it groups one or more selected offers, keeps track of their required parameters, current prices, validity/time limits, and dependencies until the customer validates the intended purchase solution. It may be **explicit** (visible to the customer) or **implicit** (not shown), but it still exists as the reference state used to keep elements up to date. *(TRAVEL BASKET, TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE, PRICE, VALIDITY CONDITION(s), OFFER RULE(s))*
+###
+### Cart (difference with Basket)
+A **Cart** is the **customer-facing shopping-cart feature** (UI/UX) used by a retailer to display and manage what the customer intends to buy. A cart may include **items outside the interoperability scope** (e.g. hotels, events, flights), and it is therefore not a reliable interoperability object by itself. In EUDIT/OTI terms, the **Basket** is the scope-relevant logical object used to manage the in-scope selected offers and their constraints, whether or not the retailer exposes it as a cart feature. *(TRAVEL BASKET)*
+
+***A* *B **ooking* *is the customer-facing result of securing and then confirming a travel purchase: it starts when one or more selected offers are secured (inventory/options held where required) for a limited time, and it becomes effective when the sale is confirmed and can proceed to fulfilment. In* *Transmodel **terms, it corresponds to: a secured state of selected offer(s) requiring reservation/hold (RESERVATION, AVAILABILITY CONDITION, SPOT ALLOCATION) linked to selected offer(s) (CUSTOMER PURCHASE PACKAGE, TRAVEL BASKET ELEMENT), followed by confirmation of the sale (SALES TRANSACTION) which triggers delivery of travel rights/documents (TRAVEL DOCUMENT(s)).***
## Scenarios
### Main scenario
-Note : In Transmodel improved with COROM project proposals, a CUSTOMER OFFER PACKAGE is created when a SALES OFFER PACKAGE has been selected and parameterised for a specific customer context; it is then inserted into the TRAVEL BASKET as part of a TRAVEL BASKET ELEMENT.
-
-#### TRAVEL BASKET management
-1. The TRANSPORT CUSTOMER shall start this use case after having selected one or more candidate FARE PRODUCT(s) and their corresponding SALES OFFER PACKAGE(s); fulfilling at least one CUSTOMER OFFER PACKAGE in the previous use case.
-2. The retailer shall open, identify or initialise to the TRANSPORT CUSTOMER a logical TRAVEL BASKET, regardless of whether the underlying technical basket is managed by the retailer, by one or more distributor(s), or by both. The logical TRAVEL BASKET may be created explicitly at the TRANSPORT CUSTOMER’s request or implicitly when the first CUSTOMER OFFER PACKAGE is added associated with the current shopping session. This TRAVEL BASKET can be transparent for the TRANSPORT CUSTOMER and not requested for a basic purchase.
-- **Display TRAVEL BASKET**
-3. At each step, the retailer shall present to the TRANSPORT CUSTOMER the current shopping context and so, the TRANSPORT CUSTOMER can see a representation/summary of what he is purchasing (current state of TRAVEL BASKET if already exists) including the details of each operation:
- - the list of TRAVEL BASKET ELEMENTs;
- - the CUSTOMER OFFER PACKAGE contained in each TRAVEL BASKET ELEMENT;
- - the detailed PRICE of each TRAVEL BASKET ELEMENT;
- - the total PRICE of the TRAVEL BASKET;
- - the quotation validity period applicable to each concerned CUSTOMER OFFER PACKAGE; and
- - the main conditions attached to each TRAVEL BASKET ELEMENT and to the basket as a whole.
-- **Creation of an empty TRAVEL BASKET (optional)**
-4. If the TRANSPORT CUSTOMER requests the creation of an empty TRAVEL BASKET, the retailer shall create or request creation of the corresponding basket state in the relevant basket implementation(s), retrieve the resulting basket state where applicable, and present the empty logical TRAVEL BASKET to the TRANSPORT CUSTOMER.
-- **Addition of one or many TRAVEL BASKET ELEMENT(s)**
-5. The TRANSPORT CUSTOMER may add a CUSTOMER OFFER PACKAGE (selected and defined in previous use case) to his TRAVEL BASKET as a TRAVEL BASKET ELEMENT either :
- - one selected CUSTOMER OFFER PACKAGE in a single action; or
- - several selected CUSTOMER OFFER PACKAGE(s) in one action, including for a multimodal, multi-leg or multi-operator TRAVEL with protection or guarantee option related to connections.
-The addition is the only operation that the TRANSPORT CUSTOMER can start the process with. This operation can be the only one available for the TRANSPORT CUSTOMER on the selling system.
-If the TRANSPORT CUSTOMER is shopping for a group larger than the standard instant-shopping scope, the retailer may interrupt this flow : the retailer sends a specific request to the relevant distributor(s), including the group-related constraints, and resumes the present use case when the quotation is returned.
-6. For each addition, the retailer shall create one TRAVEL BASKET ELEMENT corresponding to the shopping intention of the TRANSPORT CUSTOMER for the concerned part of the TRAVEL. Each TRAVEL BASKET ELEMENT shall contain one CUSTOMER OFFER PACKAGE representing the customer-specific shopping component derived from the selected SALES OFFER PACKAGE and its customer parameterisation. On each addtion, the retailer shall :
- - identify the relevant distributor for the selected SALES OFFER PACKAGE;
- - confirm (and ends the collect if required) the data required to build thne corresponding CUSTOMER OFFER PACKAGE;
- - send the relevant request to the distributor (including retailer's TRAVEL BASKET if required), where distributor-side processing is required;
- - create or update the corresponding TRAVEL BASKET ELEMENT in the relevant basket implementation(s);
- - (if required) evaluate dependencies between TRAVEL BASKET ELEMENT to assure the consistency of the TRAVEL BASKET and inform the TRANSPORT CUSTOMER of the consequences; and
- - retrieve the resulting PRICE, validity period and applicable conditions for presentation to the TRANSPORT CUSTOMER.
-Several CUSTOMER OFFER PACKAGE(s) added in one action may correspond to one multimodal, multi-leg or multi-operator TRAVEL and may be processed either as one combined basket update or recursively element by element.
-Pre-reservation step can be started at this moment. The retailer may temporarily interrupt the present use case, start the relevant reservation initiation process with the concerned distributor(s), and then resume the shopping process with the updated TRAVEL BASKET state. This reservation initiation is managed in next use case.
-- **Modification of one existing TRAVEL BASKET ELEMENT**
-7. The TRANSPORT CUSTOMER may request modification of one existing TRAVEL BASKET ELEMENT. It can be on, when applicable : quantity, date and time, validity options, eligibility data, traveller assignment, customer account context (including fare contracts and travel documents), reduction rights, class or comfort option (seat preference), ancillary selections, delivery preferences, invoicing order, VAT context. It can be on any other mandatory parameter required by the distributor.
-8. On a modification request, the retailer shall :
- - identify the TRAVEL BASKET ELEMENT concerned and the permitted characteristics that may be changed;
- - request from the TRANSPORT CUSTOMER any additional data required to perform the modification;
- - send the relevant update request to the concerned distributor, where applicable;
- - retrieve the updated CUSTOMER OFFER PACKAGE, PRICE, validity period and other applicable conditions; and
- - (if required) evaluate dependencies between TRAVEL BASKET ELEMENT to assure the consistency of the TRAVEL BASKET and inform the TRANSPORT CUSTOMER of the consequences; and
- - retrieve the resulting PRICE, validity period and applicable conditions for presentation to the TRANSPORT CUSTOMER.
-- **Removal of one or many existing TRAVEL BASKET ELEMENT(s)**
-9. The TRANSPORT CUSTOMER may request removal of one existing TRAVEL BASKET ELEMENT. He may do it by selecting it in the TRAVEL BASKET display or down the quantity to zero or with any other displayed option.
-10. For each removal, the retailer shall :
- - identify the TRAVEL BASKET ELEMENT concerned;
- - send the relevant deletion request to the concerned distributor, where applicable;
- - update the relevant TRAVEL BASKET implementation(s);
- - determine whether the removal affects any other TRAVEL BASKET ELEMENT, any combined pricing rule, any pass condition, any ancillary condition, or any other basket dependency; and
- - retrieve the resulting TRAVEL BASKET state for presentation to the TRANSPORT CUSTOMER.
-Severeal removals in one step for the TRANSPORT CUSTOMER can be managed as only one operation or recursively, one by one in order to manage element's dependencies.
-- **Clearing the whole TRAVEL BASKET**
-11. The TRANSPORT CUSTOMER may request clearing of the whole TRAVEL BAKSET. He may do it by selecting the TRAVEL BASKET or, on some systems, downing the last element quantity to zero or with any other displayed option. A additional confirmation can be required.
+
+- **Basket management**
+-
+1. The Customer shall start this use case after having selected one or more priced offers (CUSTOMER PURCHASE PACKAGE) in the Business Use Case A.
+2. The Retailer opens or initialises a basket for the current shopping session (explicitly if the Customer requests it, or implicitly when the first offer is added) (TRAVEL BASKET).
+The logical basket may be created explicitly at the Customer’s request or implicitly when the first offer is added associated with the current shopping session. For a simple purchase, This basket can be transparent for the Customer and may be replaced in the display by the direct presentation of the offer.
+
+**Display basket**
+3. At each step, the Retailer shall present the current shopping context and so, the Customer can see a representation/summary of what he is purchasing (current state of basket if already exists) including the details of each operation:
+ - current basket elements (TRAVEL BASKET ELEMENT(s)), where applicable,
+ - the offer contained in each element (CUSTOMER PURCHASE PACKAGE),
+ - the detailed price of each element (PRICE),
+ - the total price of the basket,
+ - the quotation validity periods applicable to each concerned,
+ - any validity extension possibilities,
+ - the key conditions and constraints attached to each element and to the basket as a whole or only part of it (USAGE PARAMETER(s), VALIDITY CONDITION(s)).
+
+**Creation of an empty basket (optional)**
+4. If the Customer requests the creation of an empty basket, the Retailer shall create or request creation of the corresponding basket state, retrieve the resulting basket state where applicable, and present the empty basket.
+
+**Addition of one or many basketselement (s)**
+5. The Customer may add an offer (selected and defined in previous use case) to his basket either:
+ - one selected offer in a single action; or
+ - several selected offers in one action, including for a multimodal, multi-leg or multi-operator travels with protection or guarantee option related to connections.
+A basket element may cover one or several passengers; where passengers require different offers, the basket may contain multiple elements representing those passenger-specific selections), including the group-related constraints (TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE).
+The addition is the only operation that the Customer can start the process with. This operation can be the only one available for the Customer.
+6. For each addition, the Retailer shall create one element corresponding to the shopping intention of the Customer for the concerned part of the travel. For each addition, the Retailer shall :
+ - identify the relevant Distributor(s) for the added offer (output of BUC-A);
+ - confirm (and ends the collect if required) the data required to build the corresponding valid and priceable offer,
+ - send the relevant updates requests to the concerned Distributor (including retailer's basket if required), where distributor-side processing is required;
+ - create or update the corresponding basket element (TRAVEL BASKET ELEMENT);
+ - evaluate dependencies between basket elements when required to assure the consistency of the basket and inform the Customer of the consequences;
+ - retrieve the resulting price, validity and applicable conditions for presentation (PRICE).
+Several offers added in one action may correspond to one multimodal, multi-leg or multi-operator travel and may be processed either as one combined basket update or recursively element by element.
+Pre-reservation step can be started at any moment in BUC-B: If adding an element triggers a capacity hold or reservation-related action, the Retailer starts the reservation/hold process in parallel as described in BUC-C, and then updates the basket state with the resulting status/constraints.” (SPOT RESERVATION / SPOT ALLOCATION).
+
+**Modification of one existing basket element**
+7. The Customer may request modification of one existing basket element (when supported). It can be on : quantity, date and time, validity options, eligibility data, traveller assignment, customer account context (including fare contracts and travel documents), reduction rights, class or comfort option (seat preference), ancillary selections, delivery preferences, invoicing order, VAT context (TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE). It can be on any other mandatory parameter required by the Distributor.
+Quantity may represent either multiple instances of the same selected offer, or a parameter within one offer; the Retailer applies the appropriate update mechanism accordingly (CUSTOMER PURCHASE PACKAGE).
+8. On a modification request, the Retailer shall :
+ - identify what can be changed,
+ - request from the Customer any additional required data ,
+ - send the relevant update request to the concerned Distributor(s), where required,
+ - retrieve the updated offer details, price, validity period and other applicable conditions,
+ - evaluate dependencies between basket elements and prepares consequences for the Customer if other elements are impacted,
+ - retrieve the resulting price, validity period and applicable conditions for presentation to the Customer.
+-
+**Removal of one or many existing TRAVEL BASKET ELEMENT(s)**
+9. The Customer may request removal of one or many basket element. He may do it by selecting it in the basket display or down the quantity to zero or with any other displayed option.
+10. For each removal, the retailer shall:
+ - identify the basket element(s) concerned,
+ - send the relevant deletion request to the concerned Distributor(s), where applicable,
+ - determine whether the removal affects any other basket element , any combined pricing rule, any pass condition, any ancillary condition, or any other basket dependency (fare combinability / through-fare eligibility / bundle rules/ ancillaries applicability),
+ - update the basket: repricing of affected elements and/or basket total and validity refresh or expiry handling,
+ - retrieve the resulting basket state for presentation to the Customer.
+Several removals in one step for the TRANSPORT CUSTOMER can be managed as only one operation or recursively, one by one in order to manage element's dependencies.
+
+**Clearing the whole basket**
+11. The Customer may request clearing of the whole basket. He may do it by selecting the basket or, on some systems, downing the last element quantity to zero or with any other displayed option. An additional confirmation can be required.
12. To execute this demand, the retailer shall :
- - request deletion or resetting of all TRAVEL BASKET content in the relevant basket implementation(s);
- - retrieve confirmation of the resulting empty basket state, where applicable; and
- - display the resulting empty logical TRAVEL BASKET to the TRANSPORT CUSTOMER.
-On some systems, this operation is managed as a TRAVEL BASKET removeal.
+ - request deletion or resetting entire basket content in the basket,
+ - retrieve confirmation of the resulting empty basket state, where applicable
+ - display the resulting empty logical basket to the Customer.
+On some systems, this operation is managed as a basket suppression.
-#### Final price calculation
+- **Final price calculation**
+-
- **Change management**
-13. If required, after any operation listed above and before displaying the operation result, the retailer and/or the concerned distributor(s) in interaction with the TRANSPORT CUSTOMER shall evaluate the impact of the operation on:
- - the affected TRAVEL BASKET ELEMENT;
- - any other TRAVEL BASKET ELEMENT;
- - the PRICE of one or more basket elements;
- - the total PRICE of the TRAVEL BASKET;
- - quotation validity;
- - fare combinability;
- - through-fare eligibility;
- - ancillary applicability;
- - pass validity conditions;
- - bundle conditions; and
- - any other dependency between TRAVEL BASKET ELEMENTs.
-During each evaluation, the retailer shall send to the relevant request to the concerned distributor and each of them shall return the updated shopping result for the relevant CUSTOMER OFFER PACKAGE(s), including the applicable PRICE, validity period, conditions, restrictions and any detected consequence affecting other TRAVEL BASKET ELEMENTs.
-14. The retailer shall consolidate all relevant distributor responses, together with any retailer-side basket processing result, into one updated logical TRAVEL BASKET state. If one or more quotations cannot continue without recalculation (expired), the retailer shall request a mandatory refresh of the CUSTOMER OFFER PACKAGE(s) before the logical TRAVEL BASKET can continue unchanged.
-If the requested operation has consequences on one or more other TRAVEL BASKET ELEMENTs, the retailer shall present those consequences to the TRANSPORT CUSTOMER before finalising the TRAVEL BASKET state :
- - repricing of one or more TRAVEL BASKET ELEMENTs;
- - refresh or expiry of a quotation;
- - loss, addition or modification of a reduction, negotiated fare, entitlement or pass condition;
- - invalidation or activation of a combined offer (fare combination evaluation);
- - change in ancillary eligibility or ancillary PRICE;
- - invalidation of one or more CUSTOMER OFFER PACKAGE(s);
- - deletion or replacement of dependent TRAVEL BASKET ELEMENTs; or
- - modification of the overall basket consistency.
-15. The TRANSPORT CUSTOMER shall either accept the proposed consequences and confirm the TRAVEL BASKET update, or reject the proposed consequences and cancel the operation. If the TRANSPORT CUSTOMER rejects the proposed consequences, the retailer shall preserve the previously consistent logical TRAVEL BASKET state. If the TRANSPORT CUSTOMER accepts the proposed consequences, the retailer shall confirm and apply the resulting basket state across the relevant basket implementation(s).
-16. In any case,the retailer shall inform the TRANSPORT CUSTOMER with the result and present the updated logical TRAVEL BASKET, including:
- - all current TRAVEL BASKET ELEMENTs;
- - the CUSTOMER OFFER PACKAGE contained in each element;
- - the PRICE of each element, reduction amount, VAT;
- - the total PRICE of the TRAVEL BASKET, reduction amount, VATs; and
- - the main applicable conditions and validity constraints.
-- **Pricing**
-17. The TRANSPORT CUSTOMER may also provide a promotion code, discount code, entitlement reference, reduction right, corporate identifier (and agreements) or pass-related information applicable to one or more basket elements. The promotion or discount code may be accepted, rejected, or only partially applicable depending on distributor and retailer commercial rules. If the TRANSPORT CUSTOMER, or a corporate booker acting on his behalf, requires an internal approval before continuing, he or the retailer may request that the quotation or the TRAVEL BASKET remains valid for a defined period.
-18. The retailer shall send the relevant pricing or validation request to the concerned distributor(s), and/or apply the relevant retailer-side rules, in order to update the affected CUSTOMER OFFER PACKAGE(s), TRAVEL BASKET ELEMENT(s), PRICE(s) and basket conditions. The distributor(s) shall return the updated pricing and conditions. If a holding mechanism is required, the shopping process is temporarily suspended until approval is obtained, rejected or expired.
-19. The retailer shall present the resulting updated logical TRAVEL BASKET to the TRANSPORT CUSTOMER and ensure that the logical TRAVEL BASKET remains consistent and up to date, so that no TRAVEL BASKET ELEMENT remains with:
- - an outdated PRICE;
- - an expired quotation without being identified as such;
- - an invalid CUSTOMER OFFER PACKAGE;
- - an unresolved dependency; or
- - incomplete data required for the next use case.
-20. The TRANSPORT CUSTOMER may repeat any basket operation until he decides to stop modifying the TRAVEL BASKET.
-
-#### TRAVEL BASKET finalization
-21. The retailer calculates the final price of the whole TRAVEL BASKET and shall present the final state of the TRAVEL BASKET to the TRANSPORT CUSTOMER, including the current contents, the applicable conditions, the current total PRICE, and any remaining validity constraints relevant for continuation.
-23. When the TRANSPORT CUSTOMER decides to stop modifying the basket, the TRANSPORT CUSTOMER shall validate the selected TRAVEL BASKET as the intended purchase solution and request continuation to the next step. The use case shall end when the TRAVEL BASKET is complete, consistent and ready for the next use case dealing with reservation initiation (if not started yet) and payment.
-24. Upon this validation, the retailer and/or the relevant distributor(s) shall ensure that the TRAVEL BASKET enters a locked state (frozen) in which no operation may alter the TRAVEL BASKET content, the CUSTOMER OFFER PACKAGE(s), the applicable PRICE(s), or the associated conditions (fozen maximal duration) and dependencies.
-25. The locked TRAVEL BASKET shall constitute the stable input for the next use case dealing with reservation initiation and payment.
-
+13. If required, after any add/modify/remove operation and before displaying the operation result, the Retailer and/or the concerned Distributor(s) shall evaluate the impact of the operation and refresh what is needed :
+ - repricing of affected elements and/or basket total, (PRICE)
+ - validity refresh or expiry handling,
+ - fare combinability / through-fare eligibility / bundle rules,
+ - ancillaries’ applicability and pricing,
+ - any other dependency between elements.
+During each evaluation, the Retailer detects time-limit breaches (expiry/time limits) and external changes reported by Distributor(s) (e.g. a change impacting one leg/operator). The Retailer then either:
+- refreshes the affected offer(s),
+- flags them as expired/invalid,
+- removes them and informs the Customer before proceeding.
+14. The retailer shall consolidate all relevant Distributor responses, together with any Retailer-side basket processing result, into one updated basket state. If one or more quotations cannot continue without recalculation (expired), the Retailer may request a mandatory refresh of the offer before the basket can continue unchanged or may remove expired elements.
+15. If the requested operation has consequences on one or more other elements (repricing, invalidation, forced addition/removal, expiry/refresh), the Retailer presents them to the Customer before finalising the updated basket state. The Customer shall either accept the proposed consequences and confirm the basket update or reject the proposed consequences and cancel the operation (the retailer shall preserve the previously consistent basket state). If the Customer accepts the proposed consequences, the retailer shall confirm and apply the resulting basket state.
+16. In any case, the retailer shall inform Customer with the result and present the updated basket including:
+ - all current basket elements,
+ - the offer contained in each element,
+ - the price of each element, reduction amount, VAT;
+ - the total price of the basket, reduction amount, VATs; and
+ - the main applicable conditions and validity constraints.
+
+**Pricing**
+17. The Customer may also provide a promotion code, discount code, entitlement reference, reduction right, corporate identifier (and agreements) or pass-related information applicable to one or more basket elements. This information may be entered **during basket shopping** or **later during payment (BUC-D)**, depending on how it is defined and processed. When provided at this stage, the Retailer requests validation and repricing from the relevant Distributor(s) and updates the affected basket element(s), conditions and totals.
+In some implementations, the benefit may be represented as an additional basket element (e.g. a priced item with a negative amount); in others it is applied only at payment time (BUC-D).
+The code may be accepted, rejected, or only partially applicable depending on Distributor and/or Retailer commercial rules. In all cases, the Customer is informed of acceptance/rejection/partial applicability and any consequences on selected offers, validity and dependencies.
+If the Customer, or a corporate booker acting on his behalf, requires an internal approval before continuing, he or the Retailer may request that the quotation or the basket remains valid for a defined period.
+18. The retailer could send the relevant pricing or validation request to the concerned Distributor(s), and/or apply the relevant retailer-side rules, in order to update the affected offer(s), basket element(s), price(s) and basket conditions. The Distributor(s) shall return the updated pricing and conditions. If a holding mechanism is required, the shopping process is suspended until approval is obtained, rejected or expired.
+19. The retailer shall present the resulting basket and ensure that it remains consistent and up to date, so that no element remains with:
+- an outdated price;
+- an expired quotation without being identified as such;
+- an invalid offer;
+- an unresolved dependency; or
+- incomplete data required for the next use case.
+20. The Customer may repeat any basket operation until he decides to stop modifying it.
+
+- **Basket finalization**
+-
+21. Throughout this use case, and in particular after each basket operation (add/modify/remove) or when a quotation validity changes, the Retailer calculates the final price of the whole basket and shall present the final state of the basket to the Customer, including the current contents, the applicable conditions, the current total price, and any remaining validity constraints or dependencies relevant for continuation.
+23. The Customer shall validate the basket as the intended purchase solution and request continuation to the next step. Non-nominal situations may occur (examples: distributor unavailable/timeouts, partial availability changes, expired quotation, missing mandatory parameter, dependency conflict). In these cases, the Retailer flags the impacted element(s), requests refresh when possible and prevents continuation for the impacted element(s) until resolved.
+24. When the use case ends, the basket shall be complete, consistent and ready considered ready to proceed: for reservation (BUC-C if not started yet) and payment (BUC-D). If, at this moment, progressing requires a basket lock/freeze or the start of a reservation/hold process, these actions are handled in the dedicated BUC-C (The retailer and/or the relevant Distributor(s) shall ensure that the basket enters a locked state (frozen) in which no operation may alter the basket content). If reservation is implicitly started earlier during shopping in some implementations, it can be described in BUC-C.
+###
### Alternatives scenarios
Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
-- **Direct purchase**
-1. The TRANSPORT CUSTOMER has selected a basic FARE PRODUCT which is immedialtly a CUSTOMER OFFER PACKAGE. He selects the "Purchase in one-clic" option.
-2. The TRANSPORT CUSTOEMR does not see the TRAVEL BASKET : he directly arrives on payment interface. This scenario is a shortcut to main scenario.
+- **Direct purchaseshortcut**
+1. The Customer has selected a basic offer which is immediately complete and priced. He is invited to proceed directly to the next step (example: he selects the "Purchase in one-click" option) without explicit basket view. This scenario is a shortcut to main scenario.
- **Offer hold for approval**
-1. The TRANSPORT CUSTOMER, or a corporate booker acting on his behalf, is willing to keep the TRAVEL BASKET stable for a period (longer than the automatic system does) before validating it, because an internal approval is required.
-2. The retailer sends a request to the relevant distributor(s) to maintain the quotation or the basket content valid for a defined period, according to the applicable conditions. The purchase process is put on hold during this approval period.
-3. The distributor(s) return the validity period and the applicable holding conditions. The retailer informs the TRANSPORT CUSTOMER of the approval deadline and of any constraint linked to this temporary hold.
-4. If the approval is obtained in time, the purchase process continues with the validated TRAVEL BASKET. If the approval is not obtained in time, the TRAVEL BASKET must be refreshed, repriced, or abandoned.
+This is an example of a corporate approval flow; it is not mandatory for all implementations.
+1. The Customer, or a corporate booker acting on his behalf, is willing to keep the basket stable for a period (longer than the automatic system does) before validating it, because an internal approval (or any longer quotation validity) is required.
+2. The Retailer sends a request to the relevant Distributor(s) to maintain the validity of the concerned quotation(s) for a defined period, according to the applicable conditions. This request may apply to one or more selected offers and/or to the relevant part of the basket impacted by those offers (i.e. all quotations covered by the concerned Distributor(s)). The purchase process is put on hold during this approval period (CUSTOMER PURCHASE PACKAGE(s), TRAVEL BASKET, TRAVEL BASKET ELEMENT(s), PRICE).
+3. The Distributor(s) return the validity period and the applicable holding conditions, including, where relevant, any required or optional additional offer, ancillary service, protection or guarantee option needed to maintain the quotation /basket valid for the defined period. The Retailer informs the Customer of the approval deadline and of any constraint linked to this temporary hold.
+4. If the approval is obtained in time, the purchase process continues with the validated basket. Otherwise, the basket must be refreshed, repriced, or abandoned.
+
+> **Comment (Vinke, Bob BGH, 2026-05-07):**
+> The travel basket is based on offers with no block of price bucket or seat. so a travel basket keeping can enlarge the chance of failure at provisional booking step in use case C. If this means a provisional booking, then we should move this to use case C
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> In BUC-B we only state that such a hold may be required and that the basket is updated with the resulting status/constraint. But provisonnal booking is not a mandatory step in BUC-B
- **Group quotation with dedicated group process**
-1. The TRANSPORT CUSTOMER is welling to purchase for a group of travellers, larger than what it is proposed in the catalogue. He submits a specific group offer request, for example, by email for a group quotation (specific channel).
-2. The retailer sends the request to relevant distributor(s), including group-related contraints. The purchase process is put on hold while awaiting the quotation (step 6).
-3. An agent or several agents prepare the quotation and reply, for example, by email to the request. The purchase process then continues.
-- **Effective reservation during shopping**
-1. The TRANSPORT CUSTOMER adds in his TRAVEL BASKET a CUSTOMER OFFER PACKAGE with a reservation. For this reservation a reservation-related process must be started in order to continue shopping on a consistent basis.
-2. The retailer temporary leaves the the current use case and start reservation process as described in next use case with the relevant distribtor(s) using the current state of the affected CUSTOMER OFFER PACKAGE(s).
-3. When the reservation is executed; only to secure the TRAVEL BASKET content for continuation of the shopping process, the retailer returns to the shopping process and updates the logical TRAVEL BASKET accordingly.
-7. The retailer presents the updated TRAVEL BASKET state to the TRANSPORT CUSTOMER, including the consequences of the reservation-related process on the concerned TRAVEL BASKET ELEMENT(s) and on the basket as a whole.
-8. The TRANSPORT CUSTOMER may then continue the shopping process, following presetn use case.
+> **Comment (Vinke, Bob BGH, 2026-05-07):**
+> see comment on "offer hold" if a provisional booking is needed, use case C comes in
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Added in step 2
+This is an example of group quotation flow; it is not mandatory for all implementations.
+1. The Customer is welling to purchase for a group of travellers, larger than what it is proposed in the catalogue. The Customer submits a specific group offer request, for example, by email for a group quotation (specific channel).
+2. The Retailer sends the request to relevant Distributor(s), including group-related constraints. If the quotation can be returned immediately, it is handled like a standard offer in the main scenario; otherwise, the process may put on hold while awaiting the quotation. If providing the group quotation requires a provisional booking / capacity hold, the Retailer triggers BUC-C for the concerned elements; otherwise, this remains a quotation-validity hold within BUC-B.
+3. Out of EUDIT scope: An agent or several agents may prepare the quotation and reply, for example, by email to the request. In EUDIT scope: The purchase process then continues when a quotation result is made available to the Retailer and can be used to update or create the relevant offer (CUSTOMER PURCHASE PACKAGE, TRAVEL BASKET ELEMENT).
-- **Mandatory Co-sale**
-1. The TRANSPORT CUSTOMER adds, modifies or removes one TRAVEL BASKET ELEMENT, but this operation affects another TRAVEL BASKET ELEMENT because of a dependency rule, a bundle rule, or a mandatory co-sale condition.
-2. The retailer sends the relevant update request to the concerned distributor(s) and asks for the consequences of this operation on the other TRAVEL BASKET ELEMENT(s). The purchase process is temporarily blocked while awaiting the dependency evaluation.
-3. The distributor(s) return the consequences of the operation, for example repricing, invalidation, deletion, replacement or the need to add another element.The retailer informs the TRANSPORT CUSTOMER of these consequences and asks for confirmation.
-5. If the TRANSPORT CUSTOMER accepts the consequences, the basket is updated and the purchase process continues. If he rejects them, the previous basket state is preserved.
+> **Comment (Juanjo Quesada, 2026-04-24):**
+> Is this EUDIT scope?
+> **Comment (Bourdelin, Sonia [2], 2026-05-05):**
+> I think yes for the feature but not the API to send mail nor agent work. Reformulated
-### Diagram
+- **Effective reservation during shopping ( if required to continue)**
+1. When required for continuity, adding a basket element triggers the need for reservation/hold handling for that element. (SPOT ALLOCATION / SPOT RESERVATION).
+2. The retailer starts reservation process in parallel as described in BUC-C.
+3. When the reservation is executed, the Retailer returns to the shopping process and updates the basket accordingly.
+7. The Retailer presents the updated basket state to the Customer, including the consequences of the reservation-related process.
+
+- **Mandatory co-sale**
+1. The Customer adds, modifies or removes one basket element, but this operation affects another element due to a dependency rule, a bundle rule, or any mandatory co-sale rule (throughfares management).
+2. The Retailer sends the relevant update request to the concerned distributor(s) and asks for the consequences of this operation on the other basket element(s).
+3. The Distributor(s) return the consequences of the operation, for example repricing, invalidation, deletion, replacement or the need to add another element. The Retailer informs the Customer of these consequences and asks for confirmation.
+5. If the Customer accepts the consequences, the basket is updated, and the purchase process continues. If he rejects them, the previous basket state is preserved.
+
+### Diagram
UML activity diagram
-
+
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> To update
### Links with inputs
wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx
wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
To be completed
-
-
diff --git a/wiki/use-cases/business-use-cases/buc-d-pay.md b/wiki/use-cases/business-use-cases/buc-d-pay.md
index 95f81a5..c8815c9 100644
--- a/wiki/use-cases/business-use-cases/buc-d-pay.md
+++ b/wiki/use-cases/business-use-cases/buc-d-pay.md
@@ -1,245 +1,393 @@
+In review – version 2
## Use Case Overview
-- **Business Use Case ID & Name:** BUC-D — Pay your CUSTOMER PURCHASE PACKAGE(s)
-- **Goal (Objective):** Enable the TRANSPORT CUSTOMER to pay one or more CUSTOMER PURCHASE PACKAGE(s), possibly provided by several DISTRIBUTOR(s), through a coherent customer-facing payment process, while allowing different payment architectures: retailer-side payment, distributor-side payment, shared payment, or payment through a PAYMENT PROVIDER.
+- **Business Use Case ID & Name:** BUC-D — Pay for one or more selected offers
+- **Goal (Objective):** Enable the Buyer to pay for one or more selected offers (CUSTOMER PURCHASE PACKAGEs), possibly provided by several Distributors, through a coherent customer payment experience managed by Retailer, while supporting different payment architectures (retailer-side payment, distributor-side payment, shared payment, or payment via a third-party payment provider (PAYMENT PROVIDER, PAYMENT PROVIDER ROLE)).
-- **Scope:** CUSTOMER OFFER PACKAGE completion with CHARGING MOMENT and PAYMENT METHOD confirmation/ PRICE update is necessary / dependency management between TRAVEL BASKET ELEMENTs / PAYMENT METHOD update / coordination between Retailer, Distributor and Payment Provider / payment result consolidation / payment proof and billing information / ready for next use case (fulfilment).
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> This wording avoids talking about the commercial business object on retailer side, commonly called «order». No debate about «travel package». That is smart. No problem with that. But we shall tackle that one day or another.
----
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> And for me, the retailer is first and foremost a merchant, which collects payments. Thus, The customer pays rather basket elements. These basket elements could be CPP, or not. It can manage one single payment for CPP + newspapers + goodies + …
+> In other words, the retailer transforms CPP from the Distributor into its own business objets: basket elements. Then collects payments for that and that is the end of the life cycle of these basket elements (when CPP becomes fare contracts on distributor side).
-## Terminology note — TRAVEL BASKET, TRAVEL BASKET ELEMENT, SALES TRANSACTION and order
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Rewritten to match with the business vocabulary used in BUC-A and BUC-B version 2 (Buyer, offer). For ‘order’, it will be used interbally to retailer. See chapter Terminology)
-At the beginning of this use case, the TRANSPORT CUSTOMER may still manage a **locked TRAVEL BASKET** containing one or more **TRAVEL BASKET ELEMENT(s)**, still part of the shopping/purchase preparation state. Each TRAVEL BASKET ELEMENT contains one CUSTOMER PURCHASE PACKAGE, as defined in BUC-B.
+- **Scope** (Summary):
+ - offer completion/ confirmation with confirming payable content, charging timing (CHARGING MOMENT) and accepted payment means (PAYMENT METHOD)
+ - final payable amount refresh if needed (fees, taxes, expiry/TTL, charging milestones) (PRICE)
+ - coordination management between Retailer, Distributor(s) and Payment Service Provider(s) (TRAVEL BASKET ELEMENTs / PAYMENT METHOD)
+ - payment execution (authorisation/capture/settlement trigger depending on method)
+ - payment results consolidation per selected offer and for the overall purchase
+ - payment proofs and billing information
+ - confirm purchase record (SALES TRANSACTION) for next use case (BUC-E fulfilment).
-The term **order** is not defined as a reference business concept in Transmodel. It may be implemented from the moment the purchase has been confirmed sufficiently (and "order" may be already pre-created at the beginning of the use-case). It may be explicitly used by a local implementation or by an external retailing system.
-Instead, the appropriate Transmodel concept to use when the purchase is confirmed is **SALES TRANSACTION**. A SALES TRANSACTION should be used from the moment the customer has validated the basket and the sale is sufficiently confirmed to be recorded by the Retailer :
+## Terminology note: basket, basket element, purchase record and order
+
+At the beginning of this use case, the TRANSPORT CUSTOMER may still manage a **locked** validated basket (TRAVEL BASKET) containing one or more basket element (TRAVEL BASKET ELEMENT), still part of the shopping/purchase preparation state. Each basket element contains one offer (CUSTOMER PURCHASE PACKAGE), as defined in BUC-B.
+
+The term **order** is not defined as a reference business concept in Transmodel. It may be implemented from the moment the purchase has been confirmed sufficiently (and "order" may be already pre-created at the beginning of the use-case). It may be explicitly used by a local implementation or by an external retailing system. Instead, the appropriate Transmodel concept to use when the purchase is confirmed is SALES TRANSACTION, named purchase record in the following document. A purchase record should be used from the moment the Buyer has validated the basket and the purchase is sufficiently confirmed (has reached a sufficiently binding state; typically after successful payment confirmation) to be recorded by the Retailer :
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Add: on retailer side
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> In 80% cases. Added : has reached a sufficiently binding state; typically after successful payment confirmation)
- the TRAVEL BASKET becomes the purchase input;
- - each TRAVEL BASKET ELEMENT contributes to the confirmed purchase;
+ - each TRAVEL BASKET ELEMENT contributes to the confirmed purchase content;
- each CUSTOMER PURCHASE PACKAGE remains traceable;
- the confirmed sale is represented by a SALES TRANSACTION;
- - payment may be associated with the SALES TRANSACTION and/or the CUSTOMER PURCHASE PACKAGE(s).
+ - payment may be associated with the SALES TRANSACTION and, indirectly, with the reference of CUSTOMER PURCHASE PACKAGE(s).
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Associated rather with Basket Elements (which are bound to CPP). If transmodel does a direct like with CPP, then I think it is an error.
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Yes, the payment is associated with basket element, not directly with CPP.
+> Reformulated to keep the tracability
+
+In this use case, **basket / basket element** is used when describing the payment process until payment validation, and purchase record is used after the payment validation. However, this may vary depending on the system. The confirmed sale should be represented by purchase record created or confirmed only when the purchase has reached a sufficiently binding state, typically after successful payment validation.
-In this use case, **TRAVEL BASKET / TRAVEL BASKET ELEMENT** is used when describing the payment process until payment validation, and **SALES TRANSACTION** is used after the payment validation. However, this may vary depending on the system. The confirmed sale should be represented by SALES TRANSACTION, created or confirmed only when the purchase has reached a sufficiently binding state, typically after successful payment validation.
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Ok, so retailer’s order (like the one from Amazon) = sales transaction in Transmodel ?That is not intuitive at all, but since the management of the retailer’s order is pure internal process of the retailer, that is not a problem here for EUDIT.
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Yes, not perfect matching between business voc and Transmodel voc. Order on some system covers also post payment actions (delayed card building, …).
## Actors & Context
- **Primary Actors:**
- - **TRANSPORT CUSTOMER (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)):** wants to pay with his chosen PAYMENT METHOD(s) a consistent basket suited to his TRAVEL, for himself and/or for other travellers and receive all proofs of payment.
- - **Payment Service Provider (PSP) (PAYMENT PROVIDER ROLE (API not managed by EUDIT project)):** Executes or supports the payment transaction. The PSP :
+ - Buyer (TRANSPORT USER ROLE including TRANSPORT CUSTOMER ROLE and PURCHASER ROLE (represented by the retailer)): wants to pay with his chosen payment method(s) (PAYMENT METHOD(s)) and receive all proofs of payment for himself and/or for other travellers.
+ -
+ -
+ -
+ -
+- Other end-customer Actor: Traveller: the person(s) who will actually travel and use the entitlement. The Traveller and the Buyer can be the same person but not always.
+- **Supporting Actors / Stakeholders:**
+ - **Retailer** (FARE PRODUCT RETAILER ROLE (API consumer)): orchestrates the shopping flow and customer interaction, presents the payable basket to the Buyer and may manage a logical and/or technical basket (basket consistency, requests sent to one or more Distributors). The Retailer can manage the interface with the bank (Payment Provider), coordinates the payment and keeps coherent the purchase process during payment.
+ - **Distributor** (FARE PRODUCT DISTRIBUTOR ROLE (API provider)): Provides or confirms the business data needed for payment. The Distributor may confirm payable amount, charging timing (CHARGING MOMENT(s)) with time limit(s), payment means (PAYMENT METHOD(s)) from a business point of view (payment method restrictions may be provided when applicable, but are not assumed mandatory in all cases). The Distributor confirms reservation, holding, ancillary or guarantee status (next use case). The Distributor indicates whether payment must be completed before final confirmation and applies business consequences of payment success, failure or expiry.
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Change into «may confirm».
+> In some business cases, the distributor is not in position to force any accepted payment methods. For example, a Travel Agency (retailer) can collect payments without refering to any distributor rule.
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Yes, changed. The Distributor only needs a business confirmation that payment conditions are satisfied
+ - Payment Service Provider (PSP) (PAYMENT PROVIDER ROLE (API not managed by EUDIT project)): Executes or supports the payment transaction. The PSP :
- authorises, captures, rejects, secures, schedules or confirms payment;
- may manage card payment, account debit, voucher, wallet, loyalty redemption, travel account debit or other payment instruments;
- returns the payment transaction result to the responsible Retailer and/or Distributor.
-- **Supporting Actors / Stakeholders:**
- - **Retailer (FARE PRODUCT RETAILER ROLE (API consumer)):** manages the shopping flow and customer interaction, presents the payable TRAVEL BASKET to the TRANSPORT CUSTOMER and may manage a logical and/or technical basket (basket consistency, requests sent to one or more distributors). He can manage the interface with the bank (Payment Provider), coordinates the payment and keeps coherent the purchase process during payment.
- - **Distributor (FARE PRODUCT DISTRIBUTOR ROLE (API provider)):** Provides or confirms the business data needed for payment of the CUSTOMER PURCHASE PACKAGE(s). The Distributor confirms payable amount (based on PRICE(s) calculation) and CHARGING MOMENT(s) with time limit(s), confirms accepted PAYMENT METHOD(s) from a business point of view and confirms reservation, holding, ancillary or guarantee status (next use case). He - indicates whether payment must be completed before final confirmation and applies business consequences of payment success, failure or expiry.
-
-
-- **Assumptions (context at start):**
+- **(context at start):**
- The TRANSPORT CUSTOMER can provide the additional information required to pay for the selected offer(s).
- - The PAYMENT PROVIDER ROLE may be performed, for each CUSTOMER PURCHASE PACKAGE, by:
- - the Retailer or the Distributor;
- - a third-party PSP (can be a bank, a travel account provider, a voucher provider, a loyalty provider,...)
- - or another delegated payment system.
- - The interfaces with the banks and the Payment Service Provider equipment(s) are available.
- - Depending on the implementation, each payment operation may be executed:
- - only in a retailer side;
- - only in a distributor side; or
- - in a third-party system.
- - The use case is PSP implementation-neutral and therefore specifies the required business entries and results, not the internal technical bank exchange.
+ -
+ -
+ -
----
+> **Comment (Juanjo Quesada, 2026-05-29):**
+> Should also be included or fere HOW to release the BASKET andtheir elements??
+ - or another delegated payment system.
+ - The interfaces with the banks and the Payment Service Provider equipment(s) are available.
+ - Depending on the implementation,
+ -
+ -
+ -
+ -
+ -
## Preconditions & Postconditions
-- **Preconditions (must be true before start):**
- - The TRANSPORT CUSTOMER has already completed one or more CUSTOMER PURCHASE PACKAGE(s) in the previous use case. They are ready for payment.
- - The relevant payment processing system(s) of each TRAVEL BASKET ELEMENT are identified and can be accessed.
+- Assumptions and **Preconditions (must be true before start) :**
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> To be added:
+> (or in BUC-C ?) The customer has been informed by the retailer of any additional service provided by the retailer like insurance or extension of aftersales conditions. If the customer wants to purchase them, these products become basket elements and change the total price of the basket.
+> The customer has been informed by the retailer of any extra fees independent of Distributor’s rule or fare product.
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> First point : treated as basket element but mention here because they are not «offer» (coming from distributor catalogue) => mention here in BUC-D
+> Second point : it impacts the final amount to pay.
+> => added in point 2 in main scenario, added precision in point 3, point 4
+ - The Buyer has already one or more selected offers ready to be paid, represented in the logical basket (TRAVEL BASKET, TRAVEL BASKET ELEMENT, CUSTOMER PURCHASE PACKAGE).
+ - The Retailer can access the relevant Distributor(s) for payable confirmation and can access the relevant PSP(s) for payment execution.
- The Distributor’s selling system and related pricing rules (with time limits) with dependency information are available (online service or accessible dataset).
- - The TRANSPORT CUSTOMER context needed to continue the purchase is available or can be entered, including traveller data, rights, options, delivery data, invoicing data or VAT context where required.
- - Refunds, compensation, voucher issuance after refund and other after-sales processes are out of scope of present BUC and are handled in use cases **F** and **J** dedicated to after-sales. But they refers to the same PSP interactions and APIs.
+ - The Buyer context needed to continue the purchase is available or can be entered, including traveller data, rights, options, delivery data, invoicing data or VAT context where required.
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> use case C
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Yes, it is platform fees and other addtional services that can be added
+ - Any additional Retailer-provided payable items (e.g. platform fees, delivery fees, optional services such as extended conditions/insurance when applicable) are disclosed to the Buyer and included in the payable summary if purchased.
+ - Refunds, compensation, voucher issuance after refund and other after-sales processes are out of scope of present use case and are handled in BUC-**F** and BUC-**J** dedicated to after-sales. But they refer to the same PSP interactions and APIs.
+ - The PAYMENT PROVIDER ROLE may be performed, for each payment, by:
+ - the Retailer or the Distributor;
+ - a third-party PSP (can be a bank, a travel account provider, a voucher provider, a loyalty provider,...)
+ - The use case is PSP implementation-neutral and therefore specifies the required business entries and results, not the internal technical bank exchange. Each payment operation may be executed only in a retailer side; only in a distributor side; or in a third-party system.
+ -
- **Postconditions — Success guarantees:**
- - Each CUSTOMER PURCHASE PACKAGE has a payment status, consolidated and given to TRANSPORT CUSTOMER by the Retailer.
+ - Each basket element has a Retailer payment status and proofs (receipt, invoice, payment terms, payment schedule, confirmation where applicable), consolidated in a global outcome and given to Buyer by the Retailer. Each concerned Distributor receives only the minimum confirmation required to proceed (e.g. ‘ok to fulfil’), without necessarily receiving proof that the Buyer paid via the Retailer’s PSP.
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Basket elements on retailer’s side have a payment status. CPP on distributor’s side have a status bound to their final confirmation.
+> As an example, a distributor doesn’t know if a basket element has been really paid by the customer of a travel agency, the distributor only knows that all is ok, that he can proceed to fulfilment and that the settlement process will be ok.
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Clarified that retailer manages the TB element status and the distributor only knows about the offer if the pyment is confirmed or not and the fullfilment should be done or not
- The basket state presented to the customer is consistent, regardless of whether the underlying implementation relies on a retailer basket, a distributor basket, or coordinated baskets across both.
- - This use case ends when the TRAVEL BASKET is ready for the next step; payment status is known.
- - Reservation, option, seat, ancillary, service or guarantee depending on payment will be finalized according to Distributor rules in Business Use Case E.
- - The TRANSPORT CUSTOMER receives the appropriate proof(s): receipt, invoice, payment terms, payment schedule, confirmation. Fulfilment is managed in Business Use Case E (access to TRAVEL DOCUMENT(s)).
+ - This use case ends when the basket is ready for the next step; payment status is known.
+ - Reservation, option, seat, ancillary, service or guarantee depending on payment will be finalized according to Distributor rules in BUC-C.
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> I would say Use case C
+
+> **Comment (Bourdelin, Sonia [2], 2026-05-10):**
+> yes, changed
+ - Fulfilment (travel rights / documents) is managed in BUC-E (access to TRAVEL DOCUMENT(s)).
- **Postconditions — Minimal guarantees:**
- - If the TRANSPORT CUSTOMER abandons the process or no suitable payment solution is found, the TRAVEL BASKET may remain as it is for a delay. The purchase process is suspended or ended.
+ - If the Buyer abandons the process or no suitable payment solution is found, the Retailer preserves or updates the basket state as applicable, and prevents continuation for impacted basket elements until resolved.
- The Distributor indicates which payment part remains held, is released, is cancelled, is partially cancelled or requires revalidation.
- - The Retailer consolidates the TRAVEL BASKET state and prevents fulfilment if a required payment condition is not met.
- - If funds or accounting information must be distributed, cleared or reconciled between the Retailer and one or more Distributor(s) are described in Business Use Case K.
+ - The Retailer consolidates the basket state and prevents fulfilment if a required payment condition is not met.
+ - If funds or accounting information must be distributed, cleared or reconciled between the Retailer and one or more Distributor(s) are described in BUC-K.
- The TRANSPORT CUSTOMER actions can be logged/audited (if required by the system).
- - If many CUSTOMER PURCHASE PACKAGE(s) are involved, allocation remains traceable per Distributor, SALES TRANSACTION, payment instrument and settlement rule.
-
----
-
+ - If many basket elements are involved, allocation remains traceable per Distributor, purchase record, payment instrument and settlement rule.
## Scenarios
### Main scenario
-1. The TRANSPORT CUSTOMER shall start this use case after the preceding shopping and reservation phases, when one or more CUSTOMER PURCHASE PACKAGE(s) have been selected, parameterised, inserted into a TRAVEL BASKET and locked or stabilized for payment. At this moment, it may remain elements that modify the final payment : shipping costs, payment method fees, CHARGING MOMENT, Retailer platform feees or promotions and operation fees (by example : after-sales fees).
+1. The Buyer shall start this use case after the preceding shopping and, when required, reservation phases. One or more offers have been selected, parameterised, inserted into a basket and locked or stabilized for payment. At this moment, it may remain basket elements that modify the final payment: shipping costs, payment method fees, charging timing, Retailer platform fees or promotions and operation fees (by example: after-sales fees).
- **Payment options choice**
-2. The Retailer presents to the TRANSPORT CUSTOMER a summarized payable view :
- - CUSTOMER PURCHASE PACKAGE(s) to be paid;
- - PRICE of each and total amount for the current options;
- - selected or available PAYMENT METHOD(s);
- - CHARGING MOMENT(s);
- - payment deadline(s) or milestones for group purchase;
- - fees, taxes and currency(s) information including available shipping possibilities and operation fees;
- - any deferred amount or future instalment amount, where applicable;
- - main conditions attached to payment, linked to deferred payment, B2B invoicing or corporate approval;
- - main consequences of payment failure or expiry.
-
-3. The TRANSPORT CUSTOMER selects and/or confirms the PAYMENT METHOD(s) and options.
-4. If required, the Retailer and/or Distributor shall refresh the final payable PRICE before payment confirmation and present the updated state to TRANSPORT CUSTOMER, especially if:
- - the locked validity period is close to expiry or one or more component deadlines are close to expiry;
- - one or many options changes the final amount to pay. (PAYMENT METHOD, taxes, invoicing, delivery, corporate rules or currency conversion affect the payable amount).
-
-- **Distributor and PSP contraints synchonization**
-5. For each concerned Distributor, the Retailer verifies and confirms:
- - CUSTOMER PURCHASE PACKAGE identifier;
- - final PRICE and currency;
- - taxes and invoicing constraints;
- - CHARGING MOMENT(s);
- - accepted PAYMENT METHOD(s);
- - payment time limits;
- - holding or reservation status;
- - rule in case of payment success;
- - rule in case of payment pending, failure or expiry;
- - whether the Distributor requires payment execution by a specific Payment Provider.
+2. The Retailer provides to the Buyer a payable summary including :
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> «may present»
+> We cannot interfere with the UX/UI of the retailer, but I understand that the underlying objective is to be sure that the distributor has provided all related data.
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Yes reformulated
+ - basket elements to pay,
+ - current price (PRICE) of each and total amount for the current options,
+ - selected or available payment method(s) (PAYMENT METHOD(s)),
+ - charging timing (CHARGING MOMENT(s)),
+ - payment deadline(s) or milestones for group purchase,
+ - fees, taxes and currency(s) information including available shipping possibilities and operation fees,
+ - any deferred amount or future instalment amount, where applicable,
+ - main conditions attached to payment, linked to deferred payment, B2B invoicing or corporate approval,
+ - main consequences of payment failure or expiry.
+The payable summary also includes any Retailer-provided payable items (e.g. insurance, extended after-sales conditions) and any Retailer fees independent of Distributor rules (e.g. platform/service fees, payment method fees, delivery/shipping fees where applicable), clearly identified as Retailer items and included in the total amount.
+
+3. The Buyer selects and/or confirms the payment method(s) and any payment options (split payment, voucher, corporate invoicing, instalments) including any Retailer-provided items/fees when applicable where applicable.
+4. If required, the Retailer and/or Distributor shall refresh the final payable amount before payment confirmation and present the updated state to Buyer, especially if:
+ - the locked validity period is close to expiry, or one or more component deadlines are close to expiry (charging milestone);
+ - one or many options changes the final amount to pay. (payment method, taxes, invoicing, delivery, corporate rules or currency conversion affect the payable amount),
+ - Retailer fees or selected Retailer add-ons change the payable amount.
+
+- **Distributor and PSP** constraints synchronization
+5. For each concerned Distributor, the Retailer verifies and confirms the payable constraints:
+ - identifiers,
+ - final amount and currency,
+ - taxes and invoicing constraints,
+ - charging timing,
+ - accepted payment methods,
+ - payment time limits,
+ - holding or reservation status,
+ - rule in case of payment success,
+ - rule in case of payment pending, failure or expiry and
+ - whether the Distributor requires payment execution by a specific Payment Provider.
6. Each Distributor returns the payable state and any payment-related constraints.
-7. The Retailer consolidates all Distributor responses into one coherent payment proposal for the TRANSPORT CUSTOMER. The Retailer also determines and manages the payment architecture : he identifies, for each CUSTOMER PURCHASE PACKAGE, which entity performs the PAYMENT PROVIDER ROLE:
- - Retailer-side Payment Provider;
- - Distributor-side Payment Provider;
- - third-party Payment Provider;
- - shared or mixed architecture.
-
-8. The TRANSPORT CUSTOMER may select one or mixed PAYMENT METHOD(s) that may include, when applicable :
- - bank card or other card-based payment;
- - SEPA direct debit or similar mandate-based debit;
- - wallet or account-based payment (can be on Retailer's system);
- - travel account debit;
- - voucher or travel credit;
- - miles, points or loyalty redemption;
- - corporate account or B2B invoicing arrangement;
- - cash or point-of-sale payment;
- - split payment across several means of payment; or
- - scheduled payment for deferred charging or instalments.
- Depending on the business rules, payment (and additional data) may be:
- - immediate, with direct authorisation and capture or delayed, with deferred capture or later debit;
- - split into several CHARGING MOMENT(s);
- - made by instalments according to a payment plan;
- - made by one single payment for several CUSTOMER PURCHASE PACKAGE(s);
- - verifies for particular PAYMENT METHOD (voucher, loyalty points, B2B, travel credit) with the relevant provider a particular confirmation process;
- - made by travel account debit or B2B invoice/settlement arrangement; or
- - combined with voucher, loyalty redemption or other PAYMENT METHOD(s).
-
-9. The retailer shall verify, with the relevant PSP, that the selected PAYMENT METHOD(s) are accepted for:
- - the concerned CUSTOMER PURCHASE PACKAGE(s);
- - the concerned distributor(s);
- - the TRANSPORT CUSTOMER context;
- - the country, currency and tax context;
- - the amount and charging rule;
- - the requested CHARGING MOMENT; and
- - the applicable payment deadline.
- And request to TRANSPORT CUSTOMER additional information (payer identity, billing address, invoice data, VAT number or corporate identifier, travel account identifier, voucher or travel credit reference, loyalty identifier, mandate consent, card or account credentials, strong customer authentication data, instalment acceptance conditions). The TRANSPORT CUSTOMER may see only one unique mayment (MarketPlace case) and later, the Retailer distributes, settles or reconciles the corresponding amounts with several distributor(s) according to commercial agreements (see Business Use Case K).
+7. The Retailer consolidates all Distributor responses into one coherent payment proposal for the Buyer. The Retailer also determines and manages the payment architecture: he identifies, for each basket element, who performs the PSP role (
+ - Retailer-side
+ - , Distributor-side,
+ - third-party PSP,
+ - shared).
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> part of use cse C
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Here, it is refresh of payment amount linked with payment means that are updated for any reason linked with the payment, not linked with the reservation
+
+8. The Buyer may select one or mixed payment methods that may include, when applicable :
+ - bank card or other card-based payment;
+ - SEPA direct debit or similar mandate-based debit;
+ - wallet or account-based payment (can be on Retailer's system);
+ - travel account debit;
+ - voucher or travel credit;
+ - miles, points or loyalty redemption;
+ - corporate account or B2B invoicing arrangement;
+ - cash or point-of-sale payment;
+ - split payment across several means of payment; or
+ - scheduled payment for deferred charging or instalments.
+Depending on the business rules, payment (and additional data) may be:
+ - immediate, with direct authorisation and capture or delayed, with deferred capture or later debit;
+ - split into several charging timings;
+ - made by instalments according to a payment plan;
+ - made by one single payment for several basket elements/ offers,
+ - verifies for particular payment method (voucher, loyalty points, B2B, travel credit) with the relevant provider a particular confirmation process;
+ - made by travel account debit or B2B invoice/settlement arrangement; or
+ - combined with voucher, loyalty redemption or other payment methods.
+
+9. The retailer shall verify, with the relevant PSP and/or with the relevant Distributor(s) depending on the instrument, that the selected payment methods are accepted for:
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Not always for voucher, if the voucher is published by the operator. In that case, the retailer shall check with the distributor if the voucher is compatible with Travel basket elements, if the voucher is still valid and the amount taken by the voucher, which is subtracted from the total basket price.
+>
+> Would the management of operator’s voucher deserve a dedicated section ?
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Voucher management added
+ - the concerned offers,
+ - the concerned distributor(s),
+ - the Buyer context,
+ - the country, currency and tax context,
+ - the amount and charging rule,
+ - the requested charging timing,
+ - the applicable payment deadline.
+And request to Buyer additional information (payer identity, billing address, invoice data, VAT number or corporate identifier, travel account identifier, voucher or travel credit reference, loyalty identifier, mandate consent, card or account credentials, strong customer authentication data, instalment acceptance conditions).
+For operator-issued vouchers, the Retailer verifies with the Distributor: voucher validity, compatibility with the concerned basket elements, and deductible amount.
+The Buyer may see only one unique payment (MarketPlace case) and later, the Retailer distributes, settles or reconciles the corresponding amounts with several distributor(s) according to commercial agreements (see BUC-K).
- **Architecture Retailer-side payment**
-10. The Retailer, acting directly or through its Payment Provider, initiates payment for one or more CUSTOMER PURCHASE PACKAGE(s) and receivess the transaction result.
-11. The Retailer sends each concerned Distributor a payment confirmation or payment status notification including:
- - paid amount;
- - payment status, timestamp and reference;
- - CUSTOMER PURCHASE PACKAGE(s);
- - allocation amount and currency;
- - payment instrument type where required for audit, invoicing or after-sales.
-12. Each Distributor verifies that the payment status satisfies its business rule and returns the component result (confirmed / pending / rejected / expired / revalidation required).
-13. The Retailer consolidates Distributor responses and updates the TRAVEL BASKET.
-
-- **Architecture Distributor-side payment**
-
-14. The Distributor indicates that payment must be executed through its own Payment Provider or delegated payment process. The Retailer sends the required payment initiation context to the Distributor.
-15. The Distributor, acting with its PSP, initiates payment, receives the transaction result from the Payment Provider.
-16. The Distributor returns the payment result and status to the Retailer:
- - paid and confirmed;
- - paid but fulfilment pending;
- - payment pending / refused / expired / cancelled;
- - revalidation required.
-17. The Retailer consolidates Distributor responses and updates the TRAVEL BASKET.
+10. The Retailer, acting directly or through its Payment Provider, initiates payment for one or more basket elements and receives the transaction result. The Retailer checks that the payment result has been obtained within the applicable business validity/time limits for each concerned basket element. If a time limit is breached, the Retailer flags the impacted element(s) as expired/revalidation-required and does not treat them as confirmed.
+11. The Retailer may notify each concerned Distributor a payment confirmation or payment status notification and may include in the flow :
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Not necessarily. «may send»
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Yes corrected
+ - paid amount only if required by Distributor business rules;
+ - payment status, timestamp and reference;
+ - paid basket elements identifiers / offers;
+ - allocation amount and currency if required;
+ - payment instrument type where required for audit, invoicing or after-sales (No PSP instrument details unless legally required/agreed.).
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> to much information to share with Distributor
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Depending on the case. Sentence updated
+12. Each Distributor verifies that the payment status satisfies its business rule and returns a component confirmation where applicable (e.g. “ok to proceed to fulfilment” or “revalidation required”).
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> If the payment is done within the time limit, the only result could be confirmed.. We must make sure before payment that this is always the case
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Time limit management added in point 10
+
+- **Architecture Distributor -side payment**
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> do you have an example?
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> 1 - when the payment UX is implemented as a white-label payment page. The Buyer remains on Retailer web site but the payment is executed on Distributor’s PSP
+> 2 - Single operator shopping web site : the retailer acts as front channel and the Distributor/Operator is the merchant with PSP
+
+13. The Distributor indicates that payment must be executed through its own Payment Provider or delegated payment process. The Retailer sends the required payment initiation context to the Distributor for the concerned basket element(s).
+
+> **Comment (Vinke, Bob BGH, 2026-05-06):**
+> How can this work if there are multiple distributors?
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> For pre-payment, the retailer splits the payment. Old school and not optimised.
+> A post-payment service with NFC smartcard or EMV or Fairtiq-like is rather a operator-side payment
+
+> **Comment (Bourdelin, Sonia, 2026-05-20):**
+> Optional architecure solution. Added exemples to see that is not used/ no more (performance) used in multi-operator context. But widly used in monomodal operator/retailer/distribuor context when the retailer only distributes one operator offers.
+14. The Distributor, acting with its PSP, initiates payment, receives the transaction result from the Payment Provider (authorised/captured/pending/refused and timestamp, depending on the method).
+15. The Distributor checks that the payment result has been obtained within the applicable business validity/time limits and returns the payment result and status to the Retailer:
+ - paid and confirmed when within time limits;
+ -
+ - expired/revalidation required and requests the appropriate next action (refresh/revalidation) before continuation if a limit is breached
+ -
+ -
+ - .
+The Retailer checks business validity/time limits for the concerned basket element(s) before treating them as confirmed, then records the status and consolidates.
+
+In multi-Distributor purchases, Distributor-side payment typically results in split/parallel payments per Distributor; if a single coordinated payment step is required, Retailer-side or shared payment is usually used instead.
+
+Examples: Distributor-side payment may occur:
+- when the Retailer redirects the Buyer to, or embeds, a white-label payment page operated by the Distributor (or its PSP),
+- when the Retailer acts mainly as a front channel (e.g. portal/agent), while the Distributor/Operator is the merchant of record and executes payment through its own PSP (PAYMENT PROVIDER ROLE).
+-
- **Architecture Shared Retailer-Distributor payment**
-20. Some parts should be paid through the Retailer PSP (arhictecture Retailer-side payment) and others through one or more Distributor PSP(s) (architecture Architecture Distributor-side payment). The Retailer and Distributor(s) have agreements on:
- - which CUSTOMER PURCHASE PACKAGE(s) are paid by which Payment Provider;
- - whether the TRANSPORT CUSTOMER sees one payment step or several coordinated payment steps;
- - how mixed PAYMENT METHODs are allocated;
- - how partial success is handled;
- - how payment deadlines are enforced.
- following the architecure of the paiment part, each, Retailer or Distributor, requests for the payment part.
-21. Each PSP returns the transaction result to its requestor. If necessary, each Distributor returns the business status of its paiment part to the Retailer.
-22. The Retailer consolidates all results and updates the TRAVEL BASKET.
+16. Some parts should be paid through the Retailer PSP (architecture Retailer-side payment) and others through one or more Distributor PSP(s) (architecture Distributor-side payment). The Retailer and Distributor(s) have agreements on:
+ - which basket elements are paid by which Payment Provider;
+ - whether the Buyer sees one payment step or several coordinated payment steps;
+ - how mixed payment methods are allocated;
+ - how partial success is handled;
+ - how payment deadlines are enforced.
+following the role repartition, each, Retailer or Distributor, requests for the payment part.
+17. Each PSP returns the transaction result to its requestor. If necessary, each Distributor returns the business status of its payment part to the Retailer.
- **Architecture Third-party Payment Provider**
-23. The Retailer and/or Distributor sends the payment initiation data to a third-party Payment Provider. The Payment is executed or scheduled and the transaction result is returned to his requestor.
-24. The Retailer and Distributor(s) exchange the necessary payment result information so that:
- - every CUSTOMER PURCHASE PACKAGE has a clear payment state;
- - any reservation or holding can be finalized or released;
- - billing and settlement data remain traceable;
- - the TRAVEL BASKET status remains coherent.
-
- - **Payment result**
-25. If mixed payment is used, the Retailer coordinates the authorization and allocation of each part of the payment while preserving one coherent TRAVEL BASKET. Depending on the result, the Distributor may confirms or release reservation elements (see Business Use Case E).
-26. The Retailer consolidates all payment part statuses and informs the TRANSPORT CUSTOMER of the final payment result.
-27. The Retailer and/or Distributor provides the relevant proof of payment (receipt with legal data following rule of each state), invoice, payment terms with installments, and fulfilment trigger. It can be document(s) and/or TRANSPORT CUSTOMER account update or other format.
-28. The Retailer may inform the Distributor(s) with each CUSTOMER PURCHASE PACKAGE data to create/update SALES TRANSACTION(s).
-
+18. The Retailer and/or Distributor sends the payment initiation data to a third-party Payment Provider. The Payment is executed or scheduled, and the transaction result is returned to his requestor.
+19. The Retailer and Distributor(s) exchange the necessary payment result information so that:
+ - every basket element has a clear payment state;
+ - any reservation or holding can be finalized or released;
+ - billing and settlement data remain traceable;
+ - the basket status remains coherent.
+
+- **Payment result**
+20. If mixed payment is used, the Retailer coordinates the authorization and allocation of each part of the payment while preserving one coherent basket. Depending on the result, the Distributor may confirm or release reservation elements (see BUC-E).
+21. The Retailer consolidates all payment part statuses (Distributor/third-party) responses into one coherent purchase outcome for the Buyer.
+
+22. The Retailer and/or Distributor provides the relevant proof of payment (receipt with legal data following rule of each state), invoice, payment terms with instalments, and fulfilment trigger. It can be document(s) and/or Buyer account update or another format.
+23. The Retailer may inform the Distributor(s) with each basket element data to create/update confirmed purchase record.
### Alternatives scenarios
Alternative scenarios **fully compatible** with the main scenario; using shortcuts or very detailed specific points of the main scenario.
## Payment failure
1. One payment part fails or expires.
-2. The Retailer receives the failure or expiry status from the Distributor or PSP.
-3. The Distributor indicates the consequence for the impacted CUSTOMER PURCHASE PACKAGE.
-4. The Retailer either asks for another PAYMENT METHOD, requests revalidation, or informs the TRANSPORT CUSTOMER that the purchase cannot continue.
+2. The Retailer receives the failure or expiry status from the Distributor or PSP with
+indications of the consequence for the impacted basket element(s).
+3. The Retailer either asks to retry with another payment method and/or requests revalidation or informs the Buyer that the purchase cannot continue with the impacted basket element(s).
## Negative amount
-1. The resulting financial amount is negative.
-2. No TRANSOPRT CUSTOMER payment is collected in BUC-D.
-3. The Retailer redirects the case to Business Use Case F or J for refund, compensation, credit note or voucher handling.
-## Payment after approval
-1. A corporate or group purchase requires approval before payment.
-2. The Retailer asks the Distributor(s) whether the quotation can remain valid until approval.
+> **Comment (Bourdelin, Sonia [2], 2026-05-27):**
+> Manage refund here as a negative payment
+1. The resulting financial amount is negative so
+no Buyer payment is collected in this use case.
+2. The Retailer redirects the case to BUC-F or BUC-J for refund, compensation, credit note or voucher handling.
+
+## Payment after approval (corporate / group)
+1. A corporate or group purchase requires approval before payment: the payment is delayed by an approval requirement
+2. The Retailer may request the Distributor(s) with quotation validity extension where supported.
3. Once approval is obtained, the Retailer restarts the payment coordination flow.
4. If the deadline has expired, the Distributor requires refresh, revalidation or repricing.
## Zero amount to pay
-1. If the payable amount for the current CHARGING MOMENT is equal to zero, the payment use case shall still be executed as a zero-payment confirmation flow.
+1. If the payable amount for the current charging moment is equal to zero, the payment use case may be executed as a zero-payment confirmation flow or the Retailer may skip PSP execution when allowed by business/technical rules, while still confirming with Distributors.
+
+> **Comment (BIGEX Olivier, 2026-05-12):**
+> Not necessarily. It is a solution (payment of zero Euro). But another way to confirm a free CPP is simply to skip the payment step and proceed to next BUC
+
+> **Comment (Bourdelin, Sonia, 2026-05-19):**
+> Yes. Two valid options: zero-payment confirmation flow, or skip PSP execution
No monetary transaction is initiated with a Payment Provider, unless a technical payment authorization is required by implementation rules.
2. The Retailer shall confirm with each concerned Distributor that:
- - the total amount due is zero (not necessary the Distributor part => see settlement in Business Use Case K);
- - no PAYMENT METHOD is required, or the required PAYMENT METHOD has already covered the amount;
- - the CUSTOMER PURCHASE PACKAGE can be confirmed without payment;
- - any reservation, ancillary, guarantee or service depending on payment can be finalized.
-3. The Retailer consolidates the statuses and informs the TRANSPORT CUSTOMER that no payment is due.
+ - the total amount due is zero (not necessary the Distributor part => see settlement in Business Use Case K);
+ - no payment mean is required, or it has already covered the amount;
+ - the offer can be confirmed without payment;
+ - any reservation, ancillary, guarantee or service depending on payment can be finalized.
+3. The Retailer consolidates the statuses and informs the Buyer that no payment is due.
4. The Retailer and/or Distributor provides the relevant proof of purchase, zero-amount receipt, invoice if legally required, confirmation and fulfilment trigger.
-
-### Diagram
+### Diagram
UML activity diagram
-
### Links with inputs
-wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx
-wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
+wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.docx wiki/use-cases/inputs/BRM_EUDIT_V2.3.xlsx
To be completed
-
-
diff --git a/wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.md b/wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.md
new file mode 100644
index 0000000..3fc823f
--- /dev/null
+++ b/wiki/use-cases/inputs/EUDIT.use.cases_20260324_shared.md
@@ -0,0 +1,465 @@
+# EUDIT API Use Cases for Indirect Multimodal Travel Distribution
+**Status:** Working Draft – Proposed by Amadeus for discussion in the EUDIT Use Case Working Group
+**Version:** 1 – shared in EUDIT Github on 24 March 20264
+
+## 0. Introduction
+This document presents a structured list of use cases relevant for using EUDIT API in the context of **indirect, multimodal/multi - operator travel distribution**, excluding air transport distribution itself. This list is certainly not exhaustive and is expected to evolve during the EUDIT project.
+The scope explicitly covers:
+- Distribution of **non ‑ air transport services** (rail, coach, ferry, urban and regional transport, ancillary mobility services etc)
+- **Multimodal journeys** combining several modes of transport
+- **Multi ‑ operator journeys**, potentially involving several independent transport operators
+- **Indirect distribution**, where retailers/independent distributors sell services on behalf of operators
+Air transport distribution is **out of scopeas discussed in EUDIT workgroup**. Airlines may appear **only when acting as retailers or distributors of non ‑ air content**.
+EUDIT does **not** standardise commercial rules or business models. Instead, it standardises the **ability to express, request, validate, compare, and lifecycle ‑ manage** journeys, offers, orders, passengers and services across multiple operators, modes and distribution channels.
+Each use case is described using a **common structure**:
+- **Trigger** – what initiates the use case
+- **Description** – functional scope
+- **Actors** – parties involved
+
+## 1. Actors concerned by EUDIT API use cases
+### 1.1 End Customers
+- Traveler / Passenger
+- Booker / Buyer (e.g. corporate travel arranger, family member)
+
+### 1.2 Retailers / Sellers (Distribution side)
+Actors that **interact with EUDIT as clients** of the API:
+- **Independent Travel Intermediary / Retailer**
+ - GDS / Travel Platform
+ - OTA (B2C)
+ - Corporate TMC
+ - Tour Operator
+ - Metasearch / Aggregator
+- **Airline acting as Retailer**
+ - Airline selling multimodal journeys beyond air (rail, transfers, coach, ferry, mobility services, etc.)
+- **Rail Retailer**
+ - National or regional rail retailer
+- **Multimodal Retail Platform**
+ - MaaS platforms
+ - Public transport + long‑distance aggregators
+
+### 1.3 Suppliers / Operators (Content side)
+Actors that **provide inventory, services and conditions**:
+- **Transport Operators**
+ - Rail operators
+ - Coach / bus operators
+ - Ferry / maritime operators
+ - Urban / regional public transport authorities
+ - Mobility providers
+- **Ancillary & Mobility Providers**
+ - Seat / comfort / luggage services
+ - PRM assistance providers
+ - First/last mile mobility (taxi, ride‑hailing, micromobility)
+- **Station / Airport Operators** (where relevant)
+- **Infrastructure Managers** (where relevant for disruption data)
+
+### 1.4 Financial & Settlement Actors
+- **Payment Service Providers (PSP)**
+- **Clearing & Settlement Bodies**
+ - BSP / ARC ‑like mechanisms (central accreditation, billing and settlement bodies)
+ - Rail or multimodal clearing houses
+- **Invoice Issuers / Tax Authorities**
+- **Insurance / Guarantee Providers**
+ - Travel protection
+ - Missed connection guarantees
+
+### 1.5 Supporting & Regulatory Actors
+- **Regulatory Authorities**
+- **Passenger Rights Enforcement Bodies**
+- **Data Providers**
+ - Timetables, fares, disruptions, accessibility, CO₂ data
+### 1.6 Channel / Access Path (non‑actors)
+- **Rail operator website**
+- **Airline.com (when distributing non airtransport)**
+- **Mobile app**
+- **Self ‑ Booking Tool (Corporate OBT)**
+- **Call center / assisted sales**
+- **Metasearch redirect**
+- **API ‑ to ‑ API (B2B wholesale)**
+### 1.7 Note on automated and AI-driven interactions
+Automated systems, AI agents, or orchestration layers (e.g. MCP‑based agents) are not modeled as actors in EUDIT use cases.
+ They are considered delegated execution mechanisms or interaction channels, acting on behalf of an accountable actor (traveler, retailer, or operator).
+ All contractual, commercial, regulatory, and settlement responsibilities remain with the represented actor. To be checked how we can make the EUDIT API compliant with these interactions
+
+##
+## 2. Passenger, Eligibility & Entitlement Model (Cross‑cutting)
+EUDIT use cases assume the ability to represent passenger attributes consistently **across multiple operators and modes**, without mandating a harmonised taxonomy.
+Passenger categories include (non‑exhaustive): Adult, Child, Infant, Youth/Student, Senior, Unaccompanied Minor, Passenger with Reduced Mobility (PRM), Accompanying Person, Group Passenger, Resident / Reduction Beneficiary.
+Eligibility attributes include age, residency, reduction programs, corporate identifiers, loyalty identifiers, PRM codes and companion linkage, enabling:
+- Correct fare and product mapping per operator
+- Comparison of offers across operators and modes
+- End‑to‑end servicing of multimodal journeys
+
+## 3. Detailed EUDIT Use Cases
+### A. Inspire & Plan
+**UCA1 – Multimodal & Multi ‑ operator Journey Discovery**
+**Trigger:** A traveler or retailer initiates a journey search.
+**Description:** Search journeys across multiple transport modes and multiple operators, including schedules, connections, interchanges, transfer constraints and accessibility attributes.
+Filtering options could be of type: exclude, include, preferably or mandatory
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCA2 – Journey Filtering, Comparison & Ranking**
+**Trigger:** A set of journey options across operators and/or modes is returned.
+**Description:** Filter, compare and rank journeys by price, duration, number of interchanges, mode mix, GHG/CO₂ impact, comfort, accessibility or operator.
+**Actors:** Traveler, Retailer
+
+**UCA3 – Accessibility & PRM Discovery Across Operators**
+**Trigger:** Journey search includes accessibility or PRM requirements.
+**Description:** Retrieve and compare accessibility characteristics and PRM service availability across all journey legs and operators.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCA4 – Fare, Condition & Operator Transparency**
+**Trigger:** Journey options are displayed.
+**Description:** Retrieve and compare fares, fare families, exchange/refund conditions, passenger rights and operator‑specific restrictions.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCA5 – Passenger ‑ aware Multimodal Feasibility Check**
+**Trigger:** Search includes specific passenger types (e.g. PRM, unaccompanied minor, companion).
+**Description:** Validate feasibility of multimodal and multi‑operator journeys against passenger constraints and operator rules, in particular inform of minimum connection times between several modes or operators and inform about accessibility.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCA6 – Radius ‑ based & Multi ‑ location Search**
+**Trigger:** Origin and/or destination is defined as a zone or radius.
+**Description:** Search and compare journeys using multiple nearby stations, stops or terminals across modes.
+**Actors:** Traveler, Retailer
+
+**UCA7 – Time ‑ flexible & Duration ‑ based Journey Search**
+**Trigger:** Traveler specifies time windows or journey duration constraints.
+**Description:** Search and compare journeys matching temporal and duration criteria across operators and modes.
+**Actors:** Traveler, Retailer
+
+**UCA8 – Direct vs Connecting & Mode ‑ mix Filtering**
+**Trigger:** Journey results are available.
+**Description:** Filter journeys by direct vs connecting, single‑mode vs multimodal, or preferred mode combinations.
+Filtering options could be of type: exclude, include, preferably or mandatory
+**Actors:** Traveler, Retailer
+
+### B. Shop & Price
+**UCB1 – Price Quotation / Offer Creation (Multi ‑ operator)**
+**Trigger:** A journey option is selected for pricing.
+**Description:**
+The Retailer requests a price quotation for a journey and receives one or more offers, each including pricing conditions, applicable rules, and a defined validity period (timetolive).
+Each quotation includes a validity period after which the price and/or availability may no longer be guaranteed.
+**Actors:** Retailer, Transport Operators
+
+**UCB2 – Multimodal & Multi ‑ operator Offer Construction**
+**Trigger:** Several legs, operators or modes are combined.
+**Description:** The Retailer constructs a multimodal offer composed of multiple operator products.
+The offer includes:
+- an overall quotation validity period,
+- and, where applicable, componentlevel validity periods reflecting operatorspecific rules.
+The Retailer is informed of the earliest expiry impacting the offer.
+**Actors:** Retailer, Transport Operators
+
+**UCB3 – Offer Construction with Private, Corporate or Reduced Fares**
+**Trigger:** Corporate identifiers, reduction programmes or private fare entitlements are provided.
+**Description:** The Retailer requests and constructs multimodal offers using corporatespecific or negotiated fare products, based on traveler eligibility, corporate agreements, and applicable usage conditions.
+The following parameters/rules could be used in the API:
+- corporate profiles,
+- negotiated fare identifiers,
+- fare visibility rules,
+- policy constraints.
+**Actors:** Retailer, Transport Operators, Corporate Customer
+
+**UCB4 – Pricing & Fare Combination Across Operators**
+**Trigger:** Offer spans multiple operators or fare systems.
+**Description:** The Retailer requests pricing for combined products, including throughfares where available or aggregated prices where not.
+**Actors:** Retailer, Transport Operators
+
+**UCB5 – Offer Hold for Approval (Multimodal)**
+**Trigger:** Deferred decision or approval is required.
+**Description:** The Retailer requests that a quotation remains valid for a defined period to allow internal approval processes.
+The response indicates whether such a holding period is supported and under which conditions.
+**Actors:** Retailer, Corporate Booker
+
+**UCB6 – Quotation Expiry, Refresh & Re ‑ comparison**
+**Trigger:** Offer TTL expires or pricing context changes.
+**Description:** The Retailer is informed when a quotation expires or requests a refreshed quotation, which may result in updated pricing, conditions, or availability.
+**Actors:** Retailer, Transport Operators
+
+**UCB7 – Connection Protection & Guarantee Options**
+**Trigger:** Unprotected multi‑operator or multimodal connections are identified.
+**Description:** Propose optional protection or guarantee services covering operator or mode changes.
+**Actors:** Retailer, Transport Operators, Protection Providers
+
+**UCB8 – Group Travel Offer Request (Multi ‑ operator)**
+**Trigger:** Group size exceeds instant booking thresholds.
+**Description:** The Retailer requests a group travel quotation, including availability constraints, provisional pricing, and validity conditions across one or more operators or modes.
+**Actors:** Retailer, Transport Operators
+
+**UCB9 – Public vs Private Fare Requests Across Operators**
+**Trigger:** Fare type is specified.
+**Description:** Request, validate and compare public, private, resident or reduction fares across operators.
+**Actors:** Retailer, Transport Operators
+
+**UCB10 – One ‑ way, Round ‑ trip & Combinable Multimodal Pricing**
+**Trigger:** Journey structure is defined.
+**Description:** Price one‑way, round‑trip or combinable journeys involving multiple operators or modes.
+**Actors:** Retailer, Transport Operators
+
+**UCB11 – Complex Multimodal Itinerary Pricing**
+**Trigger:** Multi‑city or open‑jaw journey is requested.
+**Description:** Price complex itineraries involving several operators, modes or passenger sets (e.g. companions joins mid-trip).
+**Actors:** Retailer, Transport Operators
+
+**UCB12 – Ancillary Discovery Across Operators (Pricing Only)**
+**Trigger:** Traveler explores optional services.
+**Description:** Retrieve and compare ancillary pricing and conditions (seats, bags, cabins, PRM services) across operators and modes.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCB13 – Seat / Space Availability & Layout Retrieval**
+**Trigger:** Seat, cabin or space options are requested.
+**Description:** Retrieve and compare availability and layouts across operators and transport modes.
+**Actors:** Retailer, Transport Operators
+
+**UCB14 – Information on Through Fares / Through Tickets**
+**Trigger :** A journey involving multiple legs or operators is priced.
+**Description:** Indicate whether a through fare or through ticket exists across multiple legs, including fare scope, conditions, passenger rights, and commercial advantages compared to separate tickets. Enable comparison between through and non-through pricing options.
+**Actors:** Retailer, Transport Operators
+
+**UCB15 – Fare Combinability Information**
+**Trigger:** Multiple fare products or operators are considered for a single journey.
+**Description:** Provide information on whether fares can be combined across legs, bounds, operators, or modes, including constraints, pricing impacts, and aftersales implications.
+**Actors:**
+Retailer, Transport Operators
+
+**UCB16 – Agreement on Journey Continuation (AJC) Information**
+**Trigger:** A multimodal or multi-operator journey is constructed.
+**Description:** Expose whether agreements on journey continuation apply between operators, including implications for disruption handling, re-accommodation, and passenger protection in case of missed connections.
+**Actors:** Retailer, Transport Operators
+
+**UCB17 – Search & Sale of Travel Passes**
+**Trigger:** The customer searches for pass-based travel options.
+**Description:** Enable search and sale of passes (e.g. Eurail, monthly, annual, regional passes), including eligibility, coverage across modes and operators, and usage constraints.
+**Actors:** Traveler, Retailer, Transport Operators, Pass Issuers
+
+**UCB18 – Pass Validity & Conditions Across Operators**
+**Trigger:** A pass is selected or evaluated.
+**Description:** Retrieve and display pass validity rules, conditions of use, blackout periods, and operator acceptance across multiple modes and operators.
+**Actors:** Retailer, Transport Operators, Pass Issuers
+
+### C. Order & Book
+**UCC1 – Multimodal & Multi ‑ operator Order Creation**
+**Trigger:** The customer confirms the purchase.
+**Description:** The Retailer creates a single order referencing multiple suppliers, preserving operatorspecific commitments and retail ownership.
+The created order may include a defined payment time limit, after which the order or parts of it may be automatically cancelled or released according to operator rules.
+In multioperator orders, payment time limits may apply at order level and/or component level, and the earliest applicable deadline governs payment completion.
+**Actors:** Retailer, Transport Operators
+
+**UCC2 – Passenger & Entitlement Management Across Operators**
+**Trigger:** Order creation requires passenger data.
+**Description:** Transmit passenger details and entitlements consistently to all involved operators.
+**Actors:** Retailer, Traveler, Transport Operators
+
+**UCC3 – Order Validation & Partial Confirmation**
+**Trigger:** Order is submitted.
+**Description:** Validate, confirm or partially confirm components of a multi‑operator order.
+**Actors:** Retailer, Transport Operators
+
+**UCC4: Order partial confirmation**
+**Trigger:** Booking response received only for a subset of the trip (not all legs confirmed booking)
+**Description:**
+Not all the legs are confirmed by the operator/supplier. The full order is not fully confirmed.
+**Actors:** Retailer, Transport Operators
+
+**UCC5 – Group Order Creation (Multi ‑ operator)**
+**Trigger:** Group offer is accepted.
+**Description:** The Retailer confirms the group offer and creates a binding order, including passenger lists, payment milestones, and specific group conditions.
+Passenger lists may be completed at a later stage (another use case to be added)
+**Actors:** Retailer, Transport Operators
+
+**UCC6 – Seat & Ancillary Assignment in Multimodal Orders**
+**Trigger:** Seat or ancillary selection is requested.
+**Description:** Assign seats or ancillaries per operator, ensuring consistency across the journey.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCC7 – Seat Preferences & Seating Constraints**
+**Trigger:**
+The customer specifies seating preferences.
+**Description:**
+Capture and transmit seating preferences and constraints, including seat position, coach, deck, adjacency to another passenger, and mandatory vs preferred requirements, across operators and modes. Support cases where not all the legs or operators or modes included in the journey can satisfy the requested preferences.
+**Actors:**
+Traveler, Retailer, Transport Operators
+
+**UCC8 – Seat Maps & Seating Logic Across Operators**
+**Trigger:** Seat selection is requested.
+**Description:** Retrieve and present seat maps and seating logic across different operators and modes, ensuring consistent representation despite heterogeneous seat models.
+**Actors:** Retailer, Transport Operators
+
+**UCC9 – Transportables : Bikes, Cars, Equipment etc**
+**Trigger:** The customer requests transport of additional items.
+**Description:** Support search, booking, and aftersales of transportables such as bikes (critical), cars (rail or ferry), sport equipment, standalone wheelchairs etc, including availability, pricing, and constraints per operator and mode.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCC10 – Standalone Seat Search, Order & Aftersales**
+**Trigger:** A seat is searched or purchased independently from the journey.
+**Description:** Enable search, ordering, modification, and refund of seats as standalone products, post-booking or independently of the original itinerary on journeys involving several modes or operators.
+Example of use case for travelers holding a EURAIL or a yearly pass and willing to reserve the seats on a journey.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCC11 – Order Splitting (Passengers / Bounds / Modes)**
+**Trigger:**
+An existing order needs to be split.
+**Description:** Support splitting an order by passenger, by bound, or by mode to enable differentiated payment, servicing, or aftersales handling while preserving traceability to the original order.
+**Actors:** Retailer, Transport Operators
+
+### D. Pay
+**UCD1 – Single Customer Payment for Multi ‑ operator Orders**
+**Trigger:** Order confirmation requires payment.
+**Description:** The Retailer collects a single payment from the customer for the full multimodal order.
+**Actors:** Traveler, Retailer, PSP
+
+**UCD2 – Deferred Payment with Operator TTL Alignment**
+**Trigger:** Payment is deferred.
+**Description:** The Retailer completes payment for an existing order within the applicable payment time limit.
+If payment is not completed before expiry, the order or impacted components may be cancelled or revalidated.
+**Actors:** Traveler, Retailer, PSP
+
+**UCD3 – Payment Expiry & Inventory Release**
+**Trigger:** Payment TTL expires.
+**Description:** The Retailer is informed when a payment time limit expires and is notified of the resulting order status (e.g. cancellation, partial cancellation, or required revalidation).
+**Actors:** Retailer, Transport Operators
+
+**UCD4: Split Payment & Settlement Instruction**
+**Trigger:** Payment completed
+**Actors:** Retailer, Settlement Bodies
+**Description:**
+The Retailer initiates settlement instructions to distribute funds to each operator according to commercial agreements.
+
+**UCD5: Multicurrency & Tax Handling**
+**Trigger:** Crossborder journey
+**Actors:** Retailer, Tax Authorities
+**Description:**
+Prices, taxes and currencies are handled in compliance with local fiscal and invoicing regulations.
+
+**UCD6 – Voucher Payment (Full or Partial)**
+**Trigger:**
+The customer chooses to pay all or part of an order using one or more vouchers or travel credits.
+**Description:**
+Enable the use of vouchers as a payment instrument, either covering the full amount or combined with other payment methods. The retailer retrieves voucher attributes (value, currency, validity, scope of use), validates applicability across operators and modes, applies the voucher amount to the order, and ensures correct residual amount handling for settlement.
+**Actors:**
+Traveler, Retailer, Transport Operators, Payment Service Provider (PSP)
+
+**UCD7 – Voucher Issuance After Refund**
+**Trigger:**
+A cancellation, change, or disruption results in a refundable amount that is settled as a voucher or credit.
+**Description:**
+Issue a voucher representing all or part of the refundable amount, including validity period, usage constraints, currency, and traceability to the original order, passengers, legs, and operators. The voucher may be reusable across future journeys and applicable to multiple modes or operators depending on rules.
+**Actors:**
+Retailer, Transport Operators, Traveler
+
+**UCD8 – Mixed Modes of Payment**
+**Trigger:**
+The customer elects to pay using multiple payment instruments.
+**Description:**
+Support payment scenarios combining several payment modes (e.g. voucher + card, corporate account + personal payment, card + miles). Ensure coordinated authorization, confirmation, and allocation of amounts per operator and per payment method, while preserving a single customer-facing order.
+**Actors:**
+Traveler, Retailer, Payment Service Provider (PSP)
+
+**UCD9 – Payment with Miles / Loyalty Redemption**
+**Trigger:**
+The customer chooses to redeem loyalty points or miles as a form of payment.
+**Description:**
+Enable partial or full payment using loyalty points or miles, including validation of eligibility, conversion rules, and applicability across operators and modes. Support combined payment scenarios where miles are used together with monetary payment.
+**Actors:**
+Traveler, Retailer, Transport Operators, Loyalty Program Provider
+
+### E. Ticketing & Fulfilment
+**UCE1 – Multi ‑ operator Ticket & Travel Document Issuance**
+**Trigger:** Payment is confirmed.
+**Description:** The Retailer retrieves and delivers all necessary travel documents (tickets, barcodes, references), possibly in heterogeneous formats.
+**Actors:** Retailer, Transport Operators
+
+**UCE2 – Unified Multimodal Itinerary Presentation**
+**Trigger:** Order is fulfilled.
+**Description:** The Retailer assembles a unified itinerary view covering all legs and operators.
+**Actors:** Retailer, Traveler
+
+### F. Pre‑trip & In‑trip Services
+**UCF1 – Cross ‑ operator Travel Information & Notifications**
+**Trigger:** Operational updates occur.
+**Description:** The Retailer receives and relays operational updates (schedule changes, platform changes, service changes, delays) affecting any operator or mode.
+**Actors:** Transport Operators, Retailer, Traveler
+
+**UCF2 – Disruption & IROPs Management (Multi ‑ operator)**
+**Trigger:** Disruption affects part of the journey.
+**Description:** The Retailer retrieves disruption information and available recovery options across operators and modes.
+**Actors:** Transport Operators, Retailer
+
+**UCF3 – Assisted Re ‑ accommodation After Disruption**
+**Trigger:** Journey is disrupted.
+**Description:** Performs reshopping/rebooking, respecting passenger rights, fare conditions, and commercial rules on the concerned operators/modes.
+**Actors:** Retailer, Transport Operators, Traveler
+
+**UCF4 – ReshoppingAfter Disruption**
+**Trigger:** A disruption affects one or more legs of the journey.
+**Description:** Enable the retailer to retrieve alternative journey options across operators and modes, allowing reshopping while preserving passenger rights, fare conditions, and operator responsibilities.
+**Actors:** Retailer, Transport Operators
+
+**UCF5 – Partial Reshopping , Rebooking & Refund After Disruption**
+**Trigger:** Only part of the journey is disrupted. But it may impact the rest of the journey
+**Description:** Support scenarios where only specific legs, bounds, or passengers are reshopped, rebooked, or refunded. Preserve consistency of the remaining journey components and ensure correct recalculation of prices, rights, and responsibilities.
+**Actors:**
+Retailer, Transport Operators, Traveler
+
+**UCF6 – Servicing Responsibility Information**
+**Trigger:** The customer requires assistance before or during travel.
+**Description:** Provide clear information on servicing responsibilities per operator, mode, leg, and bound, including whom to contact, through which channel, and for which type of issue.
+**Actors:** Retailer, Transport Operators, Traveler
+
+### G. Aftersales & Servicing
+**UCG1 – Change & Exchange Across Operators**
+**Trigger:** Traveler requests a voluntary change.
+**Description:** Modify multi‑operator itineraries and reprice impacted components.
+**Actors:** Traveler, Retailer, Transport Operators
+
+**UCG2 – Aftersales Management per Passenger / Leg / Bound**
+**Trigger:**
+An aftersales action is requested.
+**Description:**
+Support aftersales operations (change, refund, cancellation, exchange) scoped at different levels: per passenger, per leg, per bound, for all passengers, or for the entire journey, while respecting operator-specific rules.
+**Actors:**
+Retailer, Transport Operators, Traveler
+
+**UCG3 – Cancellation, Refund & Voucher Management**
+**Trigger:** Cancellation or refund is requested.
+**Description:** Apply cancellation rules and refunds per operator and mode.
+**Actors:** Retailer, Transport Operators, PSP
+
+**UCG4 – No ‑ show Handling in Multimodal Journeys**
+**Trigger:** Passenger does not show up for one component.
+**Description:** Apply no‑show consequences and cascading impacts across operators.
+**Actors:** Transport Operators, Retailer
+
+**UCG5 – Claims Handling per Mode and per Operator**
+**Trigger:**
+A passenger submits a claim (delay, cancellation, service issue).
+**Description:** Enable submission and tracking of claims per operator and per mode, including determination of applicable regulations, compensation eligibility, and responsible party.
+**Actors:** Traveler, Retailer, Transport Operators, Passenger Rights Bodies
+
+**UCG6 – Responsibility & Liability Information (Detailed)**
+**Trigger:** The customer or retailer requests clarification on responsibility.
+**Description:** Provide explicit information on responsibility and liability per portion of the journey (leg, bound, operator, mode) and overall, including implications for servicing, compensation, and claims.
+**Actors:** Retailer, Transport Operators, Traveler
+
+**UCG7 : Group Change, Cancellation or Reduction**
+**Trigger:** Group composition changes
+**Actors:** Retailer, Transport Operators
+**Description:**
+The Retailer manages group size changes, substitutions, or cancellations according to operatorspecific group conditions.
+
+### H. Post‑trip, Settlement & Reporting
+**UCH1 – Multi ‑ operator Settlement & Reconciliation**
+**Trigger:** Travel is completed.
+**Description:** Perform settlement and reconciliation across retailer and all operators involved.
+**Actors:** Retailer, Transport Operators, Clearing Bodies
+
+**UCH2: Invoicing & Accounting**
+**Trigger:** Posttrip accounting
+**Actors:** Retailer, Operators
+**Description:**
+Invoices and accounting data are issued in compliance with national and EU regulations.
+
+**UCH3 – Reporting, Analytics & Comparison**
+**Trigger:** Reporting is requested.
+**Description:** Produce operational, financial, CO2/GHG reports enabling comparison across operators and modes.
+**Actors:** Retailer, Transport Operators