Appointments

Name: Membber
Availability: InStock

6 operations. Every schema and example on this page is generated from the platform contract.

GET/api/v1/appointments

The caller's appointments.

Always scoped to the signed-in customer, ownership is part of the query, never a filter applied after fetching. There is no way to ask for somebody else's bookings.

auth customer:readop listAppointmentsrate limited errors

Parameters

store_idstring · uuid, nullablequeryoptional

Narrow to one store. Omit for every store this customer has booked with.

include_pastbooleanqueryoptional

Include appointments that have already happened. Defaults to upcoming only.

limitintegerqueryoptional

Response, 200

appointmentsarray of objectrequired

12 child fields

idstringrequired

store_idstringrequired

unit_idstringrequired

service_idstring, nullablerequired

starts_atstringrequired

ends_atstringrequired

statusstringrequired

payment_statusstringrequired

price_pencenumberrequired

deposit_pencenumberrequired

currencystringrequired

Every amount carries its currency, never inferred from the caller.

party_sizenumberrequired

curl -G "https://www.membber.com/api/v1/appointments" \
  -H "Authorization: Bearer $MEMBBER_TOKEN"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/appointments");

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.listAppointments().ok.body.json

print(response)

Response, 200

{
  "appointments": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "store_id": "6659c139-0000-4000-8000-d0c500000066",
      "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
      "service_id": "993232e5-0000-4000-8000-d0c500000099",
      "starts_at": "<starts_at>",
      "ends_at": "<ends_at>",
      "status": "<status>",
      "payment_status": "<payment_status>",
      "price_pence": 1500,
      "deposit_pence": 1500,
      "currency": "GBP",
      "party_size": 1
    }
  ]
}

POST/api/v1/appointments

Book an appointment.

Converts a hold into a booking IN PLACE, so the slot is never free for an instant between paying and being booked. Double-booking is prevented by a database constraint rather than a check, so a lost race returns STALE_SLOT and nothing is written. Price and policy are SNAPSHOTTED onto the appointment: a later change to either never rewrites what the customer agreed to. Send an Idempotency-Key, retrying is safe and will not produce a second booking.

auth customer:writeop createAppointmentidempotent retry rate limited errors

Request body

store_idstring · uuidrequired

The store being booked.

unit_idstring · uuidrequired

The staff member / room / table.

service_idstring · uuid, nullableoptional

The service booked. Its price and duration are SNAPSHOTTED onto the appointment.

starts_atstringrequired

ISO instant the appointment starts.

ends_atstringrequired

ISO instant the appointment ends.

hold_tokenstring, nullableoptional

The hold taken for this slot. Strongly recommended: without it the slot is unprotected between the availability read and this call.

guest_emailstring · email, nullableoptional

Required when booking without a signed-in customer, somebody has to be reachable.

guest_namestring, nullableoptional

Who the appointment is for, when there is no customer record.

party_sizeintegeroptional

People in the party. 1 for a normal appointment.

price_penceintegeroptional

Agreed price in the smallest currency unit. Snapshotted, a later price change never rewrites it.

deposit_penceintegeroptional

Deposit due now. Greater than zero leaves the appointment pending_payment until it is settled.

currencystringoptional

ISO currency for the amounts above. Defaults to the store's.

Response, 200

appointment_idstringrequired

The booking.

statusstringrequired

'confirmed', or 'pending_payment' when a deposit is still due.

starts_atstringrequired

ISO instant it starts.

ends_atstringrequired

ISO instant it ends, what the customer was told, not how long the unit is occupied.

payment_next_actionstring, nullableoptional

'collect_deposit' when a deposit must be taken before this booking is safe; null when nothing is owed now.

curl -X POST "https://www.membber.com/api/v1/appointments" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066",
    "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
    "starts_at": "<starts_at>",
    "ends_at": "<ends_at>"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.POST("/api/v1/appointments", {
  body: {
    store_id: "6659c139-0000-4000-8000-d0c500000066",
    unit_id: "eeebf9b6-0000-4000-8000-d0c5000000ee",
    starts_at: "<starts_at>",
    ends_at: "<ends_at>"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.createAppointment(
    body: .json(.init(
        storeId: "6659c139-0000-4000-8000-d0c500000066",
        unitId: "eeebf9b6-0000-4000-8000-d0c5000000ee",
        startsAt: "<starts_at>",
        endsAt: "<ends_at>"
    ))
).ok.body.json

print(response)

Response, 200

{
  "appointment_id": "0d727dbb-0000-4000-8000-d0c50000000d",
  "status": "<status>",
  "starts_at": "<starts_at>",
  "ends_at": "<ends_at>",
  "payment_next_action": "<payment_next_action>"
}

GET/api/v1/appointments/availability

Bookable slots for a service.

Computed from the unit's working patterns in the STORE's timezone, at the store's own slot increment, honouring lead time and booking horizon. Every slot returned has been checked against the same single authority the booking call uses, so a slot listed here is genuinely bookable, but it is still a snapshot: another customer can take one between this read and your booking, which is exactly what STALE_SLOT reports.

auth none, publicop getAppointmentAvailabilityrate limited errors

Parameters

store_idstring · uuidqueryrequired

The store to read availability for.

service_idstring · uuidqueryrequired

The service being booked, its duration and buffers shape the slots.

from_datestringqueryrequired

First date to search, YYYY-MM-DD, in the STORE's timezone.

to_datestringqueryrequired

Last date to search, YYYY-MM-DD. Clamped to the store's booking horizon.

unit_idstring · uuid, nullablequeryoptional

Restrict to one staff member / room / table. Omit to see every unit that offers the service.

Response, 200

slotsarray of objectrequired

Every slot that is genuinely bookable right now, soonest first.

3 child fields

unit_idstringrequired

Which staff member / room / table this slot belongs to.

starts_atstringrequired

ISO instant the APPOINTMENT starts (what the customer is told).

ends_atstringrequired

ISO instant the APPOINTMENT ends. The unit may be occupied longer if the service has buffers.

generated_atstringrequired

When this list was computed. A slot list is a snapshot of a moving thing, compare this before committing, and expect STALE_SLOT if it is old.

curl -G "https://www.membber.com/api/v1/appointments/availability" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066" \
  --data-urlencode "service_id=993232e5-0000-4000-8000-d0c500000099" \
  --data-urlencode "from_date=<from_date>" \
  --data-urlencode "to_date=<to_date>"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/appointments/availability", {
  params: { query: { store_id: "6659c139-0000-4000-8000-d0c500000066", service_id: "993232e5-0000-4000-8000-d0c500000099", from_date: "<from_date>", to_date: "<to_date>" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.getAppointmentAvailability(
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066", serviceId: "993232e5-0000-4000-8000-d0c500000099", fromDate: "<from_date>", toDate: "<to_date>")
).ok.body.json

print(response)

Response, 200

{
  "slots": [
    {
      "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
      "starts_at": "<starts_at>",
      "ends_at": "<ends_at>"
    }
  ],
  "generated_at": "<generated_at>"
}

POST/api/v1/appointments/cancel

Cancel an appointment (preview first).

Call without `confirm` to see exactly what cancelling costs before committing to it, then again with `confirm: true`. The fee is evaluated against the policy SNAPSHOTTED on the booking, so a shop tightening its terms next week cannot retroactively charge someone who booked under the old ones. Idempotent, cancelling twice is a no-op, never a second charge.

auth customer:writeop cancelAppointmentidempotent retry rate limited errors

Request body

appointment_idstring · uuidrequired

The appointment to cancel.

reasonstring, nullableoptional

Why, for the record and the merchant.

confirmbooleanoptional

false/omitted returns a PREVIEW of what cancelling costs and changes nothing. true performs it. A fee discovered AFTER the fact is the most complained-about thing in booking apps.

Response, 200

appointment_idstringrequired

cancelledbooleanrequired

false when this was a preview.

fee_pencenumberrequired

What cancelling costs, from the policy the customer AGREED to, not the shop's current one.

refund_pencenumberrequired

What comes back of anything already paid. Never more than was taken.

currencystringrequired

within_free_windowbooleanrequired

true when it is still early enough to cancel free.

cancel_window_hoursnumberrequired

The window that applied to THIS booking.

curl -X POST "https://www.membber.com/api/v1/appointments/cancel" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "0d727dbb-0000-4000-8000-d0c50000000d"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.POST("/api/v1/appointments/cancel", {
  body: {
    appointment_id: "0d727dbb-0000-4000-8000-d0c50000000d"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.cancelAppointment(
    body: .json(.init(
        appointmentId: "0d727dbb-0000-4000-8000-d0c50000000d"
    ))
).ok.body.json

print(response)

Response, 200

{
  "appointment_id": "0d727dbb-0000-4000-8000-d0c50000000d",
  "cancelled": true,
  "fee_pence": 1500,
  "refund_pence": 1500,
  "currency": "GBP",
  "within_free_window": true,
  "cancel_window_hours": 1
}

POST/api/v1/appointments/holds

Reserve a slot for a few minutes while paying.

Holds a slot so nobody else can take it mid-payment. Ten minutes by default, long enough for a card security check, short enough that an abandoned checkout does not sterilise a busy slot. Idempotent per hold_token. Returns STALE_SLOT if the slot went first, or HOLD_LIMIT (with Retry-After) if this unit already has too many live holds for that day, which is the anti-squatting guard.

auth customer:writeop createAppointmentHoldidempotent retry rate limited errors

Request body

unit_idstring · uuidrequired

The staff member / room / table to reserve.

starts_atstringrequired

ISO instant the appointment would start.

ends_atstringrequired

ISO instant the appointment would end.

hold_tokenstringrequired

Caller-generated idempotency key. The SAME token returns the SAME hold rather than taking a second slot, so a retry or a double tap can never consume two times.

Response, 200

hold_idstringrequired

The reservation.

expires_atstringrequired

ISO instant the hold lapses, 10 minutes by default (founder decision D10). Show this to the customer rather than guessing it.

reusedbooleanrequired

true when this token already had a live hold and it was returned unchanged (idempotent replay).

curl -X POST "https://www.membber.com/api/v1/appointments/holds" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
    "starts_at": "<starts_at>",
    "ends_at": "<ends_at>",
    "hold_token": "<hold_token>"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.POST("/api/v1/appointments/holds", {
  body: {
    unit_id: "eeebf9b6-0000-4000-8000-d0c5000000ee",
    starts_at: "<starts_at>",
    ends_at: "<ends_at>",
    hold_token: "<hold_token>"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.createAppointmentHold(
    body: .json(.init(
        unitId: "eeebf9b6-0000-4000-8000-d0c5000000ee",
        startsAt: "<starts_at>",
        endsAt: "<ends_at>",
        holdToken: "<hold_token>"
    ))
).ok.body.json

print(response)

Response, 200

{
  "hold_id": "4112d09b-0000-4000-8000-d0c500000041",
  "expires_at": "<expires_at>",
  "reused": true
}

POST/api/v1/appointments/reschedule

Move an appointment.

Secures the NEW slot before releasing the OLD one, so if the destination has gone the original booking survives untouched, you are never left with nothing. Returns STALE_SLOT if the new time went first, or OUTSIDE_POLICY_WINDOW if it is too close to the appointment to change online.

auth customer:writeop rescheduleAppointmentidempotent retry rate limited errors

Request body

appointment_idstring · uuidrequired

The appointment to move.

unit_idstring · uuidrequired

Where it is moving to, may be the same staff member / room / table.

starts_atstringrequired

ISO instant of the new start.

ends_atstringrequired

ISO instant of the new end.

hold_tokenstring, nullableoptional

A hold taken on the NEW slot. Recommended for the same reason as booking: without it the destination is unprotected.

Response, 200

appointment_idstringrequired

starts_atstringrequired

ends_atstringrequired

unit_idstringrequired

moved_in_placebooleanrequired

true when the booking was nudged within the same unit (the block moved rather than being re-taken).

curl -X POST "https://www.membber.com/api/v1/appointments/reschedule" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "0d727dbb-0000-4000-8000-d0c50000000d",
    "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
    "starts_at": "<starts_at>",
    "ends_at": "<ends_at>"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.POST("/api/v1/appointments/reschedule", {
  body: {
    appointment_id: "0d727dbb-0000-4000-8000-d0c50000000d",
    unit_id: "eeebf9b6-0000-4000-8000-d0c5000000ee",
    starts_at: "<starts_at>",
    ends_at: "<ends_at>"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.rescheduleAppointment(
    body: .json(.init(
        appointmentId: "0d727dbb-0000-4000-8000-d0c50000000d",
        unitId: "eeebf9b6-0000-4000-8000-d0c5000000ee",
        startsAt: "<starts_at>",
        endsAt: "<ends_at>"
    ))
).ok.body.json

print(response)

Response, 200

{
  "appointment_id": "0d727dbb-0000-4000-8000-d0c50000000d",
  "starts_at": "<starts_at>",
  "ends_at": "<ends_at>",
  "unit_id": "eeebf9b6-0000-4000-8000-d0c5000000ee",
  "moved_in_place": true
}