Gating features

Metering is two calls from your backend: check before an action asks whether the customer can afford it, and track after it succeeds spends the credits. The examples continue from Setup: a chat_message feature that costs 1 credit, and a customer on the Free plan.

Check, run, track

const { allowed } = await billing.checkCredits({
	customerId: user.id,
	featureId: "chat_message",
});

if (!allowed) {
	return showUpgradeOffer();
}

const message = await sendChatMessage(prompt);

await billing.trackUsage({
	customerId: user.id,
	featureId: "chat_message",
	requestId: message.id, // unique to this one use
});

decision = billing.check_credits(customer_id=user.id, feature_id="chat_message")

if not decision["allowed"]:
    return show_upgrade_offer()

message = send_chat_message(prompt)

billing.track_usage(
    customer_id=user.id,
    feature_id="chat_message",
    request_id=message.id,  # unique to this one use
)

check never spends. It returns { "allowed": true, "availableCredits": 50, "creditCost": 1 }, and allowed: false with a 200 when the balance can’t cover the cost. That’s the moment to offer an upgrade or a credit pack.
Track only what succeeded. If the action failed, don’t track it and the customer isn’t charged.
The request ID makes track idempotent. Use an ID you already store with the action: a message ID, a job ID, or a UUID you save with it. Up to 255 characters, and one ID belongs to one feature.
Retry with the same ID. If a track response is lost, send it again with the same requestId. Ledger returns the original result with "idempotent": true and charges nothing more. A new ID records a second use.

track returns what it spent:

Response

{
  "allowed": true,
  "availableCredits": 49,
  "chargedCredits": 1,
  "overageCredits": 0,
  "overageRemainingCents": null,
  "request_id": "msg_0001",
  "idempotent": false
}

Handle a refused track

check doesn’t reserve credits, so another request can spend the last credit between your check and your track. track decides again in its own transaction and can refuse with a 409. Nothing is charged, and the same request ID can succeed later, for example after the customer buys a pack.

import { TrackError } from "integrateledger/models/errors";

try {
	await billing.trackUsage({ customerId, featureId: "chat_message", requestId });
} catch (error) {
	if (!(error instanceof TrackError) || error.statusCode !== 409) {
		throw error;
	}
	console.warn(error.data$.error); // "insufficient_credits", ...
}

from integrateledger import LedgerAPIError

try:
    billing.track_usage(customer_id=customer_id, feature_id="chat_message", request_id=request_id)
except LedgerAPIError as error:
    if error.status != 409:
        raise
    print(error.code)  # "insufficient_credits", ...

`error`	Meaning	What to do
`insufficient_credits`	The balance can’t cover the cost. The body has `availableCredits` and `creditCost`.	Treat it like `allowed: false`.
`overage_cap_reached`	This use would pass the customer’s monthly overage cap.	Offer a higher cap, an upgrade or a pack.
`request_id_conflict`	The request ID was already used for a different feature.	Make IDs unique per action.

A 404 customer_not_found or feature_not_found means the customer or feature doesn’t exist with this key’s environment. Errors lists every code.

When Ledger is unreachable

The SDKs fail open by default: check is allowed and track is replayed later with the same request ID, both marked failedOpen: true, so an outage never blocks your users. Pass failOpen: false (Python fail_open=False) to handle outages yourself. Call Ledger from your backend only, never from a browser or mobile app. Usage in the dashboard lists every tracked request, charged or blocked, with the reason.

Other ways. Without an SDK, call POST /v1/check and POST /v1/track; over HTTP the request ID field is request_id.

Getting started

Concepts

Configure pricing

Customers

Migrate

Resources

Gating features

Check, run, track

Handle a refused track

When Ledger is unreachable

​Check, run, track

​Handle a refused track

​When Ledger is unreachable

Check, run, track

Handle a refused track

When Ledger is unreachable