Billing

SolvaPay bills from the plan’s options[]. A billingCycle option sets when recurring charges run. Per-unit charge and tier options set usage rates. A limit option sets included usage. See Plans for the option catalog. Credits are only the prepaid wallet. Usage rates are money per meter noun. See Plans and billing glossary.

Billing cycles

A billingCycle option makes the plan recurring:

Field	Values	Meaning
`interval`	`week`, `month`, `year`	Recurring interval
`count`	integer ≥ 1	Every N intervals. Defaults to `1`

Quarterly is { "kind": "billingCycle", "interval": "month", "count": 3 }. There is no quarterly or custom cycle enum. The cycle drives:

When the next payment is due (nextBillingDate on the purchase)
The window for usage aggregation (periodStart to periodEnd)
When included usage resets

A plan with no billingCycle is one-time (flat charge only) or usage-based (metered, billed as usage happens).

How usage is billed

Metered usage comes from usage events on a meter. The HTTP path stays POST /v1/sdk/meter-events.

Option	Role
`charge` with `per: "unit"`	Money per counted item on `meter`
`tier`	Graduated or volume rates instead of a single per-unit charge
`limit`	Included cap. `cap: 0` is unlimited. A missing limit is pay-as-you-go
`limit.onExceed`	`block` stops access; `charge` bills overage at the per-item rate
`rollover`	Unused included usage at period end (`forfeit`, `carry_forward`, …)

Overage is usage beyond the included cap, charged per meter noun. A plan with no limit bills every counted item. Limit checks:

Find the active purchase for the customer and product
Read the frozen planSnapshot.options
If the meter’s limit.cap is 0, allow immediately
Sum usage events for that meter in the current period
Compare against cap. The leftover included count is LimitResponse.remaining (-1 means unlimited)

Wallet coverage (remainingUnits) is separate: how many metered items the credit balance still covers. Do not mix the two remainings. A provider-level minimum top-up (minTopUpMinor in SolvaPay Console settings) applies to every credit top-up and auto-recharge for that provider. Amounts below it are rejected. See Auto-recharge.

Purchase states

A purchase moves through these states:

State	Description
`trialing`	Customer is in a `trial` option period
`active`	Purchase is active and the customer has access
`active` (pending cancellation)	Active with `cancelledAt` set — access continues until period end
`cancelled`	Cancel confirmed at period end
`expired`	Purchase has ended
`past_due`	Payment failed; purchase may be suspended

Reactivation

When a customer cancels a recurring purchase, it stays active with cancelledAt set until the period ends.

import { reactivateRenewal } from '@solvapay/next'

await reactivateRenewal(request, { purchaseRef: 'pur_...' })

This clears cancelledAt and restores auto-renew. A purchase.updated webhook fires. Preconditions: the purchase must be active, have cancelledAt set, and endDate must not have passed.

Plan switching

Call activatePlan with the new plan reference. If the customer already has an active purchase on a different plan for that product:

The existing purchase expires
A new purchase is created on the requested plan

import { activatePlan } from '@solvapay/next'

const result = await activatePlan(request, {
  productRef: 'prd_myapi',
  planRef: 'pln_pro',
})

This produces purchase.expired for the old purchase and purchase.created for the new one.

Usage on the purchase

Each metered purchase can carry a usage subdocument for the current period. The source of truth is the usage timeseries, not usage.used. Limit checks sum events from periodStart to now.

{
  "usage": {
    "used": 0,
    "periodStart": "2026-01-01T00:00:00Z",
    "periodEnd": "2026-02-01T00:00:00Z",
    "resetDate": "2026-02-01T00:00:00Z",
    "overageUnits": 0,
    "overageCost": 0,
    "carriedOverUnits": 0
  }
}

Recurring renewal

A daily job renews purchases whose nextBillingDate has passed and that still auto-renew:

Charge the recurring flat charge (and any due usage) when requiresPayment is true
Advance nextBillingDate by the billingCycle interval

requiresPayment is derived: any positive charge or tier amount.

Trial end

A trial option sets days and onEnd (convert, cancel, or downgrade). When the trial ends:

convert — move to the paid plan terms
cancel — end access
downgrade — move to downgradeToPricingId

If the plan requires payment and no payment method is on file, the purchase is suspended until checkout completes.

Usage reset and rollover

When a period ends, included usage resets with the new periodStart. A rollover option can carry unused included usage forward (carry_forward) or forfeit it. Advancing periodStart resets visible usage without deleting usage events.

Next steps

Plans — compose pricing from options
Plans and billing glossary — credits, meter noun, included vs wallet remaining

Get started

Guides

Managed MCP

Plans and billing

Webhooks

Admin MCP Server

Changelog

Billing cycles

How usage is billed

Purchase states

Reactivation

Plan switching

Usage on the purchase

Recurring renewal

Trial end

Usage reset and rollover

Next steps

​Billing cycles

​How usage is billed

​Purchase states

​Reactivation

​Plan switching

​Usage on the purchase

​Recurring renewal

​Trial end

​Usage reset and rollover

​Next steps

Billing cycles

How usage is billed

Purchase states

Reactivation

Plan switching

Usage on the purchase

Recurring renewal

Trial end

Usage reset and rollover

Next steps