Subscriptions

The subscriptions resource on the SDK covers the usual list + get operations, plus one method built for subscription detail pages: getWithRevenue. It fetches the subscription and its revenue/cost/margin for a time window in one round trip. This page covers:

Listing subscriptions
Getting one subscription
Getting a subscription with its revenue numbers attached

Setup

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

`subscriptions.list`

Returns a paginated list of subscriptions with optional filters.

Signature

await mf.subscriptions.list(params?: ListSubscriptionsParams): Promise<ListSubscriptionsResponse>

Parameters

All optional.

Name	Type	Description
`customerId`	`string`	Filter to one customer (MarginFront’s internal UUID).
`customerExternalId`	`string`	Filter to one customer by YOUR external id.
`agentId`	`string`	Filter to one agent.
`status`	`string`	`"active"`, `"paused"`, `"cancelled"`, `"ended"`, `"pending"`.
`page`	`number`	Page number (default 1).
`limit`	`number`	Results per page (default 20).

Example

const { subscriptions, totalResults } = await mf.subscriptions.list({
  status: "active",
  limit: 50,
});

console.log(`${totalResults} active subscriptions`);
for (const sub of subscriptions) {
  console.log(`  ${sub.customer.name} on ${sub.plan.name}`);
}

`subscriptions.get`

Fetches one subscription by id. Returns the full subscription detail plus a usage summary for the current billing period.

Signature

await mf.subscriptions.get(subscriptionId: string): Promise<SubscriptionDetail>

Example

const sub = await mf.subscriptions.get("sub_abc123");

console.log(`Status: ${sub.status}`);
console.log(`Plan: ${sub.plan.name}`);
console.log(`Usage this period: ${sub.usage.totalQuantity}`);

`subscriptions.getWithRevenue`

What it does in plain English: fetches a subscription AND its revenue numbers for a time window, in one call. Lets you render a subscription detail page (status, plan, usage, revenue, cost, margin) without juggling two round trips. Behind the scenes the SDK fires both requests in parallel, so the wall-clock time is roughly the time of one call.

Signature

await mf.subscriptions.getWithRevenue(
  subscriptionId: string,
  window?: SubscriptionRevenueWindow,
): Promise<SubscriptionDetailWithRevenue>

Parameters

Name	Type	Required	Description
`subscriptionId`	`string`	yes	The subscription id.
`window.startDate`	`string`	no	ISO date. Defaults to 30 days ago if omitted.
`window.endDate`	`string`	no	ISO date. Defaults to today if omitted.

Pass both window fields together or neither. Omitting both defaults to the last 30 days UTC.

Response shape

interface SubscriptionDetailWithRevenue {
  subscription: SubscriptionDetail;
  revenue: RevenueMetrics;
}

The subscription field is the same shape as subscriptions.get returns. The revenue field is the same canonical shape analytics.revenue returns, scoped to this one subscription. See Types Reference for the complete interfaces.

Example

// Default window (last 30 days)
const { subscription, revenue } =
  await mf.subscriptions.getWithRevenue("sub_abc123");

console.log(`Customer: ${subscription.customer.name}`);
console.log(`Plan: ${subscription.plan.name}`);
console.log(`Status: ${subscription.status}`);

console.log(`Revenue: $${revenue.revenue.toFixed(2)}`);
console.log(`Cost: $${revenue.cost.toFixed(2)}`);
console.log(`Margin: $${revenue.margin.toFixed(2)}`);

if (revenue.marginPercent !== null) {
  console.log(`Margin %: ${revenue.marginPercent.toFixed(1)}%`);
} else {
  console.log(`Margin %: not available (no revenue in window)`);
}

console.log(`Events: ${revenue.eventCount}`);
if (revenue.eventCountWithNullCost > 0) {
  console.log(
    `  (${revenue.eventCountWithNullCost} events have no cost yet. ` +
      `Check the dashboard for unmapped models.)`,
  );
}

// Explicit window
const april = await mf.subscriptions.getWithRevenue("sub_abc123", {
  startDate: "2026-04-01",
  endDate: "2026-04-30",
});

What this returns, in plain English

subscription the usual subscription detail. Customer, agent, plan, status, billing cycle, current-period usage summary.
revenue a full canonical revenue block for this one subscription, in the window you asked for. Revenue, cost, margin, marginPercent, plus the usage/recurring/seat/onetime breakdown and a per-pricing-strategy row list.

For the full shape of RevenueMetrics, see Types Reference.

When to use this

Subscription detail pages. “Customer plan overview” dashboards. Anywhere you need the subscription AND how it’s performing in one view. For just the subscription record (no revenue math), use subscriptions.get. For revenue across many subscriptions, use analytics.revenue with no filter.

Next steps

Analytics: all seven canonical analytics methods
Types Reference: full interface definitions
Customers with Revenue: the same pattern, but scoped to a customer

Getting Started

SDK Guide

MCP Guide

Integration Recipes

Internal Code Cost Clarity

Subscriptions

Subscriptions

Setup

`subscriptions.list`

Signature

Parameters

Example

`subscriptions.get`

Signature

Example

`subscriptions.getWithRevenue`

Signature

Parameters

Response shape

Example

What this returns, in plain English

When to use this

Next steps

​Subscriptions

​Setup

​subscriptions.list

​Signature

​Parameters

​Example

​subscriptions.get

​Signature

​Example

​subscriptions.getWithRevenue

​Signature

​Parameters

​Response shape

​Example

​What this returns, in plain English

​When to use this

​Next steps

Subscriptions

Setup

`subscriptions.list`

Signature

Parameters

Example

`subscriptions.get`

Signature

Example

`subscriptions.getWithRevenue`

Signature

Parameters

Response shape

Example

What this returns, in plain English

When to use this

Next steps