{"openapi":"3.1.0","info":{"title":"RatesSpot API","version":"1.0.0","description":"Headless booking API for businesses that sell time: rooms by the night, offices by the hour or month, meeting rooms by the half day, seats on a course. Amounts are integers in minor units (kobo, cents).","license":{"name":"FSL-1.1-ALv2","identifier":"FSL-1.1-ALv2"}},"servers":[{"url":"https://api.ratesspot.com","description":"RatesSpot hosted. Self-hosted servers use their own address."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key: rs_live_sk_… (secret, server only) or rs_live_pk_… (publishable, safe in browsers), or a staff session (rs_sess_…) from POST /v1/auth/login."}},"schemas":{"Login":{"type":"object","properties":{"token":{"type":"string","description":"Send as Authorization: Bearer <token>. Keep it server-side (e.g. an httpOnly cookie)."},"expiresAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"user":{"$ref":"#/components/schemas/StaffUser"}},"required":["token","expiresAt","user"]},"StaffUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"mustChangePassword":{"type":"boolean"},"isPlatformAdmin":{"type":"boolean","description":"Runs RatesSpot itself: can invite and suspend businesses"},"emailVerified":{"type":"boolean","description":"They've confirmed their email address (needed to go live)"},"merchants":{"type":"array","items":{"type":"object","properties":{"merchantId":{"type":"string"},"name":{"type":"string"},"role":{"$ref":"#/components/schemas/StaffRole"},"environment":{"type":"string","enum":["LIVE","TEST"]}},"required":["merchantId","name","role","environment"]}}},"required":["id","email","name","mustChangePassword","isPlatformAdmin","emailVerified","merchants"]},"StaffRole":{"type":"string","enum":["OWNER","MANAGER","FRONT_DESK"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_inventory"},"message":{"type":"string","example":"No Studio Flat Deluxe is free for the whole of that range."},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"password":{"type":"string","minLength":1,"maxLength":200}},"required":["email","password"]},"ChangePasswordRequest":{"type":"object","properties":{"currentPassword":{"type":"string","minLength":1,"maxLength":200},"newPassword":{"type":"string","minLength":10,"maxLength":200}},"required":["currentPassword","newPassword"]},"StaffMember":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"role":{"$ref":"#/components/schemas/StaffRole"},"since":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["userId","email","name","role","since"]},"AddedStaff":{"type":"object","properties":{"userId":{"type":"string"},"temporaryPassword":{"type":["string","null"],"description":"Shown once. Null when the person already had an account."}},"required":["userId","temporaryPassword"]},"AddStaffRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","minLength":2,"maxLength":200},"role":{"$ref":"#/components/schemas/StaffRole"}},"required":["email","name","role"]},"PasswordResetRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":320}},"required":["email"]},"PasswordReset":{"type":"object","properties":{"token":{"type":"string","minLength":20,"maxLength":200,"description":"From the emailed link"},"password":{"type":"string","minLength":1,"maxLength":200,"description":"At least 10 characters"}},"required":["token","password"]},"EmailVerification":{"type":"object","properties":{"token":{"type":"string","minLength":20,"maxLength":200,"description":"From the emailed link"}},"required":["token"]},"BusinessExport":{"type":"object","properties":{"exportedAt":{"type":"string"},"format":{"type":"string"},"note":{"type":"string"},"business":{"type":"object","additionalProperties":{}},"listings":{"type":"array","items":{"type":"object","additionalProperties":{}}},"scheduledListings":{"type":"array","items":{"type":"object","additionalProperties":{}}},"addOns":{"type":"array","items":{"type":"object","additionalProperties":{}}},"cancellationTerms":{"type":"array","items":{"type":"object","additionalProperties":{}}},"customers":{"type":"array","items":{"type":"object","additionalProperties":{}}},"bookings":{"type":"array","items":{"type":"object","additionalProperties":{}}},"payments":{"type":"array","items":{"type":"object","additionalProperties":{}}},"staff":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["exportedAt","format","note","business","listings","scheduledListings","addOns","cancellationTerms","customers","bookings","payments","staff"]},"ClosedBusiness":{"type":"object","properties":{"deleteAfter":{"type":"string"}},"required":["deleteAfter"]},"CloseBusinessRequest":{"type":"object","properties":{"password":{"type":"string","minLength":1,"maxLength":200,"description":"The signed-in person's password, to confirm"},"confirmName":{"type":"string","maxLength":200,"description":"The business's name, typed to confirm"}},"required":["password","confirmName"]},"DeleteAccountRequest":{"type":"object","properties":{"password":{"type":"string","minLength":1,"maxLength":200,"description":"The signed-in person's password, to confirm"}},"required":["password"]},"Merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"timezone":{"type":"string"},"template":{"type":["string","null"],"description":"The template id (GET /v1/templates), or null"},"words":{"$ref":"#/components/schemas/Vocabulary"}},"required":["id","name","currency","timezone","template","words"]},"Vocabulary":{"type":"object","properties":{"customer":{"type":"string"},"customers":{"type":"string"},"unit":{"type":"string"},"units":{"type":"string"},"booking":{"type":"string"},"bookings":{"type":"string"},"checkIn":{"type":"string"},"checkedIn":{"type":"string"},"checkOut":{"type":"string"},"checkedOut":{"type":"string"},"capacity":{"type":"string"}},"required":["customer","customers","unit","units","booking","bookings","checkIn","checkedIn","checkOut","checkedOut","capacity"],"description":"The words to show for this business or listing, in lower case: customer (guest, client), unit (room, desk), booking (stay, appointment), check in / check out and their statuses, capacity (goes before the number of people: sleeps, up to)"},"Resource":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"description":{"type":["string","null"],"description":"Paragraphs separated by blank lines"},"features":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","example":"https://api.ratesspot.com/media/cm…"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","url","alt","width","height"]},"description":"Main photo first"},"externalRef":{"type":["string","null"]},"capacity":{"type":"integer"},"inventory":{"type":"integer"},"allowUnitChoice":{"type":"boolean"},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"words":{"$ref":"#/components/schemas/Vocabulary"},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string","enum":["NIGHT","HOUR","BLOCK","DAY","MONTH","YEAR","BOOKING","SEAT"]},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"isDefault":{"type":"boolean"},"refundable":{"type":"boolean"},"minUnits":{"type":"integer"},"maxUnits":{"type":["integer","null"]},"dailyCap":{"type":["integer","null"],"example":4000000,"description":"Amount in minor units (kobo, cents)"},"termMonths":{"type":["integer","null"]},"blocks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"startMinute":{"type":"integer"},"endMinute":{"type":"integer"}},"required":["name","startMinute","endMinute"]}},"paymentOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentOptionKind"}},"addOns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"basis":{"type":"string","enum":["PER_BOOKING","PER_UNIT","PER_GUEST"]},"required":{"type":"boolean"}},"required":["id","name","amount","basis","required"]},"description":"Send required ones with quotes and holds"}},"required":["id","name","unit","amount","isDefault","refundable","minUnits","maxUnits","dailyCap","termMonths","blocks","paymentOptions","addOns"]}}},"required":["id","slug","name","tagline","description","features","images","externalRef","capacity","inventory","allowUnitChoice","units","words","rates"]},"PaymentOptionKind":{"type":"string","enum":["FULL","DEPOSIT","ON_ARRIVAL","INSTALMENTS"]},"Session":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"seats":{"type":"integer"},"seatsLeft":{"type":"integer"},"resourceId":{"type":["string","null"]},"hostName":{"type":["string","null"]},"description":{"type":["string","null"],"description":"What the course covers"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","example":"https://api.ratesspot.com/media/cm…"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","url","alt","width","height"]}},"pricePerSeat":{"type":["integer","null"],"example":4000000,"description":"Amount in minor units (kobo, cents)"},"rateId":{"type":["string","null"]},"occurrences":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["start","end"]}}},"required":["id","slug","name","seats","seatsLeft","resourceId","hostName","description","images","pricePerSeat","rateId","occurrences"]},"Availability":{"type":"object","properties":{"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"free":{"type":"integer","description":"Units free all day (or seats left)"},"price":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"startTimes":{"type":"array","items":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"blocks":{"type":"array","items":{"type":"string"}}},"required":["date","free"]}}},"required":["days"]},"SessionCreate":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[a-z0-9-]+$"},"name":{"type":"string","minLength":1,"maxLength":200},"seats":{"type":"integer","minimum":1},"resourceId":{"type":"string","minLength":1,"maxLength":64},"hostName":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"hostShareBps":{"type":"integer","minimum":0,"maximum":10000,"description":"Host's share in basis points: 7000 = 70%"},"pricePerSeat":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"occurrences":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["start","end"]},"minItems":1}},"required":["slug","name","seats","pricePerSeat","occurrences"]},"ClosureRequest":{"type":"object","properties":{"resourceId":{"type":"string","minLength":1,"maxLength":64},"unitId":{"type":"string","minLength":1,"maxLength":64},"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"reason":{"type":"string","maxLength":500}},"required":["resourceId","start","end"]},"Quote":{"type":"object","properties":{"currency":{"type":"string","example":"NGN"},"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"total":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"breakdown":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["date","amount"]}},"policy":{"$ref":"#/components/schemas/CancellationPolicy"},"paymentOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentOptionQuote"}},"securityDeposit":{"type":"object","properties":{"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"collected":{"type":"string","enum":["ONLINE","ON_ARRIVAL"]}},"required":["amount","collected"]},"revenueShare":{"type":"object","properties":{"host":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"merchant":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["host","merchant"]}},"required":["currency","start","end","lines","total","breakdown","policy","paymentOptions"]},"QuoteLine":{"type":"object","properties":{"kind":{"type":"string","enum":["base","rule","cap","fee","addon","discount","tax","tax_included"]},"label":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["kind","label","amount"]},"CancellationPolicy":{"type":"object","properties":{"refundable":{"type":"boolean"},"refundFees":{"type":"boolean"},"refundAddOns":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","properties":{"deadline":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"Cancelling at or after this time incurs the penalty"},"penaltyType":{"type":"string","enum":["NONE","PERCENT","FIXED","UNITS"]},"penaltyValue":{"type":"integer"}},"required":["deadline","penaltyType","penaltyValue"]}}},"required":["refundable","refundFees","refundAddOns","tiers"]},"PaymentOptionQuote":{"type":"object","properties":{"kind":{"$ref":"#/components/schemas/PaymentOptionKind"},"dueNow":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"dueNowRefundable":{"type":"boolean"},"balance":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"instalments":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["seq","dueDate","amount"]}}},"required":["kind","dueNow","dueNowRefundable","balance"]},"QuoteRequest":{"type":"object","properties":{"resourceId":{"type":"string","minLength":1,"maxLength":64,"description":"Give exactly one of resourceId or sessionId"},"sessionId":{"type":"string","minLength":1,"maxLength":64},"rateId":{"type":"string","minLength":1,"maxLength":64,"description":"Defaults to the resource's default rate"},"range":{"$ref":"#/components/schemas/Range"},"quantity":{"type":"integer","minimum":1,"description":"Units (or seats). Default 1"},"adults":{"type":"integer","minimum":1},"children":{"type":"integer","minimum":0},"unitId":{"type":"string","minLength":1,"maxLength":64,"description":"A specific unit, if the resource allows choosing"},"addOns":{"type":"array","items":{"type":"object","properties":{"addOnId":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":"integer","minimum":1}},"required":["addOnId","quantity"]}},"discountCode":{"type":"string"}},"required":["range"]},"Range":{"oneOf":[{"$ref":"#/components/schemas/NightsRange"},{"$ref":"#/components/schemas/HoursRange"},{"$ref":"#/components/schemas/BlockRange"},{"$ref":"#/components/schemas/DaysRange"},{"$ref":"#/components/schemas/MonthsRange"},{"$ref":"#/components/schemas/YearsRange"},{"$ref":"#/components/schemas/SessionRange"}],"discriminator":{"propertyName":"kind","mapping":{"nights":"#/components/schemas/NightsRange","hours":"#/components/schemas/HoursRange","block":"#/components/schemas/BlockRange","days":"#/components/schemas/DaysRange","months":"#/components/schemas/MonthsRange","years":"#/components/schemas/YearsRange","session":"#/components/schemas/SessionRange"}},"description":"How the customer chose time. Must match the rate's unit."},"NightsRange":{"type":"object","properties":{"kind":{"type":"string","enum":["nights"]},"checkIn":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"checkOut":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"}},"required":["kind","checkIn","checkOut"]},"HoursRange":{"type":"object","properties":{"kind":{"type":"string","enum":["hours"]},"start":{"type":"string","example":"2026-12-08T10:00","description":"Local time in the business's timezone (2026-12-08T10:00), or an exact time with offset (2026-12-08T10:00:00+01:00)"},"hours":{"type":"integer","minimum":1}},"required":["kind","start","hours"]},"BlockRange":{"type":"object","properties":{"kind":{"type":"string","enum":["block"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"block":{"type":"string","example":"Morning"}},"required":["kind","date","block"]},"DaysRange":{"type":"object","properties":{"kind":{"type":"string","enum":["days"]},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"days":{"type":"integer","minimum":1}},"required":["kind","start","days"]},"MonthsRange":{"type":"object","properties":{"kind":{"type":"string","enum":["months"]},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"months":{"type":"integer","minimum":1}},"required":["kind","start","months"]},"YearsRange":{"type":"object","properties":{"kind":{"type":"string","enum":["years"]},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"years":{"type":"integer","minimum":1}},"required":["kind","start","years"]},"SessionRange":{"type":"object","properties":{"kind":{"type":"string","enum":["session"]}},"required":["kind"]},"Booking":{"type":"object","properties":{"id":{"type":"string"},"resourceId":{"type":["string","null"],"description":"The resource booked; null for session bookings"},"sessionId":{"type":["string","null"],"description":"The session booked; null for resource bookings"},"status":{"$ref":"#/components/schemas/BookingStatus"},"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"quantity":{"type":"integer"},"units":{"type":"array","items":{"type":"object","properties":{"unitId":{"type":"string"},"name":{"type":"string"}},"required":["unitId","name"]}},"currency":{"type":"string"},"total":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"dueNow":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"paymentOption":{"$ref":"#/components/schemas/PaymentOptionKind"},"paymentMethod":{"type":["string","null"],"description":"card, bank_transfer, on_arrival or desk"},"holdExpiresAt":{"type":["string","null"],"example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"inArrears":{"type":"boolean"},"quote":{"$ref":"#/components/schemas/Quote"},"instalments":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"status":{"type":"string"}},"required":["seq","dueDate","amount","status"]}},"reference":{"type":"string","example":"C3C5Y96K","description":"Short reference for guests and staff"},"customer":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["id","name","email","phone"]},"itemName":{"type":"string","example":"Studio Flat Deluxe"},"adults":{"type":"integer"},"children":{"type":"integer"},"paid":{"type":"integer","example":4000000,"description":"Received minus refunded"},"balanceDue":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["CHARGE","REFUND"]},"status":{"type":"string"},"provider":{"type":"string"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["id","kind","status","provider","amount","createdAt"]}},"history":{"type":"array","items":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":"string"},"actor":{"type":"string"},"reason":{"type":["string","null"]},"at":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["from","to","actor","reason","at"]}},"metadata":{"$ref":"#/components/schemas/Metadata"},"manageToken":{"type":["string","null"],"description":"The guest's private manage-link token (GET /v1/manage/{bookingId}?token=…). On holds and single-booking reads only"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["id","resourceId","sessionId","status","start","end","quantity","units","currency","total","dueNow","paymentOption","paymentMethod","holdExpiresAt","inArrears","quote","instalments","reference","customer","itemName","adults","children","paid","balanceDue","payments","history","metadata","createdAt"]},"BookingStatus":{"type":"string","enum":["HOLD","PENDING_APPROVAL","CONFIRMED","CHECKED_IN","COMPLETED","CANCELLED","EXPIRED","NO_SHOW"]},"Metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"invoice":"INV-204"},"description":"Your own data: up to 50 keys (1–40 characters) with string values (up to 500). On updates, keys are merged; an empty string removes a key. RatesSpot never interprets it."},"HoldRequest":{"allOf":[{"$ref":"#/components/schemas/QuoteRequest"},{"type":"object","properties":{"paymentOption":{"allOf":[{"$ref":"#/components/schemas/PaymentOptionKind"},{"description":"Defaults to the rate's default option"}]},"customer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":5,"maxLength":40}},"required":["name"],"description":"Name plus an email or a phone number (or both). Card checkout needs an email for the receipt"},"holdMinutes":{"type":"integer","minimum":1,"maximum":1440,"description":"Hold longer than the merchant's default, e.g. for a payment link sent to a guest. Needs the bookings:write scope."},"paymentMethod":{"type":"string","enum":["card","bank_transfer","on_arrival","desk"],"description":"How the guest will pay. bank_transfer holds for the business's transfer time (see GET /v1/payment-methods); desk needs bookings:write."},"metadata":{"$ref":"#/components/schemas/Metadata"}}}]},"BookingUpdate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["metadata"]},"Cancellation":{"type":"object","properties":{"paid":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"penalty":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"refund":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["paid","penalty","refund"],"description":"paid = penalty + refund"},"CancelRequest":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}},"MoveRequest":{"type":"object","properties":{"unitId":{"type":"string","minLength":1,"maxLength":64}},"required":["unitId"]},"PaymentRequest":{"type":"object","properties":{"provider":{"type":"string","minLength":1,"maxLength":40,"example":"manual","description":"paystack, stripe, manual…"},"providerRef":{"type":"string","minLength":1,"maxLength":200,"description":"The provider's unique reference; recording it twice is a no-op"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"instalmentSeq":{"type":"integer","minimum":1}},"required":["provider","providerRef","amount"]},"Termination":{"type":"object","properties":{"fee":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"endsAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"cancelledInstalments":{"type":"array","items":{"type":"integer"}}},"required":["fee","endsAt","cancelledInstalments"]},"BookingList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]},"Calendar":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"timezone":{"type":"string","example":"Africa/Lagos"},"currency":{"type":"string","example":"NGN"},"listings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","active"]}}},"required":["id","name","active","units"]}},"bookings":{"type":"array","items":{"$ref":"#/components/schemas/CalendarBooking"},"description":"Bookings occupying units in the range. Cancelled, expired and lapsed holds are left out; course bookings show as their room's closures"},"closures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"resourceId":{"type":"string"},"unitId":{"type":["string","null"],"description":"Null: the whole listing"},"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"reason":{"type":["string","null"]},"courseName":{"type":["string","null"],"description":"Set when a course uses the room"}},"required":["id","resourceId","unitId","start","end","reason","courseName"]}}},"required":["from","to","timezone","currency","listings","bookings","closures"]},"CalendarBooking":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"$ref":"#/components/schemas/BookingStatus"},"resourceId":{"type":"string"},"unitIds":{"type":"array","items":{"type":"string"},"description":"Units it occupies"},"start":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"end":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"holdExpiresAt":{"type":["string","null"],"example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"customerName":{"type":["string","null"]},"quantity":{"type":"integer"},"total":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"balanceDue":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"paymentMethod":{"type":["string","null"]}},"required":["id","reference","status","resourceId","unitIds","start","end","holdExpiresAt","customerName","quantity","total","balanceDue","paymentMethod"]},"DeskPaymentRequest":{"type":"object","properties":{"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"method":{"type":"string","enum":["cash","bank_transfer","pos"],"description":"How the guest paid at the desk"}},"required":["amount","method"]},"PaymentProvider":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/CardProvider"},"livemode":{"type":"boolean"},"publicKey":{"type":["string","null"]}},"required":["provider","livemode","publicKey"],"description":"The secret key is stored encrypted and never returned."},"CardProvider":{"type":"string","enum":["paystack","stripe"],"description":"Payment provider for online card payments"},"PaymentProviderRequest":{"type":"object","properties":{"secretKey":{"type":"string","pattern":"^sk_(test|live)_[A-Za-z0-9]+$","example":"sk_test_0123456789abcdef"},"publicKey":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]+$","example":"pk_test_0123456789abcdef"}},"required":["secretKey"]},"StripeProviderRequest":{"type":"object","properties":{"secretKey":{"type":"string","pattern":"^(?:sk|rk)_(test|live)_[A-Za-z0-9]+$","example":"sk_test_0123456789abcdef","description":"Secret key, or a restricted key (rk_…) with Checkout Sessions and Refunds write access"},"publicKey":{"type":"string","pattern":"^pk_(test|live)_[A-Za-z0-9]+$","example":"pk_test_0123456789abcdef"},"webhookSecret":{"type":"string","pattern":"^whsec_[A-Za-z0-9]+$","example":"whsec_0123456789abcdef","description":"Signing secret of the Stripe webhook endpoint you pointed at RatesSpot (see GET /v1/payment-providers)"}},"required":["secretKey","webhookSecret"]},"Checkout":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/CardProvider"},"reference":{"type":"string","description":"The provider's id for this checkout: pass it to POST /v1/checkouts/verify"},"authorizationUrl":{"type":"string","format":"uri","description":"Send the guest here to pay"},"accessCode":{"type":["string","null"],"description":"For Paystack's inline popup instead of a redirect; null for Stripe"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"currency":{"type":"string"},"publicKey":{"type":["string","null"]}},"required":["provider","reference","authorizationUrl","accessCode","amount","currency","publicKey"]},"CheckoutRequest":{"type":"object","properties":{"provider":{"allOf":[{"$ref":"#/components/schemas/CardProvider"},{"description":"Use cardProvider from GET /v1/payment-methods"}]},"callbackUrl":{"type":"string","format":"uri","example":"https://example.com/booking/complete","description":"Must be on one of the business's return websites (Business: returnSites), a RatesSpot page, or localhost for test businesses. Where the provider sends the guest after paying, with ?reference=… (Stripe also adds provider=stripe)"},"email":{"type":"string","format":"email","description":"Receipt email. Defaults to the hold's customer email"}},"required":["provider","callbackUrl"]},"CheckoutStatus":{"type":"object","properties":{"paymentStatus":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"]},"bookingId":{"type":"string"},"bookingStatus":{"type":"string"}},"required":["paymentStatus","bookingId","bookingStatus"]},"CheckoutVerifyRequest":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/CardProvider"},"reference":{"type":"string","minLength":1,"maxLength":200}},"required":["provider","reference"]},"NotificationSettings":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether this server has an email provider (RESEND_API_KEY)."},"settings":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean","description":"Send emails. Off until the sending domain is verified."},"fromName":{"type":"string","minLength":1,"maxLength":100,"example":"Harbour View Suites"},"fromEmail":{"type":"string","maxLength":254,"format":"email"},"replyTo":{"type":["string","null"],"maxLength":254,"format":"email","description":"Where customers' replies go. Defaults to fromEmail, or staffEmail when sending from the shared address."},"staffEmail":{"type":["string","null"],"maxLength":254,"format":"email","description":"Gets an alert for each booking made online. None if empty."},"phone":{"type":["string","null"],"maxLength":50},"address":{"type":["string","null"],"maxLength":300},"website":{"type":["string","null"],"maxLength":200},"arrivalInfo":{"type":["string","null"],"maxLength":1000,"example":"Check-in from 1 pm. Check-out by 12 noon."},"updatedAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["enabled","fromName","fromEmail","updatedAt"]},{"type":"null"}],"description":"Null until the business saves its email settings"},"sharedSender":{"type":["string","null"],"description":"This server's shared address: leave fromEmail empty to send from it under the business's name"},"ownDomain":{"type":["string","null"],"description":"The business's own verified domain, if a platform admin has assigned one: fromEmail may use it"}},"required":["configured","settings","sharedSender","ownDomain"]},"NotificationSettingsRequest":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Send emails. Off until the sending domain is verified."},"fromName":{"type":"string","minLength":1,"maxLength":100,"example":"Harbour View Suites"},"fromEmail":{"anyOf":[{"type":"string","maxLength":254,"format":"email"},{"type":"string","enum":[""]},{"type":"null"}],"example":"bookings@example.com","description":"Empty: the server's shared address. Otherwise on the business's own verified domain"},"replyTo":{"type":["string","null"],"maxLength":254,"format":"email","description":"Where customers' replies go. Defaults to fromEmail, or staffEmail when sending from the shared address."},"staffEmail":{"type":["string","null"],"maxLength":254,"format":"email","description":"Gets an alert for each booking made online. None if empty."},"phone":{"type":["string","null"],"maxLength":50},"address":{"type":["string","null"],"maxLength":300},"website":{"type":["string","null"],"maxLength":200},"arrivalInfo":{"type":["string","null"],"maxLength":1000,"example":"Check-in from 1 pm. Check-out by 12 noon."}},"required":["enabled","fromName"]},"TestEmailRequest":{"type":"object","properties":{"to":{"type":"string","maxLength":254,"format":"email"}},"required":["to"]},"Notification":{"type":"object","properties":{"id":{"type":"string"},"template":{"anyOf":[{"type":"string","enum":["booking_confirmed","booking_cancelled","payment_receipt","staff_new_booking"]},{"type":"string"}]},"toEmail":{"type":"string"},"subject":{"type":"string"},"bookingId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","SENDING","SENT","FAILED"]},"attempts":{"type":"integer"},"lastError":{"type":["string","null"]},"sentAt":{"type":["string","null"],"example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["id","template","toEmail","subject","bookingId","status","attempts","lastError","sentAt","createdAt"]},"AdminCatalog":{"type":"object","properties":{"currency":{"type":"string"},"resources":{"type":"array","items":{"$ref":"#/components/schemas/AdminResource"}},"cancellationPolicies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"addOns":{"type":"array","items":{"$ref":"#/components/schemas/AddOn"}}},"required":["currency","resources","cancellationPolicies","addOns"]},"AdminResource":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"description":{"type":["string","null"]},"features":{"type":"array","items":{"type":"string"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"sortOrder":{"type":"integer"}},"required":["id","alt","width","height","sortOrder"]}},"capacity":{"type":"integer"},"allowUnitChoice":{"type":"boolean"},"checkInMinute":{"type":["integer","null"]},"checkOutMinute":{"type":["integer","null"]},"minLeadMinutes":{"type":"integer"},"maxLeadDays":{"type":["integer","null"]},"vocabulary":{"$ref":"#/components/schemas/VocabularyOverrides"},"sortOrder":{"type":"integer"},"active":{"type":"boolean"},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sortOrder":{"type":"integer"},"active":{"type":"boolean"},"upcomingBookings":{"type":"integer"}},"required":["id","name","sortOrder","active","upcomingBookings"]}},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string"},"unit":{"type":"string","enum":["NIGHT","HOUR","BLOCK","DAY","MONTH","YEAR","BOOKING","SEAT"]},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"isDefault":{"type":"boolean"},"refundable":{"type":"boolean"},"active":{"type":"boolean"},"minUnits":{"type":"integer"},"maxUnits":{"type":["integer","null"]},"dailyCap":{"type":["integer","null"],"example":4000000,"description":"Amount in minor units (kobo, cents)"},"termMonths":{"type":["integer","null"]},"cancellationPolicyId":{"type":["string","null"]},"blocks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"startMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"endMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"}},"required":["name","startMinute","endMinute"]}},"paymentOptions":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["FULL","DEPOSIT","ON_ARRIVAL","INSTALMENTS"]},"isDefault":{"type":"boolean"},"depositType":{"type":["string","null"],"enum":["PERCENT","FIXED","UNITS",null]},"depositValue":{"type":["integer","null"]},"depositRefundable":{"type":"boolean"},"balanceDueDaysBefore":{"type":["integer","null"]},"instalmentCount":{"type":["integer","null"]}},"required":["kind","isDefault","depositType","depositValue","depositRefundable","balanceDueDaysBefore","instalmentCount"]}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}},"fees":{"type":"array","items":{"$ref":"#/components/schemas/Fee"}},"addOns":{"type":"array","items":{"type":"object","properties":{"addOnId":{"type":"string"},"name":{"type":"string"},"amount":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"basis":{"type":"string","enum":["PER_BOOKING","PER_UNIT","PER_GUEST"]},"required":{"type":"boolean"}},"required":["addOnId","name","amount","basis","required"]}},"contract":{"type":["object","null"],"properties":{"terminationFeeType":{"type":["string","null"],"enum":["FIXED","MONTHS","PERCENT_OF_REMAINING","REPAY_DISCOUNT",null]},"terminationFeeValue":{"type":["integer","null"]},"baseAmountForDiscount":{"type":["integer","null"],"example":4000000,"description":"Amount in minor units (kobo, cents)"},"noticeMonths":{"type":"integer"},"graceDays":{"type":"integer"}},"required":["terminationFeeType","terminationFeeValue","baseAmountForDiscount","noticeMonths","graceDays"]}},"required":["id","metadata","name","unit","amount","isDefault","refundable","active","minUnits","maxUnits","dailyCap","termMonths","cancellationPolicyId","blocks","paymentOptions","rules","fees","addOns","contract"]}}},"required":["id","slug","name","tagline","description","features","metadata","images","capacity","allowUnitChoice","checkInMinute","checkOutMinute","minLeadMinutes","maxLeadDays","vocabulary","sortOrder","active","units","rates"]},"VocabularyOverrides":{"type":"object","properties":{"customer":{"type":"string","maxLength":40},"customers":{"type":"string","maxLength":40},"unit":{"type":"string","maxLength":40},"units":{"type":"string","maxLength":40},"booking":{"type":"string","maxLength":40},"bookings":{"type":"string","maxLength":40},"checkIn":{"type":"string","maxLength":40},"checkedIn":{"type":"string","maxLength":40},"checkOut":{"type":"string","maxLength":40},"checkedOut":{"type":"string","maxLength":40},"capacity":{"type":"string","maxLength":40}},"description":"Words that differ from the template's; an empty string removes one"},"PriceRule":{"allOf":[{"$ref":"#/components/schemas/PriceRuleInput"},{"type":"object","properties":{"id":{"type":"string"}},"required":["priority","active","id"]}]},"PriceRuleInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["DAY_OF_WEEK"]},"weekdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"minItems":1,"description":"0 = Sunday"}},"required":["kind","weekdays"]},{"type":"object","properties":{"kind":{"type":"string","enum":["DATE_RANGE"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"}},"required":["kind","from","to"]},{"type":"object","properties":{"kind":{"type":"string","enum":["TIME_OF_DAY"]},"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["kind","startMinute","endMinute"]},{"type":"object","properties":{"kind":{"type":"string","enum":["LENGTH_OF_STAY"]},"minUnits":{"type":"integer","minimum":1},"maxUnits":{"type":["integer","null"],"minimum":1}},"required":["kind","minUnits"]},{"type":"object","properties":{"kind":{"type":"string","enum":["LEAD_TIME"]},"minHours":{"type":["number","null"]},"maxHours":{"type":["number","null"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["EXTRA_GUEST"]},"baseGuests":{"type":"integer","minimum":0}},"required":["kind","baseGuests"]}]},"adjustment":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENT","FIXED"]},"value":{"type":"integer","description":"PERCENT in basis points (2000 = +20%, -1000 = 10% off); FIXED in minor units per night/hour/day, or per extra guest"}},"required":["type","value"]},"priority":{"type":"integer"},"active":{"type":"boolean"}},"required":["name","condition","adjustment"]},"Fee":{"allOf":[{"$ref":"#/components/schemas/ChargeInput"},{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}]},"ChargeInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":0,"example":4000000,"description":"Amount in minor units (kobo, cents)"},"basis":{"type":"string","enum":["PER_BOOKING","PER_UNIT","PER_GUEST"]}},"required":["name","amount","basis"]},"AddOn":{"allOf":[{"$ref":"#/components/schemas/ChargeInput"},{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"}},"required":["id","active"]}]},"ResourceCreate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"type":"string","maxLength":80,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"Web address on booking sites, e.g. studio-flat-deluxe"},"tagline":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":5000},"features":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":40},"capacity":{"type":"integer","minimum":1,"maximum":1000,"description":"People per unit"},"allowUnitChoice":{"type":"boolean"},"checkInMinute":{"type":["integer","null"],"minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"checkOutMinute":{"type":["integer","null"],"minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"minLeadMinutes":{"type":"integer","minimum":0},"maxLeadDays":{"type":["integer","null"],"minimum":1},"vocabulary":{"allOf":[{"$ref":"#/components/schemas/VocabularyOverrides"},{"description":"This listing's own words, e.g. a class's customers are \"students\""}]},"sortOrder":{"type":"integer"},"active":{"type":"boolean"},"units":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"maxItems":500,"description":"Names of the physical rooms, e.g. [\"Studio 1\", \"Studio 2\"]"}},"required":["name","capacity"]},"ResourceUpdate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":100},"slug":{"type":"string","maxLength":80,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"Web address on booking sites, e.g. studio-flat-deluxe"},"tagline":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":5000},"features":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":40},"capacity":{"type":"integer","minimum":1,"maximum":1000,"description":"People per unit"},"allowUnitChoice":{"type":"boolean"},"checkInMinute":{"type":["integer","null"],"minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"checkOutMinute":{"type":["integer","null"],"minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"minLeadMinutes":{"type":"integer","minimum":0},"maxLeadDays":{"type":["integer","null"],"minimum":1},"vocabulary":{"allOf":[{"$ref":"#/components/schemas/VocabularyOverrides"},{"description":"This listing's own words, e.g. a class's customers are \"students\""}]},"sortOrder":{"type":"integer"},"active":{"type":"boolean"}}},"UnitCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60}},"required":["name"]},"UnitUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"active":{"type":"boolean"},"sortOrder":{"type":"integer"}}},"RateCreate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":0,"example":4000000,"description":"Price per night, hour, block or day, in minor units"},"isDefault":{"type":"boolean"},"refundable":{"type":"boolean"},"active":{"type":"boolean"},"minUnits":{"type":"integer","minimum":1},"maxUnits":{"type":["integer","null"],"minimum":1},"dailyCap":{"type":["integer","null"],"minimum":1,"example":4000000,"description":"Hourly rates: most charged per day"},"cancellationPolicyId":{"type":["string","null"],"maxLength":64},"blocks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"startMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"endMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"}},"required":["name","startMinute","endMinute"]},"maxItems":10},"paymentOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentOptionInput"},"maxItems":3},"contract":{"$ref":"#/components/schemas/ContractInput"},"unit":{"type":"string","enum":["NIGHT","HOUR","BLOCK","DAY","MONTH","YEAR"]}},"required":["name","amount","unit"]},"PaymentOptionInput":{"type":"object","properties":{"kind":{"type":"string","enum":["FULL","DEPOSIT","ON_ARRIVAL"]},"isDefault":{"type":"boolean"},"depositType":{"type":"string","enum":["PERCENT","FIXED","UNITS"],"description":"PERCENT in basis points (5000 = 50%), FIXED in minor units, UNITS = first N nights or days"},"depositValue":{"type":"integer","minimum":1},"depositRefundable":{"type":"boolean"},"balanceDueDaysBefore":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Null = balance due on arrival"}},"required":["kind"]},"ContractInput":{"type":"object","properties":{"termMonths":{"type":"integer","minimum":2,"maximum":60},"terminationFeeType":{"type":["string","null"],"enum":["FIXED","MONTHS","PERCENT_OF_REMAINING","REPAY_DISCOUNT",null]},"terminationFeeValue":{"type":["integer","null"],"minimum":1,"description":"FIXED: minor units. MONTHS: months. PERCENT_OF_REMAINING: basis points."},"baseAmountForDiscount":{"type":["integer","null"],"example":4000000,"description":"REPAY_DISCOUNT: the month-to-month price the contract discounts"},"noticeMonths":{"type":"integer","minimum":0,"maximum":12},"graceDays":{"type":"integer","minimum":0,"maximum":60,"description":"Days after an instalment is due before the contract is in arrears"}},"required":["termMonths"],"description":"Monthly rates only: a fixed-term contract paid in monthly instalments"},"RateUpdate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":0,"example":4000000,"description":"Price per night, hour, block or day, in minor units"},"isDefault":{"type":"boolean"},"refundable":{"type":"boolean"},"active":{"type":"boolean"},"minUnits":{"type":"integer","minimum":1},"maxUnits":{"type":["integer","null"],"minimum":1},"dailyCap":{"type":["integer","null"],"minimum":1,"example":4000000,"description":"Hourly rates: most charged per day"},"cancellationPolicyId":{"type":["string","null"],"maxLength":64},"blocks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"startMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"},"endMinute":{"type":"integer","minimum":0,"maximum":1440,"description":"Minutes after midnight, local time (780 = 13:00)"}},"required":["name","startMinute","endMinute"]},"maxItems":10},"paymentOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentOptionInput"},"maxItems":3},"contract":{"$ref":"#/components/schemas/ContractInput"}}},"RateAddOnsRequest":{"type":"object","properties":{"addOns":{"type":"array","items":{"type":"object","properties":{"addOnId":{"type":"string","maxLength":64},"required":{"type":"boolean"}},"required":["addOnId"]},"maxItems":50}},"required":["addOns"]},"Course":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string"},"seats":{"type":"integer"},"seatsSold":{"type":"integer"},"pricePerSeat":{"type":"integer","example":4000000,"description":"Amount in minor units (kobo, cents)"},"hostName":{"type":["string","null"]},"description":{"type":["string","null"]},"hostShareBps":{"type":["integer","null"]},"resourceId":{"type":["string","null"]},"resourceName":{"type":["string","null"]},"active":{"type":"boolean"},"dates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"start":{"type":"string","example":"2026-12-12T09:00","description":"Local date-time in the business's timezone"},"end":{"type":"string","example":"2026-12-12T09:00","description":"Local date-time in the business's timezone"}},"required":["id","start","end"]},"description":"Empty = dates to be announced"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","alt","width","height"]}},"finished":{"type":"boolean"}},"required":["id","metadata","name","seats","seatsSold","pricePerSeat","hostName","description","hostShareBps","resourceId","resourceName","active","dates","images","finished"]},"CourseCreate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":200},"seats":{"type":"integer","minimum":1,"maximum":10000},"pricePerSeat":{"type":"integer","minimum":0,"example":4000000,"description":"Amount in minor units (kobo, cents)"},"hostName":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":2000,"description":"What the course covers, shown to guests"},"hostShareBps":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"The host's share: 7000 = 70%"},"resourceId":{"type":["string","null"],"maxLength":64,"description":"A room it uses; closed to other bookings on those dates"},"dates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"startTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"endTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["date","startTime","endTime"]},"maxItems":100,"description":"Leave empty to list the course with dates to be announced"}},"required":["name","seats","pricePerSeat","dates"]},"CourseUpdate":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"type":"string","minLength":1,"maxLength":200},"seats":{"type":"integer","minimum":1,"maximum":10000},"pricePerSeat":{"type":"integer","minimum":0,"example":4000000,"description":"Amount in minor units (kobo, cents)"},"hostName":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":2000},"hostShareBps":{"type":["integer","null"],"minimum":0,"maximum":10000},"active":{"type":"boolean","description":"false = stop selling seats; existing bookings are unchanged"}}},"ImageView":{"type":"object","properties":{"id":{"type":"string"},"alt":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"sortOrder":{"type":"integer"}},"required":["id","alt","width","height","sortOrder"]},"CourseDatesRequest":{"type":"object","properties":{"dates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"startTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"endTime":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}},"required":["date","startTime","endTime"]},"minItems":1,"maxItems":100}},"required":["dates"]},"PaymentMethods":{"type":"object","properties":{"card":{"type":"boolean","description":"Online card payments are available"},"cardProvider":{"anyOf":[{"$ref":"#/components/schemas/CardProvider"},{"type":"null"}],"description":"Which provider to start card checkouts with"},"bankTransfer":{"type":["object","null"],"properties":{"bankName":{"type":"string"},"accountName":{"type":"string"},"accountNumber":{"type":"string"},"holdHours":{"type":"integer"}},"required":["bankName","accountName","accountNumber","holdHours"],"description":"Bank details for transfers, or null if transfers aren't accepted"}},"required":["card","cardProvider","bankTransfer"]},"PaymentSettings":{"type":"object","properties":{"card":{"type":"object","properties":{"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"livemode":{"type":["boolean","null"]},"provider":{"anyOf":[{"$ref":"#/components/schemas/CardProvider"},{"type":"null"}],"description":"The one guests pay with: the first switched on (Paystack, then Stripe)"},"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/CardProvider"},"enabled":{"type":"boolean"},"livemode":{"type":"boolean"}},"required":["provider","enabled","livemode"]}}},"required":["connected","enabled","livemode","provider","providers"]},"bankTransfer":{"type":"object","properties":{"enabled":{"type":"boolean"},"bankName":{"type":["string","null"]},"accountName":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"holdHours":{"type":"integer"}},"required":["enabled","bankName","accountName","accountNumber","holdHours"]}},"required":["card","bankTransfer"]},"CardSettingRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"provider":{"type":"string","enum":["paystack","stripe"],"description":"Just this provider; omit for all"}},"required":["enabled"]},"BankTransferRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"bankName":{"type":["string","null"],"maxLength":100},"accountName":{"type":["string","null"],"maxLength":200},"accountNumber":{"type":["string","null"],"maxLength":20},"holdHours":{"type":"integer","minimum":1,"maximum":168,"description":"How long a transfer booking is held before it's released"}},"required":["enabled"]},"Template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"words":{"$ref":"#/components/schemas/Vocabulary"},"defaults":{"type":"object","properties":{"timeModel":{"type":"string","enum":["range","scheduled"]},"rateUnit":{"type":"string","enum":["NIGHT","HOUR","BLOCK","DAY","MONTH","YEAR"]},"capacity":{"type":"integer"}},"required":["timeModel","rateUnit","capacity"]}},"required":["id","name","description","words","defaults"]},"Invite":{"type":"object","properties":{"email":{"type":"string"},"hasAccount":{"type":"boolean"}},"required":["email","hasAccount"]},"InviteCheckRequest":{"type":"object","properties":{"token":{"type":"string","minLength":10,"maxLength":200}},"required":["token"]},"TestSignUp":{"allOf":[{"$ref":"#/components/schemas/Login"},{"type":"object","properties":{"merchantId":{"type":"string"},"keys":{"type":"object","properties":{"secret":{"type":"string"},"publishable":{"type":"string"}},"required":["secret","publishable"],"description":"Test keys, shown once. They work only on this test business"}},"required":["merchantId","keys"]}]},"TestSignUpRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"name":{"type":"string","minLength":2,"maxLength":200},"password":{"type":"string","minLength":10,"maxLength":200},"business":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":64,"example":"Africa/Lagos"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"NGN"},"taxRateBps":{"type":"integer","minimum":0,"maximum":5000,"description":"750 = 7.5%"},"taxInclusive":{"type":"boolean","description":"Prices include tax (true) or tax is added on top"},"metadata":{"$ref":"#/components/schemas/Metadata"},"template":{"type":["string","null"],"maxLength":40,"description":"A template id from GET /v1/templates: the words and listing defaults for this kind of business. Null for neutral words"}},"required":["name","timezone","currency"]}},"required":["email","name","password","business"]},"SignUp":{"allOf":[{"$ref":"#/components/schemas/Login"},{"type":"object","properties":{"merchantId":{"type":"string"}},"required":["merchantId"]}]},"SignUpRequest":{"type":"object","properties":{"token":{"type":"string","minLength":10,"maxLength":200,"description":"From the invite link"},"name":{"type":"string","minLength":2,"maxLength":200,"description":"Required for a new account"},"password":{"type":"string","minLength":1,"maxLength":200,"description":"New account: at least 10 characters. Existing account: its password."},"business":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":64,"example":"Africa/Lagos"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"NGN"},"taxRateBps":{"type":"integer","minimum":0,"maximum":5000,"description":"750 = 7.5%"},"taxInclusive":{"type":"boolean","description":"Prices include tax (true) or tax is added on top"},"metadata":{"$ref":"#/components/schemas/Metadata"},"template":{"type":["string","null"],"maxLength":40,"description":"A template id from GET /v1/templates: the words and listing defaults for this kind of business. Null for neutral words"}},"required":["name","timezone","currency"]}},"required":["token","password","business"]},"Business":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string","minLength":2,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":64,"example":"Africa/Lagos"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"NGN"},"taxRateBps":{"type":"integer"},"taxInclusive":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/Metadata"},"template":{"type":["string","null"]},"holdMinutes":{"type":"integer"},"hasBookings":{"type":"boolean"},"vocabulary":{"$ref":"#/components/schemas/VocabularyOverrides"},"words":{"allOf":[{"$ref":"#/components/schemas/Vocabulary"},{"description":"The words in effect"}]},"returnSites":{"type":"array","items":{"type":"string"},"description":"Websites customers may return to after paying online (besides RatesSpot's own pages)"},"returnSitesEnforced":{"type":"boolean","description":"False only for businesses from before the rule, until they save their list"}},"required":["id","slug","name","timezone","currency","taxRateBps","taxInclusive","metadata","template","holdMinutes","hasBookings","vocabulary","words","returnSites","returnSitesEnforced"]},"BusinessUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":64,"example":"Africa/Lagos"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"NGN"},"taxRateBps":{"type":"integer","minimum":0,"maximum":5000,"description":"750 = 7.5%"},"taxInclusive":{"type":"boolean","description":"Prices include tax (true) or tax is added on top"},"metadata":{"$ref":"#/components/schemas/Metadata"},"template":{"type":["string","null"],"maxLength":40,"description":"A template id from GET /v1/templates: the words and listing defaults for this kind of business. Null for neutral words"},"holdMinutes":{"type":"integer","minimum":5,"maximum":1440,"description":"How long an unpaid online booking is held"},"vocabulary":{"$ref":"#/components/schemas/VocabularyOverrides"},"returnSites":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":20,"description":"Websites customers return to after paying online, e.g. https://www.example.com. Checkouts may only send customers to these, RatesSpot's own pages, or (test businesses) localhost"}}},"SetupChecklist":{"type":"object","properties":{"catalog":{"type":"boolean"},"payments":{"type":"boolean"},"emails":{"type":"boolean"},"apiKey":{"type":"boolean"}},"required":["catalog","payments","emails","apiKey"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["SECRET","PUBLISHABLE"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Empty = everything the kind allows"},"prefix":{"type":"string"},"lastUsedAt":{"type":["string","null"],"example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"revokedAt":{"type":["string","null"],"example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00+01:00","description":"ISO date-time with offset"}},"required":["id","name","kind","scopes","prefix","lastUsedAt","revokedAt","createdAt"]},"ApiKeyCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"purpose":{"type":"string","enum":["website","browser","full"],"description":"website: secret key for a booking website's server. browser: publishable key. full: everything, for your own tools."}},"required":["name","purpose"]},"CancellationTerms":{"allOf":[{"$ref":"#/components/schemas/CancellationTermsInput"},{"type":"object","properties":{"id":{"type":"string"},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"resourceName":{"type":["string","null"]}},"required":["id","name","resourceName"]}}},"required":["refundFees","refundAddOns","id","rates"]}]},"CancellationTermsInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"refundFees":{"type":"boolean"},"refundAddOns":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","properties":{"deadline":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["hours"]},"hoursBefore":{"type":"integer","minimum":0,"maximum":8760}},"required":["kind","hoursBefore"]},{"type":"object","properties":{"kind":{"type":"string","enum":["day_time"]},"daysBefore":{"type":"integer","minimum":0,"maximum":365},"minuteOfDay":{"type":"integer","minimum":0,"maximum":1439}},"required":["kind","daysBefore","minuteOfDay"]}]},"penalty":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["NONE"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["PERCENT"]},"bps":{"type":"integer","minimum":1,"maximum":10000}},"required":["kind","bps"]},{"type":"object","properties":{"kind":{"type":"string","enum":["FIXED"]},"amount":{"type":"integer","minimum":1,"example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["kind","amount"]},{"type":"object","properties":{"kind":{"type":"string","enum":["UNITS"]},"count":{"type":"integer","minimum":1,"maximum":365}},"required":["kind","count"]}]}},"required":["deadline","penalty"]},"maxItems":6,"description":"From each deadline on, cancelling costs the penalty. Before the first deadline it's free."}},"required":["name","tiers"]},"Hours":{"type":"object","properties":{"business":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday"},"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["weekday","startMinute","endMinute"]},"description":"Empty = always open"},"resources":{"type":"array","items":{"type":"object","properties":{"resourceId":{"type":"string"},"windows":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday"},"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["weekday","startMinute","endMinute"]}}},"required":["resourceId","windows"]}},"specialDays":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"resourceId":{"type":["string","null"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"windows":{"type":"array","items":{"type":"object","properties":{"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["startMinute","endMinute"]}},"reason":{"type":["string","null"]}},"required":["id","resourceId","date","windows","reason"]}}},"required":["business","resources","specialDays"]},"WeeklyHoursRequest":{"type":"object","properties":{"resourceId":{"type":["string","null"],"maxLength":64,"description":"Null for the business's hours"},"windows":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday"},"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["weekday","startMinute","endMinute"]},"maxItems":70,"description":"Business: empty = always open. Listing: empty = use the business hours."}},"required":["resourceId","windows"]},"SpecialDayRequest":{"type":"object","properties":{"resourceId":{"type":["string","null"],"maxLength":64},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"windows":{"type":"array","items":{"type":"object","properties":{"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["startMinute","endMinute"]},"maxItems":10,"description":"Empty = closed all day"},"reason":{"type":["string","null"],"maxLength":200}},"required":["date","windows"]},"ClosureView":{"type":"object","properties":{"id":{"type":"string"},"resourceId":{"type":"string"},"resourceName":{"type":"string"},"unitId":{"type":["string","null"]},"unitName":{"type":["string","null"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$","example":"2026-12-10T14:00","description":"Local date or date-time in the business's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$","example":"2026-12-10T14:00","description":"Local date or date-time in the business's timezone"},"reason":{"type":["string","null"]}},"required":["id","resourceId","resourceName","unitId","unitName","from","to","reason"]},"LocalClosureRequest":{"type":"object","properties":{"resourceId":{"type":"string","maxLength":64},"unitId":{"type":["string","null"],"maxLength":64,"description":"Omit to close the whole listing"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$","example":"2026-12-10T14:00","description":"Local date or date-time in the business's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$","example":"2026-12-10T14:00","description":"Local date or date-time in the business's timezone"},"reason":{"type":["string","null"],"maxLength":200}},"required":["resourceId","from","to"]},"BookingTimeline":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","example":"2026-12-08T10:00:00.000Z"},"by":{"type":"string","example":"Ada Obi","description":"Who: a person's name, an API key's name, a payment provider, or System"},"kind":{"type":"string","enum":["booking","status","unit","payment","refund","instalment","change"]},"summary":{"type":"string","example":"Moved from Studio 2 to Studio 4"},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"before":{},"after":{}},"required":["field"]},"description":"The fields that changed"}},"required":["at","by","kind","summary","changes"]}}},"required":["data"]},"Activity":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string","example":"2026-12-08T10:00:00.000Z"},"actor":{"type":"string"},"by":{"type":"string","example":"Ada Obi"},"action":{"type":"string","example":"updateRate","description":"The API operation (operationId)"},"method":{"type":"string"},"path":{"type":"string"},"targets":{"type":"object","additionalProperties":{"type":"string"},"example":{"rateId":"cmw…"}},"status":{"type":"integer"}},"required":["id","at","actor","by","action","method","path","targets","status"]}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]},"PlatformMerchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"environment":{"type":"string","enum":["LIVE","TEST"]},"createdAt":{"type":"string"},"owners":{"type":"array","items":{"type":"string"}},"bookings":{"type":"integer"},"storefrontEnabled":{"type":"boolean"},"suspendedAt":{"type":["string","null"]},"suspendedReason":{"type":["string","null"]},"senderDomain":{"type":["string","null"],"description":"Its own email domain for booking emails"}},"required":["id","name","slug","environment","createdAt","owners","bookings","storefrontEnabled","suspendedAt","suspendedReason","senderDomain"]},"MerchantInvite":{"type":"object","properties":{"token":{"type":"string","description":"Shown once. The link is <dashboard>/signup?invite=<token>"},"expiresAt":{"type":"string"}},"required":["token","expiresAt"]},"MerchantInviteRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"note":{"type":"string","maxLength":200}},"required":["email"]},"SuspensionRequest":{"type":"object","properties":{"suspended":{"type":"boolean"},"reason":{"type":"string","maxLength":500}},"required":["suspended"]},"SenderDomainRequest":{"type":"object","properties":{"domain":{"type":["string","null"],"maxLength":253}},"required":["domain"]},"Feedback":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["bug","idea","question"]},"message":{"type":"string"},"page":{"type":["string","null"]},"from":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}},"required":["name","email"]},"business":{"type":["string","null"]},"createdAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","kind","message","page","from","business","createdAt","resolvedAt"]},"FeedbackRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["bug","idea","question"]},"message":{"type":"string","minLength":1,"maxLength":5000},"page":{"type":"string","maxLength":300,"description":"The dashboard page it's about"}},"required":["kind","message"]},"FeedbackResolution":{"type":"object","properties":{"resolved":{"type":"boolean"}},"required":["resolved"]},"GoLiveRequest":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"The test business"},"businessName":{"type":"string"},"website":{"type":["string","null"]},"about":{"type":"string"},"requestedBy":{"type":"string","description":"The owner's email"},"createdAt":{"type":"string"},"decidedAt":{"type":["string","null"]},"decision":{"anyOf":[{"type":"string","enum":["approved","declined"]},{"type":"null"}]},"reason":{"type":["string","null"],"description":"Why it was declined"},"liveMerchantId":{"type":["string","null"],"description":"The live business created on approval"}},"required":["id","merchantId","businessName","website","about","requestedBy","createdAt","decidedAt","decision","reason","liveMerchantId"]},"GoLiveRequestInput":{"type":"object","properties":{"about":{"type":"string","maxLength":2000,"description":"What the business is and how it takes bookings"},"website":{"type":"string","maxLength":500}},"required":["about"]},"GoLiveDecision":{"type":"object","properties":{"approve":{"type":"boolean"},"reason":{"type":"string","maxLength":500}},"required":["approve"]},"OAuthConsent":{"type":"object","properties":{"client":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"website":{"type":["string","null"]},"public":{"type":"boolean"},"verified":{"type":"boolean","description":"Registered by a RatesSpot user (not self-registered)"}},"required":["id","name","website","public","verified"]},"scopes":{"type":"array","items":{"type":"string"}},"businesses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"canGrant":{"type":"boolean","description":"Their role there allows every requested scope"}},"required":["id","name","role","canGrant"]}}},"required":["client","scopes","businesses"]},"OAuthRedirect":{"type":"object","properties":{"redirectTo":{"type":"string"}},"required":["redirectTo"]},"OAuthApproval":{"type":"object","properties":{"client_id":{"type":"string","minLength":1,"maxLength":100},"redirect_uri":{"type":"string","minLength":1,"maxLength":2000},"scope":{"type":"string","maxLength":1000},"code_challenge":{"type":"string","minLength":43,"maxLength":128},"code_challenge_method":{"type":"string","enum":["S256"]},"state":{"type":"string","maxLength":500},"resource":{"type":"string","maxLength":500}},"required":["client_id","redirect_uri","code_challenge","code_challenge_method"]},"InstalledApp":{"type":"object","properties":{"clientId":{"type":"string"},"name":{"type":"string"},"website":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"installedAt":{"type":"string"},"lastUsedAt":{"type":["string","null"]}},"required":["clientId","name","website","scopes","installedAt","lastUsedAt"]},"DeveloperApp":{"type":"object","properties":{"id":{"type":"string","description":"The client_id"},"name":{"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"website":{"type":["string","null"]},"public":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","name","redirectUris","website","public","createdAt"]},"DeveloperAppCreate":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"redirectUris":{"type":"array","items":{"type":"string","maxLength":2000},"minItems":1,"maxItems":10},"website":{"type":"string","maxLength":500},"public":{"type":"boolean","description":"No secret (mobile, desktop, CLI); PKCE only"}},"required":["name","redirectUris"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"description":"Empty: every event"},"enabled":{"type":"boolean"},"disabledReason":{"type":["string","null"],"description":"Why RatesSpot switched it off, e.g. after failing for 3 days"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00.000Z"}},"required":["id","url","description","events","enabled","disabledReason","createdAt"]},"EventType":{"type":"string","enum":["hold.created","hold.expired","booking.confirmed","booking.changed","booking.cancelled","booking.checked_in","booking.completed","booking.no_show","payment.succeeded","payment.failed","refund.created","refund.sent","instalment.overdue","contract.terminated","availability.changed","catalog.changed"]},"WebhookEndpointCreate":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","example":"https://plugin.example.com/ratesspot"},"description":{"type":"string","maxLength":200},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"maxItems":16,"description":"Which events to send. Omit or empty for all"}},"required":["url"]},"WebhookEndpointUpdate":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"description":{"type":["string","null"],"maxLength":200},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"maxItems":16},"enabled":{"type":"boolean","description":"Switch back on after fixing an endpoint RatesSpot switched off"}}},"WebhookTestResult":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["integer","null"]},"error":{"type":["string","null"]}},"required":["ok","status","error"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"]},"attempts":{"type":"integer"},"nextAttemptAt":{"type":["string","null"],"example":"2026-12-08T10:00:00.000Z"},"lastStatusCode":{"type":["integer","null"]},"lastError":{"type":["string","null"]},"deliveredAt":{"type":["string","null"],"example":"2026-12-08T10:00:00.000Z"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00.000Z"}},"required":["id","eventId","eventType","status","attempts","nextAttemptAt","lastStatusCode","lastError","deliveredAt","createdAt"]},"Event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"booking.confirmed"},"createdAt":{"type":"string","example":"2026-12-08T10:00:00.000Z"},"merchantId":{"type":"string"},"livemode":{"type":"boolean"},"data":{"type":"object","additionalProperties":{},"description":"The event's details. Events about a booking include `booking`, as it was at that moment"}},"required":["id","type","createdAt","merchantId","livemode","data"]},"Brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string","description":"The business's web address on hosted booking pages"},"brandColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#1F6F5C"},"accentColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#1F6F5C"},"fontPairing":{"type":"string","enum":["modern","classic","friendly"]},"logo":{"type":["object","null"],"properties":{"id":{"type":"string"},"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","url","width","height"]},"cover":{"type":["object","null"],"properties":{"id":{"type":"string"},"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","url","width","height"]},"about":{"type":["string","null"]},"contact":{"type":"object","properties":{"phone":{"type":["string","null"]},"whatsapp":{"type":["string","null"]},"email":{"type":["string","null"]},"address":{"type":["string","null"]},"mapUrl":{"type":["string","null"]},"instagram":{"type":["string","null"]},"website":{"type":["string","null"]}},"required":["phone","whatsapp","email","address","mapUrl","instagram","website"]},"bookingTerms":{"type":["string","null"]},"storefrontEnabled":{"type":"boolean","description":"The hosted booking page is published"},"guestCanCancel":{"type":"boolean","description":"Guests may cancel from their manage link, under the booking's own terms"},"listedInDirectory":{"type":"boolean","description":"Listed in the public directory of booking pages (shown only while live and published)"}},"required":["name","slug","brandColor","accentColor","fontPairing","logo","cover","about","contact","bookingTerms","storefrontEnabled","guestCanCancel","listedInDirectory"]},"BrandUpdate":{"type":"object","properties":{"brandColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#1F6F5C"},"accentColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$","example":"#1F6F5C"},"fontPairing":{"type":"string","enum":["modern","classic","friendly"]},"about":{"type":["string","null"],"maxLength":2000},"contact":{"type":"object","properties":{"phone":{"type":["string","null"],"maxLength":40},"whatsapp":{"type":["string","null"],"maxLength":40},"email":{"type":["string","null"],"maxLength":254},"address":{"type":["string","null"],"maxLength":300},"mapUrl":{"type":["string","null"],"maxLength":500},"instagram":{"type":["string","null"],"maxLength":500},"website":{"type":["string","null"],"maxLength":500}}},"bookingTerms":{"type":["string","null"],"maxLength":20000},"guestCanCancel":{"type":"boolean"},"listedInDirectory":{"type":"boolean"}}},"StorefrontRequest":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"StorefrontDirectory":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"The business's web address on hosted booking pages"},"name":{"type":"string"},"about":{"type":["string","null"]},"address":{"type":["string","null"]},"cover":{"type":["object","null"],"properties":{"id":{"type":"string"},"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["id","url","width","height"]}},"required":["slug","name","about","address","cover"]}}},"required":["data"]},"Storefront":{"type":"object","properties":{"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"timezone":{"type":"string"},"testMode":{"type":"boolean","description":"A test business: show that bookings aren't real"},"words":{"$ref":"#/components/schemas/Vocabulary"}},"required":["id","name","slug","currency","timezone","testMode","words"]},"brand":{"$ref":"#/components/schemas/Brand"},"publishableKey":{"type":"string","description":"The page's publishable key: public by design (browse, quote, hold, pay)"}},"required":["merchant","brand","publishableKey"]},"ManagedBooking":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/Booking"},"business":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"timezone":{"type":"string"},"contact":{"type":"object","properties":{"phone":{"type":["string","null"]},"whatsapp":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["phone","whatsapp","email"]}},"required":["name","slug","timezone","contact"]},"canCancel":{"type":"boolean","description":"The business lets guests cancel online, and this booking can be cancelled"},"cancellation":{"type":["object","null"],"properties":{"paid":{"type":"integer"},"penalty":{"type":"integer"},"refund":{"type":"integer"}},"required":["paid","penalty","refund"],"description":"What cancelling now would keep and refund"}},"required":["booking","business","canCancel","cancellation"]},"ManagedGuestUpdate":{"type":"object","properties":{"token":{"type":"string","minLength":20,"maxLength":100,"description":"From the guest's manage link"},"name":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","minLength":5,"maxLength":40}},"required":["token"]},"ManagedCancellation":{"type":"object","properties":{"paid":{"type":"integer"},"penalty":{"type":"integer"},"refund":{"type":"integer"}},"required":["paid","penalty","refund"]},"ManagedCancelRequest":{"type":"object","properties":{"token":{"type":"string","minLength":20,"maxLength":100,"description":"From the guest's manage link"},"reason":{"type":"string","maxLength":500}},"required":["token"]}},"parameters":{}},"paths":{"/v1/auth/login":{"post":{"operationId":"login","security":[],"tags":["Staff"],"summary":"Sign in to the dashboard","description":"Returns a session token valid for 7 days. Wrong email and wrong password give the same answer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Login"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Wrong email or password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many failed attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/me":{"get":{"operationId":"getSession","tags":["Staff"],"summary":"The signed-in person and the businesses they can manage","security":[{"apiKey":[]}],"responses":{"200":{"description":"You","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffUser"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/logout":{"post":{"operationId":"logout","tags":["Staff"],"summary":"Sign out this session","security":[{"apiKey":[]}],"responses":{"200":{"description":"Signed out","content":{"application/json":{"schema":{"type":"object","properties":{"signedOut":{"type":"boolean","enum":[true]}},"required":["signedOut"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/password":{"post":{"operationId":"changePassword","tags":["Staff"],"summary":"Change your password","description":"Signs out your other sessions.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}}},"responses":{"200":{"description":"Changed","content":{"application/json":{"schema":{"type":"object","properties":{"changed":{"type":"boolean","enum":[true]}},"required":["changed"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/staff":{"get":{"operationId":"listStaff","tags":["Staff"],"summary":"People with access to this business","security":[{"apiKey":[]}],"responses":{"200":{"description":"Staff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StaffMember"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addStaff","tags":["Staff"],"summary":"Give someone access","description":"New people get a temporary password (returned once) that they must change at first sign-in.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddStaffRequest"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddedStaff"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/staff/{userId}":{"patch":{"operationId":"updateStaffRole","tags":["Staff"],"summary":"Change someone's role","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["OWNER","MANAGER","FRONT_DESK"]}},"required":["role"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean","enum":[true]}},"required":["updated"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeStaff","tags":["Staff"],"summary":"Remove someone's access","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","enum":[true]}},"required":["removed"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/staff/{userId}/reset-password":{"post":{"operationId":"resetStaffPassword","tags":["Staff"],"summary":"Issue a new temporary password for a colleague","description":"Only for people who work solely at businesses you own. Signs them out everywhere.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"New temporary password, shown once","content":{"application/json":{"schema":{"type":"object","properties":{"temporaryPassword":{"type":"string"}},"required":["temporaryPassword"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/forgot-password":{"post":{"operationId":"requestPasswordReset","tags":["Staff"],"summary":"Email a password reset link","description":"Public. Always answers the same way, so it can't be used to find out who has an account. The link works for one hour.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetRequest"}}}},"responses":{"202":{"description":"If there's an account, a link is on its way"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/reset-password":{"post":{"operationId":"resetPassword","tags":["Staff"],"summary":"Choose a new password with an emailed link (signs out every session)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordReset"}}}},"responses":{"204":{"description":"Changed: sign in with the new password"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/verify-email":{"post":{"operationId":"verifyEmail","tags":["Staff"],"summary":"Confirm an email address with an emailed link","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerification"}}}},"responses":{"204":{"description":"Confirmed"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/verification-email":{"post":{"operationId":"sendVerificationEmail","tags":["Staff"],"summary":"Send the signed-in person a new link to confirm their email","security":[{"apiKey":[]}],"responses":{"204":{"description":"Sent (or already confirmed)"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/customers/{id}/erase":{"post":{"operationId":"eraseCustomer","tags":["Privacy"],"summary":"Erase a customer's personal details (on their request); their bookings and payments stay, anonymised","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Erased"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business/export":{"get":{"operationId":"exportBusiness","tags":["Privacy"],"summary":"Everything the business holds, as JSON: listings, rates, customers, bookings, payments, staff","security":[{"apiKey":[]}],"responses":{"200":{"description":"The business's data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessExport"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business/close":{"post":{"operationId":"closeBusiness","tags":["Privacy"],"summary":"Close the business: it stops working at once, and all its data is deleted after 90 days","description":"Owners only, signed in. Export the data first if you want to keep it.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseBusinessRequest"}}}},"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosedBusiness"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/account/delete":{"post":{"operationId":"deleteAccount","tags":["Privacy"],"summary":"Delete your own account (you can't be a business's only owner)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountRequest"}}}},"responses":{"204":{"description":"Deleted"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/merchant":{"get":{"operationId":"getMerchant","tags":["Catalog"],"summary":"The merchant this API key belongs to","security":[{"apiKey":[]}],"responses":{"200":{"description":"The merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Merchant"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/resources":{"get":{"operationId":"listResources","tags":["Catalog"],"summary":"List bookable resources with their rates","description":"Rooms, desks, offices and so on. Each resource has one or more rates; the rate decides how time is booked. Units are listed when guests may choose one, or for callers that can change bookings.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Resources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sessions":{"get":{"operationId":"listSessions","tags":["Catalog"],"summary":"List upcoming sessions (courses, workshops) with seats left","security":[{"apiKey":[]}],"responses":{"200":{"description":"Sessions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSession","tags":["Catalog"],"summary":"Schedule a session with seats; closes its room for each occurrence","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"rateId":{"type":"string"}},"required":["id","rateId"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/availability":{"get":{"operationId":"getAvailability","tags":["Availability"],"summary":"Calendar of availability for a resource or session","description":"Per date: units free all day and the price. For hour rates, start times with enough free units; for block rates, free blocks. To check one specific stay, request a quote instead.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"resourceId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"sessionId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"rateId","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"required":true,"description":"ISO date in the merchant's timezone","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"required":true,"description":"ISO date in the merchant's timezone","name":"to","in":"query"},{"schema":{"type":"integer","minimum":1},"required":false,"name":"quantity","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"Hour rates: booking length to look for"},"required":false,"description":"Hour rates: booking length to look for","name":"hours","in":"query"}],"responses":{"200":{"description":"Availability by date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/closures":{"post":{"operationId":"createClosureExact","tags":["Catalog"],"summary":"Close a unit or a whole resource for a period","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosureRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quotes":{"post":{"operationId":"createQuote","tags":["Booking"],"summary":"Price, policy and availability for a request. Stores nothing.","description":"Fails with the same errors a hold would (e.g. insufficient_inventory with nearestAvailable dates), so it doubles as an availability check.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/holds":{"post":{"operationId":"createHold","tags":["Booking"],"summary":"Hold units or seats while the customer pays","description":"Reserves the units for the merchant's hold time (15 minutes by default). Pay `dueNow` within that time to confirm. Requires an Idempotency-Key header: retrying with the same key returns the same hold, never a second one.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Unique per checkout attempt, e.g. a UUID"},"required":true,"description":"Unique per checkout attempt, e.g. a UUID","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldRequest"}}}},"responses":{"201":{"description":"The hold","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}":{"get":{"operationId":"getBooking","tags":["Booking"],"summary":"Get a booking","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateBooking","tags":["Booking"],"summary":"Set or remove a booking's metadata","description":"For plugins and integrations: keep your own data on the booking, e.g. an invoice number. Keys are merged; an empty string removes one.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingUpdate"}}}},"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/cancellation":{"get":{"operationId":"previewCancellation","tags":["Booking"],"summary":"What cancelling now would cost and refund","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Cancellation terms right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cancellation"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/cancel":{"post":{"operationId":"cancelBooking","tags":["Booking"],"summary":"Cancel a booking; refunds per its cancellation policy","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"}}}},"responses":{"200":{"description":"What was kept and refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cancellation"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/move":{"post":{"operationId":"moveBooking","tags":["Booking"],"summary":"Move a booking to another unit of the same resource","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveRequest"}}}},"responses":{"200":{"description":"The moved booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/payments":{"post":{"operationId":"recordPayment","tags":["Payments"],"summary":"Record a payment received for a booking","description":"For payments taken outside a built-in provider (bank transfer, cash, your own gateway). Confirms a hold once dueNow is paid. Recording the same provider + providerRef twice is a no-op.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"The booking after the payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/terminate":{"post":{"operationId":"terminateContract","tags":["Booking"],"summary":"End a term contract early","description":"Charges the notice period and the early-termination fee, cancels later instalments, and frees the unit after the notice period.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Termination result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Termination"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings":{"get":{"operationId":"listBookings","tags":["Front desk"],"summary":"List and search bookings","description":"Newest first, or `view=arrivals|departures` for a day (in arrival/departure order) or `view=in_house` for everyone checked in. Contains guests' personal data, so it needs the bookings:list scope.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["arrivals","departures","in_house"],"description":"Arrivals or departures on `date`, or everyone checked in"},"required":false,"description":"Arrivals or departures on `date`, or everyone checked in","name":"view","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"Defaults to today in the merchant's timezone"},"required":false,"description":"Defaults to today in the merchant's timezone","name":"date","in":"query"},{"schema":{"type":"string","example":"CONFIRMED,CHECKED_IN","description":"Comma-separated statuses"},"required":false,"description":"Comma-separated statuses","name":"status","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Guest name, email or phone, or a booking reference"},"required":false,"description":"Guest name, email or phone, or a booking reference","name":"q","in":"query"},{"schema":{"type":"string","maxLength":560,"pattern":"^[^:]{1,40}:.{1,500}$","example":"invoice:INV-204","description":"Only bookings whose metadata has this key:value"},"required":false,"description":"Only bookings whose metadata has this key:value","name":"metadata","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"Bookings overlapping from this local date (inclusive)"},"required":false,"description":"Bookings overlapping from this local date (inclusive)","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"...to this local date (exclusive)"},"required":false,"description":"...to this local date (exclusive)","name":"to","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of bookings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingList"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calendar":{"get":{"operationId":"getCalendar","tags":["Front desk"],"summary":"Every unit and what occupies it over a range of days, for a calendar view","description":"One call for a whole view, no paging: listings with their units, the bookings occupying them (with exact start and end), and closures. Works for nightly, hourly and monthly businesses alike. Shows guests' names, so it needs the bookings:list scope.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"First day shown (local date, inclusive)"},"required":true,"description":"First day shown (local date, inclusive)","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"Day after the last one shown (exclusive). At most 62 days after from"},"required":true,"description":"Day after the last one shown (exclusive). At most 62 days after from","name":"to","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only this listing"},"required":false,"description":"Only this listing","name":"resourceId","in":"query"}],"responses":{"200":{"description":"The calendar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/check-in":{"post":{"operationId":"checkIn","tags":["Front desk"],"summary":"Check a guest in","description":"From the arrival day. The booking must be confirmed (paid as required).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/check-out":{"post":{"operationId":"checkOut","tags":["Front desk"],"summary":"Check a guest out","description":"Early departures free the room from now; nothing is refunded.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/no-show":{"post":{"operationId":"markNoShow","tags":["Front desk"],"summary":"Mark a booking as a no-show","description":"From the arrival day. Frees the room; nothing is refunded.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/desk-payments":{"post":{"operationId":"recordDeskPayment","tags":["Front desk"],"summary":"Record money taken at the desk","description":"Cash, bank transfer or card terminal. Can't exceed the balance due. Confirms a held booking once its amount due is paid.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeskPaymentRequest"}}}},"responses":{"200":{"description":"The booking after the payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-providers/paystack":{"put":{"operationId":"connectPaystack","tags":["Payments"],"summary":"Connect the merchant's Paystack account","description":"Stores the Paystack secret key encrypted. Then set the webhook URL in the Paystack dashboard to `https://<your-api-host>/webhooks/paystack/<merchantId>` (merchantId from GET /v1/merchant).","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProviderRequest"}}}},"responses":{"200":{"description":"Connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-providers/stripe":{"put":{"operationId":"connectStripe","tags":["Payments"],"summary":"Connect the business's Stripe account","description":"In Stripe: Developers → Webhooks → add an endpoint at `https://<your-api-host>/webhooks/stripe/<merchantId>` (shown by GET /v1/payment-providers) for the events checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed and checkout.session.expired. Then send the secret key and that endpoint's signing secret here. Both are stored encrypted and never returned.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeProviderRequest"}}}},"responses":{"200":{"description":"Connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/checkout":{"post":{"operationId":"startCheckout","tags":["Payments"],"summary":"Start paying for a hold online","description":"Creates a checkout with the provider (cardProvider from GET /v1/payment-methods) for the hold's amount due now, and returns the payment page URL. After paying, the provider sends the guest to callbackUrl with ?reference=… (Stripe adds provider=stripe); call POST /v1/checkouts/verify with both. The provider's webhook confirms the booking too, whichever arrives first.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"201":{"description":"Checkout started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The payment provider failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/checkouts/verify":{"post":{"operationId":"verifyCheckout","tags":["Payments"],"summary":"Check a payment with the provider and confirm the booking","description":"Call when the guest returns from the payment page. Safe to call repeatedly; it never charges anything.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutVerifyRequest"}}}},"responses":{"200":{"description":"Payment and booking status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutStatus"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The payment provider failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/paystack/{merchantId}":{"post":{"operationId":"paystackWebhook","security":[],"tags":["Webhooks"],"summary":"Paystack webhook endpoint","description":"Verified with the x-paystack-signature header and the merchant's Paystack secret key. No API key.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"merchantId","in":"path"}],"responses":{"200":{"description":"Received","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","enum":[true]},"handled":{"type":"boolean"}},"required":["received","handled"]}}}},"401":{"description":"Bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Paystack isn't set up for this merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/stripe/{merchantId}":{"post":{"operationId":"stripeWebhook","security":[],"tags":["Webhooks"],"summary":"Stripe webhook endpoint","description":"Verified with the Stripe-Signature header and the business's webhook signing secret. No API key.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"merchantId","in":"path"}],"responses":{"200":{"description":"Received","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean","enum":[true]},"handled":{"type":"boolean"}},"required":["received","handled"]}}}},"401":{"description":"Bad signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stripe isn't set up for this business","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notification-settings":{"get":{"operationId":"getEmailSettings","tags":["Emails"],"summary":"Email settings","security":[{"apiKey":[]}],"responses":{"200":{"description":"Settings, or null if never saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setEmailSettings","tags":["Emails"],"summary":"Save email settings","description":"Confirmations, receipts and cancellation notices go to guests; staffEmail gets an alert for each online booking.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettingsRequest"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationSettings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notification-settings/test":{"post":{"operationId":"sendTestEmail","tags":["Emails"],"summary":"Send a test email now","description":"Checks the sending domain and provider. Uses the saved settings.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEmailRequest"}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The email provider refused it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notifications":{"get":{"operationId":"listEmails","tags":["Emails"],"summary":"Recent emails and whether they were sent","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"bookingId","in":"query"}],"responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notifications/{id}/retry":{"post":{"operationId":"retryEmail","tags":["Emails"],"summary":"Send a failed email again","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Queued"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog":{"get":{"operationId":"getCatalog","tags":["Catalog admin"],"summary":"Everything the business sells, including switched-off items, for editing","security":[{"apiKey":[]}],"responses":{"200":{"description":"The catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminCatalog"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/resources":{"post":{"operationId":"createListing","tags":["Catalog admin"],"summary":"Add a listing (resource), optionally with its units","description":"Add at least one rate before it can be booked.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/resources/{resourceId}":{"patch":{"operationId":"updateListing","tags":["Catalog admin"],"summary":"Change a listing; active: false stops new bookings","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"resourceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/resources/{resourceId}/units":{"post":{"operationId":"addUnit","tags":["Catalog admin"],"summary":"Add a unit (one bookable room, desk, office…)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"resourceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitCreate"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/units/{unitId}":{"patch":{"operationId":"updateUnit","tags":["Catalog admin"],"summary":"Rename, reorder or switch a unit on or off","description":"A room with upcoming bookings can't be switched off; move them first.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"unitId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteUnit","tags":["Catalog admin"],"summary":"Delete a unit that was never booked","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"unitId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/resources/{resourceId}/rates":{"post":{"operationId":"createRate","tags":["Catalog admin"],"summary":"Add a rate: a price per night, hour, block or day","description":"The first rate becomes the default. Without paymentOptions, guests pay in full.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"resourceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateCreate"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/rates/{rateId}":{"patch":{"operationId":"updateRate","tags":["Catalog admin"],"summary":"Change a rate: price, ways to pay, default, on or off","description":"Existing bookings keep the price they were made at. paymentOptions and blocks replace the current ones.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"rateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminResource"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/rates/{rateId}/rules":{"post":{"operationId":"createPriceRule","tags":["Catalog admin"],"summary":"Add a price rule: weekend, season, long stay, early bird, extra guest…","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"rateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceRuleInput"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceRule"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/rules/{id}":{"patch":{"operationId":"updatePriceRule","tags":["Catalog admin"],"summary":"Change or switch off a price rule","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"condition":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["DAY_OF_WEEK"]},"weekdays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"minItems":1,"description":"0 = Sunday"}},"required":["kind","weekdays"]},{"type":"object","properties":{"kind":{"type":"string","enum":["DATE_RANGE"]},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-12-08","description":"ISO date in the merchant's timezone"}},"required":["kind","from","to"]},{"type":"object","properties":{"kind":{"type":"string","enum":["TIME_OF_DAY"]},"startMinute":{"type":"integer","minimum":0,"maximum":1440},"endMinute":{"type":"integer","minimum":0,"maximum":1440}},"required":["kind","startMinute","endMinute"]},{"type":"object","properties":{"kind":{"type":"string","enum":["LENGTH_OF_STAY"]},"minUnits":{"type":"integer","minimum":1},"maxUnits":{"type":["integer","null"],"minimum":1}},"required":["kind","minUnits"]},{"type":"object","properties":{"kind":{"type":"string","enum":["LEAD_TIME"]},"minHours":{"type":["number","null"]},"maxHours":{"type":["number","null"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["EXTRA_GUEST"]},"baseGuests":{"type":"integer","minimum":0}},"required":["kind","baseGuests"]}]},"adjustment":{"type":"object","properties":{"type":{"type":"string","enum":["PERCENT","FIXED"]},"value":{"type":"integer","description":"PERCENT in basis points (2000 = +20%, -1000 = 10% off); FIXED in minor units per night/hour/day, or per extra guest"}},"required":["type","value"]},"priority":{"type":"integer"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceRule"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePriceRule","tags":["Catalog admin"],"summary":"Delete a price rule","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/rates/{rateId}/fees":{"post":{"operationId":"createFee","tags":["Catalog admin"],"summary":"Add a fee charged with every booking on this rate (e.g. cleaning)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"rateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeInput"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fee"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/fees/{id}":{"delete":{"operationId":"deleteFee","tags":["Catalog admin"],"summary":"Remove a fee","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/add-ons":{"post":{"operationId":"createAddOn","tags":["Catalog admin"],"summary":"Create an add-on guests can choose (e.g. breakfast, airport pickup)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOn"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/add-ons/{id}":{"patch":{"operationId":"updateAddOn","tags":["Catalog admin"],"summary":"Change or switch off an add-on","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":0,"example":4000000,"description":"Amount in minor units (kobo, cents)"},"basis":{"type":"string","enum":["PER_BOOKING","PER_UNIT","PER_GUEST"]},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOn"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/rates/{rateId}/add-ons":{"put":{"operationId":"setRateAddOns","tags":["Catalog admin"],"summary":"Choose which add-ons a rate offers, and which are required","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"rateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateAddOnsRequest"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"addOnId":{"type":"string"},"name":{"type":"string"},"amount":{"type":"integer"},"basis":{"type":"string"},"required":{"type":"boolean"}},"required":["addOnId","name","amount","basis","required"]}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/courses":{"get":{"operationId":"listCourses","tags":["Catalog admin"],"summary":"Courses and events, upcoming first, with seats sold","security":[{"apiKey":[]}],"responses":{"200":{"description":"Courses","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Course"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCourse","tags":["Catalog admin"],"summary":"Set up a course or event, with dates in local time","description":"If it uses a room, the room is closed to other bookings on those dates; refused if the room is booked then.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/courses/{id}":{"patch":{"operationId":"updateCourse","tags":["Catalog admin"],"summary":"Change name, seats, price for new bookings, host, or stop selling","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/media/{id}":{"get":{"operationId":"getPhoto","tags":["Media"],"summary":"A photo, by the id in a listing's or course's images. Public; cache it forever (it never changes)","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The photo","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/resources/{resourceId}/images":{"post":{"operationId":"addListingPhoto","tags":["Catalog admin"],"summary":"Add a photo to a listing (added last; the first photo is the main one)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"resourceId","in":"path"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"A JPEG, PNG or WebP photo, up to 8 MB"},"alt":{"type":"string","maxLength":300,"description":"What the photo shows, for screen readers and search"}}}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageView"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/courses/{id}/images":{"post":{"operationId":"addCoursePhoto","tags":["Catalog admin"],"summary":"Add a photo to a course","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"A JPEG, PNG or WebP photo, up to 8 MB"},"alt":{"type":"string","maxLength":300,"description":"What the photo shows, for screen readers and search"}}}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageView"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/images/{id}":{"patch":{"operationId":"updatePhoto","tags":["Catalog admin"],"summary":"Change a photo's description","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alt":{"type":"string","maxLength":300}},"required":["alt"]}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageView"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePhoto","tags":["Catalog admin"],"summary":"Delete a photo","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/images/{id}/move":{"post":{"operationId":"movePhoto","tags":["Catalog admin"],"summary":"Move a photo one place earlier or later","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down"]}},"required":["direction"]}}}},"responses":{"204":{"description":"Moved"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/courses/{id}/dates":{"post":{"operationId":"addCourseDates","tags":["Catalog admin"],"summary":"Add dates to a course with no seats sold (e.g. one listed with dates to be announced)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourseDatesRequest"}}}},"responses":{"200":{"description":"Dates added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/courses/{id}/dates/{dateId}":{"delete":{"operationId":"removeCourseDate","tags":["Catalog admin"],"summary":"Remove a date from a course with no seats sold","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"dateId","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-methods":{"get":{"operationId":"getPaymentMethods","tags":["Payments"],"summary":"How guests can pay right now: card online, bank transfer (with the bank details), or neither","description":"Pay on arrival is a rate payment option (see each rate's paymentOptions).","security":[{"apiKey":[]}],"responses":{"200":{"description":"Payment methods","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethods"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-settings":{"get":{"operationId":"getPaymentSettings","tags":["Payments"],"summary":"Payment settings: card (Paystack) on or paused, and bank transfer","security":[{"apiKey":[]}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSettings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-settings/card":{"put":{"operationId":"setCardPayments","tags":["Payments"],"summary":"Pause or resume card payments. Keys are kept; refunds and payments under way still complete","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSettingRequest"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSettings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-settings/bank-transfer":{"put":{"operationId":"setBankTransfer","tags":["Payments"],"summary":"Accept bank transfers: account details and how long bookings are held","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankTransferRequest"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSettings"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates":{"get":{"operationId":"listTemplates","security":[],"tags":["Sign-up"],"summary":"Templates: the words and listing defaults for kinds of business (stays, workspace, consulting, classes, salon)","description":"Public. A template is a starting point, not a business type: any business can sell listings of any kind (docs/platform.md §14).","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}},"required":["data"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup/check":{"post":{"operationId":"checkInvite","security":[],"tags":["Sign-up"],"summary":"Check an invite before showing the sign-up form","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCheckRequest"}}}},"responses":{"200":{"description":"Valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invite"}}}},"404":{"description":"Expired, used or unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup/test":{"post":{"operationId":"signUpForTesting","security":[],"tags":["Sign-up"],"summary":"Create a test business and get test keys straight away","description":"For builders. The business is in test mode: it can't take real money (live payment keys are refused), sends no emails, and its booking page says it's a test. When ready, the owner asks to go live (POST /v1/business/go-live). Returns a dashboard session and test API keys (shown once).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSignUpRequest"}}}},"responses":{"201":{"description":"Created and signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestSignUp"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup":{"post":{"operationId":"signUp","security":[],"tags":["Sign-up"],"summary":"Create a business with an invite; returns a dashboard session","description":"New people choose a password; people who already have an account enter theirs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignUpRequest"}}}},"responses":{"201":{"description":"Created and signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignUp"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business":{"get":{"operationId":"getBusiness","tags":["Business"],"summary":"Business details and settings","security":[{"apiKey":[]}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateBusiness","tags":["Business"],"summary":"Change business details (the currency is fixed once there are bookings)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUpdate"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business/setup":{"get":{"operationId":"getSetupStatus","tags":["Business"],"summary":"What's left to set up before taking bookings","security":[{"apiKey":[]}],"responses":{"200":{"description":"Checklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupChecklist"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-providers":{"get":{"operationId":"listPaymentProviders","tags":["Payments"],"summary":"Connected payment providers, and the webhook address to give them","security":[{"apiKey":[]}],"responses":{"200":{"description":"Providers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"publicKey":{"type":["string","null"]},"livemode":{"type":"boolean"},"connectedAt":{"type":"string"}},"required":["provider","publicKey","livemode","connectedAt"]}},"webhookUrl":{"type":["string","null"],"description":"Paystack's: paste into Paystack → Settings → API Keys & Webhooks"},"webhookUrls":{"type":"object","properties":{"paystack":{"type":"string"},"stripe":{"type":"string"}},"required":["paystack","stripe"],"description":"Where each provider should send webhooks. Stripe: Developers → Webhooks → Add endpoint"}},"required":["data","webhookUrl","webhookUrls"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api-keys":{"get":{"operationId":"listApiKeys","tags":["Business"],"summary":"API keys (never the secret part)","security":[{"apiKey":[]}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createApiKey","tags":["Business"],"summary":"Create an API key; the key is shown once","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"}},"required":["id","key"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","tags":["Business"],"summary":"Revoke an API key; it stops working immediately","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Revoked"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/cancellation-terms":{"get":{"operationId":"listCancellationTerms","tags":["Catalog admin"],"summary":"Cancellation terms and the rates that use them","security":[{"apiKey":[]}],"responses":{"200":{"description":"Terms","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CancellationTerms"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCancellationTerms","tags":["Catalog admin"],"summary":"Add cancellation terms","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationTermsInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationTerms"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/cancellation-terms/{id}":{"patch":{"operationId":"updateCancellationTerms","tags":["Catalog admin"],"summary":"Change cancellation terms (new bookings only; existing bookings keep theirs)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"refundFees":{"type":"boolean"},"refundAddOns":{"type":"boolean"},"tiers":{"type":"array","items":{"type":"object","properties":{"deadline":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["hours"]},"hoursBefore":{"type":"integer","minimum":0,"maximum":8760}},"required":["kind","hoursBefore"]},{"type":"object","properties":{"kind":{"type":"string","enum":["day_time"]},"daysBefore":{"type":"integer","minimum":0,"maximum":365},"minuteOfDay":{"type":"integer","minimum":0,"maximum":1439}},"required":["kind","daysBefore","minuteOfDay"]}]},"penalty":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["NONE"]}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["PERCENT"]},"bps":{"type":"integer","minimum":1,"maximum":10000}},"required":["kind","bps"]},{"type":"object","properties":{"kind":{"type":"string","enum":["FIXED"]},"amount":{"type":"integer","minimum":1,"example":4000000,"description":"Amount in minor units (kobo, cents)"}},"required":["kind","amount"]},{"type":"object","properties":{"kind":{"type":"string","enum":["UNITS"]},"count":{"type":"integer","minimum":1,"maximum":365}},"required":["kind","count"]}]}},"required":["deadline","penalty"]},"maxItems":6,"description":"From each deadline on, cancelling costs the penalty. Before the first deadline it's free."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationTerms"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCancellationTerms","tags":["Catalog admin"],"summary":"Delete cancellation terms no rate uses","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/hours":{"get":{"operationId":"getHours","tags":["Catalog admin"],"summary":"Opening hours and upcoming special days","description":"Hours govern hourly, block and day bookings. Nightly stays ignore them.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hours"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setWeeklyHours","tags":["Catalog admin"],"summary":"Replace weekly hours for the business or one listing","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeeklyHoursRequest"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hours"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/special-days":{"post":{"operationId":"addSpecialDay","tags":["Catalog admin"],"summary":"Different hours, or closed, on one date","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpecialDayRequest"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hours"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/special-days/{id}":{"delete":{"operationId":"removeSpecialDay","tags":["Catalog admin"],"summary":"Remove a special day","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hours"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/closures":{"get":{"operationId":"listClosures","tags":["Catalog admin"],"summary":"Units and listings closed now or later","security":[{"apiKey":[]}],"responses":{"200":{"description":"Closures","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClosureView"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createClosure","tags":["Catalog admin"],"summary":"Close a unit or listing between two local times (e.g. maintenance)","description":"Refused with unit_has_bookings if bookings overlap.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalClosureRequest"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClosureView"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/closures/{id}":{"delete":{"operationId":"deleteClosure","tags":["Catalog admin"],"summary":"Reopen: remove a closure","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClosureView"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bookings/{id}/timeline":{"get":{"operationId":"getBookingTimeline","tags":["Booking"],"summary":"Everything that happened to a booking: status changes, payments, moves and edits, with who and when","description":"Built from the change log, which the database writes with every change and never edits. Shows staff names, so it needs the bookings:list scope.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Oldest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingTimeline"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/activity":{"get":{"operationId":"listActivity","tags":["Business"],"summary":"Who changed what: every successful change made through the API, newest first","description":"Append-only. For owners (settings:write).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{1,19}$"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":80,"description":"Only this actor, e.g. staff:<userId> or key:<keyId>"},"required":false,"description":"Only this actor, e.g. staff:<userId> or key:<keyId>","name":"actor","in":"query"},{"schema":{"type":"string","maxLength":64,"description":"Only changes to this id (a booking, rate, listing...)"},"required":false,"description":"Only changes to this id (a booking, rate, listing...)","name":"target","in":"query"}],"responses":{"200":{"description":"A page of activity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/merchants":{"get":{"operationId":"listPlatformMerchants","tags":["Platform"],"summary":"Every business on this server, newest first","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":200,"description":"Name, web address or an owner's email"},"required":false,"description":"Name, web address or an owner's email","name":"q","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Businesses","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformMerchant"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/invites":{"post":{"operationId":"createMerchantInvite","tags":["Platform"],"summary":"Invite someone to create a live business; returns a one-time sign-up token (valid 14 days)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantInviteRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantInvite"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/merchants/{id}/suspension":{"put":{"operationId":"setMerchantSuspension","tags":["Platform"],"summary":"Suspend a business (its keys, staff access and booking page stop working) or restore it","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuspensionRequest"}}}},"responses":{"204":{"description":"Done"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/merchants/{id}/sender-domain":{"put":{"operationId":"setMerchantSenderDomain","tags":["Platform"],"summary":"Let a business send booking emails from its own domain (verify it with the email provider first), or remove it","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderDomainRequest"}}}},"responses":{"204":{"description":"Done"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feedback":{"post":{"operationId":"sendFeedback","tags":["Staff"],"summary":"Report a bug, suggest a feature or ask a question (emailed to the RatesSpot team)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/feedback":{"get":{"operationId":"listFeedback","tags":["Platform"],"summary":"Feedback, newest first","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"open","in":"query"}],"responses":{"200":{"description":"Feedback","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Feedback"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/feedback/{id}/resolved":{"put":{"operationId":"setFeedbackResolved","tags":["Platform"],"summary":"Mark feedback as dealt with, or open it again","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResolution"}}}},"responses":{"204":{"description":"Done"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business/go-live":{"get":{"operationId":"getGoLiveRequest","tags":["Business"],"summary":"The test business's latest request to go live, if any","security":[{"apiKey":[]}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"type":"object","properties":{"request":{"anyOf":[{"$ref":"#/components/schemas/GoLiveRequest"},{"type":"null"}]}},"required":["request"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestGoLive","tags":["Business"],"summary":"Ask to take real bookings: a RatesSpot admin reviews it, and approval creates your live business","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoLiveRequestInput"}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoLiveRequest"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/go-live-requests":{"get":{"operationId":"listGoLiveRequests","tags":["Platform"],"summary":"Requests to go live, newest first","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"pending","in":"query"}],"responses":{"200":{"description":"Requests","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GoLiveRequest"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/go-live-requests/{id}/decision":{"post":{"operationId":"decideGoLiveRequest","tags":["Platform"],"summary":"Approve (creates the live business, same owner) or decline with a reason","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoLiveDecision"}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoLiveRequest"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/oauth/authorization":{"get":{"operationId":"describeOAuthAuthorization","tags":["Apps"],"summary":"What an app is asking for, for the consent screen","description":"Dashboard only (a signed-in person's session).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"client_id","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2000},"required":true,"name":"redirect_uri","in":"query"},{"schema":{"type":"string","maxLength":1000},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","minLength":43,"maxLength":128},"required":true,"name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256"]},"required":true,"name":"code_challenge_method","in":"query"}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthConsent"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"approveOAuthAuthorization","tags":["Apps"],"summary":"Approve an app for the business in X-Merchant-Id; returns where to send the browser","description":"Dashboard only. The app gets no more than the person's role allows at that business.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthApproval"}}}},"responses":{"200":{"description":"Approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthRedirect"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apps":{"get":{"operationId":"listInstalledApps","tags":["Apps"],"summary":"Apps installed on this business","security":[{"apiKey":[]}],"responses":{"200":{"description":"Apps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InstalledApp"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apps/{clientId}":{"delete":{"operationId":"uninstallApp","tags":["Apps"],"summary":"Uninstall an app: its tokens stop working at once","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"clientId","in":"path"}],"responses":{"204":{"description":"Uninstalled"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/apps":{"get":{"operationId":"listDeveloperApps","tags":["Apps"],"summary":"Apps you've registered","security":[{"apiKey":[]}],"responses":{"200":{"description":"Apps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperApp"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"registerDeveloperApp","tags":["Apps"],"summary":"Register an app other businesses can install; the client secret is shown once","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperAppCreate"}}}},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DeveloperApp"},{"type":"object","properties":{"secret":{"type":["string","null"],"description":"Shown once; null for public apps"}},"required":["secret"]}]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/apps/{id}":{"delete":{"operationId":"deleteDeveloperApp","tags":["Apps"],"summary":"Delete an app you registered; every business loses it","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"summary":"Webhook endpoints","security":[{"apiKey":[]}],"responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Add a webhook endpoint; the signing secret is shown once","description":"RatesSpot POSTs each event as JSON with a `RatesSpot-Signature: t=<unix>,v1=<hex>` header: HMAC-SHA256 of `t.body` with the secret. Reply 2xx quickly. Delivery is at least once (skip an event id you've seen), not in order, and retried for about 3 days, after which the endpoint is switched off.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"type":"object","properties":{"secret":{"type":"string","example":"whsec_…","description":"Shown only now"}},"required":["secret"]}]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}":{"patch":{"operationId":"updateWebhookEndpoint","tags":["Webhooks"],"summary":"Change an endpoint, or switch it back on","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointUpdate"}}}},"responses":{"200":{"description":"The endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"summary":"Remove an endpoint","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}/test":{"post":{"operationId":"testWebhookEndpoint","tags":["Webhooks"],"summary":"Send a webhook.test event now and see what the endpoint answers","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"What happened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResult"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"Recent deliveries to an endpoint, newest first","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["data"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-deliveries/{id}/retry":{"post":{"operationId":"retryWebhookDelivery","tags":["Webhooks"],"summary":"Send an undelivered event again now","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Queued"},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"get":{"operationId":"listEvents","tags":["Webhooks"],"summary":"Events from the last 30 days, newest first","description":"The same envelopes webhooks send, so a plugin that was down can catch up.","security":[{"apiKey":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/EventType"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events/{id}":{"get":{"operationId":"getEvent","tags":["Webhooks"],"summary":"One event","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/brand":{"get":{"operationId":"getBrand","tags":["Brand"],"summary":"How the business looks on booking pages and emails","security":[{"apiKey":[]}],"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateBrand","tags":["Brand"],"summary":"Change colours, font pairing, about text, contact details or booking terms","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandUpdate"}}}},"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/brand/images/{slot}":{"post":{"operationId":"setBrandImage","tags":["Brand"],"summary":"Upload the logo or cover photo (replaces the current one)","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["logo","cover"]},"required":true,"name":"slot","in":"path"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG or WebP, up to 8 MB"},"alt":{"type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeBrandImage","tags":["Brand"],"summary":"Remove the logo or cover photo","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["logo","cover"]},"required":true,"name":"slot","in":"path"}],"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/brand/storefront":{"put":{"operationId":"setStorefront","tags":["Brand"],"summary":"Publish or hide the hosted booking page","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontRequest"}}}},"responses":{"200":{"description":"The brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/storefronts":{"get":{"operationId":"listStorefronts","tags":["Brand"],"summary":"The public directory: live booking pages whose businesses chose to be listed","description":"Public: no API key. Only businesses that are live, have published their booking page and opted in (listedInDirectory).","security":[],"responses":{"200":{"description":"Listed booking pages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontDirectory"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/storefronts/{slug}":{"get":{"operationId":"getStorefront","tags":["Brand"],"summary":"A published booking page: the business, its brand, and the page's publishable key","description":"Public: no API key. 404 unless the business has published its booking page.","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"The booking page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Storefront"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/manage/{bookingId}":{"get":{"operationId":"getManagedBooking","tags":["Guest"],"summary":"The guest's view of their booking, from their manage link","description":"Public: authorised by the token in the guest's link (no API key).","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"bookingId","in":"path"},{"schema":{"type":"string","minLength":20,"maxLength":100,"description":"From the guest's manage link"},"required":true,"description":"From the guest's manage link","name":"token","in":"query"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedBooking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateManagedGuest","tags":["Guest"],"summary":"The guest corrects their name or phone number","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"bookingId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedGuestUpdate"}}}},"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedBooking"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/manage/{bookingId}/cancel":{"post":{"operationId":"cancelManagedBooking","tags":["Guest"],"summary":"The guest cancels, if the business allows it; refunds follow the booking's terms","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64},"required":true,"name":"bookingId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedCancelRequest"}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedCancellation"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the scope this endpoint needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicts with current state, e.g. no units free","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Valid request the booking rules refuse, e.g. outside opening hours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}