usage_cost

What it shows

Attributed vendor cost over usage periods starting in [from, until): gross recorded expense, promotional credits and net cost, with function, right and native currency. group_by selects customer, holder, team or project; attribution_value optionally selects one. Rows retain their attribution and usage period; running includes current estimates and reconciled costs, billed includes only closed periods. Pages are detail, never a whole-window total. Late observations change quantities, never billed cost. Empty on a store without usage tables.

Example MCP App view

The read-only example below uses illustrative demo data and the same report component as the MCP App. These are not your books or the result of the request example.

Open the full example view.

Inputs

Send the fixed kind and these parameters at the top level of the report request, not inside input.

Required means required within its containing object; an optional parent can be omitted.

Reading the result

Running this report does not change the books. Its description above distinguishes recorded-book summaries from previews based on supplied facts or assumptions. Interpret its totals, grouping, missing-data indicators and pagination using that description. Monetary amounts are integer strings in the reported unit; ratios and assumptions can be fractional numbers. An empty result is not evidence that the business had no activity.

The public OpenAPI contract does not enumerate this report’s result fields. Fetch GET /v1/reports for its live description and parameters, and inspect the returned JSON rather than assuming an output shape.

Example request

{
  "kind": "usage_cost",
  "from": "2026-09-01",
  "until": "2026-09-30"
}

All reports · Operation and errors · Reusable schemas

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

Exact request schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "kind": {
      "const": "usage_cost"
    },
    "from": {
      "description": "Start date (YYYY-MM-DD) or UTC timestamp (RFC 3339). A date is a UTC day and includes that whole day.",
      "type": "string",
      "minLength": 1
    },
    "until": {
      "description": "End date (YYYY-MM-DD) or UTC timestamp (RFC 3339). A date is a UTC day and includes that whole day, so September ends at 2026-09-30; a timestamp includes everything before that moment.",
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "description": "Maximum rows per page, up to 100 (default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "description": "Opaque nextCursor from the preceding report page with the same filters.",
      "type": "string",
      "minLength": 1
    },
    "group_by": {
      "description": "Attribution dimension to show (default customer).",
      "type": "string",
      "minLength": 1,
      "enum": [
        "customer",
        "holder",
        "team",
        "project"
      ]
    },
    "attribution_value": {
      "description": "Select this exact customer id, holder, team or project in group_by.",
      "type": "string",
      "minLength": 1
    },
    "view": {
      "description": "running includes estimates and reconciled cost; billed keeps closed usage periods (default running).",
      "type": "string",
      "minLength": 1,
      "enum": [
        "running",
        "billed"
      ]
    }
  },
  "required": [
    "kind",
    "from",
    "until"
  ]
}