> ## 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. # Pricing Plans > Set up how much you charge per unit of each signal # 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](/api-reference/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:** ```bash theme={null} 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`):** ```json theme={null} { "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. *** ## Link a plan to an agent **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:** ```bash theme={null} 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. *** ## Unlink a plan from an 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 ```typescript theme={null} 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.