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 supported for select carriers, enabling you to cancel individual passengers or specific segments (outbound or inbound) from a booking without cancelling the entire reservation. Partial cancellations use the same /cancellations/conditions and /cancellations/create endpoints as full cancellations. To scope the cancellation, include one of the following optional parameters:

• connection_id : Cancel all passengers on a single bound (outbound or inbound) of a return trip
• passenger_ids[] : Cancel one or more specific passengers while keeping others active.

When neither parameter is provided, the request is treated as a full cancellation. For complete implementation details, request/response examples, and parameter specifications, see the Partial Cancellations guide.

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 with 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 with value 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?reason=ticket_not_used&booking=bKfceMXeLq_WeRIBspfsmg

Sample Response from /cancellations/conditions

 
{
    "data": {
        "id": "bKfceMXeLq_WeRIBspfsmg",
        "type": "cancellation_conditions",
        "attributes": {
            "allowed": true,
            "fee": 580,
            "monetary_refund": 2320,
            "voucher_refund": 0,
            "reason": "ticket_not_used",
            "partially_cancellable": false,
            "cutoff": "2026-04-27T12:19"
        },
        "relationships": {
            "deductions": {
                "data": []
            },
            "fees": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR"
    },
    "included": []
}

Sample Request to /cancellations/create

 
{
    "booking": "bKfceMXeLq_WeRIBspfsmg",
    "reason": "ticket_not_used"
}

Sample Response from /cancellations/create

 
{
    "data": {
        "id": "ZRAOjgPvBje0jaLcK4VeAw",
        "type": "cancellations",
        "attributes": {
            "state": "confirmed",
            "reason": "ticket_not_used",
            "created_as_partial": false,
            "fully_cancelled": true,
            "total_price": 2900,
            "fee": 580,
            "latest_fee": 580,
            "total_refund": 2320,
            "latest_refund": 2320,
            "monetary_refund": 2320,
            "latest_monetary_refund": 2320,
            "voucher_refund": 0,
            "latest_voucher_refund": 0,
            "created_at": "2026-04-10T17:33",
            "confirmation_expected_at": null
        },
        "relationships": {
            "agent": {
                "data": null
            },
            "customer": {
                "data": null
            },
            "fees": {
                "data": []
            },
            "vouchers": {
                "data": []
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "currency": "EUR"
    },
    "included": []
}