Skip to main content

​
Pricing Plans

A pricing plan defines how you charge for an agent’s work. It’s the answer to “how much does this cost?” for everything that agent does. You create a pricing plan once, then attach it to a customer via a subscription. Pricing plans belong to your organization and can be linked to one or more agents. The same “Pro Plan” can be offered by multiple agents — no need to recreate it for each one.
Next step after creating a plan: Add pricing strategies — the actual rates, tiers, and charge types that determine what customers pay. See the Pricing Strategies reference for the full API.

​
Create a pricing plan

In plain English: Create a new pricing plan for your organization. Think of it like defining a “Pro Plan” or “Starter Plan” tier. Optionally link it to an agent right away. Method & URL: 
POST /v1/pricing-plans
Required fields:
  • name (string, max 255 chars) — The plan’s name. Shows up in the dashboard and on invoices. Examples: "Starter Plan", "Pro Plan", "Enterprise Custom".
Optional fields:
  • agentId (UUID string) — An agent to link this plan to. If provided, the plan is immediately available for that agent. You can link more agents later via POST /v1/pricing-plans/:id/agents.
  • description (string, max 255 chars) — Longer explanation of what’s in this plan. Useful internally.
  • featuresList (object) — Structured list of features this plan includes. Free-form, MarginFront stores but doesn’t interpret. Example: { "features": ["API Access", "Advanced Analytics", "Priority Support"] }.
  • isActive (boolean, default true) — Whether this plan is currently offered. Set to false to retire a plan without deleting it (keeps historical subscription data intact).
Example curl call: 
curl -X POST https://api.marginfront.com/v1/pricing-plans \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "description": "Professional tier for mid-market customers",
    "agentId": "b47e12fa-abcd-4567-8901-234567890abc",
    "featuresList": {
      "features": ["API Access", "Advanced Analytics", "Priority Support"]
    }
  }'
What you get back (201 Created): 
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Pro Plan",
  "description": "Professional tier for mid-market customers",
  "isActive": true,
  "agents": [
    {
      "id": "b47e12fa-abcd-4567-8901-234567890abc",
      "name": "Outreach Writer",
      "agentCode": "outreach-writer"
    }
  ],
  "createdAt": "2026-04-10T14:30:00.000Z"
}
Common errors:
  • 400 Bad Request — Missing name, or agentId isn’t a valid UUID.
  • 404 Not Found — The agentId doesn’t match any agent in this org.
When to call this: Once per pricing tier, during product setup. You don’t create a new plan per customer — you create the plan once, then subscribe many customers to it.
In plain English: Make an existing plan available through a different agent. The plan itself doesn’t change — it just shows up in another agent’s list of available plans. Method & URL: 
POST /v1/pricing-plans/{planId}/agents
Required fields:
  • agentId (UUID string) — The agent to link this plan to.
Example curl call: 
curl -X POST https://api.marginfront.com/v1/pricing-plans/a1b2c3d4-.../agents \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "c58f23ab-..." }'
Common errors:
  • 404 Not Found — Plan or agent not found in this org.
  • 409 Conflict — Plan is already linked to this agent.
In plain English: Remove a plan from an agent’s available plans. The plan still exists — it’s just no longer offered by this agent. Fails if there are active subscriptions using this plan + agent combination. Method & URL: 
DELETE /v1/pricing-plans/{planId}/agents/{agentId}
Common errors:
  • 400 Bad Request — Active subscriptions exist for this plan + agent. Cancel them first.
  • 404 Not Found — Plan not found in this org.

​
Read a pricing plan

Method & URL: 
GET /v1/pricing-plans/{planId}

​
List pricing plans

Method & URL: 
GET /v1/pricing-plans
Useful query parameters (check the controller for the full list):
  • agentId — filter to plans linked to a specific agent
  • isActive — filter to only active/inactive plans

​
Update a pricing plan

Method & URL: 
PATCH /v1/pricing-plans/{planId}
Fields: name, description, featuresList, isActive. All optional.
Note: To change which agents a plan is linked to, use the link/unlink endpoints above — not PATCH.
Heads up: Changing pricing on a plan that has active subscriptions usually does NOT retroactively re-price past usage. It only affects billing periods that haven’t been invoiced yet. If you need to correct historical billing, that’s a separate manual process — talk to the team.

​
Delete a pricing plan

Method & URL: 
DELETE /v1/pricing-plans/{planId}
What it does: Permanently removes the plan. Any active subscriptions on this plan must be canceled first — otherwise the delete fails.
Prefer isActive: false over delete. Deactivating a plan stops new subscriptions while keeping all the history intact. Deletion is for cleaning up mistakes.

​
Copy a pricing plan

Method & URL: 
POST /v1/pricing-plans/{planId}/copy
When to use it: If you have a working plan and want to create a variation (e.g., an Enterprise version of your Pro plan with the same structure but different numbers), copying is faster than rebuilding from scratch. The copy includes all the plan’s current pricing rules and agent links.

​
Using the Node SDK

import { MarginFrontClient } from "@marginfront/sdk";
const mf = new MarginFrontClient("mf_sk_...");

// Create a plan
const plan = await mf.pricingPlans.create({ name: "Pro Plan" });

// Link it to an agent
await mf.pricingPlans.linkAgent(plan.id, "agent_uuid");

// Add pricing strategies (see Pricing Strategies reference)
await mf.pricingStrategies.createBulk(plan.id, [
  {
    name: "API Calls",
    agentId: "...",
    chargeType: "usage",
    pricingModel: "credit_pool",
    signalId: "...",
    tiers: [
      { lower: 0, upper: 5000, rate: 99 },
      { lower: 5000, upper: null, rate: 0.03 },
    ],
  },
  { name: "Platform Fee", agentId: "...", chargeType: "recurring", rate: 49 },
]);

// List, update, copy, delete
const { results } = await mf.pricingPlans.list({ isActive: true });
await mf.pricingPlans.update(plan.id, { description: "Updated" });
const yearly = await mf.pricingPlans.copy(plan.id, {
  newName: "Pro Yearly",
  discount: 20,
});

​
How pricing plans fit into the whole billing chain

Organization
    |
    +---- Pricing plan ----+---- Agent A  (via agent_pricing_plans link)
           (how to price)  +---- Agent B  (same plan, different agent)
                |
          Subscription ---- Customer
          (assigns plan + agent to customer)
                |
          Usage event
          (counted against the subscription,
           priced by the plan)
Quick summary:
  1. Create an agent (the service/product)
  2. Create one or more pricing plans for your org (Starter, Pro, Enterprise)
  3. Link plans to agents — the same plan can be linked to multiple agents
  4. When a customer signs up, create a subscription tying that customer to an agent + plan
  5. As the customer uses the product, log usage events — they get priced according to the customer’s subscribed plan, and rolled up into an invoice at the end of each billing period
The pricing plan is the “rulebook” that sits in the middle.