> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Fetch a subscription together with its revenue, cost, and margin in one call

# 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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
await mf.subscriptions.get(subscriptionId: string): Promise<SubscriptionDetail>
```

### Example

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/sdk/types-reference) for the complete interfaces.

### Example

```typescript theme={null}
// 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](/sdk/types-reference#revenuemetrics).

### 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](/sdk/analytics)**: all seven canonical analytics methods
* **[Types Reference](/sdk/types-reference)**: full interface definitions
* **[Customers with Revenue](/sdk/customers)**: the same pattern, but scoped to a customer