Overview - Unprice Documentation

Use @unprice/api in your server request path to authorize customer spend before paid work runs. Create or map a customer, check access, consume usage, reserve a workload budget, and inspect usage or wallet evidence. The SDK returns typed results for expected API failures. Each call returns either result or error.

Install

npm install @unprice/api

pnpm add @unprice/api

yarn add @unprice/api

bun add @unprice/api

Configure the client

Create a project API key in the project settings. Keep the key in server-side configuration. Do not send it to a browser or commit it to a repository.

import { Unprice } from "@unprice/api";

const unprice = new Unprice({
  token: process.env.UNPRICE_API_KEY!
});

Rotate the key if you believe it was exposed.

First runtime call

Use access.check for a read-only shadow check:

const { result, error } = await unprice.access.check({
  customerId: "cus_1234567890",
  featureSlug: "ai-messages"
});

if (error) {
  throw new Error(`${error.code}: ${error.message}`);
}

if (!result.allowed) {
  return new Response("Feature unavailable", { status: 403 });
}

Use usage.consume when known usage must be authorized before paid work runs:

const { result, error } = await unprice.usage.consume({
  customerId: "cus_1234567890",
  featureSlug: "ai-messages",
  eventSlug: "completions",
  idempotencyKey: "req_123",
  properties: {
    aiMessages: 1,
    inputTokens: 1840,
    outputTokens: 620
  }
});

if (error) {
  throw new Error(`${error.code}: ${error.message}`);
}

if (!result.allowed) {
  return new Response("Usage limit reached", { status: 429 });
}

For variable provider usage — an LLM call whose cost is not known until it returns — hold a maximum before the work and settle what it actually cost after:

const { result: reservation, error } = await unprice.reservations.reserve({
  customerId: "cus_1234567890",
  maximumAmountMinor: 10,
  idempotencyKey: "req_123"
});

if (error) {
  return new Response("Customer budget unavailable", { status: 402 });
}

reservations is a helper over the runs operations, not a separate API. Read the reservations helper for what each call maps to, and use runs.start / runs.consume / runs.settle / runs.end directly for multi-step workloads. Read Choose the runtime call before you connect a production path.

The client also carries the budget client: unprice.budgets and unprice.budget(key). It is published on its own as @unprice/budgets. See Unprice Budgets.

Response format

Every method returns one of these shapes:

{
  result: T // The shape depends on the method.
}

{
  error: {
    code: ErrorCode;
    docs: string;
    message: string;
    requestId: string;
  }
}

Check error before you use result. The error includes a documentation link and request ID.

Client options

Base URL

Use baseUrl to send requests to your own Unprice deployment.

string

default:"https://api.unprice.dev"

const unprice = new Unprice({
  token: process.env.UNPRICE_API_KEY!,
  baseUrl: "https://api.example.com"
});

Retries

The SDK retries network and server errors by default. Configure the retry count and backoff when your request path needs a different policy.

Hide child attributes

integer

Number of retries after the first request.

(retryCount: number) => number

Function that returns the wait time, in milliseconds, before the next attempt.

const unprice = new Unprice({
  token: process.env.UNPRICE_API_KEY!,
  retry: {
    attempts: 3,
    backoff: (retryCount) => retryCount * 1000
  }
});

Cache

Use cache to configure the standard fetch cache behavior for SDK requests.

string

Use a RequestCache value such as default, no-store, or reload.

Disable telemetry

By default, the SDK sends anonymous telemetry: runtime, platform, and SDK version. Set disableTelemetry to disable this telemetry.

const unprice = new Unprice({
  token: process.env.UNPRICE_API_KEY!,
  disableTelemetry: true
});

​Install

​Configure the client

​First runtime call

​Response format

​Client options

​Base URL

​Retries

​Cache

​Disable telemetry

Install

Configure the client

First runtime call

Response format

Client options

Base URL

Retries

Cache

Disable telemetry