# WeerOm API

> WeerOm is booking software for barbershops and salons. Its API reads one shop's services, staff, free times, customers, bookings and payments, and makes, moves and cancels bookings through the shop's own booking engine, so the shop's rules and mail apply. Webhooks tell a server when a booking or a payment changes.

Every request goes to `https://api.weerom.com/v1` and sends `Authorization: Bearer <key>`. A shop on the Premium plan makes keys in its admin. A key belongs to one shop. A read key (`wo_live_`) reads, a write key (`wo_live_`) also changes bookings and customers, and a public key (`wo_pub_`) sits in a web page and reads only the shop, services, staff and free times, and books. Answers are JSON. Money is whole cents with VAT included. Times are ISO 8601 in UTC. Each link below is the page as Markdown.

## Guides

- [Introduction](https://developers.weerom.com/docs.md): What the WeerOm API reads and changes, the webhooks it sends, where it lives and the rules every endpoint follows.
- [Quickstart](https://developers.weerom.com/docs/quickstart.md): Make a key, send your first request and read the answer.
- [Authentication](https://developers.weerom.com/docs/authentication.md): The three kinds of key, where a shop makes them, what 401 and 403 mean, and how to keep a key safe.
- [Build a booking page](https://developers.weerom.com/docs/booking-page.md): Your own booking page on any site, with WeerOm as the backend. Pick a service, show free times, make the booking and handle every answer.
- [Pagination](https://developers.weerom.com/docs/pagination.md): The list envelope, walking every page with a cursor, and syncing only what changed.
- [Webhooks](https://developers.weerom.com/docs/webhooks.md): WeerOm posts a signed JSON message to your server when a booking is made, changed or cancelled, or a payment is noted. Verify it, answer 2xx, then work.
- [Safe retries](https://developers.weerom.com/docs/idempotency.md): Send an Idempotency-Key with a POST or a PATCH, and a retry after a timeout changes nothing twice.
- [Errors](https://developers.weerom.com/docs/errors.md): The shape of every error, what each code means and what to do about it.
- [Rate limits](https://developers.weerom.com/docs/rate-limits.md): 120 requests a minute for each key, the headers that count them and how to back off.

## Use cases

- [Overview](https://developers.weerom.com/docs/use-cases.md): Ten things people build on the WeerOm API, each with the key it needs, the steps, a code sketch and what the API cannot do for it.
- [Send payments to Billit](https://developers.weerom.com/docs/use-cases/billit.md): Turn every payment a shop notes in WeerOm into an invoice in Billit, from the payment.completed webhook or by polling the payments list.
- [Bookkeeping with Accountable](https://developers.weerom.com/docs/use-cases/accountable.md): Build the same income lines the admin exports for Accountable, one per day and payment method, from the payments list.
- [Your own booking page](https://developers.weerom.com/docs/use-cases/booking-page.md): A booking page in your own design on any site, with WeerOm's agenda, rules and mail behind it.
- [Bookings in your calendar](https://developers.weerom.com/docs/use-cases/calendar.md): Copy every booking into Google Calendar or Outlook, update it when it moves and remove it when it is cancelled.
- [Customers in a mailing tool](https://developers.weerom.com/docs/use-cases/newsletter.md): Keep a Mailchimp or Brevo list in step with the shop's customers, and only mail the ones who agreed.
- [A revenue sheet](https://developers.weerom.com/docs/use-cases/revenue-sheet.md): Revenue per day, per staff member and per payment method in Google Sheets, refreshed every hour by Apps Script.
- [Automations](https://developers.weerom.com/docs/use-cases/automations.md): n8n, Make or Zapier, started by a WeerOm webhook or on a schedule, with an HTTP request to WeerOm and your own steps after it.
- [Messages by SMS or WhatsApp](https://developers.weerom.com/docs/use-cases/messages.md): Read tomorrow's bookings once a day and send each customer a reminder by SMS or WhatsApp. Webhooks cover bookings made after the daily run.
- [An assistant that books](https://developers.weerom.com/docs/use-cases/assistant.md): A chat or phone assistant that looks up free times and makes the booking, from your server with a write key.
- [Several shops on one screen](https://developers.weerom.com/docs/use-cases/several-shops.md): One key for each shop and one loop over them, for an owner with two shops or a group's dashboard.

## API reference

- [Overview](https://developers.weerom.com/docs/reference.md): Every endpoint, built from the API's OpenAPI file. Paste your key into any page to send a real request.
- [Get the shop](https://developers.weerom.com/docs/reference/shop/getShop.md): `GET /v1/shop`. The shop the key belongs to.
- [List services](https://developers.weerom.com/docs/reference/services/listServices.md): `GET /v1/services`. Every service, in the order the shop shows them.
- [Get a service](https://developers.weerom.com/docs/reference/services/getService.md): `GET /v1/services/{id}`. One service by its id.
- [List staff](https://developers.weerom.com/docs/reference/staff/listStaff.md): `GET /v1/staff`. Everyone customers can book with, in the shop's order.
- [Get a staff member](https://developers.weerom.com/docs/reference/staff/getStaffMember.md): `GET /v1/staff/{id}`. One staff member by their id.
- [List free times](https://developers.weerom.com/docs/reference/availability/listAvailability.md): `GET /v1/availability`. The times a customer can book a service, for one day or up to 14 in a row.
- [List customers](https://developers.weerom.com/docs/reference/customers/listCustomers.md): `GET /v1/customers`. Customers sorted by when the shop first saw them.
- [Get a customer](https://developers.weerom.com/docs/reference/customers/getCustomer.md): `GET /v1/customers/{id}`. One customer by their id.
- [Change a customer](https://developers.weerom.com/docs/reference/customers/updateCustomer.md): `PATCH /v1/customers/{id}`. Changes a customer's name or blocks them.
- [List bookings](https://developers.weerom.com/docs/reference/bookings/listBookings.md): `GET /v1/bookings`. Appointments sorted by start time.
- [Make a booking](https://developers.weerom.com/docs/reference/bookings/createBooking.md): `POST /v1/bookings`. Books a free time for a customer and answers with the booking.
- [Get a booking](https://developers.weerom.com/docs/reference/bookings/getBooking.md): `GET /v1/bookings/{id}`. One booking by its id.
- [Cancel a booking](https://developers.weerom.com/docs/reference/bookings/cancelBooking.md): `POST /v1/bookings/{id}/cancel`. Cancels a booking and frees its time.
- [Move a booking](https://developers.weerom.com/docs/reference/bookings/rescheduleBooking.md): `POST /v1/bookings/{id}/reschedule`. Moves a booking to another time, and to another staff member when `staff_id` is sent.
- [List payments](https://developers.weerom.com/docs/reference/payments/listPayments.md): `GET /v1/payments`. Bookings a customer paid for, sorted by when staff noted the payment.
- [Get a payment](https://developers.weerom.com/docs/reference/payments/getPayment.md): `GET /v1/payments/{id}`. One payment by its id, which is the id of the booking it settled.

## Releases

- [Changelog](https://developers.weerom.com/docs/changelog.md): What changed in the WeerOm API, newest first.

## OpenAPI

- [openapi.json](https://developers.weerom.com/openapi.json): The OpenAPI 3.1 file every reference page is built from, with an example of every object. Feed it to a client generator.

## Optional

- [llms-full.txt](https://developers.weerom.com/llms-full.txt): Every guide, use case and reference page above in one Markdown file.
