Distribusion

Welcome to the Distribusion Retailer API.

The Distribusion API allows online channels of all kinds to access and distribute ground transportation in the simplest way. Distribusion’s portfolio of inventory is fully standardised and encompasses intercity bus, rail, ferry, and airport transfer services from all around the world.

To request a demo API key or receive an overview of the accessible inventory, please reach out to us at [partner@distribusion.com](https://mailto:partner@distribusion.com) and one of our Partnership Managers will be happy to get you started.

This section provides an overview of relevant guidelines and key concepts that will enable you to get started with the Distribusion Retailer API.

More details at [https://api.distribusion.com/doc/index#retailer-api.](https://api.distribusion.com/doc/index#retailer-api.)

Getting Started

Basic Integration

Enterprise Features

Other Concepts

API Endpoints

📣 What's New

Errors

Booking Engine

Intro

Integration Types

Search SDK

Examples of Booking Engines

Custom Domain

Analytics

Languages

Agent Counter

Connectivity Services

Invoicing and Payments

Dictionary

Default

Distribusion Docs

Explore the Distribusion Documentation Portal for API guides, integration tutorials, and developer tools to connect with global ground transportation solutions seamlessly.

Demo

Production

Accreditation

Advanced Pricing Insights

AI Tools

Alternative Location Identifiers

Amendments

/amendments/{amendment_id}

/amendments/confirm

/amendments/create

Ancillaries

API Authentication

Rate Limiting & Usage Policy

/price-insights/price-hints

/price-insights/price-forecast

/price-insights/calendar

/price-insights/calendar/return

Bookings

/bookings

/bookings/{booking_id}

/bookings/{booking_id}/conditions

/bookings/{booking_id}/tickets

/bookings/create

Cancellations

/cancellations/conditions

/cancellations/create

Cards

/cards

Connections

/connections/find

/connections/seats

/connections/vacancy

Marketing Carriers

/marketing_carriers

/marketing_carriers/{marketing_carrier_id}

/marketing_carriers/{marketing_carrier_id}/booking/schema

/marketing_carriers/{marketing_carrier_id}/gtfs

/marketing_carriers/{marketing_carrier_id}/stations

Post-Sales AI Bot

/post-sales-bot/chat

/post-sales-bot/chat-init

/post-sales-bot/chat/stream

Reservations

/reservations/cancel

/reservations/confirm

/reservations/create

/reservations/{reservation_id}

Stations, Areas & Cities

/areas

/cities

/connected_stations

/stations

/stations/{station_code}

Booking Confirmation

Cancel Booking

Checking Price & Vacancy

Checking Reservation Status

Confirming Reservation

Creating Reservation

Flow Overview

Preparing Metadata

Searching for Trips

Selecting Seats

MCP Server

Retailer Agent

Discount Cards

Emissions Data

GTFS

Negotiated & Corporate Fares

Real Time

Suggestion Service

Virtual Interlining

Carrier Accreditation

Accreditation Criteria

General Accreditation

Demo Environment

Postman

Preview Distribusion Content

Asynchronous Cancellations

Fees

Booking Fees

Convenience Fees

Markup Fees

Cancellation & Refund Policies

Carrier Cancellations

Terms & Conditions

Currencies

Custom Fields

Dynamic Passenger Details

Fare Classes

Fare Features & Amenities

Geo Coordinate Search

IATA and UIC Codes Search

Journey Types

Limited Day Content

Operating Carriers

Required Passenger Detail

Passenger Types

Ticket Delivery

Ticket Types

Ticket Validity

Timezones

Webhooks

Checkout Only Integration

Full Search & Book Integration

Partial Integration

### Description

This endpoint can be used to place a reservation in carrier system. Reservation is a temporary block of a place on the ride that ensures seat availability at the moment of purchase (confirmation). Reservations hold for 10 minutes by default, and, if not confirmed, will be automatically cancelled.

In order to lock in the seats and prices upon sending the user to the checkout page, trigger a [/reservations/create](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-a2282d12-ac68-4f80-aba5-84e3ee707419?ctx=documentation) request for the specified trip and passenger details.

**Reservations overview**

Reservations is a helpful tool to ensure that the customer retains their booking and seat throughout the checkout process. Without reservations, it is possible that while the user is buying their ticket their bus or seat could be booked out, resulting in the user losing their trip.

It is important to note that even if you have implemented reservations, your integration will still work with carriers who do not support reservations yet. The flow will work as it normally does and the reservation will be simulated.

**Understanding reservations flow**

Once the user has selected a specific trip (and optionally seats) and proceeds to the checkout page, the next step is to call the [/reservations/create](https://lively-space-811588.postman.co/workspace/My-Workspace~f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-a2282d12-ac68-4f80-aba5-84e3ee707419?ctx=documentation) endpoint, which reserves the seat and price to be guaranteed for a certain period of time.

When [/reservations/create](https://lively-space-811588.postman.co/workspace/My-Workspace~f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-a2282d12-ac68-4f80-aba5-84e3ee707419?ctx=documentation) is initially called, it will return attributes that give more information on the reservation.

**Next step**

If the reservation is created successfully, users can proceed to the checkout page and the reservation can be confirmed using the [/reservations/confirm](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-43158577-b029-4b2b-84fb-e1219407890c?ctx=documentation) endpoint. [Learn more about it here](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-43158577-b029-4b2b-84fb-e1219407890c?ctx=documentation).

If the reservation flow is aborted by the user, the reservation must be cancelled using the [/reservation/cancel](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7b550e01-3930-4e40-ac9e-e3650fa19de0?ctx=documentation) endpoint.

### More Info

- **Full API integration**
    - [Trip selection and reservation](https://api.distribusion.com/doc/full-api-integration#trip-selection-and-reservation)
- **Key Concepts**
    - [Reservations](https://api.distribusion.com/doc/key-concepts#reservations)
        - [Reservations overview](https://api.distribusion.com/doc/key-concepts#reservations-overview)
        - [Understanding reservations flow](https://api.distribusion.com/doc/key-concepts#understanding-reservations-flow)
        - [Common pitfalls and errors to avoid](https://api.distribusion.com/doc/key-concepts#common-pitfalls-and-errors-to-avoid)
    - [Ancillaries](https://api.distribusion.com/doc/key-concepts#ancillaries)
        - [Supported ancillaries](https://api.distribusion.com/doc/key-concepts#supported-ancillaries)
        - [API workflow](https://api.distribusion.com/doc/key-concepts#id16)
    - [Discount cards](https://api.distribusion.com/doc/key-concepts#discount-cards)
        - [Types of supported discounts](https://api.distribusion.com/doc/key-concepts#types-of-supported-discounts)
        - [Parameters characterising discounts](https://api.distribusion.com/doc/key-concepts#parameters-characterising-discounts)
        - [API workflow](https://api.distribusion.com/doc/key-concepts#api-workflow)
    - [Currencies and locales](https://api.distribusion.com/doc/key-concepts#currencies-and-locales)
    - [Virtual interlining](https://api.distribusion.com/doc/key-concepts#virtual-interlining)
- **Rail Requirements**
    - [Fare Classes &amp; Selection](https://docs.google.com/document/d/1s8ckJhKtO2BI81a_-zg5Q1Nnf1BcGEGYLGZCuSoHmMw/edit#heading=h.6yne5i3rshju)
- **Endpoints**
    - [POST /retailers/v4/reservations/create](https://api.distribusion.com/doc/api#post-retailers-v4-reservations-create-reservations-create)

### **Description**

This endpoint can be used to confirm a reservation in carrier system. Reservation then is moved to processing state and status can be later retrieved via [/reservations/{reservation_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) endpoint.

**Workflow**

Assuming the selected trip is available, the user can now finalise the booking by entering the relevant passenger and payment details in the following sequence:

- Capture payment in a held status
- Trigger the booking by using the [/reservations/confirm](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-43158577-b029-4b2b-84fb-e1219407890c?ctx=documentationhttps://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-43158577-b029-4b2b-84fb-e1219407890c?ctx=documentation) endpoint
- Receive confirmation of the reservation via the API
- Execute full capturing of the payment
- Display the booking confirmation page
    

**Displaying prices**

The price displayed on the checkout page and used for the further booking flow **must** be the price returned by the [/reservations/create](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-a2282d12-ac68-4f80-aba5-84e3ee707419?ctx=documentation) endpoint.

Service fees 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 fulfil their services and where possible, the collection of passenger information should be minimised. In order to facilitate a dynamic checkout that gathers only necessary information from the customer, please make use of [/marketing_carriers/{marketing_carrier_id}/booking/schema](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-23775510-4696-4fe2-904c-0fe7ce4bb349?ctx=documentation) endpoint, which shows the mandatory and optional parameters per carrier.

**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}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-4b7f6a67-704f-4c88-9f76-99fd6837d089?ctx=documentation) endpoint.

**Check reservation status**

To continually check to see if the reservation is confirmed, you must use the [/reservations/{reservation_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) endpoint.

**Succesful bookings**

The `booking_id` returned through this endpoint after a successful booking can be used for all further post-booking interaction with the Distribusion API.

**Payments**

Please note that no live payments flow between your and our systems at this point. Payments are reconciled during regular settlement processes. In the booking request, you must specify `payment method: demand_note`.

**Aborting the checkout process**

In case the user aborts the checkout process, please use the [/reservations/cancel](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7b550e01-3930-4e40-ac9e-e3650fa19de0?ctx=documentation) endpoint to unblock the reserved seats in the carrier’s system.

**Next step**

After the reservation is confirmed, the status of the reservation must be checked using the [/reservations/{reservation_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) endpoint.

If the reservation is successfull, check the full booking details using the [/bookings/{booking_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-c7bbe789-f96a-4275-bff5-e0cb18cc0061?ctx=documentation) endpoint. The ticket can be accessed from the [/bookings/{booking_id}/tickets endpoint](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-ceff1d2c-19f2-4388-9c61-3fdf094d5823?ctx=documentation).

### More Info

- **Full API integration**
    - [Checkout and trip confirmation](https://api.distribusion.com/doc/full-api-integration#checkout-and-trip-confirmation)
- **Key Concepts**
    - [Reservations](https://api.distribusion.com/doc/key-concepts#reservations)
        - [Reservations overview](https://api.distribusion.com/doc/key-concepts#reservations-overview)
        - [Understanding reservations flow](https://api.distribusion.com/doc/key-concepts#understanding-reservations-flow)
        - [Common pitfalls and errors to avoid](https://api.distribusion.com/doc/key-concepts#common-pitfalls-and-errors-to-avoid)
    - [Currencies and locales](https://api.distribusion.com/doc/key-concepts#currencies-and-locales)
- **Rail Requirements**
    - [Checkout](https://docs.google.com/document/d/1s8ckJhKtO2BI81a_-zg5Q1Nnf1BcGEGYLGZCuSoHmMw/edit#heading=h.6s7lzs35n6rl)
- **Endpoints**
    - [PUT /retailers/v4/reservations/confirm](https://api.distribusion.com/doc/api#put-retailers-v4-reservations-confirm-reservations-confirm)

### **Description**

This endpoint can be used to retrieve all details regarding a specific reservation.

**How it works**

The current status of a reservation can be checked using the [/reservations/{reservation_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) endpoint.

In the response, the value `state` shows the current state of the reservation. Values can be:

- `created`: The default value, appears right after the reservation is created.
- `processing`: Shown after [/reservations/confirm](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-43158577-b029-4b2b-84fb-e1219407890c?ctx=documentation) is initially called.
- `confirmed`: Shown once the reservation is confirmed with the carrier.
- `cancelled`: Shows after the user leaves the page and [/reservations/cancelled](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7b550e01-3930-4e40-ac9e-e3650fa19de0?ctx=documentation) is called.
- `failed`: Shown if something went wrong in the booking.
    

**Processing deadline**

In the response, the `processing_deadline` value will present the date and time that the retailer should request [/reservations/{reservation_id}](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) to see if a booking was successfully created. Hence if you stop listening to it before that time frame, a discrepancy can happen.

The reservation status must be continually checked every 10 seconds until one of the following occurs:

- The reservation is confirmed and you can proceed with the post-booking actions.
- The reservation times out, in which case it will be automatically tagged as failed.
- The reservation fails, in which case the user must be notified that their booking was unsuccessful.
    

**Important**

The typical processing deadline is 10 mins and it is essential to continue listening (calling [/reservations/{reservation_id](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation)) until the deadline expires. If you stop listening before processing_deadline reaches 0 and then the booking is created, there will be a discrepancy in status of the booking between you and the carrier. If this occurs, you will still be charged and incur the transaction costs.

### More Info

- **Full API integration**
    - [Checkout and trip confirmation](https://api.distribusion.com/doc/full-api-integration#checkout-and-trip-confirmation)
- **Key Concepts**
    - [Reservations](https://api.distribusion.com/doc/key-concepts#reservations)
        - [Reservations overview](https://api.distribusion.com/doc/key-concepts#reservations-overview)
        - [Understanding reservations flow](https://api.distribusion.com/doc/key-concepts#understanding-reservations-flow)
        - [Common pitfalls and errors to avoid](https://api.distribusion.com/doc/key-concepts#common-pitfalls-and-errors-to-avoid)
- **Endpoints**
    
    - [GET /retailers/v4/reservations/{reservation_id}](https://api.distribusion.com/doc/api#get-retailers-v4-reservations-reservation-id-reservations-id)

### Description

This endpoint can be used to cancel a previously placed reservation.

**How it works**

In case the user aborts the checkout process, please use the [/reservations/cancel](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-7b550e01-3930-4e40-ac9e-e3650fa19de0?ctx=documentation) endpoint to unblock the reserved seats in the carrier’s system.

**Next step**

If needed in your flow, a new reservation can be created using the [/reservations/create](https://lively-space-811588.postman.co/workspace/f46e13d3-12d7-41eb-86e4-45523c4a451d/request/18003295-be2e40fb-0b16-4fb1-bd3c-e6af8e8c3d7a?ctx=documentation) endpoint.

### More Info

- **Full API integration**
    - [Checkout and trip confirmation](https://api.distribusion.com/doc/full-api-integration#checkout-and-trip-confirmation)
- **Key Concepts**
    - [Reservations](https://api.distribusion.com/doc/key-concepts#reservations)
        - [Reservations overview](https://api.distribusion.com/doc/key-concepts#reservations-overview)
        - [Understanding reservations flow](https://api.distribusion.com/doc/key-concepts#understanding-reservations-flow)
        - [Common pitfalls and errors to avoid](https://api.distribusion.com/doc/key-concepts#common-pitfalls-and-errors-to-avoid)
- **Endpoints**
    
    - [PUT /retailers/v4/reservations/cancel](https://api.distribusion.com/doc/api#put-retailers-v4-reservations-cancel-reservations-cancel)

<p class="slate-p " >The Reservations section of the Distribusion API allows users to create reservations, cancel reservations, confirm reservations and retrieve detailed information about existing reservations made through the platform.</p><p class="slate-p " ></p>

The Reservations section of the Distribusion API allows users to create reservations, cancel reservations, confirm reservations and retrieve detailed information about existing reservations made through the platform.

Sections

Reservations

What made this section helpful for you?

What made this section unhelpful for you?

On this page

Sections

Reservations

What made this section helpful for you?

What made this section unhelpful for you?

On this page

Ask an AI

Code with AI