Cancellations & Refunds

Cancel one or more upcoming OrderItems

This guide is intended for a Broker wishing to implement and understand how Cancellations & Refunds work with imin's Booking Platform.

There are two types of Cancellations that can happen:

• Customer Requested Cancellations: Customer decides that they can no longer make an Opportunity (e.g. if the Customer has fallen ill).

• Seller Requested Cancellations: Seller cancels their Opportunity (e.g. if the instructor has fallen ill).

Refunds

All successful cancellations will result in the Customer receiving a Refund.

For either type of successful Cancellation, the Booking System issues a cancelled OrderItem in their OrdersFeed which triggers imin to process the Refund, taking these steps:

1. imin will apply the Refund to the Customer's account. The Customer will see their bank balance go up by the amount of the Refund.

2. imin will send the Customer an email informing them of the successful Refund.

Customer Requested Cancellations

All potentially cancellable OrderItems can be found using the Upcoming OrderItems endpoint.

Not all OrderItems are Customer cancellable. The conditions that determine cancellability are detailed in the Booking Spec here. We have consolidated this logic into a boolean field named imin:isPresentlyCancellable. This field is calculated at time of the Upcoming OrderItems request.

A successful cancellation request does not guarantee that the cancellation is successful. It means that the request has satisfied the pre-conditions and the request has been sent to the Booking System.

Note that cancellations will not always be successful as imin:isPresentlyCancellable is time dependant. If the cancellation request is not successful, this will be indicated in the response. Please use this to determine how to respond to the customer (e.g. an error modal).

Please refer to the Refunds section for info on how Refunds are processed when an Opportunity has been successfully Cancelled.

Cancellation Endpoint

This endpoint is an implementation of the Order Cancellation spec in the Open Booking API.

Headers

X-API-KEY must be provided when making the request to this endpoint. This authorizes you to access the API for your customers.

Request

PATCH https://book.imin.co/api/v2/orders/:orderIdentifier

This request must be made Server-side. Otherwise, it would be possible to view the secret API key with a browser.

Body:

{
  "context": "https://openactive.io/",
  "type": "Order",
  "orderedItem": [
    {
      "type": "OrderItem",
      "id": "https://book.imin.co/api/v2/orders/{{ orderItemIdentifier }}",
      "orderItemStatus": "https://openactive.io/CustomerCancelled"
    }
  ]
}

• orderIdentifier : Identifier of the Order. Can be found in imin:order['identifier'] in the OrderItem

• orderItemIdentifier: Identifier of OrderItem to cancel

Response

For a successful cancellation request, the response will have a 204 HTTP status code and no body.

The cancellation request will also be reflected in the responses from the Upcoming OrderItems and the Order By Id endpoints. The appropriate OrderItems will now have the following:

{
    "type": "OrderItem",
    //...OrderItem fields,
    "orderItemStatus": "https://imin.co/CustomerCancellationPending"
}

We suggest that when the OrderItem has the status of CustomerCancellationPending it is reflected to the customer to inform them of the status of their request. Upon cancellation confirmation by the booking system, the status will transition to CustomerCancelled, a refund will be triggered, and a cancellation email will be sent to the customer.

If cancellation request is not successful, response will have 400 HTTP status code and body:

{
  "@context": "https://openactive.io/",
  "@type": "CancellationNotPermittedError",
  "description": {{ descriptionThatExplainsWhyCancellationIsNotPossible }}
}

Seller Requested Cancellations

Seller Requested Cancellations are out of the scope for this guide as they are implemented by the Booking System.

Seller Requested Cancellation will result in a Refund being issued to the Customer. More details can be found in the Refund section above.

For more info, please review Seller Requested Cancellations in the Booking Spec.