curl --fail-with-body "https://maatstays.wtf/v1/finance/earnings?from=2026-09-01&to=2026-09-30&page_size=100" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const headers = { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` };
for (let page = 1; ; page += 1) {
const url = new URL('https://maatstays.wtf/v1/finance/earnings');
url.searchParams.set('from', '2026-09-01');
url.searchParams.set('to', '2026-09-30');
url.searchParams.set('page', String(page));
url.searchParams.set('page_size', '100');
const res = await fetch(url, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const line of body.items) {
console.log(line.earned_on, line.net.value, line.net.currency, line.status);
}
if (!body.has_more) break;
}
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
page = 1
while True:
res = requests.get(
"https://maatstays.wtf/v1/finance/earnings",
headers=headers,
params={
"from": "2026-09-01",
"to": "2026-09-30",
"page": page,
"page_size": 100,
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for line in body["items"]:
print(line["earned_on"], line["net"]["value"], line["net"]["currency"])
if not body["has_more"]:
break
page += 1
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
"strconv"
)
type money struct {
Value string `json:"value"`
Currency string `json:"currency"`
}
type earning struct {
EarnedOn string `json:"earned_on"`
Net money `json:"net"`
Status string `json:"status"`
}
type page struct {
Items []earning `json:"items"`
HasMore bool `json:"has_more"`
}
func main() {
token := os.Getenv("MAAT_PARTNER_TOKEN")
for pageNum := 1; ; pageNum++ {
query := url.Values{}
query.Set("from", "2026-09-01")
query.Set("to", "2026-09-30")
query.Set("page", strconv.Itoa(pageNum))
query.Set("page_size", "100")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/earnings?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+token)
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
var body page
err = json.NewDecoder(res.Body).Decode(&body)
res.Body.Close()
if err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("list failed: %d", res.StatusCode)
}
for _, e := range body.Items {
fmt.Println(e.EarnedOn, e.Net.Value, e.Net.Currency, e.Status)
}
if !body.HasMore {
break
}
}
}
{
"items": [
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"earned_on": "2026-09-12",
"gross": {
"value": "4100.00",
"currency": "EGP"
},
"refunded": {
"value": "0.00",
"currency": "EGP"
},
"net": {
"value": "4100.00",
"currency": "EGP"
},
"platform_fee": {
"value": "500.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "0.00",
"currency": "EGP"
},
"status": "pending"
},
{
"booking_reference": "77b0d4e1-9a44-4b5e-8f1a-2c3d4e5f6081",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"earned_on": "2026-09-02",
"gross": {
"value": "3200.00",
"currency": "EGP"
},
"refunded": {
"value": "800.00",
"currency": "EGP"
},
"net": {
"value": "2400.00",
"currency": "EGP"
},
"platform_fee": {
"value": "400.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "100.00",
"currency": "EGP"
},
"status": "available"
}
],
"has_more": false
}List what each payment earned you
One row per PAYMENT, newest stay first — the lines behind the available and
pending figures on your balance.
One row is one payment, not one booking. A booking that is later modified takes its own additional charge and therefore has its own row, with its own stay date.
earned_on is the stay’s CHECK-IN date, not the date the money moved. June
revenue means the stays that happened in June, which is the only bucketing that
makes a year-over-year comparison line up seasonally. It is the same convention
the Maat host dashboard uses, so the two agree.
gross is what the platform booked as YOUR income for that payment — the payout
plus any cancellation-insurance premium. It is already net of the platform’s
commission and service fee, so it is not the guest’s total; for what a guest paid,
read amount_paid on the booking. refunded is what was reversed, positive, and
net is gross - refunded.
status says how far that payment’s money has got, from held in escrow to
transferred out. reserved means it is committed to an open payout request:
cleared, but neither withdrawable nor paid.
Filter with from, to and listing_id; page with page and page_size, and
keep asking while has_more is true. Both date bounds are inclusive, an
inverted range is refused rather than answered with an empty page, and a window
wider than 731 days is refused rather than truncated.
Live in a sandbox workspace. Returns 501 against a production one. A sandbox
never charges anybody, so it answers an empty page.
curl --fail-with-body "https://maatstays.wtf/v1/finance/earnings?from=2026-09-01&to=2026-09-30&page_size=100" \
-H "Authorization: Bearer $MAAT_PARTNER_TOKEN"const headers = { Authorization: `Bearer ${process.env.MAAT_PARTNER_TOKEN}` };
for (let page = 1; ; page += 1) {
const url = new URL('https://maatstays.wtf/v1/finance/earnings');
url.searchParams.set('from', '2026-09-01');
url.searchParams.set('to', '2026-09-30');
url.searchParams.set('page', String(page));
url.searchParams.set('page_size', '100');
const res = await fetch(url, { headers });
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const line of body.items) {
console.log(line.earned_on, line.net.value, line.net.currency, line.status);
}
if (!body.has_more) break;
}
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['MAAT_PARTNER_TOKEN']}"}
page = 1
while True:
res = requests.get(
"https://maatstays.wtf/v1/finance/earnings",
headers=headers,
params={
"from": "2026-09-01",
"to": "2026-09-30",
"page": page,
"page_size": 100,
},
timeout=30,
)
body = res.json()
if res.status_code >= 400:
raise RuntimeError(f"{body['code']}: {body.get('detail')}")
for line in body["items"]:
print(line["earned_on"], line["net"]["value"], line["net"]["currency"])
if not body["has_more"]:
break
page += 1
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"net/url"
"os"
"strconv"
)
type money struct {
Value string `json:"value"`
Currency string `json:"currency"`
}
type earning struct {
EarnedOn string `json:"earned_on"`
Net money `json:"net"`
Status string `json:"status"`
}
type page struct {
Items []earning `json:"items"`
HasMore bool `json:"has_more"`
}
func main() {
token := os.Getenv("MAAT_PARTNER_TOKEN")
for pageNum := 1; ; pageNum++ {
query := url.Values{}
query.Set("from", "2026-09-01")
query.Set("to", "2026-09-30")
query.Set("page", strconv.Itoa(pageNum))
query.Set("page_size", "100")
req, _ := http.NewRequest(http.MethodGet,
"https://maatstays.wtf/v1/finance/earnings?"+query.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+token)
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
var body page
err = json.NewDecoder(res.Body).Decode(&body)
res.Body.Close()
if err != nil {
log.Fatal(err)
}
if res.StatusCode >= 400 {
log.Fatalf("list failed: %d", res.StatusCode)
}
for _, e := range body.Items {
fmt.Println(e.EarnedOn, e.Net.Value, e.Net.Currency, e.Status)
}
if !body.HasMore {
break
}
}
}
{
"items": [
{
"booking_reference": "5f3a91c2-e8b4-4a71-9c30-1e2f3a4b5c6d",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"earned_on": "2026-09-12",
"gross": {
"value": "4100.00",
"currency": "EGP"
},
"refunded": {
"value": "0.00",
"currency": "EGP"
},
"net": {
"value": "4100.00",
"currency": "EGP"
},
"platform_fee": {
"value": "500.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "0.00",
"currency": "EGP"
},
"status": "pending"
},
{
"booking_reference": "77b0d4e1-9a44-4b5e-8f1a-2c3d4e5f6081",
"listing_id": "7c4b1e58-2a90-4f61-b3d2-5e8a1c0f7d24",
"earned_on": "2026-09-02",
"gross": {
"value": "3200.00",
"currency": "EGP"
},
"refunded": {
"value": "800.00",
"currency": "EGP"
},
"net": {
"value": "2400.00",
"currency": "EGP"
},
"platform_fee": {
"value": "400.00",
"currency": "EGP"
},
"refunded_platform_fee": {
"value": "100.00",
"currency": "EGP"
},
"status": "available"
}
],
"has_more": false
}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
1-based page number. Defaults to the first page.
x >= 1Rows per page. The same default and the same ceiling on every list in this API.
A page_size above the maximum is refused with validation_failed naming
the parameter — never silently clamped, because a caller who believes they asked
for 500 and received 200 will stop walking a set they have not finished.
1 <= x <= 200Only earnings whose earned_on — the stay's check-in date — is on or after this date. Inclusive. Omit for no lower bound.
Only earnings whose earned_on is on or before this date. Inclusive. Omit for no upper bound. A from after to, or a window wider than 731 days, is refused with 400 validation_failed rather than truncated.
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 page of earning lines.
One page of earning lines, newest stay first.
Show child attributes
Show child attributes
Whether another page exists. There is no total: counting the whole set to answer one page is work neither of us needs.
Pages are numbered and the list is newest first, so a payment that
settles while you are walking shifts the rows behind it. Key what you
collect by booking_reference and earned_on, or narrow with from and
to so the set you are paging cannot move.