Skip to main content

​
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:
  1. Listing subscriptions
  2. Getting one subscription
  3. 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.
NameTypeDescription
customerIdstringFilter to one customer (MarginFront’s internal UUID).
customerExternalIdstringFilter to one customer by YOUR external id.
agentIdstringFilter to one agent.
statusstring"active", "paused", "cancelled", "ended", "pending".
pagenumberPage number (default 1).
limitnumberResults 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

NameTypeRequiredDescription
subscriptionIdstringyesThe subscription id.
window.startDatestringnoISO date. Defaults to 30 days ago if omitted.
window.endDatestringnoISO 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