Core API concepts

Organizations#

An organization is the commercial and authorization boundary. The API credential selects it; request payloads cannot override it.

Customer Accounts#

Customer Accounts are organization-scoped business entities. Integrations reference an existing active account through customer_reference; the calculation API never silently creates one.

Calculations#

A calculation is a canonical result with a public opaque identifier, source activity, governed methodology and factor lineage. Test and Live results remain environment-isolated.

External References#

external_reference is the caller's stable shipment or business identifier. It is not tenant authority. Keep it unique enough for operational support and reconciliation.

Emission Factors and versions#

factor_reference resolves an active governed factor available to the credential organization for the activity date. Responses expose safe source/version information, not private factor records.

Methodology#

The logistics engine uses tonne-kilometres and an approved kgCO2e/tkm factor. Boundary and methodology version are returned with the result.

Idempotency#

One Idempotency-Key identifies one logical write. A retry with the same material payload returns the same result; a different payload returns 409.

Usage capacity and contract periods#

Commercial usage is aggregated inside effective monthly, annual or custom contract dates. Rate limits protect throughput and do not represent billing units.

Reading customers#

Customer Accounts are organization-scoped business entities, not tenants and not memberships. Integrations resolve an existing active account by external_reference. A typo cannot silently create an account. The same reference in another organization is inaccessible.

GET /customers/{customerReference} requires customers:read. The /emissions suffix additionally requires customer-analytics:read and returns only calculations in the credential environment.