Overview - Unprice Documentation

Use @unprice/api to put the customer money path inside your server request path: create or map a customer, check access, consume usage, reserve budgeted runs, inspect wallet credits, and explain usage or ingestion evidence. The SDK returns typed results instead of throwing for expected API errors, so every request has an explicit result or error branch.

Install

 npm install @unprice/api

 pnpm add @unprice/api

 yarn add @unprice/api

 bun install @unprice/api

Unprice API key

Create a project API key in the project settings, then provide it to the client from server-side code:

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

const unprice = new Unprice({ token: "<API_KEY>" });

Always keep your API key on the server and reset it if you suspect it has been compromised.

First runtime call

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.message);
}

console.log(result.allowed);

For request-path enforcement when the usage amount is known:

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.message);
}

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

Read Choose the runtime call before wiring a production path.

Response format

Every method returns either an error or a result field, never both and never neither.

{
  result: T // the result depends on what method you called
}

{
  error: {
    // A machine readable error code
    code: ErrorCode;

    // A link to our documentation explaining this error in more detail
    docs: string;

    // A human readable short explanation
    message: string;

    // The request id for easy support lookup
    requestId: string;
  }
}

Checking for errors

Check the error property before using result. API errors include a docs link and request ID for support lookup.

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

const unprice = new Unprice({
  token: env.UNPRICE_API_KEY,
  baseUrl: env.UNPRICE_API_URL
})

const { result, error } = await unprice.paymentMethods.list({
  customerId: "cus_123",
  provider: "stripe"
});

if (error) {
  // handle potential network or bad request error
  // a link to our docs will be in the `error.docs` field
  console.error(error.message);
  return;
}

return result

Options

The constructor accepts some options to customize the behavior:

Base Url

Run all requests against your own Unprice instance.

string

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

const unprice = new Unprice({
  //...
  baseUrl: "https://my.domain"
})

Retries

By default the client will retry on network errors, you can customize this behavior:

Hide child attributes

integer

How often to retry

(retryCount: number) => number

A function that returns how many milliseconds to wait until the next attempt is made.

const unprice = new Unprice({
  // ...
  retry: {
    attempts: 3,
    backoff: (retryCount) => retryCount * 1000
  }
})

Cache

Configure the fetch cache behavior.

As of October 2023, the cache option is not yet implemented in cloudflare workers and will throw an error if used.

string

Available options are: default, force-cache, no-cache, no-store, only-if-cached or reload.

const unprice = new Unprice({
  // ...
  cache: "no-cache"
})

Disable telemetry

By default, Unprice collects anonymous telemetry data to help us understand which versions of our SDK is being used, and in which environment. If you wish to disable this, you can do so by passing a boolean flag to the constructor:

const unprice = new Unprice({
  disableTelemetry: true
})

​Install

​Unprice API key

​First runtime call

​Response format

​Checking for errors

​Options

​Base Url

​Retries

​Cache

​Disable telemetry

Install

Unprice API key

First runtime call

Response format

Checking for errors

Options

Base Url

Retries

Cache

Disable telemetry