> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unprice.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> TypeScript client for the Unprice public API.

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

<CodeGroup>
  ```bash npm theme={null}
   npm install @unprice/api
  ```

  ```bash pnpm theme={null}
   pnpm add @unprice/api
  ```

  ```bash yarn theme={null}
   yarn add @unprice/api
  ```

  ```bash bun theme={null}
   bun install @unprice/api
  ```
</CodeGroup>

## Unprice API key

Create a project API key in the [project settings](https://app.unprice.com), then provide it to the
client from server-side code:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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](/quickstart/choose-operation) before wiring a production path.

## Response format

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

<CodeGroup>
  ```ts Success theme={null}
  {
    result: T // the result depends on what method you called
  }
  ```

  ```ts Error theme={null}
  {
    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;
    }
  }
  ```
</CodeGroup>

## Checking for errors

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

```ts theme={null}
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.

<ParamField body="baseUrl" type="string" default="https://api.unprice.dev">
  ```ts theme={null}
  const unprice = new Unprice({
    //...
    baseUrl: "https://my.domain"
  })
  ```
</ParamField>

### Retries

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

<ParamField body="retry">
  <Expandable defaultOpen>
    <ParamField body="attempts" type="integer">
      How often to retry
    </ParamField>

    <ParamField body="backoff" type="(retryCount: number) => number">
      A function that returns how many milliseconds to wait until the next attempt is made.
    </ParamField>
  </Expandable>
</ParamField>

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

### Cache

Configure the `fetch` cache behavior.

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

<ParamField body="cache" type="string">
  Available options are: `default`, `force-cache`, `no-cache`, `no-store`, `only-if-cached` or `reload`.
</ParamField>

```ts theme={null}
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:

```ts theme={null}
const unprice = new Unprice({
  disableTelemetry: true
})
```