Cancel an appointment, or update it (portal)

With an API key or as a partner: cancel only. Send status: cancelled and a
cancellation_reason. The client is emailed that the appointment was cancelled; the
email promises nothing about money. Cancelling moves no money.

  • API key (the vendor's own, or a partner key naming the vendor in X-Vendor-Code):
    needs the appointments:manage scope. A key cannot refund: refund: true is refused
    with 403 and nothing is cancelled. Refunds are made from the portal.
  • Partner staff (partner portal session naming the vendor in X-Vendor-Code): need
    the partner permission edit appointment (owners and admins by default). Choosing
    refund: true also needs the partner permission refund appointment (owners by
    default).

Any other field, or any status other than cancelled, is refused for these callers
with 403 and nothing changes.

Vendor staff (portal) can also change the staff member, shift, appointment type,
location and attachments, and mark an appointment completed, with the edit appointment
permission.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

Appointment number

Body Params
string | null
enum

Only cancelled with an API key or as a partner.

Allowed:
string | null

Required when setting status to cancelled.

boolean | null
Defaults to false

Only with status: cancelled, and never with an API key. Cancelling moves no
money unless this is true. When true the booking is refunded through the
gateway it was paid on (Paystack, Stripe, Startbutton) or back to the client's
wallet. Needs the refund appointment permission. Checked before anything is
cancelled: a booking the partner collected on its own gateway, a rebooked
appointment, a refund beyond what is left or one the vendor can no longer cover
refuses the whole request with 422 and nothing is cancelled.

number | null
≥ 0.01

With refund, a partial refund in the booking's currency. Omitted, everything left is refunded.

attachment_ids
array of integers | null

Vendor staff only. File IDs to attach to the appointment.

attachment_ids
integer | null

Vendor staff only.

integer | null

Vendor staff only.

integer | null

Vendor staff only.

integer | null

Vendor staff only.

boolean | null

Vendor staff only. Email the client about a staff, shift or type change.

boolean | null

Vendor staff only. Email staff about a staff, shift or type change.

Headers
string

Partners only (key or staff session). The slug of the vendor whose appointment this is.

Responses

401

Unauthenticated

403

A key without appointments:manage; a partner staff member without edit appointment
(Insufficient permissions); anything but a cancel from a key or a partner
(Partners and API keys can only cancel an appointment here.); a refund with an API
key (Refunds cannot be made with an API key. Refund from the portal.); a refund
without the refund appointment permission; or an invalid vendor assignment.

404

Appointment not found, or X-Vendor-Code names no vendor of yours (OYS-PARTNER-1001)

422

Validation error, an appointment that is not scheduled or in progress, or a refund that cannot be made (the message says why; nothing was cancelled)

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json