Cancellation and reschedule

​

Cancellation & reschedule policies

Cancellation and reschedule behavior is defined explicitly in the Product Details API.

​

Eligibility and cutoff

• cancellationPolicy.cancellable and reschedulePolicy.reschedulable are simple booleans — the operation is either allowed or not allowed.
• cancellableUpToInMinutes / reschedulableUpToInMinutes define the cutoff before the experience start time. Requests submitted after the cutoff are not accepted.
• Policies may differ across products and across variants of the same product. Read them from the API per variant; do not assume uniform behavior.

Partners must:

• Read and rely on the API response
• Surface the correct policy to users before booking
• Not assume uniform behavior across variants

​

Refund handling

Refunds are a separate concern from cancellation eligibility. The cancellable flag and cancellableUpToInMinutes cutoff only determine whether Headout accepts the cancellation — they do not describe how money is returned. API Partner accounts

• When an eligible booking is cancelled, the partner’s Headout wallet is topped up automatically with the full booking amount.
• The partner is responsible for refunding the end customer through their own payment system. Headout does not contact or refund the end customer.

Affiliate accounts

• When an eligible booking is cancelled, Headout refunds the end customer directly.

​

Cancellation & reschedule lifecycle

Cancellation and reschedule are not a pollable status machine like booking status. They are asynchronous requests: you submit one, Headout fulfils it against the supplier in the background, and you observe the effect on the booking. There is no separate “cancellation status” or “reschedule status” to query.

​

Request flow

Both Cancel and Reschedule follow the same two-phase shape:

1. Synchronous acknowledgement. The endpoint validates input, ownership, and business rules (eligibility, cutoff window, valid future slot for reschedule) and returns immediately. success: true means the request was accepted into the asynchronous queue — it does not mean it has been fulfilled. success: false means it was rejected up-front (e.g. a business-rule failure) and no async job is enqueued.
2. Asynchronous fulfilment. The request is processed against the supplier in the background. The submit acknowledgement is not the outcome — always treat the booking itself (via webhook or Get Booking) as the source of truth.

​

Outcomes

Cancellation:

• → CANCELLED when the supplier cancellation succeeds. A CANCELLED booking-status webhook fires; the change is also visible on Get Booking.
• → no change if the supplier can’t cancel. The request stays pending and the booking remains confirmed until it’s resolved (may need manual intervention). Acceptance at submit time does not guarantee cancellation.

Reschedule:

• → re-booked on the new slot when it succeeds. The booking round-trips CANCELLED → PENDING → COMPLETED and startDateTime / endDateTime update to the new slot. The intermediate CANCELLED is not terminal.
• → no change on failure. The booking stays on its original slot and status.

Because a successful reschedule re-books the booking, how you observe it differs by channel:

• Webhooks — you receive a PENDING then a COMPLETED event for the same bookingId. The intermediate CANCELLED is suppressed, so no CANCELLED webhook is sent for a reschedule. Don’t treat the PENDING event as a brand-new booking.
• Polling Get Booking — a poll landing mid-reschedule can transiently return CANCELLED before the booking returns to PENDING → COMPLETED. Don’t treat a CANCELLED poll result as terminal while a reschedule is in flight.

​

Key notes

• Rely on the booking, not the acknowledgement. A success: true response only means the request was queued. Confirm the actual outcome via webhook or Get Booking.
• CANCELLED is not always terminal. It’s final for a genuine cancellation, but a reschedule round-trips the booking through CANCELLED and back to PENDING → COMPLETED. Don’t hard-code CANCELLED as a final state — especially when polling.
• Cancellation and reschedule are mutually exclusive. A new request is rejected while the other operation is still being processed.
• Cancellation is idempotent. Re-cancelling an already-cancelled booking returns success without side effects; a cancellation that previously failed can be retried.
• Reschedule is one-shot. A booking that has already been rescheduled cannot be rescheduled again, and a reschedule that previously failed is blocked — contact your Headout SPOC for manual intervention.