set_supplier_relationship · Set a supplier relationship

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`); a deactivated caller is refused first
idempotency: natural
emits: supplier_relationship.changed
MCP tool: set_supplier_relationship
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/set_supplier_relationship

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 relationship it is.
contact_id	text	required	1 to 20 characters The party: one of the org's contacts, as list_supplier_relationships names it.
relationship	one_of	required	one of partner, supplier, default partner or supplier records it; default removes the record, so the party is a supplier, or a partner when it feeds the org by API.
api_fed	boolean	optional	true records that the party feeds the org's inventory by API, false removes that; left out, the feed is unchanged. Recording a feed the party already has records it again, by the caller and now.

Response

contact_id · string · The party: the org's contact an intake names as its vendor.
name · stringnull · The contact's name.
relationship · string · How the org stands with it: the relationship recorded, else partner when it feeds the org by API, else supplier. The catalog shows its unowned inventory under this source.
recorded · boolean · Whether an org admin recorded the relationship; false when it is the default.
api_fed · boolean · Whether the party feeds the org's inventory by API, which makes it a partner unless a relationship is recorded.
set_by · stringnull · The user_id of the org admin who recorded the relationship; null when none is recorded.
set_at · stringnull · When it was recorded; null when none is.
api_fed_by · stringnull · Who last recorded the API feed: a user_id, or declaration:<ticket>; null when the party has none.
api_fed_at · stringnull · When the API feed was last recorded; null when the party has none.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "description": "The party: the org's contact an intake names as its vendor.",
      "x-data-class": "operational"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The contact's name.",
      "x-data-class": "operational"
    },
    "relationship": {
      "type": "string",
      "enum": [
        "partner",
        "supplier"
      ],
      "description": "How the org stands with it: the relationship recorded, else partner when it feeds the org by API, else supplier. The catalog shows its unowned inventory under this source.",
      "x-data-class": "operational"
    },
    "recorded": {
      "type": "boolean",
      "description": "Whether an org admin recorded the relationship; false when it is the default.",
      "x-data-class": "operational"
    },
    "api_fed": {
      "type": "boolean",
      "description": "Whether the party feeds the org's inventory by API, which makes it a partner unless a relationship is recorded.",
      "x-data-class": "operational"
    },
    "set_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "The user_id of the org admin who recorded the relationship; null when none is recorded.",
      "x-data-class": "operational"
    },
    "set_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was recorded; null when none is.",
      "x-data-class": "operational"
    },
    "api_fed_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "Who last recorded the API feed: a user_id, or declaration:<ticket>; null when the party has none.",
      "x-data-class": "operational"
    },
    "api_fed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the API feed was last recorded; null when the party has none.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "contact_id",
    "name",
    "relationship",
    "recorded",
    "api_fed",
    "set_by",
    "set_at",
    "api_fed_by",
    "api_fed_at"
  ],
  "additionalProperties": false
}

Refusals

party_not_found · 422 · the org has no contact with that id

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileF

APIF

MCPF*

VoiceD2

PushF

OneBoxN

OutboundN

MCP: approval required
Voice: degraded: confirmation
OneBox: no document originates a supplier relationship
Outbound: crosses to no counterparty

Events

supplier_relationship.changed audit_only

None.