Recurring appointments

Create a recurring appointment

Create a new recurring appointment for a customer.

Recurring appointments are created in the background by the system based on the specified frequency and date range. Appointments are created but not automatically confirmed. Only barbers can create recurring appointments, and each customer is limited to one recurring appointment per barber.

Retrying the same request with the same Idempotency-Key replays the original recurring appointment. Reusing that key for a different request conflicts, and a concurrent identical request reports that the original request is still in progress. Replay state is retained for 24 hours; after that, the same key begins a new request.

POST

barbers

{barberId}

recurringAppointments

curl --request POST \
  --url https://api.guile.app/barbers/{barberId}/recurringAppointments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "frequency": "weekly",
  "startDate": "2020-01-01",
  "active": true,
  "customerReference": {
    "id": "0190f0c0-7b2a-7b3c-9d4e-5f6a7b8c9d0e",
    "givenName": "Jordan",
    "surname": "Nguyen"
  },
  "location": {
    "id": "0190f0c0-2222-7222-8222-222222222222",
    "name": "SoHo",
    "shopName": "Guile Cuts"
  },
  "services": [
    {
      "id": "0190f0c0-3333-7333-8333-333333333333",
      "name": "Haircut",
      "cost": "45.00"
    }
  ]
}
'

{
  "id": "0190f0c0-bbbb-7bbb-8bbb-bbbbbbbbbbbb",
  "frequency": "weekly",
  "startDate": "2026-08-15",
  "active": true,
  "barber": {
    "id": "0190f0c0-1111-7111-8111-111111111111",
    "givenName": "Marcus",
    "surname": "Lee"
  },
  "customerReference": {
    "id": "0190f0c0-7b2a-7b3c-9d4e-5f6a7b8c9d0e",
    "givenName": "Jordan",
    "surname": "Nguyen"
  },
  "location": {
    "id": "0190f0c0-2222-7222-8222-222222222222",
    "name": "SoHo",
    "shopName": "Guile Cuts"
  },
  "services": [
    {
      "id": "0190f0c0-3333-7333-8333-333333333333",
      "name": "Haircut",
      "cost": "45.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/dateOccursInPast",
  "title": "Date Occurs In Past",
  "status": 422,
  "detail": "The recurring series must start on today or a future date.",
  "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.

Body

application/json

Request body for creating a recurring appointment. Only barbers can create recurring appointments.

frequency

enum<string>

required

The frequency at which appointments recur. Appointments are created in the background by the system based on this frequency.

Available options:

daily,

weekly,

biweekly,

semimonthly,

monthly,

quarterly,

annually

startDate

string<date>

required

The start date for the recurring appointment series. Appointments will be created starting from this date.

Pattern: ^\d{4}-\d{2}-\d{2}$

active

boolean

default:true

required

Whether the recurring appointment is active. When inactive, no new appointments will be created for this series.

customerReference

object

required

A reference to the customer for this recurring appointment.

Show child attributes

location

object

required

The location for appointments in this series.

Show child attributes

services

object[]

required

The services for appointments in this series.

Show child attributes

endDate

string<date>

The end date for the recurring appointment series, if specified. If not specified, appointments are created up to one year from the start date or current date, whichever is later.

Pattern: ^\d{4}-\d{2}-\d{2}$

Response

Created.

A representation of a recurring appointment.

frequency

enum<string>

required

The frequency at which appointments recur. Appointments are created in the background by the system based on this frequency.

Available options:

daily,

weekly,

biweekly,

semimonthly,

monthly,

quarterly,

annually

startDate

string<date>

required

The start date for the recurring appointment series. Appointments will be created starting from this date.

Pattern: ^\d{4}-\d{2}-\d{2}$

active

boolean

required

Whether the recurring appointment is active. When inactive, no new appointments will be created for this series.

customerReference

object

required

A reference to the customer for this recurring appointment. Its surname is omitted when the customer limits barber visibility to the surname initial.

Show child attributes

string

required

The unique identifier for this recurring appointment.

barber

object

required

A reference to the barber for this recurring appointment.

Show child attributes

location

object

required

The location for appointments in this series.

Show child attributes

services

object[]

required

The services for appointments in this series.

Show child attributes

createdAt

string<date-time>

required

The date-time when this resource was created, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

updatedAt

string<date-time>

required

The date-time when this resource was updated, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

endDate

string<date>

The end date for the recurring appointment series, if specified. If not specified, appointments are created up to one year from the start date or current date, whichever is later.

Pattern: ^\d{4}-\d{2}-\d{2}$

displayName

string

The customer name the authenticated barber may display. Under initial-only visibility, this contains the given name and surname initial, never the full surname.

curl --request POST \
  --url https://api.guile.app/barbers/{barberId}/recurringAppointments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "frequency": "weekly",
  "startDate": "2020-01-01",
  "active": true,
  "customerReference": {
    "id": "0190f0c0-7b2a-7b3c-9d4e-5f6a7b8c9d0e",
    "givenName": "Jordan",
    "surname": "Nguyen"
  },
  "location": {
    "id": "0190f0c0-2222-7222-8222-222222222222",
    "name": "SoHo",
    "shopName": "Guile Cuts"
  },
  "services": [
    {
      "id": "0190f0c0-3333-7333-8333-333333333333",
      "name": "Haircut",
      "cost": "45.00"
    }
  ]
}
'

{
  "id": "0190f0c0-bbbb-7bbb-8bbb-bbbbbbbbbbbb",
  "frequency": "weekly",
  "startDate": "2026-08-15",
  "active": true,
  "barber": {
    "id": "0190f0c0-1111-7111-8111-111111111111",
    "givenName": "Marcus",
    "surname": "Lee"
  },
  "customerReference": {
    "id": "0190f0c0-7b2a-7b3c-9d4e-5f6a7b8c9d0e",
    "givenName": "Jordan",
    "surname": "Nguyen"
  },
  "location": {
    "id": "0190f0c0-2222-7222-8222-222222222222",
    "name": "SoHo",
    "shopName": "Guile Cuts"
  },
  "services": [
    {
      "id": "0190f0c0-3333-7333-8333-333333333333",
      "name": "Haircut",
      "cost": "45.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/dateOccursInPast",
  "title": "Date Occurs In Past",
  "status": 422,
  "detail": "The recurring series must start on today or a future date.",
  "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 a recurring appointment

Headers

Path Parameters

Body

Response