Create an appointment cancellation

POST

barbers

{barberId}

appointments

{appointmentId}

cancellations

curl --request POST \
  --url https://api.guile.app/barbers/{barberId}/appointments/{appointmentId}/cancellations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "actor": "client",
  "reason": "barberCanceled"
}
'

{
  "appointment": {
    "id": "0190f0c0-4444-7444-8444-444444444444",
    "givenName": "Jordan",
    "barber": {
      "id": "0190f0c0-1111-7111-8111-111111111111",
      "givenName": "Marcus",
      "surname": "Lee"
    },
    "location": {
      "id": "0190f0c0-2222-7222-8222-222222222222",
      "name": "SoHo",
      "shopName": "Guile Cuts"
    },
    "services": [
      {
        "id": "0190f0c0-3333-7333-8333-333333333333",
        "name": "Haircut",
        "cost": "45.00"
      }
    ],
    "occursOn": "2026-08-15T15:30:00.000Z",
    "duration": "PT45M",
    "cost": "45.00",
    "state": "canceled",
    "paymentState": "pending",
    "totalAuthorized": "0.00",
    "totalCaptured": "0.00",
    "totalRefunded": "0.00",
    "createdAt": "2026-08-01T16:00:00.000Z",
    "updatedAt": "2026-08-01T16:00:00.000Z"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "id": "0190f0c0-cccc-7ccc-8ccc-cccccccccccc",
  "type": "https://docs.guile.app/problems/cancellationActorReasonMismatch",
  "title": "Cancellation Actor Reason Mismatch",
  "status": 422,
  "detail": "That reason does not apply to the selected actor.",
  "occurredAt": "2026-08-01T16:00:00.000Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

Headers

Idempotency-Key

string

required

A client-generated idempotency key to ensure operations are only processed once even if a client retries the operation. The V4 UUID format, as defined in RFC 4122, is recommended to avoid collisions but is not required.

Maximum string length: 255

Path Parameters

barberId

string

required

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

appointmentId

string

required

Body

application/json

Request body for creating an appointment cancellation as a barber.

actor

enum<string>

required

The party responsible for the cancellation.

Available options:

barber,

client

reason

enum<string>

required

The cancellation reason. Use clientCanceled or noShow for a client actor, barberCanceled for a barber actor, and other for either actor.

Available options:

clientCanceled,

noShow,

barberCanceled,

other

applyCancellationFee

boolean

Whether to apply the derived cancellation fee. Has no effect when the reason derives no fee; when omitted, system default rules apply.

note

string

An optional cancellation note visible to the client.

Maximum string length: 500

Response

Ok. The operation succeeded.

A barber-facing representation of an appointment.

appointment

object

required

The appointment resource.

Show child attributes

client

object

The barber's client record linked to the appointment customer.

Show child attributes

bookingMessage

string

The customer message saved with the appointment at booking time.

Maximum string length: 500

referencePhotos

object[]

Approved appointment reference photos visible to the barber and customer.

Maximum array length: 3

Show child attributes

cancellation

object

The cancellation decision recorded when the appointment is canceled.

Show child attributes

cancellationFeePreviews

object

The fee amounts available before a cancellation decision.

Show child attributes

curl --request POST \
  --url https://api.guile.app/barbers/{barberId}/appointments/{appointmentId}/cancellations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "actor": "client",
  "reason": "barberCanceled"
}
'

{
  "appointment": {
    "id": "0190f0c0-4444-7444-8444-444444444444",
    "givenName": "Jordan",
    "barber": {
      "id": "0190f0c0-1111-7111-8111-111111111111",
      "givenName": "Marcus",
      "surname": "Lee"
    },
    "location": {
      "id": "0190f0c0-2222-7222-8222-222222222222",
      "name": "SoHo",
      "shopName": "Guile Cuts"
    },
    "services": [
      {
        "id": "0190f0c0-3333-7333-8333-333333333333",
        "name": "Haircut",
        "cost": "45.00"
      }
    ],
    "occursOn": "2026-08-15T15:30:00.000Z",
    "duration": "PT45M",
    "cost": "45.00",
    "state": "canceled",
    "paymentState": "pending",
    "totalAuthorized": "0.00",
    "totalCaptured": "0.00",
    "totalRefunded": "0.00",
    "createdAt": "2026-08-01T16:00:00.000Z",
    "updatedAt": "2026-08-01T16:00:00.000Z"
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

{
  "id": "0190f0c0-cccc-7ccc-8ccc-cccccccccccc",
  "type": "https://docs.guile.app/problems/cancellationActorReasonMismatch",
  "title": "Cancellation Actor Reason Mismatch",
  "status": 422,
  "detail": "That reason does not apply to the selected actor.",
  "occurredAt": "2026-08-01T16:00:00.000Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "status": 349,
  "detail": "<string>",
  "instance": "<string>",
  "attributes": {},
  "recovery": {
    "rateLimit": {
      "limit": 123,
      "remaining": 123,
      "resetsAt": "2023-11-07T05:31:56Z"
    }
  },
  "problems": [
    {
      "type": "<string>",
      "title": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": 349,
      "detail": "<string>",
      "instance": "<string>",
      "attributes": {}
    }
  ]
}

Get started

Public APIs

API concepts

Metadata

Admin

Authentication

Appointments

Payments

Barbers

Businesses

Clients

Customers

Fees

Integrations

Invitations

Payouts

Photos

Refunds

Reviews

Services

Shops

Create an appointment cancellation

Headers

Path Parameters

Body

Response