Commercial Apps overview

Product ability: Commercial Apps are the commercial operating system for your product. Ask check / consume / state instead of scattering subscription, quota, seat, and trial logic across every endpoint. Payment providers still move money; Commercial owns commercial state.

Continue with Entitlements for check, consume, and state.

Commercial Apps are Cliodot’s commercial operating system for modern software — customers, plans, features, subscriptions, entitlements, usage, seats, licenses, renewals, invoices, and payment orchestration — so your product asks one place for commercial decisions instead of rebuilding billing logic in every service.

Whether you ship SaaS, an API, AI product, CRM, ERP, mobile app, or internal enterprise software, you eventually need subscriptions, feature limits, quotas, trials, upgrades, and renewals. That work is not what makes your product unique — yet teams rebuild it over and over.

Your product asks: can this customer do this?
        ↓
Commercial App evaluates plan, usage, seats, trial, payment, …
        ↓
allowed / denied + reason + remaining limits

Your application focuses on business value. Cliodot manages commercial logic.

The problem Commercial solves#

Without a Commercial App, teams invent tables for customers, plans, features, subscriptions, invoices, payments, usage, quotas, trials, seats, and licenses — then every endpoint grows its own commercial checks:

• Has the subscription expired?
• Is this feature on the plan?
• Is quota exhausted?
• Is the trial still active?
• Do they have an available seat?

That logic spreads across services. Pricing changes become risky. Consistency becomes nearly impossible.

The solution#

Centralize every commercial decision. Your backend asks Cliodot; Commercial evaluates subscription, plan, feature availability, usage, quotas, seats, trials, expiration, grace, payment state, and licenses — and returns a single decision your app follows.

Commercial is not a replacement for Stripe, Paystack, or other payment providers. It orchestrates commercial state while capabilities process money.

What the Commercial ability gives you#

How a commercial decision works#

1. Configure plans, features, and payment methods in the portal (not the runtime SDK).
2. Create customers and subscribe them to a plan (charge through the configured capability when amount is due).
3. At runtime, call check before an action and consume when usage should increment.
4. Read state / subscription when you need the full commercial snapshot.
5. Initiate and confirm payments when charging an existing subscription or invoice; renewals follow renewal_mode.

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

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

Portal vs SDK#

Runtime client lives in the cliodot package. Base path: /commercial. Auth: x-cliodot-app-id + Bearer cak_…, or app secret.

Customer refs accept internal id or customer_key. Plan and feature refs accept id or key.

If an Identity Provider is linked to the Commercial App, present Identity credentials for runtime auth (same pattern as other Cliodot products).