Entities

Spendware APIs and SDKs are organized around a small set of domain entities. Understanding these objects makes the quickstart and API reference easier to navigate.

Entity	What It Represents	Developer Touchpoint
Organization	Account boundary for members, billing, subscriptions, provider settings, and webhooks.	Usually selected by the dashboard or management automation.
Project	Product or application boundary for customer usage and cost attribution.	Created before customers and runtime keys.
Customer	End user, tenant, account, or workspace whose usage should be tracked.	Passed in SDK runtime context or resolved through external IDs.
Customer credit grant	Immutable credit lot in customer currency that offsets spend as usage is accepted.	Created through management API or SDK to adjust customer balances; consumed by usage and optionally reversed.
Customer credit allocation	Record of credit consumption from a grant for one accepted usage event, or a reversal of unused value.	Created automatically by usage or manually through the reversal API.
User API key	Management credential for automation.	Used with management SDKs and raw API calls.
Customer key	Runtime credential scoped to a customer.	Used by provider adapters and usage logging calls.
Usage event	Recorded provider request, token, cost, or error activity.	Written by SDKs or direct usage APIs.
Pricing rule	Cost model for provider/model usage.	Used for estimates, billing, and profitability analysis.
Plan	Commercial package with pricing and limits.	Managed through billing automation or dashboard workflows.
Subscription	Organization-scoped plan enrollment.	Used by billing workflows.
Billing template	Layout and rule template for invoice documents.	Used when previewing or generating billing output.
Billing cycle	Customer billing period summary.	Read for invoices, ledger, and finance workflows.
Guardrail	Usage or cost threshold with an action.	Created to enforce limits or alert on spend.
Provider setting	Effective provider/model pricing or policy source.	Used to resolve cost and routing decisions.
Webhook endpoint	Subscriber URL and event filter configuration.	Created by integrators to receive events.
Webhook event	Durable event emitted by Spendware.	Delivered to matching webhook endpoints.
Webhook delivery	One endpoint-specific delivery job for an event.	Inspected during retries and debugging.
Webhook delivery attempt	One HTTP attempt to a subscriber.	Used to diagnose response codes and transport failures.

External IDs

External IDs are stable identifiers from your own system. Use URL-safe strings for projects, customers, and other assets when you want Spendware to map usage to records that may not have internal Spendware IDs in your runtime service.

Use external IDs consistently. Avoid passing UUID objects where SDK or API contracts expect strings.

Ownership Boundaries

Use organization-level records for account and billing ownership. Use projects to separate products, applications, environments, or major business units. Use customers for the tenant or end-customer whose usage should be charged, limited, or analyzed.