Choose the runtime call

The runtime call depends on what your app needs to decide. Use this rule first:

record tells Unprice what happened. consume decides whether known usage may happen now. runs hold a budget before a workload starts, for cost that is not known yet. access.check asks without changing state.

Use eventSlug for the broad event your app observed, such as completions. Use featureSlug for the specific product feature you are checking or consuming, such as ai-messages, ai-generations, or ai-tools.

Decision table

Use case	Call	Blocks paid work?	Mutates state?	Best for
Compare Unprice against existing logic	`access.check`	No	No	Shadow mode, preflight UI, entitlement checks
Enforce a known usage amount before work runs	`usage.consume`	Yes	Yes	API calls, exports, known-cost actions
Report usage without blocking the request	`usage.record`	No	Yes, asynchronously	Background metering, invoice evidence, eventual analytics
Hold a maximum for one variable-cost call	`reservations.reserve` then `reservation.settle`	Yes	Yes	LLM calls priced on tokens you cannot predict
Authorize spend across multi-step work	`runs.start` / `runs.consume` / `runs.settle` / `runs.end`	Yes	Yes	Workflows, jobs, tools, agents, custom workloads

`access.check`: ask without changing state

Use access.check when you want to know whether a customer can use a feature, but you do not want to consume usage or reserve credits.

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

if (error) {
  throw new Error(error.message);
}

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

Use it in shadow mode by logging result.allowed beside your current logic.

`usage.consume`: decide and apply now

Use usage.consume when the request path needs a synchronous commercial decision and the usage amount is known before the work runs.

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

if (error) {
  throw new Error(error.message);
}

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

usage.consume is the enforcing path for a known-cost action. Retry the same logical request with the same idempotencyKey.

`usage.record`: report for evidence

Use usage.record when the request should not wait for Unprice to decide. It queues the usage event for metering, analytics, and invoice evidence.

const { error } = await unprice.usage.record({
  customerId: "cus_1234567890",
  eventSlug: "completions",
  idempotencyKey: request.id,
  properties: {
    aiMessages: 1,
    aiGenerations: 2,
    aiTools: 3,
    inputTokens: 1840,
    outputTokens: 620,
    model: "gpt-4.1-mini"
  }
});

if (error) {
  console.error(error.message);
}

usage.record never blocks over-budget work. Do not use it as a spend gate. One async event can carry several measured properties; meters decide which property applies to each feature.

`runs`: hold a budget envelope

Use budgeted runs when a paid action unfolds over multiple steps and can spend more than expected. The run labels the workload and holds a budget before it starts. For the single-call case — one LLM request whose cost you only learn from the response — the reservations helper wraps the same operations in three lines. The operations below are for when you need the steps apart.

// Reserve spend before the workload creates cost.
const { result: run, error } = await unprice.runs.start({
  customerId: "cus_1234567890",
  budgetAmountMinor: 5000,
  idempotencyKey: `run:${request.id}`,
  workloadType: "workflow",
  workloadId: "wf_summary_123"
});

if (error) {
  throw new Error(error.message);
}

// Only start the paid work after the reservation is running.
if (run.status !== "running") {
  return new Response(`Run rejected: ${run.status}`, { status: 429 });
}

let finalStatus: "completed" | "failed" = "completed";

try {
  // Authorize known usage before starting this billable step.
  const { result: usage, error: consumeError } = await unprice.runs.consume({
    runId: run.runId,
    featureSlug: "ai-tools",
    eventSlug: "completions",
    idempotencyKey: `run:${request.id}:step:summary`,
    properties: {
      aiTools: 3,
    }
  });

  if (consumeError) {
    throw new Error(consumeError.message);
  }

  if (!usage.accepted) {
    finalStatus = "failed";
    return new Response(`Run rejected: ${usage.reason}`, { status: 429 });
  }
} catch (error) {
  finalStatus = "failed";
  throw error;
} finally {
  // Always close the run so unused reservation funds are released.
  const { error: endError } = await unprice.runs.end({
    runId: run.runId,
    status: finalStatus
  });

  if (endError) {
    console.error(endError.message);
  }
}

Call runs.consume as the workload spends and runs.end when it finishes. Unprice does not own the workload executor; it owns the budget reservation, spend decision, and evidence trail.

When actual usage is only known after work

The example above authorizes a known amount before a step runs. For variable provider usage, reserve with runs.start, run the workload, then use runs.settle to account for actual usage. Keep settlement retryable if the response is lost. Do not release the reservation in finally while incurred usage is still unaccounted for.

Shortcut

Simple request path

Use usage.consume when one request maps to a known usage amount.

Multi-step workload

Use runs.start when the workload needs a budget before it begins.

Features

Concepts

Decision table

`access.check`: ask without changing state

`usage.consume`: decide and apply now

`usage.record`: report for evidence

`runs`: hold a budget envelope

When actual usage is only known after work

Shortcut

Simple request path

Multi-step workload

​Decision table

​access.check: ask without changing state

​usage.consume: decide and apply now

​usage.record: report for evidence

​runs: hold a budget envelope

​When actual usage is only known after work

​Shortcut

Simple request path

Multi-step workload

Decision table

`access.check`: ask without changing state

`usage.consume`: decide and apply now

`usage.record`: report for evidence

`runs`: hold a budget envelope

When actual usage is only known after work

Shortcut