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+, Bun, Deno, Cloudflare Workers and edge functions.
npm install @pricepilot/sdkCreate one shared client
import { Leverprice } from "@pricepilot/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,
});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.
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.
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. 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, from your product guard. |
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. |