Skip to main content
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: 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. Included usage needs a billing cycle. A pay-as-you-go plan cannot carry a limit. Overage is usage beyond the included cap. draw_credits pays it from prepaid credits as each request is served, and denies the request when the balance cannot cover one unit. On a recurring plan with no limit, every counted item is paid from prepaid credits the same way. Usage is never billed to the card. Limit checks:
  1. Find the active purchase for the customer and product
  2. Read the frozen planSnapshot.options
  3. If the meter’s limit.cap is 0, allow immediately
  4. Sum usage events for that meter in the current period
  5. Compare against cap. The leftover included count is LimitResponse.remaining (-1 means unlimited)
When the request includes freeAllowance (a free-* meter), the check skips the purchase snapshot and counts usage against that cap instead. Denial sets paywallReason: 'limit_reached'. remaining / used / limit still report the free-meter remainder. See Add a free allowance to MCP tools. 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:

​
Reactivation

When a customer cancels a recurring purchase, it stays active with cancelledAt set until the period ends.
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:
  1. The existing purchase expires
  2. A new purchase is created on the requested plan
This produces purchase.expired for the old purchase and purchase.created for the new one.

​
Usage on the purchase

An SDK purchase carries the billing period of the active usage window. It does not carry counts.
used, remaining, and limit come from POST /v1/sdk/limits. That check sums usage events from periodStart to now.

​
Recurring renewal

A daily job renews purchases whose nextBillingDate has passed and that still auto-renew:
  1. Charge the recurring flat charge off-session on the card saved at checkout, when requiresPayment is true
  2. Advance nextBillingDate by the billingCycle interval only after that charge is collected
A decline, a card that needs authentication, a missing saved card, or a tax calculation failure leaves the purchase past_due and does not move nextBillingDate. Access continues while retries run. requiresPayment is derived: any positive charge or tier amount. Recurring checkout saves the card for later renewals and failed-payment retries.

​
Trial end

A trial option sets days and onEnd (convert or cancel). When the trial ends:
  • convert — charge the plan off-session and move to the paid terms. If that charge cannot be collected, the purchase becomes past_due
  • cancel — end access
A reverse trial is cancel plus an auto-assigned free plan on the product. The customer lands on that free plan when the trial ends. There is no downgrade target on the trial option.

​
Usage reset

When a period ends, included usage resets with the new periodStart. Unused included usage does not carry over. Advancing periodStart resets visible usage without deleting usage events.

​
Next steps