ConnectCloud Developers

Add an interim or the final payment to the plan (hr:work:billing)

POST /api/desk/v1/projects/{id}/payments

Module: Desk · operationId: createProjectPayment · Tag: Projects · Auth: access token (Authorization: Bearer <accessToken>)

It is due at once when its milestone is reached or its date has come. A project has one final payment.

Parameters

Name In Type Required Description
id path string yes Id or number

Request body

application/json (required)

  • amount (number): Net amount or percentage (amountKind)
  • amountKind (string): fixed: amount is net EUR; percent: amount is a percentage of the project's budgetAmount (one of fixed, percent)
  • clearDueOn (boolean): Remove the due date
  • clearMilestone (boolean): Remove the milestone
  • dueOn (string (date)): Date the payment is due
  • milestoneId (string): Milestone that makes the payment due
  • position (integer): Position in the payment plan
  • role (string): interim payment or the final payment (one of interim, final)
  • taxRate (number): Default: the project type's (19)
  • title (string): Title of the payment (invoice line)
  • version (integer): Current version (required on change)

Example:

{
  "amount": 30,
  "amountKind": "percent",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
  "role": "interim",
  "taxRate": 19,
  "title": "Abschlag nach Datenübernahme"
}

Responses

  • 201 Payment (application/json)
  • 400 Invalid payment, a second final payment, or a milestone of another project

Fields of the 201 answer:

  • amount (number): Net amount or percentage (amountKind)
  • amountKind (string): fixed: amount is net EUR; percent: a share of the project's budgetAmount (one of fixed, 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 date
  • grossTotal (number, nullable, read-only): Gross total of the invoice
  • id (string, read-only): Id of the payment
  • invoiceNumber (string, read-only): Given by trade on release
  • invoicedOn (string (date), nullable, read-only): Invoice date
  • lastError (string, read-only): Why the last send to trade failed
  • milestoneId (string, nullable): Due when this milestone of the project is reached
  • net (number, nullable, read-only): The net amount today (null: a percentage without budget amount)
  • netTotal (number, nullable, read-only): Net total of the invoice
  • position (integer): Position in the payment plan
  • projectId (string, read-only): Project of the payment
  • requestedAt (string (date-time), nullable, read-only): When the invoice draft was handed to trade
  • requestedBy (string, read-only): The person, or system (automatic draft)
  • role (string): interim payment or the final payment (one of interim, final)
  • sendAttempts (integer, read-only): Attempts to hand the draft to trade
  • state (string, read-only): State of the payment (one of planned, 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 trade
  • version (integer): Version of the payment; send it back on change

Example 201 answer:

{
  "amount": 30,
  "amountKind": "percent",
  "attempt": 1,
  "document": {},
  "dueOn": null,
  "grossTotal": 7996.8,
  "id": "7d4e5f6a-8b9c-4d0e-9f2a-4b5c6d7e8f01",
  "invoiceNumber": "RE-2026-0187",
  "invoicedOn": "2026-11-11",
  "lastError": "",
  "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e02",
  "net": 6720,
  "netTotal": 6720,
  "position": 0,
  "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "requestedAt": "2026-11-10T16:05:00Z",
  "requestedBy": "emma.maier@muster-it.example",
  "role": "interim",
  "sendAttempts": 1,
  "state": "invoiced",
  "taxRate": 19,
  "title": "Abschlag nach Konfiguration",
  "tradeTransactionId": "8f5a6b7c-9d0e-4f1a-8b2c-3d4e5f6a7b01",
  "version": 4
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/string/payments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"amount":30,"amountKind":"percent","milestoneId":"6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03","role":"interim","taxRate":19,"title":"Abschlag nach Datenübernahme"}'

View as Markdown · Interactive reference · OpenAPI