Cancel Booking

Checking Cancellation Conditions

Once a customer has booked a ticket, Distribusion enables customer facing platforms to display the cancellation conditions that apply to the user’s booking.

The /cancellations/conditions endpoint requires only the booking_id to be specified and returns three parameters from which the cancellation conditions can be identified and clearly displayed:

• allowed : Boolean, specifies whether the booking is cancellable or not.
• fee : The charge that will apply to the cancellation of the booking and must be deducted from the booking price to compute the refund value. The value is provided in the carrier’s currency (fractional unit), which is also specified in the response.
• cutoff : The latest time at which the booking can be cancelled at this fee, e.g. 2025-06-15T06:05.

Conducting a Cancellation

The /cancellations/create endpoint enables the execution of the cancellation and requires only the booking_id to be specified. The response provides the information that can be displayed to the user to confirm the cancellation:

• total_price : The total price of the original booking.
• fee : The amount that has been charged for the cancellation.
• total_refund : The amount that can be refunded to the customer, calculated as total price - fee.
• created_at : Time stamp of execution of cancellation.

The booking will be cancelled in the carrier’s system and accordingly accounted for in the following clearing cycle between the retail platform and Distribusion.

For specific carriers like SNCF, a cancellation request may not be confirmed immediately. In these cases, the response from /cancellations/create will have a state of "pending". This scenario requires a special asynchronous process to check for the final cancellation status. For complete details, please see the full guide on how to Support Asynchronous Cancellations.

Partial Cancellations

Partial cancellations are not supported by Distribusion yet. It means only the full booking can be cancelled, and cancellations for just one of the passengers in the booking, for one of the segments only (outbound or inbound) or for ancillaries only are not supported.

Grace Period Cancellations

For certain carriers, a special cancellation window known as a "grace period" is available, typically for a few hours after the booking is made. This allows for a cancellation, often without a fee, under specific conditions. Deutsche Bahn is one of the carriers that supports both regular and grace period cancellations. The duration of the grace period is not fixed; it can be 3, 6, or even 12 hours, depending on your agreement with DB.

The type of cancellation you wish to perform is determined by the presence of the reason parameter in your API calls. To request a grace period cancellation for a DB booking, you must send a request to the /cancellations/conditions and /cancellations/create endpoints and include the parameter reason=value ticket_not_used. If you attempt a cancellation after the window has closed, the API will return a successful response but with allowed: false in the body, indicating that the grace period cancellation is not possible.

Technical Cancellations

Technical cancellations, often referred to as "voids" in carrier terminology, allow retailers to cancel and refund a ticket immediately after booking, bypassing potential penalties or standard cancellation fees. This functionality is offered by Deutsche Bahn and SNCF and is intended strictly for cases where a technical issue occurred during the automated booking flow (e.g., a timeout with the Payment Service Provider where a ticket was issued but the payment failed, or a distribution channel error).

To request a technical cancellation, you must include the parameter reason=technical_cancellation in your API calls to /cancellations/conditions and /cancellations/create. If you attempt a cancellation after the window has closed, the API will return a successful response but with allowed: false in the body, indicating that the technical cancellation is not possible.

SNCF usually allows technical cancellations for the duration of the current accounting session (the current day).

Best Practices

1. Make live calls to /cancellations/conditions: The /cancellations/conditions endpoint is a live call to the carrier’s system and returns the conditions that are valid at the time of the request. These conditions can change over time if the carrier has dynamic cancellation conditions and should thus be retrieved whenever the user opens a page on which the cancellation conditions are displayed.
2. Display the cancellation conditions to user: It is recommended to display the full conditions of cancellation to users at the time they initiate the process to request a cancellation. This could appear as a popup to confirm the cancellation, but it can also be displayed in other ways.
3. Define sender of cancellation 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. If set to false, you also have to create a version of the cancellation email. For more details check our Ticket Delivery guide.

Enterprise Features

Besides cancelling a booking, some carriers support amendments to bookings. For more details about how to handle it, check our Amendments guide.

API Examples

Sample Request to /cancellations/conditions

 
https://api.distribusion.com/retailers/v4/cancellations/conditions?booking=XJUYXc0HyEoPfi6-IUn_SA

Sample Response from /cancellations/conditions

 
{
    "data": {
        "id": "XJUYXc0HyEoPfi6-IUn_SA",
        "type": "cancellation_conditions",
        "attributes": {
            "allowed": true,
            "fee": 3100,
            "monetary_refund": 12400,
            "voucher_refund": 0,
            "cutoff": "2024-09-03T07:30"
        },
        "relationships": {
            "deductions": {
                "data": []
            },
            "fees": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR"
    },
    "included": []
}

For more samples responses, check the /cancellations/conditions endpoint page.

Sample Request to /cancellations/create

https://api.distribusion.com/retailers/v4/cancellations/create?booking=XJUYXc0HyEoPfi6-IUn_SA 

Sample Response from /cancellations/create

 
{
    "data": {
        "id": "SraLnTNoeDw4z6Qg9bDmSQ",
        "type": "cancellations",
        "attributes": {
            "state": "confirmed",
            "total_price": 15500,
            "fee": 3100,
            "total_refund": 12400,
            "monetary_refund": 12400,
            "voucher_refund": 0,
            "created_at": "2024-08-26T16:22",
            "confirmation_expected_at": null
        },
        "relationships": {
            "fees": {
                "data": []
            },
            "vouchers": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR"
    },
    "included": []
}

For more samples responses, check the /cancellations/create endpoint page.