Order Cancellations

To cancel an order, you'll need to create an order cancellation, check the refund_amount returned, and, if you're happy to go ahead and cancel the order.

The refund specified by refund_amount, if any, will be returned to your original payment method (i.e. your Duffel balance). You'll then need to refund your customer (e.g. back to their credit/debit card).

Schema

confirmed_at
datetime

The ISO 8601 datetime that indicates when the order cancellation was confirmed

Example: "2020-01-17T11:51:43.114803Z"
created_at
datetime

The ISO 8601 datetime at which the order cancellation was created

Example: "2020-04-11T15:48:11.642Z"
expires_at
datetime

The ISO 8601 datetime by which this cancellation must be confirmed

Example: "2020-01-17T10:42:14.545052Z"
id
string

Duffel's unique identifier for the order cancellation

Example: "ore_00009qzZWzjDipIkqpaUAj"
live_mode
boolean

Whether the order cancellation was created in live mode. This field will be set to true if the order cancellation was created in live mode, or false if it was created in test mode.

Example: false
order_id
string

Duffel's unique identifier for the order

Example: "ord_00009hthhsUZ8W4LxQgkjo"
refund_amount
string

The amount that will be returned to the original payment method if the order is cancelled, determined according to the fare conditions. This may be 0.00 if the fare is non-refundable. It will include the refund amount of the flights and the services booked.

Example: "90.80"
refund_currency
string

The currency of the refund_amount, as an ISO 4217 currency code. It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered). For hold orders that are awaiting payment, the refund amount will always be 0.00.

Example: "GBP"
refund_to
enum

Where the refund, once confirmed, will be sent. card is currently a restricted feature. awaiting_payment is for pay later orders where no payment has been made yet.

Possible values: "arc_bsp_cash", "balance", "card", "voucher", or "awaiting_payment"

List order cancellations

Retrieves a paginated list of order cancellations

Query Parameters

after
string

A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
before
string

A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
limit
integer

The maximum number of records to return per page. Defaults to 50. May be set to any integer between 1 and 200. For more information on how to paginate through records, see the Pagination section.

Example: 1
Default value: 50
order_id
string

Filters the returned order cancellations by a specific order's unique identifier.

Example: "ord_00009hthhsUZ8W4LxQgkjo"

Endpoint

GET https://api.duffel.com/air/order_cancellations

Request

curl -X GET --compressed "https://api.duffel.com/air/order_cancellations?after=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&before=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&limit=1&order_id=ord_00009hthhsUZ8W4LxQgkjo" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Duffel-Version: beta" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
  "meta": {
    "limit": 50,
    "after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
  },
  "data": [
    {
      "refund_to": "arc_bsp_cash",
      "refund_currency": "GBP",
      "refund_amount": "90.80",
      "order_id": "ord_00009hthhsUZ8W4LxQgkjo",
      "live_mode": false,
      "id": "ore_00009qzZWzjDipIkqpaUAj",
      "expires_at": "2020-01-17T10:42:14.545052Z",
      "created_at": "2020-04-11T15:48:11.642Z",
      "confirmed_at": "2020-01-17T11:51:43.114803Z"
    }
  ]
}

Create a pending order cancellation

To begin the process of cancelling an order you need to create an order cancellation. The OrderCancellation will contain the refund_amount due from the Airline.

To proceed, you must confirm the cancellation using the Confirm an order cancellation endpoint.

Body parameters

order_id
string
required

Duffel's unique identifier for the order

Example: "ord_001"

Endpoint

POST https://api.duffel.com/air/order_cancellations

Request

curl -X POST --compressed "https://api.duffel.com/air/order_cancellations" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Duffel-Version: beta" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
  "data": {
    "order_id": "ord_001"
  }
}'

Response

{
  "data": {
    "refund_to": "arc_bsp_cash",
    "refund_currency": "GBP",
    "refund_amount": "90.80",
    "order_id": "ord_00009hthhsUZ8W4LxQgkjo",
    "live_mode": false,
    "id": "ore_00009qzZWzjDipIkqpaUAj",
    "expires_at": "2020-01-17T10:42:14.545052Z",
    "created_at": "2020-04-11T15:48:11.642Z",
    "confirmed_at": "2020-01-17T11:51:43.114803Z"
  }
}

Confirm an order cancellation

Once you've created a pending order cancellation, you'll know the refund_amount you're due to get back.

To actually cancel the order, you'll need to confirm the cancellation. The booking with the airline will be cancelled, and the refund_amount will be returned to the original payment method (i.e. your Duffel balance). You'll then need to refund your customer (e.g. back to their credit/debit card).

URL parameters

id
string
required

Duffel's unique identifier for the order cancellation

Example: "ore_00009qzZWzjDipIkqpaUAj"

Endpoint

POST https://api.duffel.com/air/order_cancellations/{id}/actions/confirm

Request

curl -X POST --compressed "https://api.duffel.com/air/order_cancellations/{id}/actions/confirm" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Duffel-Version: beta" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
  "data": {
    "refund_to": "arc_bsp_cash",
    "refund_currency": "GBP",
    "refund_amount": "90.80",
    "order_id": "ord_00009hthhsUZ8W4LxQgkjo",
    "live_mode": false,
    "id": "ore_00009qzZWzjDipIkqpaUAj",
    "expires_at": "2020-01-17T10:42:14.545052Z",
    "created_at": "2020-04-11T15:48:11.642Z",
    "confirmed_at": "2020-01-17T11:51:43.114803Z"
  }
}

Get a single order cancellation

Retrieves an order cancellation by its ID.

URL parameters

id
string
required

Duffel's unique identifier for the order cancellation

Example: "ore_00009qzZWzjDipIkqpaUAj"

Endpoint

GET https://api.duffel.com/air/order_cancellations/{id}

Request

curl -X GET --compressed "https://api.duffel.com/air/order_cancellations/{id}" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Duffel-Version: beta" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
  "data": {
    "refund_to": "arc_bsp_cash",
    "refund_currency": "GBP",
    "refund_amount": "90.80",
    "order_id": "ord_00009hthhsUZ8W4LxQgkjo",
    "live_mode": false,
    "id": "ore_00009qzZWzjDipIkqpaUAj",
    "expires_at": "2020-01-17T10:42:14.545052Z",
    "created_at": "2020-04-11T15:48:11.642Z",
    "confirmed_at": "2020-01-17T11:51:43.114803Z"
  }
}