Adding cancel for any reason

Preview

This is not yet finalised. It may change, or be removed or be not yet accessible.

What do you need to start?

Note: this service is only available by request during the beta phase. If you wish to book Cancel For Any Reason services, please contact us via the Help Centre or via email

This guide will go through the changes you need to make in the booking flow to be able to list and book a Cancel For Any Reason service on an offer. It's important you know the basics of how to create a booking.

If you are not familiar with how to create an order please head over to our Quick Start Guide.
This guide will start from an offer so make sure you grab an offer ID for a flight before we start.

Tip

We've put together a Postman Collection that contains all of the requests you'll need to follow along with this guide.

Overview

The Cancel For Any Reason (CFAR) service allows customers to claim a percentage refund on their flight in the event that they need to cancel, subject to terms and conditions.

CFAR is listed among the available_services. Available services are specific to an offer but not surfaced through the API by default. The changes we'll make to work with available services are:

Retrieve an offer along with its available_services
Look for the CFAR service in the list of available items
Include the service on order creation
See the service booked on an order

Getting services for an offer

We start by fetching the offer to make sure to get its most up-to-date information. The get offer endpoint gives you the ability to retrieve available services with the offer by applying the query parameter return_available_services set to true. Using a valid offer ID you can use:

Shell
curl -X GET --compressed "https://api.duffel.com/air/offers/$OFFER_ID?return_available_services=true"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Duffel-Version: v2"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

This request will return an offer which now includes the available_services attribute.

Available services

Returned services have a type property at their top level. Filtering this to cancel_for_any_reason will show if the service is available on the selected offer.

Cancel for any reason is only purchasable for an entire flight for all passengers, so the segment_ids and passenger_ids should have all flight segments and all passengers listed.

The services has fields total_cost and total_currency to expose the cost of adding this service to an order.

The metadata block includes a variety of information describing the offered service and details relevant to the customer. These include:

terms_and_conditions_url - URL with the terms and conditions for customers

merchant_copy - Information to display to customers

refund_amount - The amount the customer will receive back if the service is used, in total_currency

Learn more

For a complete description of the available services schema check out the API reference.

https://duffel.com/docs/api/offers/schema

Booking with services

Once you know what offer and service a user wants to book, all you have to do is send a request to the create order endpoint with 2 small changes to the payload.

Shell
curl -X POST --compressed "https://api.duffel.com/air/orders"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Duffel-Version: v2"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
  -d '{
  "data": {
    "selected_offers": ["'"$OFFER_ID"'"],
    "payments": [
      {
        "type": "balance",
        "currency": "'"$TOTAL_CURRENCY"'",
        "amount": "'"$TOTAL_AMOUNT"'"
      }
    ],
    "passengers": [
      {
        "phone_number": "+442080160508",
        "email": "tony@example.com",
        "born_on": "1980-07-24",
        "title": "mr",
        "gender": "m",
        "family_name": "Stark",
        "given_name": "Tony",
        "infant_passenger_id": "'"$INFANT_PASSENGER_ID"'",
        "id": "'"$ADULT_PASSENGER_ID_1"'"
      },
      {
        "phone_number": "+442080160509",
        "email": "potts@example.com",
        "born_on": "1983-11-02",
        "title": "mrs",
        "gender": "m",
        "family_name": "Potts",
        "given_name": "Pepper",
        "id": "'"$ADULT_PASSENGER_ID_2"'"
      },
      {
        "phone_number": "+442080160506",
        "email": "morgan@example.com",
        "born_on": "2019-08-24",
        "title": "mrs",
        "gender": "f",
        "family_name": "Stark",
        "given_name": "Morgan",
        "id": "'"$INFANT_PASSENGER_ID"'"
      }
    ],
    "services": [
      {
        "quantity": 2,
        "id": "'"$SERVICE_ID_1"'"
      },
      {
        "quantity": 1,
        "id": "'"$SERVICE_ID_2"'"
      }
    ]
  }
}'

You must add the attribute services to your request payload. This field should contain a list of services to be book along with the offer specified in the selected_offers field. Each service on the list here must contain the available service ID ($SERVICE_ID_N) and the desired quantity.

The payment amount ($TOTAL_AMOUNT) must be increased by the amount times quantity of each service you'd like to purchase. For example, if your offer total is 50 GBP and you include service A with quantity 2 and total_amount 10 GBP, the amount of the payment should now be 70 GBP.

Services on Order

Once the booking has gone through in the airline's system we will return the usual order create response payload to you. You can always retrieve your order by ID:

Shell
curl -X GET --compressed "https://api.duffel.com/air/orders/$ORDER_ID"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Duffel-Version: v2"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

Services

The service object will look exactly the same as the available service except for maximum_quantity being replaced with quantity.

Claiming

During the beta phase, there is not yet an API-driven method of claiming a CFAR cancellation. To request a cancellation and refund, please contact Duffel via the Help Centre or via email, and the refund will be credited back to your balance.

Learn more

To look at the services and documents schema, please visit our API reference:

https://duffel.com/docs/api/offers/schema

Keep Learning

Now you are able to add Cancel For Any Reason to an order! Once we support more ancillary services you'll be able to rely on the same flow but apply it to other available service types. If you'd like to get a deeper look into the API reference to learn more you can jump to: