cliodotDocsMain site
Sign inStart building
Commercial Apps

Entitlements and usage

Check allow/deny, consume usage, and read customer subscription state and plan intervals.

PrerequisitesCommercial Apps overview
TypeScript
const result = await commercial.check({
  customer: "acme-corp",
  feature: "api_calls",
  quantity: 1,
});

if (!result.allowed) {
  throw new Error(result.reason);
}

Maps to POST /commercial/v1/check.

Consume usage#

Omit quantity to use the feature default_increment (usually 1).

TypeScript
await commercial.consume({
  customer: "acme-corp",
  feature: "api_calls",
});

Maps to POST /commercial/v1/consume.

Customer subscription / state#

Primary read for entitlements + usage/limits + trial + seats:

TypeScript
const state = await commercial.getCustomerSubscription("acme-corp", {
  include_billing: true,
});

console.log(state.plan?.key, state.features.api_calls);

Maps to GET /commercial/v1/customers/:customerId/subscription.

Thin alias:

TypeScript
await commercial.state({ customer: "acme-corp" });

Maps to GET /commercial/v1/state?customer=… (POST /v1/state also accepted).

Plan intervals#

Plans expose interval as one of daily, weekly, monthly, quarterly, biannual, yearly, custom, lifetime, none.

When interval is custom, the plan includes interval_days (e.g. 3, 10). Subscriptions snapshot that as plan_interval_days / billing_interval_days. Usage period keys and renewals follow the interval (including custom day lengths). Plans are created in the portal, not this SDK.