Core Concepts

Config

Your billing config lives in your project and defines the billing model Guapocado should sync.

The CLI can push the same config into sandbox or production:

npx guap push --sandbox
npx guap push --production

Customer ID

customerId is the app identity being billed or checked. It can be a user, organization, team, workspace, account, project, or any other stable ID in your product.

customerId: "org_123"

For example, user-based billing might use customerId: user.id, while organization-based billing might use customerId: organization.id.

Entitlement

An entitlement is something a customer can access or use.

await guap.has("advanced-analytics");

Guapocado uses three entitlement types: feature, meter, and limit.

Usage

Usage tracks balances for metered entitlements.

await guap.usage.balance("api-calls");
await guap.usage.consume("api-calls", 1);
await guap.usage.refund("api-calls", 1);

Limits

Limits return the effective numeric allowance for entitlements like seats, projects, or workspaces.

await guap.limit("seats");