# Introduction

Source: https://developers.weerom.com/docs

> What the WeerOm API reads and changes, the webhooks it sends, where it lives and the rules every endpoint follows.

The WeerOm API lets your software work with a shop's data. It reads the shop, its services, its staff, its free times, its customers, its bookings and its payments. It also takes bookings, cancels and moves them, and changes customers, through the shop's own booking engine. The shop's rules apply and the shop's mail goes out, as if the customer had booked on the shop's own site. When a booking or a payment changes, WeerOm can post it to your server as a webhook.

## One address for every shop

```txt
https://api.weerom.com/v1
```

Every shop uses this base URL. The key you send says which shop you work with, and a key works on that shop and no other.

## What you can read

| Endpoint | What it returns |
| --- | --- |
| `GET /shop` | The shop the key belongs to: name, country, currency, time zone, language. |
| `GET /services` | Every service, with its price and its name in five languages. |
| `GET /staff` | Everyone customers can book with. Name and whether they are active. |
| `GET /availability` | The free times for one service, for 1 to 14 days, for one staff member or everyone who does the service. |
| `GET /customers` | Customers, newest first. Look one up by `email` or `phone`. |
| `GET /bookings` | Appointments, by start time. Filter by status, staff, customer and dates. |
| `GET /payments` | Bookings a customer paid for, by the moment staff noted the payment. |

Each list except `/availability` also has a `GET /{list}/{id}` for one object.

## What you can change

| Endpoint | What it does |
| --- | --- |
| `POST /bookings` | Books a free time. The customer gets the shop's confirmation mail. |
| `POST /bookings/{id}/cancel` | Cancels a booking and frees its time. |
| `POST /bookings/{id}/reschedule` | Moves a booking to another time or another staff member. |
| `PATCH /customers/{id}` | Changes a customer's name, or blocks them from booking online. |

There is no endpoint that makes a customer. A booking makes its customer, or reuses the one the shop knows by that phone number. The [API reference](https://developers.weerom.com/docs/reference) has every field.

## What WeerOm sends you

| Event | When |
| --- | --- |
| `booking.created` | A booking is made, online, by staff or through the API. |
| `booking.updated` | A booking moves, changes service, or is marked completed or a no-show. |
| `booking.cancelled` | A booking is cancelled. |
| `payment.completed` | Staff note a payment, or correct one. |

The shop adds your address in its admin and gives you a secret. Each message is signed with it. [Webhooks](https://developers.weerom.com/docs/webhooks) covers the message, the signature and the retries.

## Rules every endpoint follows

- **Keys.** Send `Authorization: Bearer ...` with every request. A read key reads, a write key also changes, and a public key sits in a web page and books. See [Authentication](https://developers.weerom.com/docs/authentication).
- **Who acts.** A write takes `as`: `customer`, the default, keeps the shop's rules, and `staff` acts as the shop. A public key may not send it.
- **Retries.** A `POST` or `PATCH` takes an `Idempotency-Key`, so a retry after a timeout does nothing twice. See [Safe retries](https://developers.weerom.com/docs/idempotency).
- **Lists.** A list answers `{ "object": "list", "data", "has_more", "next_cursor" }`. See [Pagination](https://developers.weerom.com/docs/pagination).
- **Money.** Amounts are whole cents with VAT included, beside a `currency`. `4000` with `"EUR"` is €40.
- **Time.** Times are ISO 8601 in UTC, such as `2026-11-21T18:15:00.000Z`. The shop's own zone is `time_zone` on `GET /shop`.
- **Names.** Field names are snake_case. A field, once out, keeps its name and its meaning for all of v1.
- **Errors.** Every error answers `{ "error": { "code", "message", "request_id" } }`. See [Errors](https://developers.weerom.com/docs/errors).
- **Limits.** 120 requests a minute for each key. See [Rate limits](https://developers.weerom.com/docs/rate-limits).
- **Browsers.** The API answers `Access-Control-Allow-Origin: *`, so a page on any site can call it. Only a public key belongs in a page. A read or write key in a browser is a key anyone can read.
- **Changes.** A webhook tells your server within seconds that a booking or a payment changed. Where nobody can add an address, or a run once an hour is enough, ask for what changed with `updated_after` or `paid_after`. See [Webhooks](https://developers.weerom.com/docs/webhooks#polling-as-the-fallback).

## Who can use it

A shop on the Premium plan makes keys in its WeerOm admin. If you build for a shop, ask the owner for a key of the kind you need. If you run the shop, the [quickstart](https://developers.weerom.com/docs/quickstart) starts with making one.

## What people build

[Build a booking page](https://developers.weerom.com/docs/booking-page) is the full guide for a booking page of your own. The [use cases](https://developers.weerom.com/docs/use-cases) cover ten more, from invoices in Billit to an assistant that books.

## The spec and files for AI tools

The reference on this site is built from the OpenAPI 3.1 file of the API. Feed the same file to a client generator or to Postman: [openapi.json](https://developers.weerom.com/openapi.json).

For an AI assistant or a coding agent:

- [llms.txt](https://developers.weerom.com/llms.txt) lists every page with one line on each, in the [llmstxt.org](https://llmstxt.org) format.
- [llms-full.txt](https://developers.weerom.com/llms-full.txt) holds every guide, use case and reference page as Markdown in one file, with the fields and examples of each endpoint.
- Every page is also Markdown at its own address with `.md` added, such as [/docs/webhooks.md](https://developers.weerom.com/docs/webhooks.md). The **Copy Markdown** button at the top of a page copies it.
