postSupersede commercial agreement version

Required capabilitycommercial_agreements.manage

Authentication: Send Authorization: Bearer <access_token>.

Closes an agreement version by setting status to superseded and effective_to. Requires commercial_agreements.manage and read access because the controller reads the current agreement first. effective_to must not precede effective_from or be more than five minutes in the past. An already closed version returns 409.

Parameters

Name Location Type Required Description and constraints
agreement_id path string Yes format: uuid
Idempotency-Key header string No Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128

Request

Required request body.

Request body schema

Field Type Required Description and constraints
effective_to string Yes format: date-time

Additional fields are not accepted.

Request URL

POST
POST /enterprise-commercial-agreements/{agreement_id}/supersede

Request Body

application/json
{
  "effective_to": "2026-05-01T10:00:00Z"
}

Responses

Response

application/json
{
  "agreement": {
    "client_scope": {
      "kind": "all_clients"
    },
    "created_at": "2026-05-01T10:00:00Z",
    "effective_from": "2026-05-01T10:00:00Z",
    "effective_to": "2026-05-01T10:00:00Z",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "metadata": null,
    "service_bindings": [
      {
        "fee_schedule": {
          "bps": 25,
          "model": "bps"
        },
        "service_type": "conversion"
      }
    ],
    "status": "superseded",
    "version": 1
  }
}

Resource created successfully.

Response 201 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
agreement object Yes No additional fields

Additional fields are not accepted.

application/json body.agreement
Field Type Required Description and constraints
client_scope object or object Yes
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
effective_from string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
effective_to string or null Yes
enterprise_ref string Yes pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
metadata object or null No
service_bindings object[] Yes
status "draft" / "active" / "superseded" Yes
version integer Yes maximum: 9007199254740991; exclusiveMinimum: 0

Additional fields are not accepted.

application/json body.agreement.client_scope

At least one alternative must match.

application/json body.agreement.client_scope: alternative 1
Field Type Required Description and constraints
kind "all_clients" Yes

Additional fields are not accepted.

application/json body.agreement.client_scope: alternative 2
Field Type Required Description and constraints
client_ref string Yes pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
kind "single_client" Yes

Additional fields are not accepted.

application/json body.agreement.effective_to

At least one alternative must match.

application/json body.agreement.effective_to: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.agreement.effective_to: alternative 2

Type: null.

application/json body.agreement.metadata

At least one alternative must match.

application/json body.agreement.metadata: alternative 1

Type: object.

application/json body.agreement.metadata: alternative 2

Type: null.

application/json body.agreement.service_bindings

Type: object[].

application/json body.agreement.service_bindings item
Field Type Required Description and constraints
fee_schedule object Yes No additional fields
service_type "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" Yes

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule
Field Type Required Description and constraints
minimum object or null No
maximum object or null No
bps integer or null No
fixed object or null No
metadata object or null No
model "fixed" / "bps" / "fixed_plus_bps" / "tiered" Yes
rounding_mode "half_up" / "up" / "down" or null No
tiers object[] or null No

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.minimum

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 1
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.maximum

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 1
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.bps

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 1

Type: integer. minimum: 0; maximum: 9007199254740991

application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.fixed

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 1
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.metadata

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 1

Type: object.

application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: "half_up" / "up" / "down".

application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.tiers

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1

Type: object[].

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item
Field Type Required Description and constraints
bps integer or null No
fixed object or null No
up_to_amount string or null Yes

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: integer. minimum: 0; maximum: 9007199254740991

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: string. pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: null.

application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 2

Type: null.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object or null No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer or null No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 403 schema

Content type: application/json.

See response 401 schema.

Response 404 schema

Content type: application/json.

See response 401 schema.

Response 409 schema

Content type: application/json.

See response 401 schema.

Response 500 schema

Content type: application/json.

See response 401 schema.

Response 502 schema

Content type: application/json.

See response 400 schema.

Response 503 schema

Content type: application/json.

See response 400 schema.