The payment plan of a project with contract value and invoiced sum (hr:work:billing)
GET /api/desk/v1/projects/{id}/payments
Module: Desk · operationId: getProjectBilling · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | Id or number |
Responses
- 200 Billing (
application/json)
Fields of the 200 answer:
autoDraft(boolean): The project type requests payments as soon as they are duecontractValue(number): Net sum of all payments (what the final invoice bills in total)invoiced(number): Net of the released invoicespayments(array of ProjectPayment): Payments of the plan in orderamount(number): Net amount or percentage (amountKind)amountKind(string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one offixed,percent)attempt(integer, read-only): Documents made so far; the trade reference is desk:project-payment::document(object, read-only): The invoice handed to trade (once requested)dueOn(string (date), nullable): Due on this dategrossTotal(number, nullable, read-only): Gross total of the invoiceid(string, read-only): Id of the paymentinvoiceNumber(string, read-only): Given by trade on releaseinvoicedOn(string (date), nullable, read-only): Invoice datelastError(string, read-only): Why the last send to trade failedmilestoneId(string, nullable): Due when this milestone of the project is reachednet(number, nullable, read-only): The net amount today (null: a percentage without budget amount)netTotal(number, nullable, read-only): Net total of the invoiceposition(integer): Position in the payment planprojectId(string, read-only): Project of the paymentrequestedAt(string (date-time), nullable, read-only): When the invoice draft was handed to traderequestedBy(string, read-only): The person, or system (automatic draft)role(string): interim payment or the final payment (one ofinterim,final)sendAttempts(integer, read-only): Attempts to hand the draft to tradestate(string, read-only): State of the payment (one ofplanned,due,requested,drafted,invoiced,skipped)taxRate(number): VAT rate in percent (max 100)title(string): Title of the payment (invoice line) (max length 200)tradeTransactionId(string, read-only): Invoice transaction in tradeversion(integer): Version of the payment; send it back on change
Example 200 answer:
{
"autoDraft": false,
"contractValue": 22400,
"invoiced": 6720,
"payments": [
{
"amount": 30,
"amountKind": "percent",
"attempt": 1,
"dueOn": null,
"grossTotal": 7996.8,
"id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
"invoiceNumber": "RE-2026-0187",
"invoicedOn": "2026-11-11",
"milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
"net": 6720,
"netTotal": 6720,
"position": 0,
"projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"role": "interim",
"state": "invoiced",
"taxRate": 19,
"title": "Abschlag nach Konfiguration",
"version": 4
},
{
"amount": 30,
"amountKind": "percent",
"attempt": 0,
"dueOn": null,
"id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f02",
"milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
"net": 6720,
"position": 1,
"projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"role": "interim",
"state": "planned",
"taxRate": 19,
"title": "Abschlag nach Datenübernahme",
"version": 1
},
{
"amount": 40,
"amountKind": "percent",
"attempt": 0,
"dueOn": null,
"id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f03",
"milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e04",
"net": 8960,
"position": 2,
"projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"role": "final",
"state": "planned",
"taxRate": 19,
"title": "Schlussrechnung",
"version": 1
}
]
}
Example request
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments' \
-H "Authorization: Bearer $ACCESS_TOKEN"