Reporting metered usage

Microsoft Marketplace charges usage above a plan's flat price through custom meter dimensions. Your application reports usage to Transakt with POST /api/v1/metered-usage; Transakt resolves each record to the customer's Marketplace subscription and sends it to Microsoft's metering service.

Before you startCopy Anchor Link

• The plan is a flat-rate Marketplace plan. Microsoft offers custom meters on flat-rate plans only; per-user plans have none.
• Its dimensions are set on the plan's Marketplace mapping in the Admin Portal (Catalogue › Marketplace offers, the plan's Metering dimensions), with the dimension ids exactly as in Partner Center.
• Your API client has the scope Metered usage: write (usage:write); an Entra application also needs the app role Usage.Write.All.

Report a batchCopy Anchor Link

Send 1 to 100 records. Each names the tenant and your product (and optionally the plan), the dimension id, the quantity and the hour it belongs to:

curl -X POST "$TRANSAKT_API/api/v1/metered-usage" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-1b7d-4c0e-9a51-0e2b7a1d4401" \
  -d '{
    "records": [
      { "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47", "product": "planner",
        "dimension": "api-calls", "quantity": 1250, "usageStartAt": "2026-10-08T08:00:00Z" }
    ]
  }'

{
  "recorded": 1,
  "refused": 0,
  "results": [
    {
      "index": 0,
      "outcome": "Recorded",
      "reportId": "0193a8f2-…",
      "subscriptionId": "0193a8f2-…",
      "status": "Pending",
      "dimension": "api-calls",
      "quantity": 1250,
      "usageStartAt": "2026-10-08T08:00:00.000Z",
      "usageEndAt": "2026-10-08T09:00:00.000Z",
      "error": null
    }
  ]
}

The answer is 200 with one result per record, in the order sent. Each record is checked and saved on its own: one refused record never undoes another.

The rulesCopy Anchor Link

• Hour buckets. Usage is reported per UTC hour: usageStartAt is truncated to the hour, and the hour must have ended (metering.window_not_ended). Report each hour once, with the total for that hour.
• The last 24 hours only. Microsoft takes usage for the past 24 hours; an older hour is refused (metering.window_too_old, with the oldest allowed hour in args). Report soon after each hour ends.
• One report per subscription, dimension and hour. This is also Microsoft's duplicate rule. A different quantity is accepted until the report has been sent; afterwards it is refused (metering.window_already_reported).
• Usage above the base fee only. A quantity of 0 is recorded as Skipped and not sent. Quantities are at least 0, at most 1,000,000,000, with up to 6 decimals.
• Active subscriptions. Usage is taken for an Active, subscribed Marketplace subscription. After a suspension or cancellation, hours that started before it can still be reported while they are within 24 hours.
• Resolution. A record is resolved to the tenant's Marketplace subscriptions of the product in your workspace (narrowed by plan when given) whose plan has the dimension. None gives metering.subscription_not_found (or the reason the newest candidate cannot take the hour); several give metering.subscription_ambiguous: send plan.
• Idempotency. The per-hour rule already makes a retry safe; an Idempotency-Key header is honoured when you send one, not required.

What happens nextCopy Anchor Link

Transakt sends due reports to Microsoft in batches, retries transient failures, and records each report's final status: Accepted, QuantityMismatch (Microsoft already holds another quantity for the hour), Rejected (with Microsoft's reason), Expired (the 24 hours passed) or Skipped. A report that ends Rejected, Expired or QuantityMismatch notifies your subscription support team. Your team sees every report, and can reconcile Transakt's reports with Microsoft's records, on the Admin Portal's Metered usage page.