Contract
- shape
- entity
- authority
- act
- evidence
- none
- subscription
- false
- permission
- any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
- idempotency
- natural
- emits
- org.settings_changed
- MCP tool
- update_org_settings
- decision_set
- approve, reject, edit, request_info
- REST
- POST https://api.containertradehq.com/v1/cap/update_org_settings
Through MCP this call returns an approval request first; see Approvals.
Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose settings change. Not a test twin: change its live org. |
| settings | settings | required | The keys to change: each to {value, locked} or to null to clear the org's own value. |
| expected_version | text | optional | 1 to 128 characters The version a previous answer carried. If the org's settings have changed since, nothing is applied and the call is refused version_conflict. Leave out to write unconditionally. |
Response
org_id· string · The org.settings· object · Every key's effective value at the org, where it came from, and where it is locked.version· string · The version of the org's own settings this call left: send it as expected_version, or as If-Match.
Full JSON Schema
{
"type": "object",
"properties": {
"org_id": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-org-id",
"description": "The org.",
"x-data-class": "operational"
},
"settings": {
"type": "object",
"properties": {
"base_currency": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"date_format": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD/MM/YYYY",
"MM/DD/YYYY"
],
"description": "How dates are shown."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"fiscal_year_start": {
"type": "object",
"properties": {
"value": {
"type": "string",
"pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$",
"description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"locale": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"en-US",
"en-GB",
"de-DE",
"fr-FR",
"es-ES",
"nl-NL"
],
"description": "The language and regional format of the interface."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_booking": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_invoice": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_order": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_purchase_order": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_release": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"numbering_series_vendor_bill": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$",
"description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"shell_last_tab": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"depots",
"sell",
"source",
"intel"
],
"description": "The tab of the app's header a person last chose, which they land on when they sign in."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"timezone": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$",
"description": "The IANA time zone times are shown in."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"units_of_measure": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"metric",
"imperial"
],
"description": "Metric or imperial weights and dimensions. An org decides it for everyone in it."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
},
"week_starts_on": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"monday",
"sunday"
],
"description": "The first day of a week in calendars and weekly reports."
},
"source": {
"type": "string",
"enum": [
"platform",
"account",
"org",
"unit",
"user"
]
},
"locked_at": {
"type": [
"string",
"null"
],
"enum": [
"platform",
"account",
"org",
"unit",
"user",
null
]
}
},
"required": [
"value",
"source",
"locked_at"
],
"additionalProperties": false
}
},
"required": [
"base_currency",
"date_format",
"fiscal_year_start",
"locale",
"numbering_series_booking",
"numbering_series_invoice",
"numbering_series_order",
"numbering_series_purchase_order",
"numbering_series_release",
"numbering_series_vendor_bill",
"shell_last_tab",
"timezone",
"units_of_measure",
"week_starts_on"
],
"additionalProperties": false,
"description": "Every key's effective value at the org, where it came from, and where it is locked.",
"x-data-class": "operational"
},
"version": {
"type": "string",
"description": "The version of the org's own settings this call left: send it as expected_version, or as If-Match.",
"x-data-class": "operational"
}
},
"required": [
"org_id",
"settings",
"version"
],
"additionalProperties": false
} Refusals
twin_mirrors_live· 422 · the org is a test twin, whose settings are its live org'ssetting_not_overridable· 422 · the platform does not let an org set this keysetting_locked· 422 · the platform or the org's account locked this keyversion_conflict· 409 · the org's settings changed since the expected version; read them again
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
- Mobile: degraded: composition
- MCP: approval required
- Voice: degraded: composition
- OneBox: no document originates a settings change
- Outbound: crosses to no counterparty
Events
org.settings_changedaudit_only