Pricing Strategies

A pricing strategy is the actual pricing rule inside a plan. If a pricing plan is the “Pro Plan” container, strategies are the line items: “

0.01 per API call," "

49/month platform fee,” “5,000 calls for

99 then

0.03 overage.” A plan can have multiple strategies. Most plans combine a few:

A usage strategy for per-event billing (tied to a signal)
A recurring strategy for a fixed monthly fee
A onetime strategy for a setup fee
A seat_based strategy for per-user pricing

Each strategy has a charge type (what kind of charge) and a pricing model (how the math works).

Charge types

Charge type	What it means	Example
`usage`	Pay per event/unit. Requires a linked signal.	$0.01 per API call
`recurring`	Fixed fee every billing cycle	$49/month platform fee
`onetime`	One-time fee, charged on first invoice only	$500 setup fee
`seat_based`	Per-seat/per-user pricing	$10/seat/month

Pricing models

The pricing model determines how the rate math works for usage and seat_based strategies.

Flat

Every unit costs the same price. Simple multiplication.

quantity × rate = total
1,000 calls × $0.01 = $10

Graduated

Different rates for different quantity ranges — like tax brackets. Each range is charged at its own rate.

Tier 1:  0–1,000    @ $0.010/call = $10.00
Tier 2:  1,001–5,000 @ $0.008/call = $32.00
Tier 3:  5,001+      @ $0.005/call = varies

1,200 calls → (1,000 × $0.01) + (200 × $0.008) = $11.60

Volume

Total quantity determines ONE rate for ALL units. The more you use, the cheaper each unit gets — but the rate applies to everything, not just the overflow.

Tier 1:  0–999     @ $0.010/call
Tier 2:  1,000–4,999 @ $0.008/call
Tier 3:  5,000+     @ $0.005/call

1,200 calls → 1,200 × $0.008 = $9.60  (all at Tier 2 rate)

Credit Pool

Flat fee for a pool of units, then per-unit overage. You pay the pool price whether you use 1 unit or all of them. Only after exceeding the pool does the overage rate kick in.

Pool:    5,000 calls for $99 flat
Overage: $0.03/call after that

3,000 calls → $99          (pool covers it)
6,000 calls → $99 + $30    (1,000 overage × $0.03)

Tier layout for credit pool:

[
  { "lower": 0, "upper": 5000, "rate": 99 },
  { "lower": 5000, "upper": null, "rate": 0.03 }
]

The first tier’s rate is the flat pool price (not per-unit). The second tier’s rate is the per-unit overage rate.

Create pricing strategies (bulk)

In plain English: Add one or more pricing strategies to a plan. You can create all your strategies in one call — send an array. Method & URL:

POST /v1/pricing-plans/{planId}/pricing-strategies

The request body is an array of strategies (even if you’re only creating one). Required fields per strategy:

name (string) — Strategy name, e.g. “API Call Pool”
agentId (UUID) — Which agent this strategy belongs to
chargeType (string) - One of: usage, recurring, onetime, seat_based

Optional fields:

signalId (UUID) — Required if chargeType is usage. The signal this strategy prices.
pricingModel (string) - One of: flat, graduated, volume, credit_pool. Required for usage and seat_based.
billingFrequency (string) — monthly or yearly (default: monthly)
tiers (array) — Tier configuration. Each tier has lower (number), upper (number or null), rate (number).
rate (number) — Flat rate. Used when pricingModel is flat or there are no tiers.
minimumCommitment (number) — Minimum units/seats to bill for, even if actual usage is lower.
active (boolean, default true) — Whether this strategy is active.
tags (string[]) — Tags for categorization.

Example — create three strategies in one call:

curl -X POST https://api.marginfront.com/v1/pricing-plans/PLAN_ID/pricing-strategies \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "API Call Pool",
      "agentId": "AGENT_ID",
      "chargeType": "usage",
      "pricingModel": "credit_pool",
      "signalId": "SIGNAL_ID",
      "tiers": [
        { "lower": 0, "upper": 5000, "rate": 99 },
        { "lower": 5000, "upper": null, "rate": 0.03 }
      ]
    },
    {
      "name": "Platform Fee",
      "agentId": "AGENT_ID",
      "chargeType": "recurring",
      "rate": 49
    },
    {
      "name": "Setup Fee",
      "agentId": "AGENT_ID",
      "chargeType": "onetime",
      "rate": 500
    }
  ]'

What you get back (201 Created): Array of created strategies with IDs. Using the SDK:

const strategies = await client.pricingStrategies.createBulk("PLAN_ID", [
  {
    name: "API Call Pool",
    agentId: "AGENT_ID",
    chargeType: "usage",
    pricingModel: "credit_pool",
    signalId: "SIGNAL_ID",
    tiers: [
      { lower: 0, upper: 5000, rate: 99 },
      { lower: 5000, upper: null, rate: 0.03 },
    ],
  },
  {
    name: "Platform Fee",
    agentId: "AGENT_ID",
    chargeType: "recurring",
    rate: 49,
  },
]);

Common errors:

400 Bad Request — Missing required fields, or signalId not provided for a usage strategy.
404 Not Found — Plan, agent, or signal not found in this org.

List pricing strategies

Method & URL:

GET /v1/pricing-plans/{planId}/pricing-strategies

Query parameters:

chargeType - Filter by charge type (usage, recurring, onetime, seat_based)
pricingModel — Filter by pricing model (flat, graduated, volume, credit_pool)
active — Filter by active status (true or false)
page, limit — Pagination (default: page 1, limit 10)

Using the SDK:

const { results } = await client.pricingStrategies.list("PLAN_ID", {
  chargeType: "usage",
  active: true,
});

Get a pricing strategy

Method & URL:

GET /v1/pricing-plans/{planId}/pricing-strategies/{strategyId}

Using the SDK:

const strategy = await client.pricingStrategies.get("PLAN_ID", "STRATEGY_ID");

Update a pricing strategy

Method & URL:

PATCH /v1/pricing-plans/{planId}/pricing-strategies/{strategyId}

All fields are optional. Only send what you want to change. Example — change the overage rate on a credit pool strategy:

curl -X PATCH https://api.marginfront.com/v1/pricing-plans/PLAN_ID/pricing-strategies/STRATEGY_ID \
  -H "x-api-key: mf_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tiers": [
      { "lower": 0, "upper": 5000, "rate": 99 },
      { "lower": 5000, "upper": null, "rate": 0.05 }
    ]
  }'

Using the SDK:

const updated = await client.pricingStrategies.update(
  "PLAN_ID",
  "STRATEGY_ID",
  {
    tiers: [
      { lower: 0, upper: 5000, rate: 99 },
      { lower: 5000, upper: null, rate: 0.05 },
    ],
  },
);

Bulk update + create

In plain English: Update existing strategies and create new ones in a single call. Useful when reconfiguring an entire plan. Method & URL:

PATCH /v1/pricing-plans/{planId}/pricing-strategies

Request body:

{
  "strategies": {
    "new": [
      {
        "name": "New Fee",
        "agentId": "...",
        "chargeType": "recurring",
        "rate": 29
      }
    ],
    "update": [{ "id": "EXISTING_ID", "rate": 59 }]
  }
}

Delete a pricing strategy

Method & URL:

DELETE /v1/pricing-plans/{planId}/pricing-strategies/{strategyId}

Soft-delete (sets deletedAt, doesn’t destroy data). Using the SDK:

await client.pricingStrategies.delete("PLAN_ID", "STRATEGY_ID");

How strategies fit in the billing chain

Pricing Plan ("Pro Plan")
    |
    +---- Strategy: "API Call Pool"    (usage, credit_pool)
    |       └── Signal: "api_calls"
    +---- Strategy: "Platform Fee"     (recurring, $49/mo)
    +---- Strategy: "Setup Fee"        (onetime, $500)
    +---- Strategy: "Seat License"     (seat_based, flat, $10/seat)
    |
    Subscription (assigns this plan to a customer + agent)
    |
    Invoice (sums all strategy charges for the billing period)

Resources

Reference

Pricing Strategies

Pricing Strategies

Charge types

Pricing models

Flat

Graduated

Volume

Credit Pool

Create pricing strategies (bulk)

List pricing strategies

Get a pricing strategy

Update a pricing strategy

Bulk update + create

Delete a pricing strategy

How strategies fit in the billing chain

​Pricing Strategies

​Charge types

​Pricing models

​Flat

​Graduated

​Volume

​Credit Pool

​Create pricing strategies (bulk)

​List pricing strategies

​Get a pricing strategy

​Update a pricing strategy

​Bulk update + create

​Delete a pricing strategy

​How strategies fit in the billing chain

Pricing Strategies

Charge types

Pricing models

Flat

Graduated

Volume

Credit Pool

Create pricing strategies (bulk)

List pricing strategies

Get a pricing strategy

Update a pricing strategy

Bulk update + create

Delete a pricing strategy

How strategies fit in the billing chain