Start collecting the MSP usage of a month (tenant:trade:msp:write)
POST /api/trade/v1/msp/collect
Module: Trade · operationId: collectMspUsage · Tag: MSP billing · Auth: access token (Authorization: Bearer <accessToken>)
Claims the run of the month of every enabled provider and answers 202 at once with them as running
(runs[].runId); the providers are collected in the background, since one may take minutes (Ingram reads
every subscription and waits out its API quota). Follow the outcome with listMspRuns. A provider whose run
another collection holds is listed with errors. The collection fetches the usage of the month from every
enabled provider (MailStore, Sophos, Ingram – Microsoft CSP is
bought through Ingram; ITC Riemer is uploaded instead, uploadMspItcReport), keeps the raw answers in the database (rawAnswers of the run) and replaces the provider's items of the month in one
step; a second collection of the same month never duplicates items. After a successful run every item is
published as trade.usage.recorded with the run id. A failing provider fails only its run (runs, errors)
and keeps the items collected before. Year and month come from the body or the query; without them the
previous month (Europe/Berlin) is collected. The scheduler collects the previous month on the first days of
every month by itself. Drafts of the month become stale and must be recomputed.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
year |
query | integer | ||
month |
query | string | Month number, or YYYY-MM. |
Request body
application/json
month(integer): (max 12)providers(array of string): Providers to collect (duplicates count once); only their runs are claimed. Empty or missing collects every enabled provider. A name that is not an enabled provider answers400with codeprovider_not_enabled.year(integer)
Example:
{
"month": 10,
"providers": [
"sophos",
"ingram"
],
"year": 2026
}
Responses
- 202 Collection started; the claimed runs are
running,totalItemsis 0 (application/json) - 400 Invalid request or a provider that is not enabled (code
provider_not_enabled) (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) - 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) - 503 The configuration store is not available. (
application/json)
Fields of the 202 answer:
errors(array of string): Providers that failed or whose run another collection holds.month(integer): Month (1–12) of the billing month.providersRun(array of string): Providers collected.runs(array of object): Run of each provider.error(string): Why the run failed.items(integer): Number of usage items of the run.provider(string): MSP provider (mailstore,sophos,ingram,itc, …).runId(string (uuid)): Id of the usage run.status(string):running: another collection of the provider and month is running; nothing was done. (one ofrunning,succeeded,failed)
totalItems(integer): Number of usage items collected.year(integer): Year of the billing month.
Example 202 answer:
{
"errors": [],
"month": 10,
"providersRun": [
"sophos",
"ingram"
],
"runs": [
{
"items": 0,
"provider": "sophos",
"runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f02",
"status": "running"
},
{
"items": 0,
"provider": "ingram",
"runId": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f03",
"status": "running"
}
],
"totalItems": 0,
"year": 2026
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/msp/collect' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"month":10,"providers":["sophos","ingram"],"year":2026}'