Quick start
Create a project in the dashboard. You get a test key (pp_sk_test_…) and a live key (pp_sk_live_…), shown once. Keep them on your server, for example in LEVERPRICE_SECRET_KEY. The SDK runs on Node 20+ (ESM and CommonJS), Bun, Deno, Cloudflare Workers and edge functions; Python, PHP, Ruby and Go work the same way.
npm install @leverprice/sdkCreate one shared client
import { Leverprice } from "@leverprice/sdk";
export const leverprice = new Leverprice({
secretKey: process.env.LEVERPRICE_SECRET_KEY, // server-only, never in the browser
products: {
// Local guardrails: prices outside these bounds are never returned.
pro: { currency: "usd", fallbackPrice: 1900, minPrice: 1500, maxPrice: 3900 },
},
});
leverprice.preload(); // optional, for long-lived serversShow the price
Call getPrice() where a person actually sees the price. Pass the incoming request so the SDK can read cookies, the user agent and prefetch hints, and append every Set-Cookie value it returns.
const quote = await leverprice.getPrice("pro", { request, userId: user?.id });
for (const cookie of quote.setCookie) headers.append("Set-Cookie", cookie);
render(quote.price); // minor units, e.g. 2900 = $29.00Charge the same price
Ask again where the checkout is created and charge quote.price. Never trust a price sent by the browser. Pass quote.metadata whole: it is the signed record of which price the visitor saw.
const q = await leverprice.getPrice("pro", { request });
await stripe.checkout.sessions.create({
mode: "payment",
line_items: [{ quantity: 1, price_data: { currency: q.currency, unit_amount: q.price, product_data: { name: "Pro" } } }],
metadata: q.metadata, // signed attribution: pass it whole
payment_intent_data: { metadata: q.metadata },
success_url, cancel_url,
});Python, PHP, Ruby, Go
The same SDK exists for every major server language. All of them pass one shared set of conformance tests generated from our server code, so a visitor gets the same price, cookie and attribution whichever of your services answers: a Node front end and a Python checkout share visitors.
npm install @leverprice/sdk # Node, Bun, Deno, Workers (ESM and CommonJS)
pip install leverprice # Python 3.9+
composer require leverprice/leverprice-php # PHP 8.1+
bundle add leverprice # Ruby 3.1+
go get github.com/leverprice/leverprice-go # Go 1.22+Only naming follows each language. Everything on this page applies unchanged: pass the request, append every Set-Cookie value, charge price and pass metadata whole to the checkout.
import os
from leverprice import Leverprice, apply_cookies
leverprice = Leverprice(
secret_key=os.environ.get("LEVERPRICE_SECRET_KEY"),
products={"pro": {"currency": "usd", "fallback_price": 1900, "min_price": 1500, "max_price": 3900}},
)
quote = leverprice.get_price("pro", request, user_id=user_id) # Django, Flask, FastAPI
response = apply_cookies(response, quote) # quote.price, quote.metadata; async: get_price_async$leverprice = new \Leverprice\Leverprice([
'secretKey' => getenv('LEVERPRICE_SECRET_KEY') ?: null,
'products' => ['pro' => ['currency' => 'usd', 'fallbackPrice' => 1900, 'minPrice' => 1500, 'maxPrice' => 3900]],
]);
$quote = $leverprice->getPrice('pro', ['request' => $request, 'userId' => $userId]); // Laravel, Symfony, PSR-7
$response = $quote->applyCookiesTo($response); // $quote->price, $quote->metadataLEVERPRICE = Leverprice::Client.new(
secret_key: ENV["LEVERPRICE_SECRET_KEY"],
products: { "pro" => { currency: "usd", fallback_price: 1900, min_price: 1500, max_price: 3900 } },
)
quote = LEVERPRICE.get_price("pro", request: request, user_id: current_user&.id) # Rails, Sinatra, Rack
Leverprice.write_cookies(response, quote) # quote.price, quote.metadatalp, err := leverprice.New(leverprice.Options{
SecretKey: os.Getenv("LEVERPRICE_SECRET_KEY"),
Products: map[string]leverprice.ProductGuard{"pro": {Currency: "usd", FallbackPrice: 1900, MinPrice: 1500, MaxPrice: 3900}},
})
q, err := lp.GetPrice(r.Context(), "pro", leverprice.PriceRequest{Request: r, UserID: userID})
q.WriteCookies(w) // q.Price, q.MetadataSource and framework guides: Node, Python, PHP, Ruby, Go.
Verify revenue
The recommended way is to send your provider's signed webhooks straight to Leverprice. In the dashboard open Payments, connect your provider, add the generated URL as a webhook endpoint, and paste back its signing secret. A signing secret can confirm events but cannot move money; never paste an API key.
| Provider | Events |
|---|---|
| Stripe | checkout.session.completed, checkout.session.async_payment_succeeded, charge.refunded |
| Polar | order.paid, order.refunded |
| Lemon Squeezy | order_created, order_refunded |
| Dodo Payments | payment.succeeded, refund.succeeded |
If you cannot connect webhooks, report purchases from your existing webhook handler. The dashboard labels this revenue as unverified.
await leverprice.trackPurchase({
provider: "stripe",
orderId: session.payment_intent,
amount: session.amount_total - (session.total_details?.amount_tax ?? 0),
currency: session.currency,
metadata: session.metadata,
});Use your coding agent
Open Install in your project and copy the integration prompt. It is written for Claude Code, Codex or Cursor, includes your products and price ranges, and never contains a secret: the key is referenced by its environment variable name.
AI agents (MCP)
Connect Claude, ChatGPT, Cursor or any other MCP client, and the agent can do everything you can do in the dashboard: create products, start and stop price tests, read results, lock in the winner. It acts as you, with your role, and every change appears in your audit log under the agent's name.
npx leverprice setupsetup finds Claude Code, Codex, Cursor, VS Code, Gemini CLI and Windsurf on your computer and adds the Leverprice MCP server to each. The first time an agent uses it, you approve it in the browser with one click.
Add one client by hand
Every client connects to https://app.leverprice.com/mcp and signs in through your browser. In Claude Code, finish with /mcp → Authenticate. npx leverprice setup --print prints all of these.
claude mcp add --transport http --scope user leverprice "https://app.leverprice.com/mcp"codex mcp add leverprice --url "https://app.leverprice.com/mcp" && codex mcp login leverprice{
"mcpServers": {
"leverprice": { "url": "https://app.leverprice.com/mcp" }
}
}code --add-mcp '{"name":"leverprice","type":"http","url":"https://app.leverprice.com/mcp"}'gemini mcp add --transport http --scope user leverprice "https://app.leverprice.com/mcp"In claude.ai, Claude Desktop and ChatGPT, open Settings → Connectors, choose Add custom connector and paste the same URL. Clients that only run local servers can start npx -y leverprice mcp, which signs in with npx leverprice login.
CI and cloud agents
Where there is no browser, create a personal access token in Settings → Agents. It is shown once. Set it as LEVERPRICE_TOKEN and the CLI uses it instead of the browser login. The same token works as Authorization: Bearer for the MCP server and the REST API. Give each agent or pipeline its own token, so you can revoke one without touching the rest.
export LEVERPRICE_TOKEN=lp_pat_… # from Settings → Agents
npx leverprice get_overview
curl -H "Authorization: Bearer $LEVERPRICE_TOKEN" "https://app.leverprice.com/api/me"Stay in control
- Read-only access. Choose read only when you approve an agent, create a read-only token, or run
npx leverprice login --read-only. The agent then sees only reading tools, and every change is refused. - Revoke any time. Disconnect an app or revoke a token in Settings → Agents. Its tokens stop working on the next request. Tokens can also be set to expire.
- A person grants access. Only someone signed in to the dashboard can connect or revoke an agent. Agents cannot pay: upgrading a plan returns a checkout link for you.
- Money in minor units. Every amount is an integer in minor units, as in the SDK:
1900is $19.00.
Guarantees
- Fails safe. If Leverprice is off, slow (no config within 500 ms), down, misconfigured or returns anything unexpected,
getPrice()returns yourfallbackPrice. It never throws for those reasons. - Verified config. Root key, then keyset, then config. Versions only move forward and configs expire.
- Bounded. Every price is checked against your local
minPrice,maxPriceandcurrency. - Sticky and tamper-proof. Visitors keep their price through an HMAC-signed cookie. Rotating your API key does not reshuffle them.
- Private. Visitor and user ids are hashed on your server; Leverprice only sees the hash.
- No price flips. A visitor who got the fallback during an outage keeps it for the rest of the session.
- Serverless-friendly. No timers keep your process alive. Call
await leverprice.flush()orctx.waitUntil(leverprice.flush())before a function returns.
Requests and cookies
Pass the incoming request: a Fetch Request, a Node IncomingMessage or any object with headers. quote.setCookie is an array of Set-Cookie values, usually empty; append every value to your response. Pricing several products on one page? Pass the same request object to each call so the quotes share one visitor cookie.
Regional prices
One price rarely fits every country. Turn on regional prices for a product and a visitor from India sees ₹999 where a visitor from the US sees $29. Leverprice sorts 232 countries into five tiers from World Bank price levels, converts each price at central-bank rates and lands it on a price point people in that currency are used to. You can move a tier, move a country, or type any price by hand.
export const leverprice = new Leverprice({
secretKey: process.env.LEVERPRICE_SECRET_KEY,
countryHeader: "cf-ipcountry", // the header your host sets: x-vercel-ip-country, cloudfront-viewer-country…
products: {
pro: {
currency: "usd",
fallbackPrice: 2900,
minPrice: 1900,
maxPrice: 4900,
// Currencies you can charge in, each with its own hard bounds. The dashboard writes this block.
regional: {
usd: { minPrice: 800, maxPrice: 4900 },
eur: { minPrice: 1100, maxPrice: 6000 },
inr: { minPrice: 48000, maxPrice: 230000 },
},
},
},
});
const quote = await leverprice.getPrice("pro", { request });
quote.price; // 99900
quote.currency; // "inr": pass both to your checkout
quote.country; // "IN"- You name the country header. There is no default, because a header a visitor can send themselves would let them choose their price. Or pass
countrytogetPrice()yourself. - Your code bounds every regional price. A price is served only in a currency listed under
regionaland only inside its bounds. Anything else gets your standard price. - Tests run in every country at once. A visitor keeps one variant and pays that variant's price for their country. Results show which price each tier of countries prefers.
- Prices stay put. A local-currency price moves only after the exchange rate drifts 10% away from it, and a price you set by hand never moves.
Exposures
An exposure is one person seeing an experiment price. By default the SDK logs it the first time a visitor gets a price, once per visitor and experiment. Prefetch and prerender requests are priced but not counted. If you compute the price before it is visible, use manual mode:
const quote = await leverprice.getPrice("pro", { request, exposure: "manual" });
// Later, when the price is actually on screen:
leverprice.logExposure(quote);Bots
Crawlers, link previewers, headless browsers, monitors and command-line clients get your standard price with reason bot: no assignment, no cookie, no exposure. Bring your own detection with getPrice(key, { request, bot: true }); the built-in check is exported as isBot(userAgent).
Kill switch
Set LEVERPRICE_DISABLED=1 or pass disabled: true. It is checked on every call: getPrice() returns your fallback price, sets no cookies, makes no network calls and logs nothing. A missing or malformed secret key behaves the same way.
Outages
When no usable config is available, the quote sets a 30-minute __pp_f cookie. While it is present the browser keeps your fallback price, so prices only change after 30 minutes of inactivity.
Trust chain
The SDK embeds only Leverprice's offline root public keys. Each config carries a keyset of online signing keys, signed by a root key, and must be signed by one of them. Keyset and config versions only move forward, so a revoked key cannot come back. The config refreshes every 30 seconds and right away when a response announces a newer version.
Reference
getPrice(productKey, context?) returns a quote. Context: request, cookie, userAgent, userId, exposure, bot, country. It throws only if productKey is missing from products.
| Field | Meaning |
|---|---|
price | Minor units. Use it for display and as the checkout amount. |
currency | Lowercase ISO 4217: your product's currency, or the region's. |
country | The visitor's country when known, else null. |
regional | true when the price is the regional price of that country. |
isFallback | true when the price is your fallback price. |
reason | Why this price was chosen. See below. |
metadata | { pp_exp, pp_var, pp_vid, pp_sig } for the checkout, signed. Empty outside experiments. |
setCookie | Set-Cookie values to append, zero or more. |
checkoutUrl | No-code mode: hosted checkout link for this price, or null. |
| Reason | Price |
|---|---|
experiment | The visitor's sticky variant. |
base_price | Standard price, no experiment running. |
bot | Standard price, never enrolled. |
disabled | Fallback: kill switch or no valid secret key. |
no_config | Fallback: no usable signed config. Sets the outage pin. |
pinned_fallback | Fallback: this browser got a fallback earlier in the session. |
out_of_bounds | Fallback: a price fell outside your min and max. |
| Method | What it does |
|---|---|
logExposure(quote) | Logs a manual-mode exposure. |
trackPurchase({ … }) | Reports a purchase from your webhook handler. Never throws. |
trackRefund({ … }) | Reports a refund. Never throws. |
flush() | Sends queued events. Money events are retried and kept on failure. |
refresh() / preload() | Fetches the config now, or only if none is loaded. |