ConnectCloud Developers

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 answers 400 with code provider_not_enabled.
  • year (integer)

Example:

{
  "month": 10,
  "providers": [
    "sophos",
    "ingram"
  ],
  "year": 2026
}

Responses

  • 202 Collection started; the claimed runs are running, totalItems is 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_enabled and itc_no_supplier (upload only), or conflict (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 of running, 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}'

View as Markdown · Interactive reference · OpenAPI