Skip to main content
This guide makes an async function paid and serves it from a web route. Each call is checked against the customer’s plan. An allowed call runs and is recorded as usage. A call that isn’t allowed raises PaywallError, and the route answers 402 with a checkout link.

Prerequisites

  • The Python SDK installed, with SOLVAPAY_SECRET_KEY and SOLVAPAY_PRODUCT_REF set. See Installation.
  • Starlette and uvicorn: pip install starlette uvicorn. FastAPI works the same way.

Make a function paid

1

Write the app

Save this as app.py:
2

Run it

3

Call it

While the customer is within their plan, you get the summary. Once they aren’t, you get a 402:
The x-user-id header keeps the example short. In your app, take the customer from your own session or token, never from a value the caller can set.

How payable() works

  • customer_ref is your own user id. It must be passed as a keyword argument. SolvaPay creates the customer on first use and links it to that id. A call without customer_ref raises SolvaPayError with code identity_required.
  • payable() wraps async functions only.
  • The product comes from SOLVAPAY_PRODUCT_REF, or @solvapay.payable(product="prd_..."). It’s resolved when the decorator runs, so set the variable before you import the module.
  • Use meter="..." to bill a meter other than the default requests, and customer_ref_arg="user_id" when your function names the customer argument differently.
  • If the function raises, the call is recorded as failed and the exception reaches you unchanged.

Show the paywall

PaywallError.gate is a dict with the API’s camelCase keys. The fields you’ll use most:
The message is written for MCP clients and names the account tool. In a web app, show your own copy and link to checkoutUrl.

Next steps