Plans

A plan is pricing you attach to a product. It is a single type with an ordered options[] list. What a plan “is” — recurring, usage-based, hybrid, or one-time — is a derived label, not a field you send. Console templates (Recurring, Usage-based, One-time, Hybrid, Blank) only seed that list. They are not persisted types. Money on options is integer minor units of the option’s currency (cents for USD). Usage rates in the console are money per meter noun ($0.02 / request). Credits are only the prepaid wallet — see Plans and billing glossary.

How a plan is stored

Product (prd_myapi)
├── Plan: Free (pln_abc123) — billingCycle + $0 flat charge + autoAssigned
├── Plan: Pro (pln_def456) — billingCycle + $19 flat charge
└── Plan: Usage (pln_ghi789) — per-request charge + included limit

Plans live on the product. There is no separate plans collection, no plan type discriminator, and no subtype fields such as setupFee, creditsPerUnit, basePrice, or freeUnits.

You send	The API derives
`options[]`	`planType` / `type` (`recurring`, `usage-based`, `hybrid`, `one-time`)
Positive charge or tier amounts	`requiresPayment`
`kind: "hidden"`	Hidden from customer surfaces
`kind: "autoAssigned"`	Product fallback / pre-selected plan

planType on some responses is a back-compat label for analytics and UI. Do not send type when you create or update a plan.

Option catalog

Each option is discriminated on kind. Optional label is allowed on every kind.

`charge`

A price. per is flat, unit, or seat. Per-unit charges require meter.

Field	Type	Description
`amountMinor`	`number`	Amount in `currency`, integer minor units
`currency`	`string`	ISO 4217 code
`per`	`enum`	`flat`, `unit`, or `seat`
`meter`	`string`	Required when `per` is `unit`
`oneTime`	`boolean`	Setup fee. Only valid on `per: "flat"`

A plan offers several currencies by holding multiple charges of the same role that differ only by currency. Amounts are set per currency, not FX-converted.

`billingCycle`

Makes the plan recurring. Omit it for one-time or pay-as-you-go usage.

Field	Type	Description
`interval`	`enum`	`week`, `month`, or `year`
`count`	`number`	Every N intervals. Defaults to `1`. Quarterly is `month` + `count: 3`
`anchor`	`string`	Optional first cycle boundary (ISO datetime). Defaults to activation time

`tier`

Volume or graduated rates for a meter. The embedded charge is per-unit. One option per band — see Tiered for a worked example and for how the two modes differ.

Field	Type	Description
`from`	`number`	Start of the band, inclusive. The first band starts at `0`
`to`	`number \| null`	End of the band, exclusive — the next band starts here. `null` is the unbounded top band
`mode`	`enum`	`graduated` or `volume`. Every band on a meter must use the same one
`charge`	`object`	Embedded per-unit charge (`amountMinor`, `currency`, `per: "unit"`, `meter`). Its `meter` is what groups the band

`limit`

Included cap for a meter. Copy says included. cap: 0 means unlimited.

Field	Type	Description
`cap`	`number`	Included count. `0` is unlimited
`scope`	`enum`	`billing_period`, `lifetime`, or `rolling_window`
`meter`	`string`	Meter this cap applies to
`onExceed`	`enum`	`block`, `throttle`, `charge`, `notify`, `top_up`, or `auto_upgrade`
`windowDays`	`number`	Required when `scope` is `rolling_window`
`onExceedPricingId`	`string`	Target plan when `onExceed` is `auto_upgrade`

A missing limit is pay-as-you-go (every counted item is billed). It is not unlimited.

`entitlement`

A feature flag or numeric benefit on the plan. The console label is Benefit. The wire kind stays entitlement.

Field	Type	Description
`feature`	`string`	Feature key
`value`	`boolean \| number \| string`	Granted value
`scope`	`string`	Optional scope

`trial`

Field	Type	Description
`days`	`number`	Trial length
`onEnd`	`enum`	`convert`, `cancel`, or `downgrade`
`requireCard`	`boolean`	Collect a card before the trial starts
`downgradeToPricingId`	`string`	Target plan when `onEnd` is `downgrade`

`discount`

Field	Type	Description
`mode`	`enum`	`percentage` or `fixed`
`value`	`number`	Percentage: basis points (`5000` = 50%). Fixed: minor units
`currency`	`string`	Required when `mode` is `fixed`
`duration`	`enum`	`once`, `repeating`, or `forever`
`cycles`	`number`	Required when `duration` is `repeating`
`appliesTo`	`enum`	`recurring`, `setup`, `usage`, or `all`

`rollover`

What happens to unused included usage at period end.

Field	Type	Description
`meter`	`string`	Meter to roll
`treatment`	`enum`	`forfeit`, `carry_forward`, `credit_units`, or `credit_money`
`capUnits`	`number`	Optional carry-forward cap
`maxCycles`	`number`	Optional max periods unused usage can carry
`rateMinor`	`number`	Per-item value when `treatment` is `credit_money`
`currency`	`string`	Required when `treatment` is `credit_money`

Markers

Kind	What it does
`autoAssigned`	Product fallback / pre-selected plan. At most one per product
`hidden`	Off every customer-facing surface. Grant only by direct assignment

Markers are catalog metadata. They do not change pricing math.

Common compositions

These labels are derived. Send the options, not "type": "…".

Recurring — flat charge + billing cycle

{
  "name": "Pro",
  "currency": "USD",
  "options": [
    { "kind": "billingCycle", "interval": "month" },
    { "kind": "charge", "per": "flat", "amountMinor": 1900, "currency": "USD" },
    { "kind": "trial", "days": 14, "onEnd": "convert" }
  ]
}

A $0 flat charge plus autoAssigned is a free recurring fallback.

Usage-based — per-unit charge, no billing cycle

{
  "name": "Pay as you go",
  "currency": "USD",
  "options": [
    {
      "kind": "charge",
      "per": "unit",
      "amountMinor": 2,
      "currency": "USD",
      "meter": "requests"
    },
    {
      "kind": "limit",
      "cap": 1000,
      "scope": "billing_period",
      "meter": "requests",
      "onExceed": "charge"
    }
  ]
}

amountMinor: 2 is $0.02 per request. Do not send creditsPerUnit as a plan field. Minimum top-up is a provider setting (minTopUpMinor in SolvaPay Console settings), not a plan option. See Auto-recharge.

Tiered — banded rates for one meter

A tier option is one band. Send one per band, contiguous and covering the whole range: each band’s from is the previous band’s to, the first starts at 0, and exactly one band — the last — sets to: null for everything above it.

{
  "name": "Scale",
  "currency": "USD",
  "options": [
    {
      "kind": "tier",
      "from": 0,
      "to": 1000,
      "mode": "graduated",
      "charge": { "per": "unit", "amountMinor": 2, "currency": "USD", "meter": "requests" }
    },
    {
      "kind": "tier",
      "from": 1000,
      "to": null,
      "mode": "graduated",
      "charge": { "per": "unit", "amountMinor": 1, "currency": "USD", "meter": "requests" }
    }
  ]
}

Every band in a group shares one mode, and the two modes price the same usage differently. For 1,500 requests against the plan above:

`mode`	What it charges	Total
`graduated`	Each band prices the requests that fall inside it: 1,000 × $0.02 + 500 ×$ 0.01	$25.00
`volume`	The total picks one band and prices everything at that rate: 1,500 × $0.01	$15.00

Group bands by meter. A plan can tier two meters by sending two groups, each contiguous in its own charge.meter. Bands are grouped by that meter, never by their position in options[]. A meter is priced by bands or by a charge with per: "unit" — not both. Both are per-request prices on the same requests, so sending both is rejected. Bands and limit compose: the cap is the included count, and the bands price the overage above it. A plan with "cap": 1000 and the bands above includes the first 1,000 requests and prices request 1,001 onward from the band it lands in. Set onExceed: "charge" so exceeding the included count bills rather than blocks. Tiered usage on a recurring plan bills at the end of each billing period. On a plan with no billing cycle it is charged in real time against the credit balance.

Hybrid — recurring fee plus metered usage

{
  "name": "Pro plus usage",
  "currency": "USD",
  "options": [
    { "kind": "billingCycle", "interval": "month" },
    { "kind": "charge", "per": "flat", "amountMinor": 4900, "currency": "USD" },
    {
      "kind": "charge",
      "per": "unit",
      "amountMinor": 2,
      "currency": "USD",
      "meter": "requests"
    },
    {
      "kind": "limit",
      "cap": 1000,
      "scope": "billing_period",
      "meter": "requests",
      "onExceed": "charge"
    }
  ]
}

Bands replace the flat per-unit charge rather than joining it — a meter is priced one way or the other. The derived label is still hybrid when a billing cycle and a meter are both present.

One-time — flat charge, no cycle

{
  "name": "Lifetime",
  "currency": "USD",
  "options": [
    { "kind": "charge", "per": "flat", "amountMinor": 9900, "currency": "USD" }
  ]
}

Identity fields

These sit on the plan next to options[]:

Field	Type	Description
`reference`	`string`	Auto-generated (`pln_XXXXXXXX`)
`name`	`string`	Plan name
`description`	`string`	Optional
`currency`	`string`	Display currency. Defaults from the first money option
`status`	`enum`	`active`, `inactive`, or `archived`
`features`	`object`	Optional feature flags
`metadata`	`object`	Optional provider metadata
`maxActiveUsers`	`number`	Optional concurrent-user cap
`accessExpiryDays`	`number`	Optional access lifetime
`taxBehavior`	`enum`	`auto`, `inclusive`, or `exclusive`

Hidden and auto-assigned plans

Add { "kind": "hidden" } to keep a plan off checkout, the SDK catalog, and MCP. Customers cannot self-select it. Assign it from the SolvaPay Console customer page. Direct assignment stamps the purchase with admin_assignment. Add { "kind": "autoAssigned" } to make the plan the product fallback (MCP tool access when no tool-specific plan is set, and new-customer pre-selection). Setting a new auto-assigned plan clears the marker on the previous one.

Plans are embedded in products

A product owns its plans. Create, update, and delete them through the product. Plan references are globally unique.

Plan API

All plan endpoints are scoped to a product. Send options[]. Do not send type, creditsPerUnit, basePrice, setupFee, or freeUnits.

Method	Endpoint	Description
`GET`	`/sdk/products/:productRef/plans`	List plans for a product
`GET`	`/sdk/products/:productRef/plans/:planRef`	Get a single plan
`POST`	`/sdk/products/:productRef/plans`	Create a plan
`PUT`	`/sdk/products/:productRef/plans/:planRef`	Update a plan
`DELETE`	`/sdk/products/:productRef/plans/:planRef`	Delete a plan

PUT replaces the full options[] when you send it.

Plans and MCP servers

Server default plan — defaultPlanRef on an MCP server uses the product’s auto-assigned plan when no tool-specific plan is set
Per-tool plan assignments — tools can reference plans via planIds

When plans change, MCP server configurations sync automatically.

Purchase snapshots

A purchase freezes the plan’s options[] at buy time. Changing the live plan does not change existing purchases.

{
  "planSnapshot": {
    "reference": "pln_abc123",
    "name": "Pro",
    "price": 1900,
    "currency": "USD",
    "options": [
      { "kind": "billingCycle", "interval": "month" },
      { "kind": "charge", "per": "flat", "amountMinor": 1900, "currency": "USD" }
    ]
  }
}

price and planType on the snapshot are derived from those options.

Next steps

Billing — cycles, usage, trials, and renewals
Plans and billing glossary — credits, meter noun, included vs wallet remaining
Usage events — record usage from the TypeScript SDK

Get started

Guides

Managed MCP

Plans and billing

Webhooks

Admin MCP Server

Changelog

How a plan is stored

Option catalog

`charge`

`billingCycle`

`tier`

`limit`

`entitlement`

`trial`

`discount`

`rollover`

Markers

Common compositions

Recurring — flat charge + billing cycle

Usage-based — per-unit charge, no billing cycle

Tiered — banded rates for one meter

Hybrid — recurring fee plus metered usage

One-time — flat charge, no cycle

Identity fields

Hidden and auto-assigned plans

Plans are embedded in products

Plan API

Plans and MCP servers

Purchase snapshots

Next steps

​How a plan is stored

​Option catalog

​charge

​billingCycle

​tier

​limit

​entitlement

​trial

​discount

​rollover

​Markers

​Common compositions

​Recurring — flat charge + billing cycle

​Usage-based — per-unit charge, no billing cycle

​Tiered — banded rates for one meter

​Hybrid — recurring fee plus metered usage

​One-time — flat charge, no cycle

​Identity fields

​Hidden and auto-assigned plans

​Plans are embedded in products

​Plan API

​Plans and MCP servers

​Purchase snapshots

​Next steps

How a plan is stored

Option catalog

`charge`

`billingCycle`

`tier`

`limit`

`entitlement`

`trial`

`discount`

`rollover`

Markers

Common compositions

Recurring — flat charge + billing cycle

Usage-based — per-unit charge, no billing cycle

Tiered — banded rates for one meter

Hybrid — recurring fee plus metered usage

One-time — flat charge, no cycle

Identity fields

Hidden and auto-assigned plans

Plans are embedded in products

Plan API

Plans and MCP servers

Purchase snapshots

Next steps