Commercial Agreements

A CommercialAgreement is the versioned configuration that controls how fees are applied to operations inside a tenant scope. The platform models two distinct levels: a platform-level agreement between the platform and the enterprise, and an enterprise-level agreement between the enterprise and its end clients.

What Belongs Here

Two agreement levels apply at different boundaries:

  • PlatformCommercialAgreement binds services to a providing platform operator and defines platform fees for the enterprise. Platform staff manage this configuration.
  • EnterpriseCommercialAgreement defines service fee schedules for all clients of an enterprise or one named client. client_scope selects all_clients or single_client.

Each version carries version, status, effective_from, effective_to, and service_bindings. Fee schedules support fixed, basis-point, fixed-plus-basis-point, and tiered models, with optional minimum and maximum fees. Money values use value and currency.

Managing Enterprise Versions

Action Public endpoint
List versions for an enterprise and client scope GET /enterprise-commercial-agreements
Read a version by ID GET /enterprise-commercial-agreements/:id
Create a version with an effective start and service bindings POST /enterprise-commercial-agreements
End an existing version's effective window POST /enterprise-commercial-agreements/:id/supersede

Use a new version for a new fee schedule. Superseding records effective_to on the existing version; it does not submit the replacement schedule. The caller must have the required commercial-agreement capabilities and scope coverage for the enterprise and client selection.

Fees On Operations

The agreement configures pricing. An operation's fee summary records the fees applied to that operation. Use pricing previews to inspect the current economics, and the operation response to reconcile the resulting charges.