curl --fail-with-body -X POST https://maatstays.wtf/v1/sandbox/bookings \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed"
}'const res = await fetch('https://maatstays.wtf/v1/sandbox/bookings', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
listing_id: '7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24',
check_in: '2026-09-12',
check_out: '2026-09-16',
guests: 3,
status: 'confirmed',
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.booking_reference); // watch for booking.confirmed
import os
import requests
res = requests.post(
"https://maatstays.wtf/v1/sandbox/bookings",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed",
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
print(body["booking_reference"]) # watch for booking.confirmed
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
BookingReference string `json:"booking_reference"`
}
func main() {
body, _ := json.Marshal(map[string]any{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed",
})
req, _ := http.NewRequest(http.MethodPost,
"https://maatstays.wtf/v1/sandbox/bookings", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("sandbox booking failed: %d", res.StatusCode)
}
var out payload
if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
log.Fatal(err)
}
fmt.Println(out.BookingReference) // watch for booking.confirmed
}
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"property": {
"provider_id": "my-prop-9001",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"property_id": "3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
},
"inventory_kind": "unit",
"status": "confirmed",
"stay": {
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"check_in_time": "15:00",
"check_out_time": "12:00",
"guests": 3
},
"amount_paid": {
"value": "5000.00",
"currency": "EGP"
},
"instant_booking": false,
"cancellation": null,
"created_at": "2026-08-30T18:42:11.000Z",
"console_url": "https://maatstays.wtf/bookings/5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d"
}Create a booking in your sandbox
Creates a synthetic booking on one of your sandbox listings, so you can watch
the real booking.* webhooks arrive at your endpoint before you go live.
The booking is made the way a real one is: the same availability check, the same price quote, the same booking record and therefore the same events, delivered to your endpoint in the same envelope with the same signature. It is not a rehearsal of a booking — it is a booking, on inventory that only exists in your sandbox.
Why you need it. A sandbox listing is never sold: nothing in a sandbox reaches
a payment provider, so no guest can ever check out on one. Without this operation
GET /v1/bookings would answer an empty page forever, confirm and reject
would have nothing to act on, and the booking webhooks — the larger half of what
you build against — could not be seen at all until real money was involved.
Pick which half of the lifecycle you want. status: "pending" mints a booking
waiting on a host decision and sends booking.requested; you then drive it with
POST /v1/bookings/{booking_reference}/confirm or /reject and watch the next
event. status: "confirmed" mints one already confirmed and sends
booking.confirmed straight away.
What it never does. There is no guest field, and there will not be one: the guest is synthetic, minted by us, and the same one every time for your workspace. No money moves and no payment provider is contacted. Nobody is emailed or notified. The amount on the booking comes from your listing’s own price for those dates, so the figures have the shape a real booking’s do.
It holds real nights on your sandbox calendar, exactly as a real booking
would, so a second call over the same dates is refused with 409 conflict,
and conflicts names every night that is closed — the same member, in the
same shape, that PUT /v1/blocks/{external_uid} answers a collision with.
Move the window, or free the nights from the Maat console. A stay may cover at
most 30 nights.
Two codes share 409 here. Branch on code, never on the status.
conflict is retryable with a different window; sandbox_only — the listing
is the one in your LIVE workspace, and the fixture only ever creates bookings
on sandbox inventory — never is. 409 inventory_not_supported for an
experience or a service: this creates stays only.
404 listing_not_found for everything else: an id that names nothing, and an
id that names a listing outside your own live/sandbox pair. Those are one
answer on purpose, so the status here cannot be used to find out whether an
id names another workspace’s inventory.
Live in a sandbox workspace. Returns 501 against a production one, after
full authentication and validation, and nothing is created.
One more thing has to be true before a delivery leaves the platform: an operator enables the outbound delivery job. See Webhooks for how to tell whether it is on.
curl --fail-with-body -X POST https://maatstays.wtf/v1/sandbox/bookings \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed"
}'const res = await fetch('https://maatstays.wtf/v1/sandbox/bookings', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
listing_id: '7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24',
check_in: '2026-09-12',
check_out: '2026-09-16',
guests: 3,
status: 'confirmed',
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
console.log(body.booking_reference); // watch for booking.confirmed
import os
import requests
res = requests.post(
"https://maatstays.wtf/v1/sandbox/bookings",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
json={
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed",
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
print(body["booking_reference"]) # watch for booking.confirmed
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type payload struct {
BookingReference string `json:"booking_reference"`
}
func main() {
body, _ := json.Marshal(map[string]any{
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"guests": 3,
"status": "confirmed",
})
req, _ := http.NewRequest(http.MethodPost,
"https://maatstays.wtf/v1/sandbox/bookings", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode >= 400 {
log.Fatalf("sandbox booking failed: %d", res.StatusCode)
}
var out payload
if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
log.Fatal(err)
}
fmt.Println(out.BookingReference) // watch for booking.confirmed
}
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"property": {
"provider_id": "my-prop-9001",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"unit_id": "8e4b2a17-5c39-4d61-b0f2-7a9c3e51d804",
"property_id": "3c9d1f42-7b60-4a18-9e55-0d2a6f8c31b7"
},
"inventory_kind": "unit",
"status": "confirmed",
"stay": {
"check_in": "2026-09-12",
"check_out": "2026-09-16",
"check_in_time": "15:00",
"check_out_time": "12:00",
"guests": 3
},
"amount_paid": {
"value": "5000.00",
"currency": "EGP"
},
"instant_booking": false,
"cancellation": null,
"created_at": "2026-08-30T18:42:11.000Z",
"console_url": "https://maatstays.wtf/bookings/5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d"
}Authorizations
A short-lived partner token, obtained by exchanging your API key at
POST /token. Send it as Authorization: Bearer <access_token>.
Tokens live for fifteen minutes by default and never for more than an hour. Mint one per batch of work, not one per request.
The token carries the workspace and the environment its key was issued for. You cannot change either by asking: the exchange ignores everything in the request body for exactly that reason.
It also carries the key's scopes (scope, a list). Every operation names a
scope as x-maat-scope, and a token whose key lacks it is refused with
403 insufficient_scope, naming the scope. Scopes are fixed when a key is
issued and are re-read from the key on every request, so a key narrowed today is
narrowed on its next call — the token's scope is what the key held at exchange
time, for your own reading, never what authorizes a request.
x-maat-scope is the floor, and on the quick-action operations it is not the
whole requirement. PUT and DELETE /listings/{listing_id}/quick-actions/{template_key}
carry rules:write, and additionally require pricing:write when
template_key begins pricing. — the capability depends on the template in
the path, because a cleaning fee changes what a guest pays and a minimum stay
does not. The refusal is the same 403 insufficient_scope, naming
pricing:write. The two READS apply the same requirement without erroring:
GET /listings/{listing_id}/quick-actions still lists the pricing.* rows but
withholds their applied state, and GET /listings/{listing_id}/rules omits the
pricing rules entirely and reports pricing_withheld in warnings. These four
are the only operations in this document whose requirement is not exactly their
x-maat-scope, and each of them says so machine-readably:
x-maat-scope-additional lists the second scope it can require and
x-maat-scope-additional-when says what happens without it.
Never send it as a cookie or in a query string, and never store it — store the API key, mint tokens from it.
Body
What to mint. There is no guest field, no amount and no currency, and none of them is coming: the guest is synthetic and minted by us, and the amount comes from your listing's own price for those dates — which is what makes the figures on the resulting webhook the shape a real booking's are.
The listing to book. Must be in a sandbox workspace, and must be a stay — an experience or a service is a 409 inventory_not_supported.
First night of the stay.
Departure day, EXCLUSIVE — the guest is gone by then. At most 30 nights after check_in, because the booking holds those nights on a real sandbox calendar.
The party SIZE. Never a per-guest anything.
1 <= x <= 50Which half of the lifecycle to watch. See SandboxBookingStatus.
pending, confirmed Response
The booking, in exactly the shape GET /v1/bookings/{booking_reference}
reads it back. Its events are already on their way.
One booking, as your workspace reads it.
There is NO guest identity here, anywhere: no name, no initial, no email, no
phone, no reference you could join against another read. Every field is a fact
about a STAY, not a fact about a person. console_url is the honest pointer to
where a person IS seen — the host console, where an authenticated human sees who
is arriving. That is deliberately slower than a field on this wire, and it is the
point.
There is no cancellation over this API. Cancelling a confirmed stay creates refunds and penalties and belongs to a person in the app.
Maat's own booking id, and the correlation key for every later event. Treat it as OPAQUE: store it and echo it back, but do not parse it or derive anything from its shape. It is a UUID today and the contract does not promise it always will be.
Which of your inventory was booked. One object rather than four ids at the root, so that the same accessor reads a booking, a booking event and a publication event.
Show child attributes
Show child attributes
What was sold. This contract manages unit stays; a write against the other two is refused with inventory_not_supported.
See InventoryKind.
unit, service, experience A closed vocabulary, not the platform's internal state. pending is the
only state confirm and reject act on.
See BookingStatus.
pending, confirmed, checked_in, completed, cancelled, rejected The stay itself — when, and how many people. Never who.
The two door times are the UNIT's own, for a booking whose
inventory_kind is unit. A service or an experience hangs off no
unit and has no door: those bookings carry the platform defaults (15:00 /
12:00) so the field is always present and always a real time, and an
integration that staffs a door should branch on inventory_kind rather than
treat them as the operator's own answer.
Show child attributes
Show child attributes
What the guest paid, as one object. null when it cannot be stated — a
legacy row with no recorded amount resolves to null, never to "0.00":
zero would read as free, and null means "we do not know".
Show child attributes
Show child attributes
True when the listing takes bookings without the host approving each one.
Present only on a cancelled booking.
Show child attributes
Show child attributes
When the booking was created in Maat.
The host console's page for this booking — where a person is seen.