Docs

Connect Leverprice.

One zero-dependency SDK on your server. It hands your code a number; your checkout, keys and card data never leave you.

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.

Terminal
npm install @pricepilot/sdk

Create one shared client

lib/leverprice.ts
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 servers

Show 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.

pricing page
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.00

Charge 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.

checkout
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.

Events to subscribe the Leverprice endpoint to
ProviderEvents
Stripecheckout.session.completed, checkout.session.async_payment_succeeded, charge.refunded
Polarorder.paid, order.refunded
Lemon Squeezyorder_created, order_refunded
Dodo Paymentspayment.succeeded, refund.succeeded

If you cannot connect webhooks, report purchases from your existing webhook handler. The dashboard labels this revenue as unverified.

webhook handler
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 your fallbackPrice. 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, maxPrice and currency.
  • 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() or ctx.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:

manual exposure
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.

Quote fields
FieldMeaning
priceMinor units. Use it for display and as the checkout amount.
currencyLowercase ISO 4217, from your product guard.
isFallbacktrue when the price is your fallback price.
reasonWhy this price was chosen. See below.
metadata{ pp_exp, pp_var, pp_vid, pp_sig } for the checkout, signed. Empty outside experiments.
setCookieSet-Cookie values to append, zero or more.
checkoutUrlNo-code mode: hosted checkout link for this price, or null.
Reasons
ReasonPrice
experimentThe visitor's sticky variant.
base_priceStandard price, no experiment running.
botStandard price, never enrolled.
disabledFallback: kill switch or no valid secret key.
no_configFallback: no usable signed config. Sets the outage pin.
pinned_fallbackFallback: this browser got a fallback earlier in the session.
out_of_boundsFallback: a price fell outside your min and max.
Methods
MethodWhat 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.