Consume run usage - Unprice Documentation

// Authorize known usage before starting the billable step.
const { result, error } = await unprice.runs.consume({
  runId: "brun_123",
  featureSlug: "ai-tools",
  eventSlug: "completions",
  idempotencyKey: "run:req_123:step_1",
  // This call consumes only the selected feature.
  properties: {
    aiTools: 3,
    step: "summarize"
  }
});

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

if (!result.accepted) {
  console.log(result.reason);
  return;
}

console.log(result.run.remainingAmountMinor);

{
  "accepted": true,
  "reason": "accepted",
  "run": {
    "runId": "brun_123",
    "status": "running",
    "customerId": "cus_1234567890",
    "budgetAmountMinor": 5000,
    "consumedAmountMinor": 1200,
    "remainingAmountMinor": 3800,
    "currency": "USD",
    "workloadType": "workflow",
    "workloadId": "wf_summary_123",
    "traceId": "trace_123",
    "parentRunId": null
  }
}

// Authorize known usage before starting the billable step.
const { result, error } = await unprice.runs.consume({
  runId: "brun_123",
  featureSlug: "ai-tools",
  eventSlug: "completions",
  idempotencyKey: "run:req_123:step_1",
  // This call consumes only the selected feature.
  properties: {
    aiTools: 3,
    step: "summarize"
  }
});

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

if (!result.accepted) {
  console.log(result.reason);
  return;
}

console.log(result.run.remainingAmountMinor);

{
  "accepted": true,
  "reason": "accepted",
  "run": {
    "runId": "brun_123",
    "status": "running",
    "customerId": "cus_1234567890",
    "budgetAmountMinor": 5000,
    "consumedAmountMinor": 1200,
    "remainingAmountMinor": 3800,
    "currency": "USD",
    "workloadType": "workflow",
    "workloadId": "wf_summary_123",
    "traceId": "trace_123",
    "parentRunId": null
  }
}

Use runs.consume before a billable step when its usage amount is known. It applies a synchronous metered event to the run and can reject the step before it creates cost. If the provider has already incurred variable usage, use runs.settle.

// Authorize known usage before starting the billable step.
const { result, error } = await unprice.runs.consume({
  runId: "brun_123",
  featureSlug: "ai-tools",
  eventSlug: "completions",
  idempotencyKey: "run:req_123:step_1",
  // This call consumes only the selected feature.
  properties: {
    aiTools: 3,
    step: "summarize"
  }
});

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

if (!result.accepted) {
  console.log(result.reason);
  return;
}

console.log(result.run.remainingAmountMinor);

{
  "accepted": true,
  "reason": "accepted",
  "run": {
    "runId": "brun_123",
    "status": "running",
    "customerId": "cus_1234567890",
    "budgetAmountMinor": 5000,
    "consumedAmountMinor": 1200,
    "remainingAmountMinor": 3800,
    "currency": "USD",
    "workloadType": "workflow",
    "workloadId": "wf_summary_123",
    "traceId": "trace_123",
    "parentRunId": null
  }
}

Request

string

required

The budgeted run ID.

string

required

The specific feature or entitlement to consume against the running budget.

string

required

Logical key used to deduplicate this run consumption event.

string

Broad event kind configured in Unprice.

string

Optional event ID from your system.

number

Optional epoch-millisecond event timestamp.

object

Event properties used by meters. The targeted feature’s meter reads the relevant field from this object.

Response

boolean

required

Whether the run consumption event was accepted.

string

required

Decision reason. Expected values include accepted, duplicate, insufficient_budget, expired, not_running, and entitlement_denied.

object

required

Current budget run summary after the decision.

​Request

​Response

Request

Response