Hand the payment's invoice to trade as a draft; writes desk.project.payment_requested (hr:work:billing)
POST /api/desk/v1/projects/{id}/payments/{pid}/request
Module: Desk · operationId: requestProjectPayment · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)
The invoice is made once, dated today: an interim invoice bills the payment's net amount; the final invoice bills the contract value (one line per VAT rate) and deducts the invoiced interim invoices, interim payments not requested yet become skipped. Trade numbers and releases it after a person's review; trade's feed moves the payment to drafted, invoiced, or back to due when the draft is discarded or the invoice revoked. When trade cannot be reached the payment stays requested (lastError) and desk retries; requesting it again sends at once.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | yes | |
pid |
path | string | yes |
Responses
- 200 Payment (drafted, or requested when trade did not take it yet) (
application/json) - 400 The project has no customer, or a percentage without budget amount
- 409 payment_state: already on its way, or an interim invoice is not released yet (final invoice)
- 503 Project billing is not connected to trade
Fields of the 200 answer:
amount(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:
{
"amount": 30,
"amountKind": "percent",
"attempt": 1,
"dueOn": null,
"id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f02",
"lastError": "",
"milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
"net": 6720,
"position": 1,
"projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
"requestedAt": "2026-11-18T09:30:00Z",
"requestedBy": "emma.maier@muster-it.example",
"role": "interim",
"sendAttempts": 0,
"state": "requested",
"taxRate": 19,
"title": "Abschlag nach Datenübernahme",
"version": 3
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments/string/request' \
-H "Authorization: Bearer $ACCESS_TOKEN"