Margin Data API

Get margin summary

Returns total revenue, cost, and margin for the organization with warnings about unattributed data and profitability classification. Call it with a GET request to /margin-data/summary, authenticated with a restricted API key and the "revenue:read" scope.

Returns total revenue, cost, and margin for the organization with warnings about unattributed data and profitability classification. Margin requires revenue data from your connected Stripe account; connect it in your dashboard under Settings then Integrations. Note that a not-yet-connected account and a genuine zero-revenue period both return "0", so verify the connection before interpreting zeros. If no revenue has been synced for the period, revenue fields return "0", margin_percent is null (division by zero is undefined), and profitability_category reflects cost-only activity (unprofitable when cost > 0, break-even when there is no activity). Revenue is recognized on an accrual basis: each revenue record's amount is attributed across its billing period. Costs are attributed to the time the usage event occurred. Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.

Authentication and scopes

Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the revenue:read scope.

Parameters

Name	In	Type	Required	Description
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).

Response fields

Fields returned in the 200 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.

Field	Type	Description
`summary`	`object`	Organization-level margin summary for the requested period.
`total_revenue`	`string`	Total revenue for the period, decimal string in USD. Returns "0" when no revenue has been synced from your connected Stripe account.
`total_cost`	`string`	Total cost for the period, decimal string in USD.
`margin_amount`	`string`	Revenue minus cost for the period, decimal string in USD. Negative when cost exceeds revenue.
`margin_percent`	`number (double)` nullable	Margin percentage ((revenue - cost) / revenue * 100), rounded to 2 decimal places. Null when revenue for the period is zero (division by zero is undefined).
`profitability_category`	`profitable` \| `break-even` \| `unprofitable`	Profitability classification. `profitable` when the margin percentage is above 20, `break-even` between 0 and 20 (or when there is no activity at all), `unprofitable` below 0 (or when there is cost with zero revenue).
`revenue_record_count`	`number (double)`	Number of revenue records included in total_revenue.
`cost_record_count`	`number (double)`	Number of cost records included in total_cost.
`unattributed_revenue`	`string`	Revenue in the window that could not be attributed to a specific end user, decimal string in USD. Computed as a raw sum of revenue records whose recognition period starts inside the window, which is a different basis than the accrual-recognized total_revenue, so treat it as a companion diagnostic rather than a strict subset of total_revenue.
`unattributed_cost`	`string`	Cost not attributed to any end user, decimal string in USD. Included in total_cost but absent from the per-end-user breakdown.
`warnings`	`object[]`	Data-quality warnings about unattributed revenue or cost. Empty when all records are attributed.
`type`	`unattributed_revenue` \| `unattributed_cost` \| `revenue_not_connected`	Warning category. `unattributed_revenue` means revenue records exist that are not linked to any end user; `unattributed_cost` means cost records exist that are not linked to any end user. Unattributed amounts are included in organization totals but absent from the per-end-user breakdown. `revenue_not_connected` means your organization has no active Stripe revenue connection, so a `total_revenue` of "0" reflects a missing connection rather than a genuine zero-revenue period; connect Stripe to populate revenue and margin.
`count`	`number (double)`	Number of records affected by this warning. `0` for the `revenue_not_connected` warning, which reflects connection status rather than a set of records.
`message`	`string`	Human-readable description of the warning.

Error codes

Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.

Status	When it happens
`400`	Invalid query parameters. Check that start_date and end_date are valid ISO 8601 dates.
`401`	Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.
`403`	API key lacks the revenue:read scope. Use a key that includes the revenue:read scope.
`422`	Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.
`429`	Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.

Rate limits and retries

Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.

GEThttps://api.bearlumen.com/v1/margin-data/summary

Response example

Success response (200):

{
  "summary": {
    "cost_record_count": 13,
    "margin_amount": "5138.8199999999999991",
    "margin_percent": 42.5,
    "profitability_category": "profitable",
    "revenue_record_count": 5,
    "total_cost": "6952.7",
    "total_revenue": "12091.5199999999999991",
    "unattributed_cost": "431.06",
    "unattributed_revenue": "1240.12"
  },
  "warnings": [
    {
      "count": 1,
      "message": "1 revenue record(s) without customer attribution",
      "type": "unattributed_revenue"
    },
    {
      "count": 1,
      "message": "1 cost record(s) without customer attribution",
      "type": "unattributed_cost"
    },
    {
      "count": 0,
      "message": "No active Stripe revenue connection. Revenue totals reflect no connected source, not necessarily zero revenue.",
      "type": "revenue_not_connected"
    }
  ]
}