The imin Platform
2.0.0
2.0.0
  • Introduction to the imin Platform
  • Using the Platform
    • imin's Platform Products
    • Authentication
    • Our Platform Data
      • Understanding Responses
      • Namespaces and Extensions
      • Defensive Data Consumption
      • Mocking the Interface
  • platform products
    • Search
      • imin Events API
        • Events API Reference
        • Virtual & Physical Sessions
        • Concepts
          • EventSeries
          • ScheduledSessions and eventSchedules
          • Activities and Collections
            • Activities
            • Activity Concept Collections
          • Accessibility Support
          • Prices
        • Filters
          • Modes
          • Age Ranges
          • Dates and Times
          • Activities and Concept Collections
          • High Frequency Sessions
      • imin Facilities API
        • Query Parameter Search
          • Mandatory Query Parameters
            • mode=discovery-geo
            • mode=upcoming-slots
          • Optional Query Parameters
        • ByID Search
          • FacilityUse By-ID
          • Slot By-ID
        • FacilityUses and IndividualFacilityUses
        • Slots
        • Facilities Slot Booking
      • imin Places API [BETA]
        • Example Request & Response
    • Firehose
      • Introduction to the Firehose
      • Accessing the Firehose
      • Firehose Usage Policy & Restrictions
      • Firehose and Search
      • Bookable Firehose Feeds
      • Bookable Sellers Feed
      • Attribution Catalog Endpoint
    • Live Timetables
      • Pre-Requisites: Open Data Feeds
      • The Onboarding Process
        • 1. Ensuring your Data Offers the Best User Experience
        • 2. Setting up and Embedding your First Timetable
        • 3. Setting up the Rest of your Timetables
        • 4. Activating Booking via Guest Checkout
      • Features Available Upon Request
      • Styling the Live Timetables
      • FAQs
    • Data Dashboard
  • incorporating book and pay
    • imin Branded Checkout
      • Introduction
      • Setup
        • Information We Require From You
        • Actions You Need to Complete
      • Authenticated Checkout
        • Testing [BETA]
        • 👪Group Booking [BETA]
      • Standalone Checkout
      • Firehose and Checkout [BETA]
        • Loading the Checkout via Firehose
    • imin Booking Platform
      • Customer Account Management
        • Create Customer Account
        • Update Customer Account
        • Get Customer Account
        • Delete Customer Account
        • Example Scenario
        • Payment Card Management
        • Linked Accounts
        • Entitlement
          • Evidence Requests
          • Entitlement Pricing in Search
          • Entitlement Pricing in Checkout
        • Access Pass
        • Webhooks
      • Orders
        • Order History
        • Order (by ID)
        • Cancellations & Refunds
      • Upcoming OrderItems
      • Receipt (by ID)
  • imin and booking systems
    • Seller Onboarding
      • API
  • HINTS & TIPS
    • Get the Best Out of Search
      • Displaying Schedule Information
      • URLs and Offering a Call to Action
      • Searching by Activity
      • Your Search Results and HighFrequencySessions
      • Customer Specific Images
  • Info for Data Publishers
    • Your RPDE Feed & the imin Platform [BETA]
      • Providing Places Data [BETA]
      • Providing Schedule Information [BETA]
Powered by GitBook
On this page
  • Refunds
  • Customer Requested Cancellations
  • Cancellation Endpoint
  • Seller Requested Cancellations
  1. incorporating book and pay
  2. imin Booking Platform
  3. Orders

Cancellations & Refunds

Cancel one or more upcoming OrderItems

PreviousOrder (by ID)NextUpcoming OrderItems

Last updated 3 years ago

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

There are two types of Cancellations that can happen:

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

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

Refunds

All successful cancellations will result in the Customer receiving a .

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 endpoint.

Not all OrderItems are Customer cancellable. The conditions that determine cancellability are detailed in the Booking Spec . We have consolidated this logic into a boolean field named imin:isPresentlyCancellable. This field is calculated at time of the 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 .

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 section for info on how Refunds are processed when an Opportunity has been successfully Cancelled.

Cancellation Endpoint

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.

{
    "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.

This endpoint is an implementation of the .

The cancellation request will also be reflected in the responses from the and theendpoints. The appropriate OrderItems will now have the following:

For more info, please review in the Booking Spec.

Order Cancellation spec in the Open Booking API
Upcoming OrderItems
Order By Id
Seller Requested Cancellations
Broker
Customer Requested Cancellations
Customer
Opportunity
Seller Requested Cancellations
Seller
Refund
Upcoming OrderItems
here
Upcoming OrderItems
Booking System
Refunds