Core concepts

Products and plans
Plan types
Meters
Customer references
Paywall protection flow
Purchase lifecycle
Authentication flow
Usage tracking
Next steps

Products and plans

Products

A product represents the API, app, or MCP server you monetize.

Product reference (prd_...)
Name and description

Products are created in SolvaPay Console and are available for SDK integration by default.

const payable = solvaPay.payable({
  product: 'prd_myapi',
})

Plans

A plan defines pricing and access for a product.

Plan reference (pln_...)
Type: recurring, usage-based, one-time, or hybrid
Price and currency
Features
Status: active, inactive, or archived

Plans are configured as part of product setup. Customers select a plan during activation; the SDK resolves the correct plan from the customer’s purchase automatically.

Product-plan relationship

One product can have multiple plans
Plans are embedded in products
One default plan per product
Paywall checks verify plan access for a product

Plan types

Type	Description	Best for
Recurring	Fixed price billed on a cycle	SaaS subscriptions
Usage-based	Pay-per-use tracked by a meter	APIs and token services
Hybrid	Recurring fee plus usage overage	Enterprise mixed workloads
One-time	Single purchase without recurring billing	Digital goods and lifetime access

See Plans overview for full plan behavior.

Meters

Meters define what usage to measure.

Default meters: api_requests, requests, api_calls, tokens
MCP tool meters: tool:{toolName}
Custom meters for business-specific usage

Plans can enforce limits using meter data. See Meters overview for details.

Customer references

A customer reference (customerRef) maps your user identity to SolvaPay.

const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
  email: 'user@example.com',
  name: 'Jane Doe',
})

For HTTP adapters, pass customer identity in headers or auth context.

app.post('/tasks', payable.http(async req => {
  const customerRef = req.headers['x-customer-ref']
  return { ok: true, customerRef }
}))

Create-or-link semantics

When you call POST /v1/sdk/customers (or ensureCustomer / syncCustomer) with an email that already exists under this provider and the caller supplies an externalRef, the API links the externalRef onto the existing customer instead of returning 409 Conflict. This lets you idempotently adopt pre-existing SolvaPay customers when wiring up your own auth layer for the first time. Callers without externalRef still get 409 on duplicate email so the behavior is explicit.

Update a customer

Use PATCH /v1/sdk/customers/:reference to backfill or change externalRef, name, or email. Only the fields you supply are modified.

await fetch(`https://api.solvapay.com/v1/sdk/customers/${ref}`, {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${process.env.SOLVAPAY_SECRET_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ externalRef: 'auth_user_12345' }),
})

Data helpers

Three read-only endpoints power customer-facing UI without bloating check_purchase:

GET /v1/sdk/platform-config — browser-safe platform values (today: the SolvaPay Stripe publishable key used to initialize the Stripe.js client). Resolves against the sandbox or live environment matching your secret key. Call it once on page load before mounting <PaymentForm>; additions will land here rather than in /sdk/merchant.
GET /v1/sdk/merchant — provider identity safe to render in checkout and mandate copy: name, legalName, supportContact, termsUrl, privacyUrl, iconUrl (square app icon), and logoUrl (absolute URL resolved against ASSETS_BASE_URL). Used by SDK components like MandateText and CheckoutSummary.
GET /v1/sdk/payment-method?customerRef=… — returns { kind: 'card', brand, last4, expMonth, expYear } or { kind: 'none' }. The card brand and last4 are mirrored onto the Customer by the payment_intent.succeeded webhook, so this endpoint reads from SolvaPay’s database with no Stripe round-trip. Safe to poll alongside check_purchase.

All three are exposed as route-wrapper helpers in @solvapay/next (getMerchant, getProduct, getPaymentMethod), as fetch handlers in @solvapay/server/fetch, and as MCP tools in the default createSolvaPayMcpServer tool surface.

Paywall protection flow

When your handler is wrapped with payable(), the SDK:

Resolves customer reference
Checks purchase status
Checks usage limits
Executes business logic when allowed
Tracks usage
Returns a paywall response when blocked

Example blocked response

{
  error: 'PaywallError',
  message: 'Purchase required',
  checkoutUrl: 'https://checkout.solvapay.com/...',
}

Purchase lifecycle

Purchase states:

Active — customer has access
Pending cancellation — active with cancelledAt set; access continues until period end, can be reactivated
Cancelled — cancel confirmed at period end
Expired — purchase ended (period elapsed or plan switch)
Past due — payment failed; may be suspended

Cancel and reactivate renewal

import { cancelRenewal, reactivateRenewal } from '@solvapay/next'

// Cancel auto-renewal (access continues until period end)
await cancelRenewal(request, { purchaseRef: 'pur_...', reason: 'Too expensive' })

// Undo cancellation while still in active period
await reactivateRenewal(request, { purchaseRef: 'pur_...' })

Activate a plan directly

Activate a product for a customer on a specific plan without checkout. Handles free plans, credit-based activation, usage-based (PAYG) plans, and plan switching.

import { activatePlan } from '@solvapay/next'

const result = await activatePlan(request, {
  productRef: 'prd_...',
  planRef: 'pln_...',
})
// result.status: 'activated' | 'already_active' | 'topup_required' | 'payment_required' | 'invalid'

Activation policy by plan type:

Free — always activated.
Usage-based (PAYG) — topup-first: returns topup_required at zero balance and only activated once the customer’s credit balance covers at least one unit. Route the customer through a top-up (createTopupPaymentIntent) first, then re-run activatePlan to create the active purchase.
Recurring / hybrid — return payment_required when the customer has no card on file. Route them to checkout before granting access.

When the customer already has an active purchase on a different plan, activatePlan automatically expires the old purchase and creates a new one. See Purchase lifecycle management for the full guide.

Authentication flow

You keep your existing auth and map identities to SolvaPay customers. Common pattern:

Extract user ID from your auth layer
Use ID as customerRef
Sync email/name as needed
Run purchase checks

Usage tracking

Use payable() for automatic usage tracking, or record usage directly.

await solvaPay.trackUsage({
  customerRef: 'user_123',
  actionType: 'api_call',
  units: 1,
  outcome: 'success',
  productRef: 'prd_P9Q0R1S2',
})

Usage-based and hybrid plans enforce limits from meter data.

Next steps

Customer linkage (bring your own client and IdP) — ensureCustomer(externalRef) from any backend
Quick start
CLI setup
Installation
Plans overview
Meters overview

TypeScript SDK

Table of contents

Products and plans

Products

Plans

Product-plan relationship

Plan types

Meters

Customer references

Create-or-link semantics

Update a customer

Data helpers

Paywall protection flow

Example blocked response

Purchase lifecycle

Cancel and reactivate renewal

Activate a plan directly

Authentication flow

Usage tracking

Next steps

​Table of contents

​Products and plans

​Products

​Plans

​Product-plan relationship

​Plan types

​Meters

​Customer references

​Create-or-link semantics

​Update a customer

​Data helpers

​Paywall protection flow

​Example blocked response

​Purchase lifecycle

​Cancel and reactivate renewal

​Activate a plan directly

​Authentication flow

​Usage tracking

​Next steps

Table of contents

Products and plans

Products

Plans

Product-plan relationship

Plan types

Meters

Customer references

Create-or-link semantics

Update a customer

Data helpers

Paywall protection flow

Example blocked response

Purchase lifecycle

Cancel and reactivate renewal

Activate a plan directly

Authentication flow

Usage tracking

Next steps