---
title: "Billing transaction metrics"
method: POST
path: "/api/billing-transactions/metrics"
tags: ["billing_transactions"]
---

# Billing transaction metrics

`POST /api/billing-transactions/metrics`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/billing-transactions/metrics`
- Auth: HTTP bearer and API key in header `Team-SID`

Period-bound money sums over the buyer's transactions, per currency (by_currency keyed by ISO 4217, never summed across): how much was paid and taxed in the window. period {from, to} is required; filter is the search filter and every axis applies, though billed_at and created_at scope the counts only (period is the sums' one window). Gross sums: refunds are not modeled.

Contract:
- MCP tool `get_billing_transactions_metrics`, registry package `mcp.id/billing_transactions`, mount `id.billing`.
- Operation `metrics`, response envelope `metrics`.
- Flags: read only.

## Request body

- GetBillingTransactionsMetricsRequest: Request body of `get_billing_transactions_metrics`.
  - `filter` object: Scopes the rows the metrics are computed over: the search filter operators. Omit for all rows.
    - `sid` object: Transaction sid(s).
      - `eq` string
      - `in` string[]
    - `owner_user_sid` object: The buyer.
      - `eq` string
      - `in` string[]
    - `team_sid` object: The notified workspace.
      - `eq` string
      - `in` string[]
      - `is_null` boolean
    - `subscription_sid` object: One subscription's charges.
      - `eq` string
      - `in` string[]
      - `is_null` boolean
    - `paddle_transaction_id` object: Paddle's id.
      - `eq` string
      - `in` string[]
    - `invoice_number` object: Locate one invoice; is_null false = the rows with a PDF.
      - `eq` string
      - `in` string[]
      - `is_null` boolean
    - `status` object: billed | paid | completed | past_due | canceled.
      - `eq` 'billed' | 'paid' | 'completed' | 'past_due' | 'canceled'
      - `ne` 'billed' | 'paid' | 'completed' | 'past_due' | 'canceled'
      - `in` string[]
      - `nin` string[]
    - `origin` object: subscription_charge | subscription_update | one_time.
      - `eq` 'subscription_charge' | 'subscription_update' | 'one_time'
      - `ne` 'subscription_charge' | 'subscription_update' | 'one_time'
      - `in` string[]
      - `nin` string[]
    - `collection_mode` object: automatic | manual.
      - `eq` 'automatic' | 'manual'
      - `ne` 'automatic' | 'manual'
      - `in` string[]
    - `currency` object: ISO 4217.
      - `eq` string
      - `in` string[]
    - `billed_at` object: ISO 8601 bounds.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
      - `is_null` boolean
    - `created_at` object: ISO 8601 bounds.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
  - `period` object, required: Required metrics window.
    - `from` string, required: ISO 8601 UTC window start (inclusive).
    - `to` string, required: ISO 8601 UTC window end; at or after from.

## Response `200`

`metrics` success envelope.

- GetBillingTransactionsMetricsResponse
  - `success` true, required
  - `operation` 'metrics', required
  - `metrics` object, required
    - `filter` object
    - `period` object
      - `from` string, required
      - `to` string, required
    - `aggregated` object
      - `counts` object
      - `metrics` object
        - `transactions_count` integer, required: Rows with billed_at inside the window, all currencies.
        - `last_billed_at` string, nullable, required: ISO 8601 UTC, the newest billed_at in the window; null when none.
        - `by_currency` object, required: One entry per ISO 4217 code present in the window; money never crosses currencies.
    - `metrics` object
      - `transactions_count` integer, required: Rows with billed_at inside the window, all currencies.
      - `last_billed_at` string, nullable, required: ISO 8601 UTC, the newest billed_at in the window; null when none.
      - `by_currency` object, required: One entry per ISO 4217 code present in the window; money never crosses currencies.
  - `applied_filters` object
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)