curl --fail-with-body "https://maatstays.wtf/v1/finance/earnings/summary?from=2026-09-01&to=2026-09-30&granularity=month" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const url = new URL('https://maatstays.wtf/v1/finance/earnings/summary');
url.searchParams.set('from', '2026-09-01');
url.searchParams.set('to', '2026-09-30');
url.searchParams.set('granularity', 'month');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const bucket of body.buckets) {
// A bucket is a period AND a currency. Two currencies in one month are
// two buckets, never one sum.
console.log(bucket.period, bucket.currency, bucket.net.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/finance/earnings/summary",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
params={"from": "2026-09-01", "to": "2026-09-30", "granularity": "month"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for bucket in body["buckets"]:
# A bucket is a period AND a currency.
print(bucket["period"], bucket["currency"], bucket["net"]["value"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
)
type money struct {
Value string `json:"value"`
}
type bucket struct {
Period string `json:"period"`
Currency string `json:"currency"`
Net money `json:"net"`
}
type summary struct {
Buckets []bucket `json:"buckets"`
}
func main() {
query := url.Values{}
query.Set("from", "2026-09-01")
query.Set("to", "2026-09-30")
query.Set("granularity", "month")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/earnings/summary?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body summary
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("summary failed: %d", res.StatusCode)
}
for _, b := range body.Buckets {
fmt.Println(b.Period, b.Currency, b.Net.Value)
}
}
{
"buckets": [
{
"period": "2026-09-01",
"currency": "EGP",
"gross": {
"value": "7300.00",
"currency": "EGP"
},
"refunded": {
"value": "800.00",
"currency": "EGP"
},
"net": {
"value": "6500.00",
"currency": "EGP"
},
"platform_fee": {
"value": "900.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "100.00",
"currency": "EGP"
},
"bookings": 2
},
{
"period": "2026-09-01",
"currency": "USD",
"gross": {
"value": "640.00",
"currency": "USD"
},
"refunded": {
"value": "0.00",
"currency": "USD"
},
"net": {
"value": "640.00",
"currency": "USD"
},
"platform_fee": {
"value": "80.00",
"currency": "USD"
},
"refunded_platform_fee": {
"value": "0.00",
"currency": "USD"
},
"bookings": 1
}
]
}Total your earnings by day, week or month
The same earning lines, totalled — one bucket per period AND per currency.
A month in which you settled in two currencies is TWO buckets, not one sum. There is no total across them anywhere in this API.
period is the bucket’s FIRST day at every granularity, so month gives
2026-09-01 rather than 2026-09 and one date parser reads all three. A week
starts on the Monday.
bookings counts the distinct bookings that contributed. A payment we have not
yet matched to a booking counts in the amounts and not in that number — a window
of seconds after a payment settles.
from, to and granularity are all REQUIRED. A summary aggregates everything
inside its window in one pass, so an unbounded one would sweep your whole history
on every call; and the three granularities bucket the same rows very differently,
so we would rather be told which you want than guess. The window is inclusive at
both ends and may span at most 731 days.
Use listing_id to narrow to one listing. It filters inside your own workspace,
so a listing that is not yours returns an empty series rather than somebody
else’s revenue.
Live in a sandbox workspace. Returns 501 against a production one. A sandbox
never charges anybody, so it answers an empty series.
curl --fail-with-body "https://maatstays.wtf/v1/finance/earnings/summary?from=2026-09-01&to=2026-09-30&granularity=month" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const url = new URL('https://maatstays.wtf/v1/finance/earnings/summary');
url.searchParams.set('from', '2026-09-01');
url.searchParams.set('to', '2026-09-30');
url.searchParams.set('granularity', 'month');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` },
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const bucket of body.buckets) {
// A bucket is a period AND a currency. Two currencies in one month are
// two buckets, never one sum.
console.log(bucket.period, bucket.currency, bucket.net.value);
}
import os
import requests
res = requests.get(
"https://maatstays.wtf/v1/finance/earnings/summary",
headers={"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"},
params={"from": "2026-09-01", "to": "2026-09-30", "granularity": "month"},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for bucket in body["buckets"]:
# A bucket is a period AND a currency.
print(bucket["period"], bucket["currency"], bucket["net"]["value"])
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
)
type money struct {
Value string `json:"value"`
}
type bucket struct {
Period string `json:"period"`
Currency string `json:"currency"`
Net money `json:"net"`
}
type summary struct {
Buckets []bucket `json:"buckets"`
}
func main() {
query := url.Values{}
query.Set("from", "2026-09-01")
query.Set("to", "2026-09-30")
query.Set("granularity", "month")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/earnings/summary?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MAAT_PARTNER_TOKEN"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var body summary
if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("summary failed: %d", res.StatusCode)
}
for _, b := range body.Buckets {
fmt.Println(b.Period, b.Currency, b.Net.Value)
}
}
{
"buckets": [
{
"period": "2026-09-01",
"currency": "EGP",
"gross": {
"value": "7300.00",
"currency": "EGP"
},
"refunded": {
"value": "800.00",
"currency": "EGP"
},
"net": {
"value": "6500.00",
"currency": "EGP"
},
"platform_fee": {
"value": "900.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "100.00",
"currency": "EGP"
},
"bookings": 2
},
{
"period": "2026-09-01",
"currency": "USD",
"gross": {
"value": "640.00",
"currency": "USD"
},
"refunded": {
"value": "0.00",
"currency": "USD"
},
"net": {
"value": "640.00",
"currency": "USD"
},
"platform_fee": {
"value": "80.00",
"currency": "USD"
},
"refunded_platform_fee": {
"value": "0.00",
"currency": "USD"
},
"bookings": 1
}
]
}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.
Query Parameters
First day of the summary window, inclusive, over earned_on — the stay's check-in date. Required: a summary totals everything inside its window in one pass, so an unbounded one would sweep your whole history on every call.
Last day of the summary window, inclusive. A from after to, or a window wider than 731 days, is refused with 400 validation_failed rather than truncated.
How to bucket the window.
Required rather than defaulted: the three bucket the same rows very differently, and a caller who did not say which they wanted should be told to say so.
See EarningsGranularity.
How an earnings summary is bucketed. period is always the bucket's FIRST day, so
one date parser reads all three.
See EarningsGranularity.
day, week, month Only earnings on this listing. Filters inside your own workspace, so a listing that is not yours returns an empty result rather than another workspace's revenue.
Response
One bucket per period and currency, oldest first.
One bucket per period and currency, oldest first. There is no total across currencies anywhere in this response.
Show child attributes
Show child attributes