ConnectCloud Developers

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 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 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"

View as Markdown · Interactive reference · OpenAPI