Skip to main content
POST
Check usage limits for a customer and product

Authorizations

Authorization
string
header
required

Provider secret API key (sk_live_… / sk_test_…) supplied as a Bearer token.

Body

application/json
customerRef
string
required
Required string length: 1 - 20
productRef
string
required
Required string length: 1 - 20
freeAllowance
object

SDK-only free-tool allowance. Authenticated by the provider secret key, so cap is the provider's own declaration, not customer input.

includeCheckoutSession
boolean
meterName
string
usageType
string

Response

Limit check result

remaining
number
required

Remaining usage units before hitting the limit. -1 means unlimited (no finite cap).

Example:

997

withinLimits
boolean
required

Whether the customer is within their usage limits

Example:

true

activationRequired
boolean

True when the customer must activate a priced default plan before usage is allowed

autoRecharge
object

Per-provider auto-recharge snapshot read off the customer document. Omitted when no config exists.

balance
object

Prepaid usage balance context when the default plan is usage-based

checkoutSessionId
string

Checkout session ID if payment is required

Example:

"e3f1c2d4b6a89f001122334455667788"

checkoutUrl
string

Checkout URL if payment is required

Example:

"https://solvapay.com/customer/checkout?id=e3f1c2d4b6a89f001122334455667788"

confirmationUrl
string

Customer portal confirmation URL when activation is required (fallback when not starting checkout)

creditBalance
number

Credit balance in credits (100 credits = 1 minor currency unit), for pre-paid usage-based plans

creditsPerUnit
number

Credits deducted per metered item (for prepaid usage-based plans)

currency
string

ISO 4217 currency code for credit fields

limit
number

The effective finite cap for this meter. Present only when the backend measured a finite cap.

meterName
string

The meter name to use when tracking usage events

Example:

"requests"

needsTopUp
boolean

Access is blocked until prepaid credits cover the next unit — past an included cap with onExceed: draw_credits, or from the first unit on a recurring meter with no limit.

overage
boolean

Access is granted past the included cap and the usage is paid from prepaid credits — onExceed: draw_credits.

paywallReason
enum<string>

Authoritative paywall classification shared with Managed MCP. Present on denial responses only.

Available options:
activation_required,
topup_required,
payment_required,
limit_reached
planName
string

Display name of the active or default plan

planRef
string

Active plan reference when the customer already holds a purchase

plans
object[]

Active plans on the product available for activation or checkout

product
object

Product the limit check applies to

purchaseRef
string

Active purchase reference when the customer already holds a purchase

used
number

Consumed usage units this period. Present only when the backend measured a finite cap.