Skip to main content

​
Subscriptions

A subscription ties a customer to a pricing plan. It’s the thing that says “starting on this date, bill this customer according to this plan’s rules.” Until a customer has a subscription, MarginFront doesn’t know how to charge them. Usage events can still be logged, but there’s no pricing rule attached. Creating a subscription is the most complex create in the whole API because it brings together four other objects: a customer, an agent, a pricing plan, and a start date. All four have to already exist before you can create the subscription.

​
The whole integration chain

Before you can create a subscription, you need (in this order):
  1. A customer. See customers.
  2. An agent. See agents.
  3. One or more signals attached to that agent. See signals.
  4. A pricing plan attached to that agent. See pricing-plans.
Once those exist, you create the subscription that glues customer ↔ plan together. After that, every usage event you log gets priced according to the subscribed plan and rolled up into an invoice at the end of the billing period.

​
Create a subscription

In plain English: Start billing a customer according to a pricing plan. You’re saying “from this date forward, charge this customer for this agent’s usage according to this plan.” Method & URL: 
POST /v1/subscriptions
Required fields:
  • name (string): a human-readable name for the subscription. Useful for identifying it in the dashboard.
  • planId (UUID string): the pricing plan’s internal ID. From the pricing plan’s create response.
  • agentId (UUID string): the agent’s internal ID. Must match the agent that the plan belongs to.
  • customerId (UUID string): the customer’s internal ID. From the customer’s create response.
  • startDate (ISO 8601 date string): when this subscription starts billing. Can be in the past (for backdating) or the future (for scheduled activation). Example: "2026-04-10T00:00:00.000Z".
Optional fields (most common):
  • status ("upcoming" | "active" | "ended", default "upcoming"): current state. Use "active" if you want billing to start immediately.
  • billingCycle ("monthly" | "yearly" | "custom", default "monthly"): how often invoices are generated.
  • billingModel ("subscription" | "usage" | "hybrid", default "subscription"): how billing is calculated.
    • "subscription" = flat recurring fee
    • "usage" = pay only for what you use
    • "hybrid" = base fee + usage
  • netTerms (number, default 30): payment terms in days after invoice issued.
Other optional fields:
  • endDate (ISO date): fixed end date if this is a time-limited subscription
  • isForever (boolean, default false): set true for subscriptions with no end date (ignores endDate)
  • subscriptionDetails (object): free-form metadata specific to this subscription
  • seatsCount (number, default 0): for per-seat pricing
  • customCycleDays (number): only when billingCycle is "custom"; how many days between invoices
  • proratedAmount (number): proration adjustment for mid-cycle starts
  • timezone (string): override for billing period calculations
  • billingDay (1-31): day of the month invoices are generated
  • invoiceMemo (string): a note that appears on every invoice for this subscription
  • metadata (object): custom key/value pairs; stored but not interpreted
Example curl call (the minimum to get a working subscription): 
curl -X POST https://api.marginfront.com/v1/subscriptions \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Pro Subscription",
    "planId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "agentId": "b47e12fa-abcd-4567-8901-234567890abc",
    "customerId": "5e7f8a3d-1234-5678-9abc-def012345678",
    "startDate": "2026-04-10T00:00:00.000Z",
    "status": "active",
    "billingCycle": "monthly"
  }'
What you get back (201 Created): 
{
  "id": "sub_9a8b7c6d-...",
  "name": "Acme Pro Subscription",
  "planId": "a1b2c3d4-...",
  "agentId": "b47e12fa-...",
  "customerId": "5e7f8a3d-...",
  "startDate": "2026-04-10T00:00:00.000Z",
  "status": "active",
  "billingCycle": "monthly",
  "createdAt": "2026-04-10T14:30:00.000Z"
}
Common errors:
  • 400 Bad Request: missing one of the required fields, or a UUID is the wrong format, or startDate isn’t a valid ISO date.
  • 404 Not Found: one of the referenced objects (customer, agent, plan) doesn’t exist in this org.
  • 409 Conflict: this customer already has an overlapping active subscription for this plan, depending on your org’s rules.
When to call this: When a customer upgrades, signs up for a paid plan, or activates a trial. This is the “billing starts now” moment.

​
Read a subscription

Method & URL: 
GET /v1/subscriptions/{subscriptionId}

​
Read a subscription with revenue

In plain English: fetch a subscription together with its revenue, cost, and margin for a time window. Use this to power subscription detail pages without two round trips. Method & URL: 
GET /v1/subscriptions/{subscriptionId}/revenue
Query parameters (all optional):
  • startDate (ISO date): start of the window, inclusive
  • endDate (ISO date): end of the window, inclusive
If you omit both, MarginFront defaults the window to the last 30 days (UTC). Example: 
curl "https://api.marginfront.com/v1/subscriptions/9a8b7c6d-.../revenue?startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: $MF_API_SECRET_KEY"
What it returns: a canonical RevenueMetrics object scoped to this subscription. Same shape as GET /v1/analytics/revenue, same math. Revenue, cost, margin, margin percent, the usage/recurring/seat/onetime breakdown, per-subscription breakdown (one row for this subscription), per-strategy breakdown. See the SDK types reference for the full RevenueMetrics shape. Using the SDK: client.subscriptions.getWithRevenue(id, window) wraps this endpoint and returns { subscription, revenue } in a single call (it fires the subscription fetch and this revenue fetch in parallel). See SDK subscriptions. Common errors:
  • 404 Not Found: no subscription with that ID exists in this org.
  • 401 Unauthorized: API key missing or wrong.

​
List subscriptions

Method & URL: 
GET /v1/subscriptions
Useful query parameters: customerId, status, agentId (check the controller for the full list).

​
Update a subscription

Method & URL: 
PATCH /v1/subscriptions/{subscriptionId}
Fields: most fields from create are updatable. The structural fields (planId, agentId, customerId) generally should NOT be changed. If a customer switches plans, it’s usually cleaner to end the current subscription and create a new one rather than mutating the existing subscription, because it preserves a clean audit trail for accounting. The billing dates can’t be changed after a subscription is created. The startDate and the current billing period’s start and end dates decide which usage each invoice picks up, so they’re locked once the subscription exists. If you include any of them in a PATCH, the request comes back 400 Bad Request with a message naming the fields you tried to move. To bill on a different schedule, end this subscription and create a new one that starts on the dates you want.

​
Update invoice dates

Method & URL: 
PATCH /v1/subscriptions/{subscriptionId}/invoice-dates
What it does: Adjusts when future invoices will be generated for this subscription. Use this for things like “customer wants to move their billing day from the 1st to the 15th.”

​
Read the subscription changelog

Method & URL: 
GET /v1/subscriptions/{subscriptionId}/changelog
What it returns: a history of all changes made to this subscription: plan changes, price updates, date adjustments, status transitions. Useful for audit trails and for customer support when someone asks “when did that price change?”

​
Using the Node SDK

// List all subscriptions
const { data } = await mf.subscriptions.list();

// Read a specific subscription
const sub = await mf.subscriptions.get("sub_9a8b7c6d-...");
Subscription CREATE is not yet wrapped by the @marginfront/sdk npm package. For now, create subscriptions through the HTTP API using curl or your language of choice. See the “Create a subscription” section above.