Approve an MSP invoice for booking (tenant:trade:msp:approve)
POST /api/trade/v1/msp/invoices/{id}/approve
Module: Trade · operationId: approveMspInvoice · Tag: MSP billing · Auth: access token (Authorization: Bearer <accessToken>)
Only a fresh draft without problems (or a failed invoice) can be approved. Trade then books it as an INVOICE
(Verkauf) with the idempotency key of customer and month, so a customer's month is booked exactly once, also
after a restart or a lost answer; the document number is written back and trade.msp.invoice.created is
published. A failed attempt is retried a minute later, three times per approval.
Approval means the poster issues the invoice in Verkauf: final document number, XRechnung with the KoSIT
check, the XML filed in DMS, and the mail with the XML to the customer when the delivery is send. A refusal (e.g. the
KoSIT check) leaves the MSP invoice failed with error and the transactionId of the Verkauf draft.
The Verkauf draft carries typeData.issueRefusal; issuing it in Verkauf (issueInvoiceDraft) marks the refused MSP
invoice posted.
Approval needs every active connector to have collected the month (409 collection_incomplete).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json
delivery(object): Replaces the invoice's delivery before approving; empty keeps it.
Example:
{
"delivery": "send"
}
Responses
- 200 Approved (
application/json) - 400 Error (
application/json) - 401 No valid session or bearer token (no body).
- 403 Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (
application/json) - 404 Not found in the tenant. (
application/json) - 409 The state does not allow it:
month_closed(an invoice of the month is approved or booked),msp_disabled,collection_incomplete(not every active connector has collected the month),run_in_progress,itc_not_enabledanditc_no_supplier(upload only), orconflict(e.g. a stale draft, open problems, an invoice past draft). (application/json)
Fields of the 200 answer:
addressId(string (uuid)): Masterdata address of the customer.addressName(string): Name of the customer.approvedAt(string (date-time)): When the invoice was approved.approvedBy(string): Who approved the invoice.attempts(integer): Number of posting attempts.computedAt(string (date-time)): When the draft was computed.delivery(MspDelivery):send: approving issues the invoice in Verkauf and mails it to the customer;issue: it is only issued (final number, XRechnung, the XML in DMS). (one ofsend,issue)error(string): Why the last posting failed.id(string (uuid)): Id of the MSP invoice.lines(array of MspInvoiceLine): Positions of the invoice.articleNumber(string): Article number in masterdata.contractId(string (uuid)): Contract of the position.contractItemId(string (uuid)): The contract position of afixedline.kind(string):fixed(a contract item) orusage(collected usage). (one offixed,usage)name(string): Name printed on the invoice position.position(integer): Position number of the line.problem(string): Why the position cannot be billed as it is.provider(string): MSP provider (mailstore,sophos,ingram,itc, …).quantity(number): Quantity.sourceSku(string): The provider's SKU.text(string): Printed below the name; missing when none. ITC:VM: <name>of the virtual machine.total(number): Net total of the position.unitPrice(number): Missing when no price is known (a problem).usageItemIds(array of string (uuid)): The usage items of ausageline.
month(integer): Month (1–12) of the billing month.netTotal(number): Net total of the invoice.postedAt(string (date-time)): When the invoice was posted.problems(array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).stale(boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.status(string): Status of the MSP invoice (draft,approved,posting,posted,failed). (one ofdraft,approved,posting,posted,failed)transactionId(string (uuid)): The booked INVOICE in trade.transactionNumber(string): Number of the invoice in Verkauf once posted.year(integer): Year of the billing month.
Example 200 answer:
{
"addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
"addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
"approvedAt": "2026-11-05T09:12:00Z",
"approvedBy": "laura.kaestner@muster-it.example",
"attempts": 0,
"computedAt": "2026-11-03T06:12:00Z",
"delivery": "send",
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
"lines": [
{
"articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
"kind": "usage",
"name": "Microsoft 365 Business Standard 1YM",
"position": 1,
"provider": "ingram",
"quantity": 12,
"sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
"total": 150,
"unitPrice": 12.5,
"usageItemIds": [
"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
]
},
{
"articleNumber": "ITC7030222P1MM",
"kind": "usage",
"name": "ITC CLOUD Server CPU Performance Plus",
"position": 2,
"provider": "itc",
"quantity": 4,
"sourceSku": "7030222",
"text": "VM: kanzlei-srv01",
"total": 38,
"unitPrice": 9.5,
"usageItemIds": [
"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
]
},
{
"articleNumber": "ITC7030220P1MM",
"kind": "usage",
"name": "ITC CLOUD Server RAM 1 GB",
"position": 3,
"provider": "itc",
"quantity": 16,
"sourceSku": "7030220",
"text": "VM: kanzlei-srv01",
"total": 51.2,
"unitPrice": 3.2,
"usageItemIds": [
"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
]
},
{
"articleNumber": "ITC7030003P1MM",
"kind": "usage",
"name": "ITC CLOUD 3 Wege Storage Standard je GB",
"position": 4,
"provider": "itc",
"quantity": 500,
"sourceSku": "7030003",
"text": "VM: kanzlei-srv01",
"total": 60,
"unitPrice": 0.12,
"usageItemIds": [
"0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
]
},
{
"articleNumber": "DL-9005",
"contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
"contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
"kind": "fixed",
"name": "Supportpauschale Fernwartung, monatlich",
"position": 5,
"quantity": 1,
"total": 180,
"unitPrice": 180
}
],
"month": 10,
"netTotal": 479.2,
"problems": [],
"stale": false,
"status": "approved",
"year": 2026
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/approve' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"delivery":"send"}'