API

Confirming Reservation

Once the reservation is created and is on hold (when supported by the carrier) the user has enough time to enter their personal details and complete the payment. Once this is completed, the reservation can be confirmed using the /reservations/confirm endpoint.

Required Fields for Confirming Reservation

The response from the /connections/vacancy and /reservations/create endpoints outline which passenger fields are required or optional for the /reservations/confirm request. This helps you adapt your booking form and validation to improve user experience, reduce errors, and meet carrier requirements. For more details check our Dynamic Passenger Fields guide.

Recommended Flow

After the selected trip is reserved, the user can finalize the booking by entering the relevant passenger and payment details in the following sequence:

Capture payment in a held status (handled outside of Distribusion)
Trigger the booking by using the /reservations/confirm endpoint
Receive confirmation of the reservation via /reservations/{reservation_id} endpoint
Execute full capturing of the payment (handled outside of Distribusion)
Display the booking confirmation page

Carrier-generated VAT invoices

Some carriers issue their own VAT invoice for a booking and send it to the customer directly. Where
an integration supports this, the invoice details are collected during checkout and passed on the
reservation.

The fields are accepted on /reservations/confirm, alongside the passenger and payment details
already sent at that step:

Title

Description

Title

Parameter	Type	Description
`business_name`	string	Legal name of the entity the invoice is issued to.
`tax_id`	string	Tax identification number of that entity.
`vat_number`	string	VAT registration number of that entity

All three are optional, and all three are echoed back on the reservation and booking responses.

Carrier support and the exact subset of fields a carrier requires vary by integration — a carrier
that issues its own invoices may reject a request that omits a field it treats as mandatory. This is
currently supported for Deutsche Bahn and Trenitalia; the Partnership Manager can confirm the
required fields for a given carrier.

Best Practices

Display correct prices: The price displayed on the checkout page and used for the further booking flow must be the price returned by the /reservations/create endpoint.
Display markups: Service fees or markups added by the booking platform must be separately and transparently displayed to the user.
Collect only required customer information: Different carriers require varying information during the booking process in order to fullfil their services and where possible, the collection of passenger information should be minimized. In order to facilitate a dynamic checkout that gathers only necessary information from the customer, please make use of the info from /connections/vacancy and /reservations/create endpoints and check our Dynamic Passenger Fields guide.
Cancel reservation when checkout process is aborted: In case the user aborts the checkout or payment process, please use the /reservations/cancel endpoint to unblock the reserved seats in the carrier’s system. Do not just let the reservation timeout since other users won’t be able to see those seats until it does. The current status of a reservation can be checked using the /reservations/{reservation_id} endpoint.
Display carrier terms and conditions: It is mandatory to display the terms and conditions of the respective carrier on the checkout page. You can find the terms and conditions of the carrier from the terms parameter in the /marketing_carriers/{marketing_carrier_id} endpoint. Note that some carriers might have multiple links or long text in this field.
Process your payments: No live payments flow between your and our systems at this point. Payments are reconciled during regular settlement processes. In the /reservations/confirm request, you must specify payment_method = demand_note by default.
Do not call confirm & cancel in same booking flow: You should never call /reservations/confirm & /reservations/cancel in the same flow. Once confirmed we are attempting to create the booking, calling both will respond in an error. In this case, /reservations/create will need to be called to cancel booking after confirmation.
Do not confirm reservation multiple times: Calling /reservations/confirm multiple times does not change the timing or affect the finality reservation. Instead, it is much more efficient to simply call the /reservations/{reservation_id} endpoint to check on the status of the reservation.
Define sender of confirmation email: At the time of confirming the reservation you can specify if the user should receive the default confirmation and cancellation emails created by Distribusion or emails created by you. For more details check our Ticket Delivery guide.

Enterprise Features

After ancillaries are added to the /reservations/create step they don't have to be added again to the /reservations/confirm request. For more details, check our guide on Ancillaries.

When discount cards are applied to the /reservations/create step they don't have to be added again to the /reservations/confirm request. For more details, check our guide on Discount Cards.

Next Step

After the reservation is confirmed, the status of the reservation must be checked.

API Examples

Sample Request to /reservations/confirm

JSON

{
    "reservation_id": "RFK7YNAF",
    "execute_payment": "false",
    "payment_method": "demand_note",
    "terms_accepted": "true",
    "send_customer_email": "true",
    "title": "mr",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com",
    "passengers": [
        {
            "type": "PNOS",
            "id": "pax-33-1",
            "first_name": "John",
            "last_name": "Smith",
            "birthdate": "1997-10-22"
        },
        {
            "type": "PNOS",
            "id": "pax-11-2",
            "first_name": "Ana",
            "last_name": "Smith",
            "birthdate": "1997-10-22"
        }
    ]
}

Sample Response from /reservations/confirm