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.

GET https://api.bearlumen.com/v1/margin-data/summary

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 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"
    }
  ]
}

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.