Reservations helper - Unprice Documentation

reservations is a convenience layer in the TypeScript SDK over the runs operations. It is not a separate API and has no endpoints of its own. Use it for the common shape: hold a maximum, run one piece of variable-cost work, settle what it actually cost.

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

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

// 1. Hold the most this call may cost, against the customer's budget.
const { result: reservation, error } = await unprice.reservations.reserve({
  customerId: "cus_1234567890",
  maximumAmountMinor: 10,
  idempotencyKey: messageId
});

// 2. A denial returns here. The provider is never called.
if (error) {
  return new Response("Customer budget unavailable", { status: 402 });
}

const generation = await generateText({ model, prompt, maxOutputTokens: 2_000 });

// 3. Settle actual usage. This also closes the run and releases the remainder.
const settlement = await reservation.settle({
  featureSlug: "ai-output-tokens",
  eventSlug: "completions",
  id: messageId,
  properties: { outputTokens: generation.usage.outputTokens }
});

if (settlement.error) throw settlement.error;

What each call maps to

Helper	Operations it performs
`reservations.reserve({ maximumAmountMinor, ... })`	`runs.start({ budgetAmountMinor: maximumAmountMinor, ... })`
`reservation.settle(input)`	`runs.settle({ ...input, runId })`, then `runs.end({ runId, status })`
`reservation.release()`	`runs.end({ runId, status: "canceled" })`

settle derives the end status from the settlement: completed when it is accepted or a duplicate, failed otherwise. It appends :settle to your idempotency key for the settlement call, so pass the same key you used to reserve.

The reservation object

string

The run ID. Identical to runId in the runs operations.

string

The customer the budget was held against.

integer

The amount held, in minor units. The same value runs.start reports as budgetAmountMinor.

string

Currency of the held amount.

Common mistakes

settle and release are methods on the reservation returned by reserve, not on the reservations resource. unprice.reservations.settle(...) does not exist.

Do not call runs.end after reservation.settle(). Settling already ended the run. A second end call is redundant and can conflict with the recorded status.
Do not mix the two styles on one run. If you need runs.consume for intermediate steps, or a status the helper does not produce, use the runs operations directly for that whole run.
Use release() for the abandoned path, not settle() with zero usage. release cancels the run and returns the full hold; a zero settlement records a real settlement of nothing.

When to use the `runs` operations instead

Reach past the helper when the work is multi-step or long-lived:

Start a run

Full control over workloadType, workloadId, traceId, and parentRunId.

Consume mid-run

Authorize a known amount partway through, before a billable step.

Settle usage

Account for usage while leaving the run open for more steps.

End a run

Close the run yourself and release the unused budget.

​What each call maps to

​The reservation object

​Common mistakes

​When to use the runs operations instead

Start a run

Consume mid-run

Settle usage

End a run

What each call maps to

The reservation object

Common mistakes

When to use the `runs` operations instead