Appointments

Decline a booking request

Reject an approval-pending booking request as the owning barber and preserve the client-visible reason.

Decline is an idempotent terminal decision and never authorizes, captures, or settles appointment money. Repeating the same request body with the same idempotency key replays the original response; changing the reason while reusing the key returns idempotencyKeyConflict.

A new decision after the request was confirmed, rejected, expired, or canceled returns appointmentApprovalNotPending. Concurrent confirm, decline, customer cancellation, and expiry attempts produce exactly one terminal booking-request result.

POST

barbers

{barberId}

appointments

{appointmentId}

rejected

curl --request POST \
  --url https://api.guile.app/barbers/{barberId}/appointments/{appointmentId}/rejected \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "Fully booked that afternoon"
}
'

{
  "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": "rejected",
    "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": {}
    }
  ]
}

{
  "id": "0190f0c0-cccc-7ccc-8ccc-cccccccccccc",
  "type": "https://docs.guile.app/problems/appointmentApprovalNotPending",
  "title": "Appointment Approval Not Pending",
  "status": 409,
  "detail": "Only pending requests can be declined.",
  "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": {}
    }
  ]
}

{
  "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 declining an approval-pending booking request.

reason

string

required

The client-visible reason the barber declined the booking request.

Required string length: 1 - 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}/rejected \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "reason": "Fully booked that afternoon"
}
'

{
  "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": "rejected",
    "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": {}
    }
  ]
}

{
  "id": "0190f0c0-cccc-7ccc-8ccc-cccccccccccc",
  "type": "https://docs.guile.app/problems/appointmentApprovalNotPending",
  "title": "Appointment Approval Not Pending",
  "status": 409,
  "detail": "Only pending requests can be declined.",
  "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": {}
    }
  ]
}

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

Decline a booking request

Headers

Path Parameters

Body

Response