Concepts
Understand environments, connections, resources, operations, and usage.
Organization
The customer of AccountingKit. Every API key, environment, connection, operation, webhook, contract, and usage event belongs to exactly one organization.
Environment
Each organization has isolated test and live environments. API keys select an environment, so a
request cannot cross from test into live by changing a parameter. Test and live have separate
connections, webhook endpoints, usage, and idempotency records.
External account
Your stable identifier for your own customer or workspace. Supply it when creating a connect session. It remains provider-neutral and lets you map a connection back to your data model.
Provider app
The OAuth application your organization owns, initially a Xero developer app. On a paid plan you register its client credentials and webhook signing key once. Connections retain the provider-app identity used for authorization, so token refresh and webhook routing always use the same app.
Connection
One authorized accounting organization, initially a Xero tenant. A connection stores its provider tenant ID, display name, scopes, sync state, metadata, and encrypted OAuth token envelope.
Resource
A normalized accounting object. Lists are served from the synchronized cache for predictable latency and pagination. Point reads contact the provider and refresh the cache. Normalized records and encrypted raw provider payloads are retained for 30 days for support and reconciliation.
A zero-retention connection performs live reads without persisting any provider record, and so cannot support cached lists, synchronization, or durable automations. Choose the mode when you create the connection; it is fixed for that connection's life.
Operation
A durable unit of background work. Automations, synchronization, webhook delivery, and retention run as operations with persisted attempts, leases, exponential backoff, and terminal dead-letter state.
Idempotency
Every public write and automation requires Idempotency-Key. Keys are scoped to the organization
and environment and retained for 30 days. The same key and request replay the original response.
Plan and usage
Your plan sets a connection limit, an included volume of API operations and automation runs, and the rate that applies beyond it. Usage events are immutable and idempotent: an automation run is metered once, after it succeeds, and a retry never double-counts. Each billing period is frozen into a statement, so a past month cannot be rewritten after the fact.
Provider response bytes are metered per connection for cost visibility. They are not billable usage.