BillMate API

BillMate’s API is free and lets your own client or script read and manage your groups, expenses and payments. Every user generates their own keys from their profile.

Getting started

Sign in to BillMate, open Profile → API keys and create a key (read-only or read and write). Copy it right away: it is never shown again.

Send the key in the Authorization header of every request:

curl 'https://billmate.it/api/me' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Responses are JSON. Amounts are integers in minor units (cents).

Keys and permissions

Each key acts on behalf of the user who created it and only sees the data that user can access.
Read-only: GET requests only. Read and write: also create, edit and delete.
You can have up to 10 active keys, with an optional expiry (1 day to 2 years). Revoke a key from your profile: it stops working immediately.
The server only stores a hash of the key: if you lose it, create a new one.
Treat the key like a password: never put it in public apps, repositories or web pages. If you think it leaked, revoke it.

Not available with keys

For safety, keys cannot manage other keys, sessions, encrypted payment methods, invitations, account deletion or the admin area. Endpoints not listed here answer 403 API_KEY_FORBIDDEN.

Conventions

Amounts: integers in minor units (4000 = €40.00). In balances, a positive value means “you are owed”, negative “you owe”.
Ids: UUIDs. Calendar dates: YYYY-MM-DD. Instants: ISO 8601 in UTC.
Request bodies are JSON with Content-Type: application/json, up to 1 MB.
Expenses and payments are always records: BillMate never moves money.
CORS: API keys can also be used from web clients on other domains.

Usage limits

Up to 240 requests per minute per user, of which at most 90 writes. Beyond the limit the response is 429 with a Retry-After header. Usage is free with no daily quotas.

Errors

Errors carry an HTTP status and a JSON body {"error": {"code": "…", "details": …}}.

HTTP	code	Description
401	UNAUTHORIZED	Missing, invalid, expired or revoked key.
403	API_KEY_READ_ONLY	The key is read-only and the request writes.
403	API_KEY_FORBIDDEN	Endpoint not available with API keys.
403	FORBIDDEN	The user lacks permission for the action (e.g. editing someone else’s expense).
403	LEGAL_REQUIRED	The user must accept the updated documents in the app.
404	NOT_FOUND	Resource does not exist or is not visible to the user.
409	CONFLICT	State conflict (e.g. outdated `expectedVersion`).
422	VALIDATION	Invalid data: `details.fields` lists the fields.
429	RATE_LIMITED	Too many requests: wait `details.retryAfterSec` seconds.

Endpoints

Account and reference data

GET`/api/me`Permission: read-only

Profile of the key’s user

Example

curl -X GET 'https://billmate.it/api/me' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "id": "47542df6-597a-45b4-ab18-816c4b538265",
  "name": "Anna",
  "email": "anna@example.com",
  "avatarUrl": null,
  "locale": "it",
  "defaultCurrency": "EUR",
  "onboarded": true,
  "createdAt": "2026-10-21T15:11:20.346Z"
}

GET`/api/meta`Permission: read-only

Enabled currencies, categories and limits

Reference data for creating expenses: currencies (with decimals), platform and group categories, and the suggested rate between two currencies.

Parameters

Field	Type	Description
groupId query	string (uuid)	Also includes this group’s custom categories.
from query	string	Source currency for the suggested rate.max 3
to query	string	Target currency for the suggested rate.max 3

Example

curl -X GET 'https://billmate.it/api/meta' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimals": 2,
      "enabled": true
    }
  ],
  "categories": [
    {
      "id": "c1…",
      "key": "food",
      "name": null,
      "labels": {
        "it": "Cibo",
        "en": "Food"
      },
      "icon": "utensils",
      "color": "#c2410c"
    }
  ],
  "rate": null
}

GET`/api/dashboard`Permission: read-only

Overview: totals, groups, friends and recent activity

Example

curl -X GET 'https://billmate.it/api/dashboard' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "totals": [
    {
      "currency": "EUR",
      "owedToYou": 1500,
      "youOwe": 0,
      "net": 1500
    }
  ],
  "groups": [
    "…"
  ],
  "friends": [
    "…"
  ],
  "friendCount": 1,
  "incomingRequests": 0,
  "activity": [
    "…"
  ],
  "unread": 0
}

GET`/api/balances`Permission: read-only

Balances: total, per friend and per group

Amounts in minor units. A positive value means you are owed money, a negative one that you owe.

Example

curl -X GET 'https://billmate.it/api/balances' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "totals": [
    {
      "currency": "EUR",
      "owedToYou": 1500,
      "youOwe": 0,
      "net": 1500
    }
  ],
  "friends": {
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": [
      {
        "currency": "EUR",
        "amountMinor": 1500
      }
    ]
  },
  "groups": {
    "d19d0200-ea0e-4d0a-a899-2b96bf06ac03": {
      "currency": "EUR",
      "net": 1500
    }
  }
}

GET`/api/activity`Permission: read-only

Activity feed

Parameters

Field	Type	Description
before query	string	ISO 8601 date: returns only earlier activity (pagination, 50 at a time).

Example

curl -X GET 'https://billmate.it/api/activity' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "items": [
    {
      "id": "a1…",
      "type": "expense_added",
      "entityType": "expense",
      "entityId": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "data": {
        "description": "Cena in Trastevere",
        "amountMinor": 4000,
        "currency": "EUR"
      },
      "createdAt": "2026-10-21T15:11:20.735Z",
      "actor": {
        "id": "47542df6-597a-45b4-ab18-816c4b538265",
        "name": "Anna",
        "avatarUrl": null
      }
    }
  ]
}

Groups

GET`/api/groups`Permission: read-only

List your groups

Parameters

Field	Type	Description
archived query	string	`true` for archived groups (default: `false`).true \| false

Example

curl -X GET 'https://billmate.it/api/groups' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "items": [
    {
      "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "name": "Weekend a Roma",
      "type": "trip",
      "currency": "EUR",
      "archivedAt": null,
      "role": "owner",
      "memberCount": 2,
      "members": [
        {
          "id": "47542df6-597a-45b4-ab18-816c4b538265",
          "name": "Anna",
          "avatarUrl": null
        },
        {
          "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
          "name": "Luca",
          "avatarUrl": null
        }
      ],
      "myBalanceMinor": 1500
    }
  ]
}

POST`/api/groups`Permission: write

Create a group

Request body

Field	Type	Required	Description
name	string	yes	Group name (max 60 characters).max 60
type	string	no	Group type.trip \| home \| couple \| event \| family \| other · default "other"
currency	string	no	Group currency (ISO 4217, default EUR).default "EUR"
notes	object	no	Optional notes.
simplifyDebts	boolean	no	Simplify debts into fewer payments (default: true).default true
memberIds	string (uuid)[]	no	Friends to add right away (they must already be your friends).max 50

Example

curl -X POST 'https://billmate.it/api/groups' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weekend a Roma","type":"trip","currency":"EUR","simplifyDebts":true}'

Response 201

{
  "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03"
}

GET`/api/groups/{id}`Permission: read-only

Group detail, with members and balances

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Example

curl -X GET 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "group": {
    "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "name": "Weekend a Roma",
    "type": "trip",
    "currency": "EUR",
    "simplifyDebts": true,
    "archivedAt": null
  },
  "myRole": "owner",
  "members": [
    {
      "userId": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "role": "owner"
    }
  ],
  "balances": {
    "currency": "EUR",
    "simplified": true,
    "net": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "amountMinor": 1500
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "amountMinor": -1500
      }
    ],
    "transfers": [
      {
        "from": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "to": "47542df6-597a-45b4-ab18-816c4b538265",
        "amountMinor": 1500
      }
    ],
    "totalSpentMinor": 4000,
    "settledUp": false
  }
}

PATCH`/api/groups/{id}`Permission: write

Update a group

All fields are optional; group-edit permission is required. Returns the updated detail.

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Request body

Field	Type	Required	Description
name	string	no	max 60
type	string	no	trip \| home \| couple \| event \| family \| other
currency	string	no
notes	object	no
simplifyDebts	boolean	no
policy	object	no

Example

curl -X PATCH 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weekend a Napoli"}'

DELETE`/api/groups/{id}`Permission: write

Delete a group

Owner only, and only by sending the group’s exact name in `confirmName`.

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Request body

Field	Type	Required	Description
confirmName	string	yes

Example

curl -X DELETE 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"confirmName":"Weekend a Roma"}'

Response 200

{
  "ok": true
}

Expenses

GET`/api/expenses`Permission: read-only

List visible expenses

Paginated (`page`, `limit` up to 100). The response includes `users` with the names of the people mentioned.

Parameters

Field	Type	Description
groupId query	string (uuid)	Only expenses of this group.
friendId query	string (uuid)	Only expenses between you and this friend.
personId query	string (uuid)	Only expenses this person takes part in.
categoryId query	string (uuid)	Only this category.
q query	string	Text search in description and notes.max 100
from query	string	Earliest date (YYYY-MM-DD).
to query	string	Latest date (YYYY-MM-DD).
status query	string	`active` (default), `deleted` or `all`.active \| deleted \| all · default "active"
kind query	string	`expense` or `refund`.expense \| refund
page query	integer	Page, from 1.1–1000 · default 1
limit query	integer	Items per page (1–100, default 30).1–100 · default 30

Example

curl -X GET 'https://billmate.it/api/expenses' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "items": [
    {
      "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "groupName": "Weekend a Roma",
      "kind": "expense",
      "description": "Cena in Trastevere",
      "notes": null,
      "amountMinor": 4000,
      "currency": "EUR",
      "baseCurrency": "EUR",
      "fxRate": "1.00000000",
      "amountBaseMinor": 4000,
      "category": null,
      "expenseDate": "2026-10-21",
      "splitMethod": "equal",
      "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
      "createdAt": "2026-10-21T15:11:20.630Z",
      "updatedAt": "2026-10-21T15:11:20.630Z",
      "deletedAt": null,
      "version": 1,
      "payments": [
        {
          "userId": "47542df6-597a-45b4-ab18-816c4b538265",
          "paidMinor": 4000
        }
      ],
      "splits": [
        {
          "userId": "47542df6-597a-45b4-ab18-816c4b538265",
          "owedMinor": 2000,
          "inputValue": null
        },
        {
          "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
          "owedMinor": 2000,
          "inputValue": null
        }
      ],
      "myNetMinor": 2000,
      "canEdit": true,
      "canDelete": true
    }
  ],
  "hasMore": false,
  "page": 1,
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

POST`/api/expenses`Permission: write

Create an expense

Returns the detail of the created expense. Amounts are always in minor units. Use `clientId` for a safe retry.

Request body

Field	Type	Required	Description
groupId	object	no	Group of the expense; omitted or null for an expense between friends outside a group.
description	string	yes	Short description (max 140 characters).max 140
notes	object	no	Optional notes (max 1000 characters).
amountMinor	integer	yes	Total amount in minor units (cents): 4000 = 40.00. Must be greater than zero.0–9999999999999
currency	string	yes	ISO 4217 code of the currency the expense was paid in (e.g. EUR).
fxRate	object	no	Rate to the group currency, only when the currencies differ and no known rate exists.
categoryId	object	no	Category (id from GET /api/meta).
expenseDate	string	yes	Expense date (YYYY-MM-DD).
splitMethod	string	yes	Split method: equal, exact, percent, shares, adjust or items.equal \| exact \| percent \| shares \| adjust \| items
payments	object[]	yes	Who paid and how much (the sum must equal amountMinor).max 50
participants	object[]	yes	Who takes part in the split; `value` is used for exact (amount), percent (percentage ×100), shares and adjust.max 50
items	object[]	no	Receipt line items, only with splitMethod=items.max 60
clientId	object	no	Client-generated UUID: makes creation idempotent (a second send with the same id does not duplicate the expense).

Example

curl -X POST 'https://billmate.it/api/expenses' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","description":"Cena in Trastevere","amountMinor":4000,"currency":"EUR","expenseDate":"2026-10-21","splitMethod":"equal","payments":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265","paidMinor":4000}],"participants":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265"},{"userId":"b93e456c-f17f-4d42-a36f-96f75dad14f3"}]}'

Response 201

{
  "expense": {
    "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
    "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "groupName": "Weekend a Roma",
    "kind": "expense",
    "description": "Cena in Trastevere",
    "notes": null,
    "amountMinor": 4000,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "fxRate": "1.00000000",
    "amountBaseMinor": 4000,
    "category": null,
    "expenseDate": "2026-10-21",
    "splitMethod": "equal",
    "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
    "createdAt": "2026-10-21T15:11:20.630Z",
    "updatedAt": "2026-10-21T15:11:20.630Z",
    "deletedAt": null,
    "version": 1,
    "payments": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "paidMinor": 4000
      }
    ],
    "splits": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "owedMinor": 2000,
        "inputValue": null
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "owedMinor": 2000,
        "inputValue": null
      }
    ],
    "myNetMinor": 2000,
    "canEdit": true,
    "canDelete": true
  },
  "attachments": [],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

GET`/api/expenses/{id}`Permission: read-only

Expense detail

Includes items, refunds, attachment metadata and the revision history.

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Example

curl -X GET 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "expense": {
    "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
    "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "groupName": "Weekend a Roma",
    "kind": "expense",
    "description": "Cena in Trastevere",
    "notes": null,
    "amountMinor": 4000,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "fxRate": "1.00000000",
    "amountBaseMinor": 4000,
    "category": null,
    "expenseDate": "2026-10-21",
    "splitMethod": "equal",
    "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
    "createdAt": "2026-10-21T15:11:20.630Z",
    "updatedAt": "2026-10-21T15:11:20.630Z",
    "deletedAt": null,
    "version": 1,
    "payments": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "paidMinor": 4000
      }
    ],
    "splits": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "owedMinor": 2000,
        "inputValue": null
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "owedMinor": 2000,
        "inputValue": null
      }
    ],
    "myNetMinor": 2000,
    "canEdit": true,
    "canDelete": true,
    "items": [],
    "refunds": [],
    "refundedMinor": 0,
    "remainingRefundableMinor": 4000
  },
  "attachments": [],
  "revisions": [
    {
      "id": "r1…",
      "version": 1,
      "changeType": "create",
      "changedBy": "47542df6-597a-45b4-ab18-816c4b538265",
      "createdAt": "2026-10-21T15:11:20.630Z"
    }
  ],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

PUT`/api/expenses/{id}`Permission: write

Update an expense

Replaces the whole expense (same body as creation, plus an optional `expectedVersion`). Returns the updated detail.

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Request body

Field	Type	Required	Description
groupId	object	no	Group of the expense; omitted or null for an expense between friends outside a group.
description	string	yes	Short description (max 140 characters).max 140
notes	object	no	Optional notes (max 1000 characters).
amountMinor	integer	yes	Total amount in minor units (cents): 4000 = 40.00. Must be greater than zero.0–9999999999999
currency	string	yes	ISO 4217 code of the currency the expense was paid in (e.g. EUR).
fxRate	object	no	Rate to the group currency, only when the currencies differ and no known rate exists.
categoryId	object	no	Category (id from GET /api/meta).
expenseDate	string	yes	Expense date (YYYY-MM-DD).
splitMethod	string	yes	Split method: equal, exact, percent, shares, adjust or items.equal \| exact \| percent \| shares \| adjust \| items
payments	object[]	yes	Who paid and how much (the sum must equal amountMinor).max 50
participants	object[]	yes	Who takes part in the split; `value` is used for exact (amount), percent (percentage ×100), shares and adjust.max 50
items	object[]	no	Receipt line items, only with splitMethod=items.max 60
clientId	object	no	Client-generated UUID: makes creation idempotent (a second send with the same id does not duplicate the expense).
expectedVersion	integer	no	Version the client read: if the expense changed meanwhile the edit is rejected with 409.

Example

curl -X PUT 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","description":"Cena in Trastevere (con mancia)","amountMinor":4400,"currency":"EUR","expenseDate":"2026-10-21","splitMethod":"equal","payments":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265","paidMinor":4400}],"participants":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265"},{"userId":"b93e456c-f17f-4d42-a36f-96f75dad14f3"}],"expectedVersion":1}'

DELETE`/api/expenses/{id}`Permission: write

Delete an expense

Soft delete: the expense stays in the history with `deletedAt`.

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Example

curl -X DELETE 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "ok": true
}

Settlements

GET`/api/settlements`Permission: read-only

List recorded settlements

Parameters

Field	Type	Description
groupId query	string (uuid)	Only settlements of this group.
friendId query	string (uuid)	Only settlements between you and this friend.

Example

curl -X GET 'https://billmate.it/api/settlements' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "items": [
    {
      "id": "s1…",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "fromUserId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "toUserId": "47542df6-597a-45b4-ab18-816c4b538265",
      "amountMinor": 500,
      "currency": "EUR",
      "method": "cash",
      "note": null,
      "settledOn": "2026-10-21",
      "createdBy": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "canDelete": true
    }
  ],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

POST`/api/settlements`Permission: write

Record a payment between two people

BillMate is a ledger: this call records a payment that already happened, it does not move money.

Request body

Field	Type	Required	Description
groupId	object	no	Group of the payment; null for a payment between friends.
fromUserId	string (uuid)	yes	Who paid.
toUserId	string (uuid)	yes	Who received.
amountMinor	integer	yes	Amount in minor units, greater than zero.0–9999999999999
currency	string	yes	ISO 4217 currency.
method	string	no	cash, bank_transfer, paypal, revolut, satispay or other (default cash).cash \| bank_transfer \| paypal \| revolut \| satispay \| other · default "cash"
note	object	no	Optional note (max 300 characters).
settledOn	string	yes	Payment date (YYYY-MM-DD).

Example

curl -X POST 'https://billmate.it/api/settlements' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","fromUserId":"b93e456c-f17f-4d42-a36f-96f75dad14f3","toUserId":"47542df6-597a-45b4-ab18-816c4b538265","amountMinor":500,"currency":"EUR","method":"cash","settledOn":"2026-10-21"}'

Response 201

{
  "id": "s1…"
}

DELETE`/api/settlements/{id}`Permission: write

Remove a recorded settlement

Parameters

Field	Type	Description
id path	string (uuid)	Resource id.

Example

curl -X DELETE 'https://billmate.it/api/settlements/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "ok": true
}

Friends

GET`/api/friends`Permission: read-only

Friends and friend requests

Example

curl -X GET 'https://billmate.it/api/friends' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Response 200

{
  "friends": [
    {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "email": "luca@example.com",
      "avatarUrl": null,
      "explicit": true,
      "balances": [
        {
          "currency": "EUR",
          "amountMinor": 1500
        }
      ]
    }
  ],
  "incoming": [],
  "outgoing": []
}

OpenAPI 3.1 spec

Download the spec to generate a client or import it into Postman and Insomnia: /developers/openapi.json

BillMate API

Getting started

Keys and permissions

Not available with keys

Conventions

Usage limits

Errors

Endpoints

Account and reference data

GET/api/mePermission: read-only

GET/api/metaPermission: read-only

GET/api/dashboardPermission: read-only

GET/api/balancesPermission: read-only

GET/api/activityPermission: read-only

Groups

GET/api/groupsPermission: read-only

POST/api/groupsPermission: write

GET/api/groups/{id}Permission: read-only

PATCH/api/groups/{id}Permission: write

DELETE/api/groups/{id}Permission: write

Expenses

GET/api/expensesPermission: read-only

POST/api/expensesPermission: write

GET/api/expenses/{id}Permission: read-only

PUT/api/expenses/{id}Permission: write

DELETE/api/expenses/{id}Permission: write

Settlements

GET/api/settlementsPermission: read-only

POST/api/settlementsPermission: write

DELETE/api/settlements/{id}Permission: write

Friends

GET/api/friendsPermission: read-only

OpenAPI 3.1 spec

GET`/api/me`Permission: read-only

GET`/api/meta`Permission: read-only

GET`/api/dashboard`Permission: read-only

GET`/api/balances`Permission: read-only

GET`/api/activity`Permission: read-only

GET`/api/groups`Permission: read-only

POST`/api/groups`Permission: write

GET`/api/groups/{id}`Permission: read-only

PATCH`/api/groups/{id}`Permission: write

DELETE`/api/groups/{id}`Permission: write

GET`/api/expenses`Permission: read-only

POST`/api/expenses`Permission: write

GET`/api/expenses/{id}`Permission: read-only

PUT`/api/expenses/{id}`Permission: write

DELETE`/api/expenses/{id}`Permission: write

GET`/api/settlements`Permission: read-only

POST`/api/settlements`Permission: write

DELETE`/api/settlements/{id}`Permission: write

GET`/api/friends`Permission: read-only