BlaBlaCar Pro
API docs by Redocly

BlaBlaCar Pro IMS (2.0.5)

Download OpenAPI specification:

BlaBlaCar Team IMS: team-ims@blablacar.com

External API

Abstract

BlaBlaCar Pro IMS API Usage Guide

BlaBlaCar Pro IMS API is an external API designed to provide partners and developers with access to various functionalities of BlaBlaCar’s Inventory Management System (IMS). This API allows third-party services to integrate seamlessly with BlaBlaCar Pro by searching and booking operations for bus journeys through HTTP requests.

This guide provides a step-by-step overview of how to interact with the BlaBlaCar Pro IMS API. The API allows partners to manage journey bookings, retrieve journey details, and access transport schedules.

1. Authentication

Before accessing any resources, you must authenticate using the /organizations/authentication/login endpoint to obtain a token. This token is required for all subsequent API requests.

Endpoint:

  • POST /organizations/authentication/login

Use your credentials to authenticate and receive an authorization token, which you will include in the header of all future requests.

2. Retrieve Available Axes (Daily Update)

Once authenticated, you can retrieve all available combinations of cities and stops where journey searches can be performed. This should be done daily to keep the data up to date.

Endpoint:

  • GET /inventory/journeys/axes

Use this endpoint to get the axes (combinations of locations or stop points) that are available for journey searches. This data should be refreshed daily.

3. Retrieve Additional Information on Locations and Stops

To get more detailed information about locations and stops, use the following endpoints. These endpoints provide additional geographic data that might be necessary for your application.

Endpoints:

  • GET /inventory/geo/locations/** – Retrieves information about cities, towns, or geographic locations.
  • GET /inventory/geo/points/** – Retrieves details about specific stops or points of interest within those locations.

4. Search for Journeys Between Locations

Once the axes are retrieved and mapped to yuor geography data (if it's needed), you can search for available journeys between specific stops or locations for a particular journey date.

Endpoint:

  • POST /inventory/journeys/search

Use this endpoint to search for journey options between two stops or locations for a specific date. The result will include all available journey options for the specified route.

5. Retrieve Journey Details

After finding a suitable journey, you can get more detailed information about that journey, such as prices, availability, available seats, route details, and applicable discounts.

Endpoint:

  • POST /inventory/journeys/details

This endpoint provides detailed information about a specific journey, including available seats, pricing, discounts, and the journey schedule/route info.

6. Manage Orders and Tickets

You can perform various operations related to booking, purchasing, canceling, and refunding tickets using the /inventory/orders endpoints. These operations include purchase tickets, booking tickets, confirming bookings, canceling bookings, and retrieving information about previously booked tickets and orders. Each of these operations work in scope of order, except refund. Refund operation works in scope of particular ticket.

Key Endpoints:

  • PUT /inventory/orders/{order_id} – Book a journey (create order with tickets) in various ways.
  • PUT /inventory/orders/{order_id}/cancellation – Cancel an order with tickets.
  • PUT /inventory/orders/tickets/{ticket_id}/cancellation – Cancel a ticket.
  • GET /inventory/orders/{order_id}/tickets/{ticket_id}/refund-options – Get available refund options
  • PUT /inventory/orders/{order_id}/tickets/{ticket_id}/refund – Refund a purchased ticket.
  • PUT /inventory/orders/{order_id}/payment-confirmation – Confirm payment for a booking.
  • GET /inventory/orders/{order_id} – Retrieve information about an existing order, including tickets.
  • GET /inventory/orders/tickets/{ticket_id} – Retrieve information about an existing ticket.

7. Retrieve the Full Schedule of Available Bus Lines (Daily Update)

To maintain a local index of available bus lines and avoid performing a search for journey variants each time, you can retrieve the full available bus schedule once a day. This will allow you to perform offline searches and order processing.

Endpoints:

  • GET /inventory/overviews/sellable-inventory – Retrieves the full schedule of sellable inventory.
  • POST /inventory/journeys/bus-line-scoped-search – Searches for available journeys within specific bus line.

These endpoints are used to build a local cache of available bus lines, so agents can handle orders without querying for journey search every time.

8. Getting additional information

This section describes endpoints that allow you to get the names of objects by their identifiers

Endpoint:

  • POST /organizations/carriers/name-lookup – Getting a list of carrier names by a list of their IDs.

9. Manage personal customer accounts

This section describes the endpoints that allow the management of personal customer accounts.

Endpoints:

  • POST /inventory/customers/accounts – Register a new customer with an account or an account for an existing customer of your organization.
  • POST /inventory/customers/accounts/login – Log in customer of your organization to their account.
  • GET /inventory/customers/{customer_id}/account – Get customer account data.
  • PUT /inventory/customers/{customer_id}/account – Update customer account data.
  • POST /inventory/customers/accounts/password-reset-requests – Request to initiate a password reset process for a customer account.
  • POST /inventory/customers/accounts/password-reset-code-checks – Check the validity of the password reset code
  • POST /inventory/customers/accounts/password-resets – Reset password for a customer account.
  • GET /inventory/customer-order-histories/{customer_id} – Get list of orders created for a customer of your organization.

Managing personal customer accounts only makes sense if you implement your own sales channel (website, mobile app) with support for a personal customer account and also if you want to use personal customer accounts to link them to orders made through this sales channel. This also makes it possible to use personal discounts for customers, such as "Bonus Trip" or "Promo Code".

10. Localization Support

All endpoints in the BlaBlaCar Pro IMS API can return localized information based on the X-Locale header. This header allows you to specify the language in which the API should return responses.

Supported Languages:

  • English (en)
  • Ukrainian (uk)
  • Czech (cs)
  • Polish (pl)
  • Portuguese (Brazil) (pt)
  • Russian (ru)

To use this feature, simply include the X-Locale header in your request with one of the supported language codes. The API will then return responses with localized data, such as translated messages and region-specific formats.

11. Currency Support

All endpoints related to prices or currency-based information support an optional X-Currency header. This header allows you to specify the desired currency code for returned prices, based on the ISO 4217 currency standard.

ISO 4217 Currency Codes:

The X-Currency header should contain a valid ISO 4217 currency code (e.g., USD for US dollars, EUR for euros). By providing this header, you can request prices in a specific currency.

Default Behavior:

If the X-Currency header is not provided, the API will return prices in the default currency set for the partner organization. This default currency is configured based on the partner’s profile parameters.

12. Features of applying discounts

The IMS BlaBlaCar Pro system provides two types of discounts:

  • Automatically applied discounts:

    • Group (dependent on the specified number of tickets per order)
    • Pre-booking (dependent on the number of days of pre-sale)
    • Round trip (applies to the return journey if it's with the same carrier)
    • For a period (the carrier can set a discount for a configurable date range)
    • Weekly (the carrier can set a list of weekdays and assign a specific discount percentage to them)

  • Discounts selected manually by a user of the system (cashier, call-center operator, driver, etc.) or by a passenger from a list, depending on the booking method:

    • By age (configured by age range, e.g., "up to X years" or "after X years", upon presentation of a certificate or pension ID)
    • Student (upon presentation of a student ID)
    • Special (a benefit category and discount percentage configured by the carrier)

All these discounts can be dynamically set by the carrier with various parameters, both for a specific bus line and for the carrier as a whole, as well as in mixed variations. Each can have its own percentage and other settings. It is impossible to strictly classify these discounts (for example, by tariff type).

Therefore, in the response to a request to the /journeys/details endpoint, you can see two different fields related to discounts for each segment (there can be more than one if there is a return trip).

The first such field is ticket_pricing.automatic_discount. It can only contain one discount object, as this is the discount automatically calculated by the system.

The ticket_pricing.automatic_discount object has the following fields:

  • id - the discount code to apply when booking tickets for the order
  • name - the name of the discount
  • ticket_price_with_discount - the ticket price including the applied discount.
  • value - the discount value object, which can contain either a percentage or amount, depending on the type field.
  • category - the discount category as an object:
    • name - the discount type:
      • GROUP - group (for the number of tickets in an order)
      • PRE_BOOKING - daily (for advance purchase)
      • TWO_WAY - round trip (for the return journey)
      • PERIOD - for a period (for a date interval)
      • WEEKLY - by days of the week (for specific days of the week)
    • additional fields for discount parameters, the composition of which depends on the discount type

The second such field is ticket_pricing.available_discounts. It contains an array of discount objects, as these are the discounts that are selected manually (for display in a selection field).

Any of these objects can be applied to any passenger, but if an automatically calculated discount could be applied, it is replaced by the one that was selected. That is, only one discount can apply to a single passenger.

Each object in this ticket_pricing.available_discounts array has the same fields as the ticket_pricing.automatic_discount object, and this is where the following discount types are found:

  • AGE - age-based (by passenger age parameters)
  • SPECIAL - benefit (by passenger benefit category)
  • STUDENT - student

The application of discounts has some additional features; in the response to a /journeys/details request, you can receive:

  • The basic price: ticket_pricing.base_ticket_price (without discount)
  • The price including the automatically applied discount: ticket_pricing.ticket_price_with_automatic_discount
  • If there is an automatically applied discount, the ticket_pricing.automatic_discount object (there can be only one).
  • If there are selectable discounts, an array of discounts for selection ticket_pricing.available_discounts.

The automatically applied discount must be explicitly specified by its id in the order_items.rides.discount.id field when submitting a request to the PUT /orders/{order_id} endpoint to create an order. Otherwise, this discount will not be applied, and the order will be processed at the basic price.

The discount objects (both automatic and selectable) contain everything needed: code, price, name, percentage. For this to be applied during purchase, the discount ID must be passed in the order_items.rides.discount.id field for each passenger to whom the discount applies.

Regarding the /journeys/search endpoint, in the rides.ticket_pricing object, you can get:

  • The basic price: ticket_pricing.base_ticket_price (without discount)
  • The price including the automatically applied discount: ticket_pricing.ticket_price_with_automatic_discount
  • The value of the automatically applied discount, if any: automatic_discount.value
  • If there are selectable discounts, an array of discounts for selection ticket_pricing.statutory_discounts, which only includes the selectable discount types:
    • AGE - age-based (by passenger age parameters)
    • SPECIAL - benefit (by passenger benefit category)
    • STUDENT - student

Authentication

Authentication

logIn

User must call this endpoint to login to BlaBlaCar Pro

Authorizations:
bearerAuth
Request Body schema: application/json
required
login
required
string non-empty

User login

password
required
string non-empty

Password provided by user

Responses

Request samples

Content type
application/json
{
  • "login": "osem",
  • "password": "bNgtI8_Ht"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "token_expires_at": 1725185410,
  • "user_id": "8fb86ca0-5b47-46b4-a2f3-c96843bcb552",
  • "organization_id": "692614f3-49a1-4bb8-ae02-55e62d3595ed"
}

Carrier

Carrier information

lookupCarrierNames

Get a list of carrier names by IDs. Return names even for carriers that marked as deleted. Method POST is used to be able to send a large list of IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
Array
string <uuid>

ID of a carrier

Responses

Request samples

Content type
application/json
[
  • "54ecbbaf-f192-431c-b0da-8b3ac3494301"
]

Response samples

Content type
application/json
{
  • "names": [
    ]
}

CustomerAccount

getCustomerOrderHistory

Get list of orders created for a customer of your organization

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
Example: 2c9d85b7-e364-4f3d-a32b-10c4ab62f052

ID of the customer

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

registerCustomerAccount

Register a new customer with an account or an account for an existing customer of your organization

Authorizations:
bearerAuth
Request Body schema: application/json
required
login
required
string
password
required
string
first_name
required
string
last_name
required
string
email
required
string
required
object (CustomerPhoneNumber)

Responses

Request samples

Content type
application/json
{
  • "login": "john-doe-42",
  • "password": "password123*",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john_doe@example.com",
  • "phone_number": {
    }
}

Response samples

Content type
application/json
{
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052",
  • "login": "john-doe-42",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john_doe@example.com",
  • "phone_number": {
    }
}

requestCustomerAccountPasswordReset

Request to initiate a password reset process for a customer account

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Request Body schema: application/json
required
email
required
string

Email of the customer account for which to initiate password reset

password_reset_page_url
required
string

URL of the web page to which to send the link to the customer. URL will be appended with a password reset code required for completing the password reset

Responses

Request samples

Content type
application/json
{
  • "email": "john_doe@example.com",
  • "password_reset_page_url": "string"
}

Response samples

Content type
application/json
{
  • "code": "ERROR_ILLEGAL_ARGUMENT",
  • "message": "Invalid value provided for property name",
  • "arguments": [
    ]
}

resetCustomerAccountPassword

Reset password for a customer account

Authorizations:
bearerAuth
Request Body schema: application/json
required
new_password
required
string

New password to set for customer account

password_reset_code
required
string

Code sent to the customer as a part of a password reset link, when password reset was initiated

Responses

Request samples

Content type
application/json
{
  • "new_password": "newpassword123*",
  • "password_reset_code": "9vbOafxZBKwQZu1rVCBQ0mwTgMWv8IDq"
}

Response samples

Content type
application/json
{
  • "code": "ERROR_ILLEGAL_ARGUMENT",
  • "message": "Invalid value provided for property name",
  • "arguments": [
    ]
}

checkCustomerAccountPasswordResetCode

Check the validity of the password reset code

Authorizations:
bearerAuth
Request Body schema: application/json
required
password_reset_code
required
string

Code sent to the customer as a part of a password reset link, when password reset was initiated

Responses

Request samples

Content type
application/json
{
  • "password_reset_code": "9vbOafxZBKwQZu1rVCBQ0mwTgMWv8IDq"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052"
}

logInToCustomerAccount

Log in customer of your organization to their account

Authorizations:
bearerAuth
Request Body schema: application/json
required
login
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "login": "john-doe-42",
  • "password": "password123*"
}

Response samples

Content type
application/json
{
  • "account": {
    },
  • "authentication": {
    }
}

getCustomerAccount

Get customer account data

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
Example: 2c9d85b7-e364-4f3d-a32b-10c4ab62f052

ID of the customer

header Parameters
X-Customer-Authentication
string
Example: bm90aGluZyB0byBzZWUgaGVyZQ

Token that was returned after customer authentication. Proves that current operation is performed on behalf of that customer

Responses

Response samples

Content type
application/json
{
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052",
  • "login": "john-doe-42",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john_doe@example.com",
  • "phone_number": {
    }
}

updateCustomerAccount

Update customer account data

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
Example: 2c9d85b7-e364-4f3d-a32b-10c4ab62f052

ID of the customer

header Parameters
X-Customer-Authentication
string
Example: bm90aGluZyB0byBzZWUgaGVyZQ

Token that was returned after customer authentication. Proves that current operation is performed on behalf of that customer

Request Body schema: application/json
required
login
required
string
password
string
first_name
required
string
last_name
required
string
email
required
string
required
object (CustomerPhoneNumber)

Responses

Request samples

Content type
application/json
{
  • "login": "john-doe-42",
  • "password": "password123*",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john_doe@example.com",
  • "phone_number": {
    }
}

Response samples

Content type
application/json
{
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052",
  • "login": "john-doe-42",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "john_doe@example.com",
  • "phone_number": {
    }
}

Geo

Stops and settlements geo information

findLocationsByName

Search locations by part of name

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Request Body schema: application/json
required
query
required
string >= 2 characters

A part of the location name search for

limit
integer
Default: 20

Limit of elements in response. Default 20.

Responses

Request samples

Content type
application/json
{
  • "query": "Kye",
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

getLocationsByIds

Get list location by IDs. Used by POST to be able to send a large list of location IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
Array
integer <int64> (LocationId)

ID of a location

Responses

Request samples

Content type
application/json
[
  • 1290
]

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

getLocationPointsSummary

Get list of points by location ID in short form

Authorizations:
bearerAuth
path Parameters
location_id
required
integer <int64> (LocationId)
Example: 1290

ID of a location

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "location": {
    },
  • "points": [
    ]
}

getLocationsSummaryByIds

Get list location by IDs in short form with localized names. Used by POST to be able to send a large list of location IDs.

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Request Body schema: application/json
required
Array
integer <int64> (LocationId)

ID of a location

Responses

Request samples

Content type
application/json
[
  • 1290
]

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

getPointsByIds

Get list points by IDs Used by POST to be able to send a large list of point IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
Array
integer <int64> (PointId)

ID of a point

Responses

Request samples

Content type
application/json
[
  • 1048592
]

Response samples

Content type
application/json
{
  • "points": [
    ]
}

getPointsSummaryByIds

Get list points by IDs in short form with localized names Used by POST to be able to send a large list of point IDs.

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Request Body schema: application/json
required
Array
integer <int64> (PointId)

ID of a point

Responses

Request samples

Content type
application/json
[
  • 1048592
]

Response samples

Content type
application/json
{
  • "points": [
    ]
}

Journey

Journeys search and get journey information

searchForJourneys

Search for journeys

Authorizations:
bearerAuth
query Parameters
include_statutory_discounts
boolean
Example: include_statutory_discounts=true

specifies if the list of available statutory discounts for every ride should be returned

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Currency
required
string
Example: gbp

The currency that will be used when including prices in response

X-Client
string
Example: ims-frontend

The client that is making the request.

Request Body schema: application/json
required
required
object (JourneySearchRequestedPath)

Requested journey origin and destination

departure_date
required
string <date>

Desired departure date

return_date
string <date>

Desired return date for round trip

date_flexibility
integer [ 1 .. 3 ]

The number of days before and after the specified departure/return date that should also be checked for available journeys. If not specified, journeys will only be searched for on the specified date.

passenger_count
integer >= 1
Default: 1

Number of passengers

customer_id
string <uuid>

ID of the customer for whom this journey search is performed

Responses

Request samples

Content type
application/json
{
  • "path": {
    },
  • "departure_date": "2022-07-15",
  • "return_date": "2022-07-16",
  • "date_flexibility": 2,
  • "passenger_count": 2,
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052"
}

Response samples

Content type
application/json
{
  • "journeys": [
    ]
}

detailsOfJourney

Returns details of journey

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Currency
required
string
Example: gbp

The currency that will be used when including prices in response

X-Client
string
Example: ims-frontend

The client that is making the request.

Request Body schema: application/json
required
id
required
string

Journey ID

passengers_size
integer
Deprecated

Number of passengers in journey. Deprecated, use passenger_count instead

passenger_count
integer >= 1
Default: 1

Number of passengers

customer_id
string <uuid>

ID of the customer for whom this journey is considered

Responses

Request samples

Content type
application/json
{
  • "id": "YjgxYTc2YmYtZjgxYi00YTI5LTkxY2MtNzVlOTdlOTZkNjQ2OjExNzA4MzQ6MTQwNDk2OQ==",
  • "passengers_size": 3,
  • "passenger_count": 2,
  • "customer_id": "2c9d85b7-e364-4f3d-a32b-10c4ab62f052"
}

Response samples

Content type
application/json
{
  • "id": "YjgxYTc2YmYtZjgxYi00YTI5LTkxY2MtNzVlOTdlOTZkNjQ2OjExNzA4MzQ6MTQwNDk2OQ==",
  • "rides": [
    ],
  • "allowed_operations": {
    },
  • "ordering": {
    }
}

getAxesForJourneys

Returns all available axes for journeys. Available axes include all possible connections from stop point id to stop point id and from location id to location id, with separate summary descriptions for all stop points and locations that occur in the axes.

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Currency
string
Example: gbp

The currency that will be used when including prices in response

X-Client
string
Example: ims-frontend

The client that is making the request.

Responses

Response samples

Content type
application/json
{
  • "point_axes": [
    ],
  • "location_axes": [
    ],
  • "points": [
    ],
  • "locations": [
    ]
}

searchForJourneysInScopeOfBusLine

Search for available journeys in scope of the specified bus line

Authorizations:
bearerAuth
Request Body schema: application/json
required
bus_line_id
required
string <uuid>

Bus line ID

required
object (JourneySearchRequestedPointToPointPath)

Request journey origin and destination points

departure_date
required
string <local-date>

Date of departure from origin point

Responses

Request samples

Content type
application/json
{
  • "bus_line_id": "c87499fc-5bc2-4314-87d9-d001ff07684a",
  • "path": {
    },
  • "departure_date": "string"
}

Response samples

Content type
application/json
{
  • "journeys": [
    ]
}

Order

createOrder

Create new order

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Client
string
Example: ims-frontend

The client that is making the request.

Request Body schema: application/json
required
create_mode
required
string
Enum: "PURCHASE" "BOOK" "RESERVE" "BOOK_WITH_PAYMENT_AT_BOARDING"

Mode that should be used to create the order

  • PURCHASE - Create an order with tickets which marked as already paid.
  • BOOK - Create an order with booked tickets to be paid later. The booking expiration time depends on trip configuration and returned in the response as booking_expiration_time. If the order is not paid during this time, it will be automatically cancelled.
  • RESERVE - Reserve places for short period of time until payment will be done. The reservation time can be specified in the request using reservation_hold_time parameter. If the order is not paid during this time, it will be automatically cancelled.
  • BOOK_WITH_PAYMENT_AT_BOARDING - Create an order with tickets that should be paid during boarding.

Available modes depend on the allowed_operations for the journey and can be obtained from the search results or journey details.

  • purchase_allowed - allows to create order in PURCHASE and RESERVE modes
  • booking_allowed - allows to create order in BOOK mode
  • payment_at_boarding_allowed - allows to create order in BOOK_WITH_PAYMENT_AT_BOARDING mode
currency_code
required
string

ISO 4217 alpha-3 currency code of this order

journey_id
required
string

ID of journey from a search result

required
Array of objects (CreateOrderRequestItem) non-empty

List of passengers and their places for all journey rides.

cashless_payment
boolean

Whether the order have been paid using cashless method. Can be specified only with 'create_mode' = PURCHASE. By default is false

reservation_hold_time
string

Time during which seats will be reserved before payment confirmation or automatic cancellation of the order. Can be specified only with 'create_mode' = RESERVE. Formatted as ISO8601 duration. Up to 2 hours.

customer_id
string <uuid>

ID of the customer of your organization for whom this order is created

Responses

Request samples

Content type
application/json
{
  • "create_mode": "RESERVE",
  • "currency_code": "EUR",
  • "journey_id": "ZGlyZWN0fDF8OTI5MTU4fDExMzY4OTR8OGJlYjA4ZmMtZjcyYS00MjczLTgyNmEtZjJkMzU4MzBmNGRj",
  • "order_items": [
    ],
  • "cashless_payment": false,
  • "reservation_hold_time": "PT30M",
  • "customer_id": "6ef93320-28ad-4a1f-9aed-479e28fa567f"
}

Response samples

Content type
application/json
{
  • "id": "7aed543e-2ab8-4ed5-af43-f116eb47207c",
  • "number": "1231",
  • "creation_details": {
    },
  • "payment_details": {
    },
  • "cancellation_details": {
    },
  • "reissued_from": {
    },
  • "reissue_details": {
    },
  • "reservation_expires_at": "2022-07-21T17:32:28Z",
  • "booking_expires_at": "2022-07-21T17:32:28Z",
  • "price": {
    },
  • "customer": {
    },
  • "allowed_operations": [
    ],
  • "available_operations": {
    },
  • "tickets": [
    ]
}

getOrderById

Get an order

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
query Parameters
ticket_id
string <uuid>
Deprecated
Example: ticket_id=9950e86b-024a-4dcf-9276-8e1c5e6e240f

If this parameter is specified then the response contains data only for the given ticket ID. Deprecated.

include_tickets
boolean
Default: true
Example: include_tickets=false

If this parameter is true then the response contains tickets.

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "id": "7aed543e-2ab8-4ed5-af43-f116eb47207c",
  • "number": "1231",
  • "creation_details": {
    },
  • "payment_details": {
    },
  • "cancellation_details": {
    },
  • "reissued_from": {
    },
  • "reissue_details": {
    },
  • "reservation_expires_at": "2022-07-21T17:32:28Z",
  • "booking_expires_at": "2022-07-21T17:32:28Z",
  • "price": {
    },
  • "customer": {
    },
  • "allowed_operations": [
    ],
  • "available_operations": {
    },
  • "tickets": [
    ]
}

confirmPaymentForOrder

Confirm payment for a previously booked or reserved order

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
Request Body schema: application/json
required
cashless_payment
required
boolean

Whether the order have been paid using cashless method.

Responses

Request samples

Content type
application/json
{
  • "cashless_payment": false
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request was specified incorrectly. Please check."
}

cancelOrder

Cancel order. All tickets will be cancelled. Paid orders can be cancelled within a limited time window after payment confirmation or order creation to cancel an erroneous purchase operation.

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c

Responses

Response samples

Content type
application/json
{
  • "order": {
    },
  • "tickets": [
    ]
}

getOrderTicketFormsAsPdf Deprecated

Get a PDF document with ticket printed forms of the order. If specified the ticket_id parameter then a response contains a print form only for this ticket. Deprecated: use /orders/{order_id}/tickets/printout/pdf instead

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
query Parameters
ticket_id
string <uuid>
Example: ticket_id=9950e86b-024a-4dcf-9276-8e1c5e6e240f

If this parameter is specified then the response contains data only for the given ticket ID.

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request was specified incorrectly. Please check."
}

getOrderTicketPdf

Get a PDF document with ticket printed forms of the order. If specified the ticket_id parameter then a response contains a print form only for this ticket.

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
query Parameters
ticket_id
string <uuid>
Example: ticket_id=9950e86b-024a-4dcf-9276-8e1c5e6e240f

If this parameter is specified then the response contains data only for the given ticket ID.

header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request was specified incorrectly. Please check."
}

getTicketRefundOptions

Get options that can be used to refund ticket

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
ticket_id
required
string <uuid>
Example: 92d9acb4-2daa-49c9-b193-bea48eb54fc9
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

refundTicket

Refund specified ticket

Authorizations:
bearerAuth
path Parameters
order_id
required
string <uuid>
Example: 7aed543e-2ab8-4ed5-af43-f116eb47207c
ticket_id
required
string <uuid>
Example: 92d9acb4-2daa-49c9-b193-bea48eb54fc9
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Request Body schema: application/json
required
refund_type
required
string
Enum: "BY_RULE" "FULL" "BLOCKED_TRIP" "CUSTOM"

The type of the refund which will be used for the refund operation. CUSTOM refund is not available here, can only be used for refund amendment

percentage_to_refund
number

Percentage to be return by rule. Specified for refund type BY_RULE. Should be from one of available refund options.

enforce_refund
boolean

Whether requesting refund with specified refund type that is not available in the refund options list. It is not guaranteed that request will be performed

non_refundable_sales_commission
boolean

Whether agent commission should be taken first. Applicable only for BlaBlaCar-affiliated agents

Responses

Request samples

Content type
application/json
{
  • "refund_type": "BY_RULE",
  • "percentage_to_refund": 50,
  • "enforce_refund": false,
  • "non_refundable_sales_commission": false
}

Response samples

Content type
application/json
{
  • "ticket_id": "92d9acb4-2daa-49c9-b193-bea48eb54fc9",
  • "ticket_number": "6548732",
  • "ticket_price": 250.5,
  • "currency_code": "UAH",
  • "ticket_created_at": "2022-01-01T11:11:11Z",
  • "ticket_refunded_at": "2022-01-02T10:05:11Z",
  • "departure": {
    },
  • "arrival": {
    },
  • "passenger": {
    },
  • "seat": {
    },
  • "bus": {
    },
  • "bus_line": {
    },
  • "trip": {
    },
  • "carrier": {
    },
  • "insurer": {
    },
  • "inventory_source": {
    },
  • "branding": {
    },
  • "qr_code": {
    },
  • "seller_contacts": {
    },
  • "used_refund_option": {
    },
  • "refund_breakdown": {
    },
  • "ticket_note": "string"
}

cancelTicketById

Cancel one ticket. Paid ticket can be cancelled within a limited time window after payment confirmation or order creation to cancel an erroneous purchase operation.

Authorizations:
bearerAuth
path Parameters
ticket_id
required
string <uuid>
Example: 92d9acb4-2daa-49c9-b193-bea48eb54fc9

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "Request was specified incorrectly. Please check."
}

getTicketById

Get a ticket

Authorizations:
bearerAuth
path Parameters
ticket_id
required
string <uuid>
Example: 92d9acb4-2daa-49c9-b193-bea48eb54fc9
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

Responses

Response samples

Content type
application/json
{
  • "id": "92d9acb4-2daa-49c9-b193-bea48eb54fc9",
  • "order_id": "7aed543e-2ab8-4ed5-af43-f116eb47207c",
  • "number": "6548732",
  • "created_by_organization": {
    },
  • "status_details": {
    },
  • "departure": {
    },
  • "arrival": {
    },
  • "route_details": {
    },
  • "passenger": {
    },
  • "seat": {
    },
  • "bus_line": {
    },
  • "trip": {
    },
  • "bus": {
    },
  • "carrier": {
    },
  • "insurer": {
    },
  • "inventory_source": {
    },
  • "price_details": {
    },
  • "price_breakdown": {
    },
  • "payment_details": {
    },
  • "refund_request": {
    },
  • "refund_details": {
    },
  • "refund_rules": {
    },
  • "luggage_rules": "You may have only one 30kg bag",
  • "reissued_from": {
    },
  • "reissue_details": {
    },
  • "branding": {
    },
  • "qr_code": {
    },
  • "available_operations": {
    },
  • "note": "string"
}

Overview

Timetable and axes common information

getSellableInventoryOverview

Get an overview of the inventory available for sale

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Currency
string
Example: gbp

The currency that will be used when including prices in response

Responses

Response samples

Content type
application/json
{
  • "currency": "UAH",
  • "bus_lines": [
    ]
}

getSellableTripSeatsOverview

Get an overview of the trip seats available for sale

Authorizations:
bearerAuth
header Parameters
X-Locale
required
string <BCP47Locale> (BCP47Locale) ^([a-zA-Z]{2,3})(-[a-zA-Z]{4})?(-[a-zA-Z]{2}|...
Example: en-GB

The locale on which the response will be created

X-Currency
string
Example: gbp

The currency that will be used when including prices in response

Request Body schema: application/json
required
trip_departure_date
required
string <local-date>

Departure date of the trips included in the seat availability overview

Responses

Request samples

Content type
application/json
{
  • "trip_departure_date": "2024-05-31"
}

Response samples

Content type
application/json
{
  • "currency": "UAH",
  • "trips": [
    ]
}

Versions

Changelog

[2.0.6] - 2026-03-30

Changes

  • Added support for the fixed amount discounts
    • in the /journeys/search response ticket_pricing.ticket_automatic_discount_percentage is deprecated in favor of the new automatic_discount.value property.
    • in the RideDiscount model the percentage property is deprecated in favor of the new value property. It affects the following:
      • statutory_discounts in the /journeys/search response
      • automatic_discount and available_discounts in the /journeys/details response
    • added value_type property to the ticket discount model to indicate whether the discount is a percentage or a fixed amount.
  • Added branding to the Ride model with carrier organization brand name.
  • Added route_details to the Ticket with information about bus changes.
  • In the Ticket model extended the insurer object with insurance_contract containing information about the insurance contract related to the ticket.
  • Deprecated GET inventory/orders/{order_id}/tickets-form/pdf in favor of the new GET inventory/orders/{order_id}/tickets/printout/pdf endpoint.

[2.0.5] - 2025-11-05

Changes

  • The price_breakdown, refund_rules, luggage_rules, branding, and qr_code properties added to the ticket model.
    • price_breakdown: Provides a detailed breakdown of the ticket price components.
    • refund_rules: Contains information about the refund conditions for the ticket.
    • luggage_rules: A text description of the luggage transportation rules.
    • branding: Contains organization branding data for ticket forms.
    • qr_code: Provides a QR code for use with the driver mobile application.
  • A new ordering object has been added to the details of journey response model. This introduces several new schemas to provide detailed information about what passenger data is recommended for booking.
  • Added the sales_closing_planned_at field to the details of journey model for each ride.
  • Added the ees_passenger_verification_required field to the details of journey model for each ride.
  • The document field in CreateOrderPassenger and TicketPassenger schemas now references PassengerTravelDocument instead of PassengerDocument.
  • The document field in CreateOrderPassenger and TicketPassenger schemas which references PassengerDocument renamed to discount_document.
  • The new PassengerTravelDocument schema expands the document information to include issuing_country and expiration_date.
  • The point_id and point_name fields in the RideBusChange schema are now deprecated. They are replaced by a new point object.
  • The X-Locale header parameter was changed from a generic string to a stricter BCP47Locale format.
  • The TicketRefund schema was renamed to TicketRefundDetails. The structure of these renamed schemas remains the same
  • The ExtendedPhoneNumber schema was renamed to OrganizationPhoneNumber. The structure of these renamed schemas remains the same
  • The payment_processing field has been removed from the order model.
  • The detailed_passenger_information_required field in the details of journey ride models is now marked as deprecated.

[2.0.4] - 2025-07-17

Changes

  • The payment_processing parameter for the PUT inventory/orders/{order_id} endpoint has been removed since it was never supported

[2.0.3] - 2025-06-25

Changes

  • The ticket_id parameter for the GET inventory/orders/{order_id} endpoint has been deprecated

[2.0.2] - 2025-02-14

Changes

  • Added endpoints inventory/customers/accounts/** for customer account management
  • Added endpoint organizations/carriers/name-lookup for bulk carrier names lookup
  • Added new passenger_count parameter to inventory/journeys/search endpoint
  • Added new customer_id parameter to inventory/journeys/search endpoint
  • Added new customer_id parameter to inventory/journeys/details endpoint
  • The passengers_size parameter for the inventory/journeys/details endpoint has been deprecated and a new passenger_count parameter has been added instead
  • Added new BONUS_TRIP category to available discounts with qualifying_trip_count and ticket_limit individual properties
  • Added new created_by_organization field to the ticket details information in responses related to orders and tickets

[2.0.1] - 2024-11-07

Changes

  • Fixed path for endpoints /inventory/orders/** instead of incorrect /orders/orders/**
  • In input parameters of the PUT /inventory/orders/{order_id} endpoint, the field order_items[].passenger.document.number became optional
  • In response to a request to the POST /organizations/authentication/login endpoint, two new fields have been added: user_id, organization_id