Book a demo

set_customer_stage

Set an org's customer stage

act entity tenant-private since 2026-10-01

Sets where a customer org is in Trade HQ's sales cycle: prospect, pilot, or customer, which clears the stage (an org with none is a customer). The org's Linear customer shows it as its status after the next customer sync, which this call asks for at once. Setting the stage it already has changes nothing. Only a customer org has a stage; a test twin follows its live org. Trade HQ staff only.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: 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.customer_stage_changed
MCP tool
set_customer_stage
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/set_customer_stage

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

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The customer org.
stageone_ofrequiredone of prospect, pilot, customer
prospect, pilot, or customer to clear the stage.

Response

  • org_id · string · The org.
  • stage · string · The org's stage now: prospect, pilot, or customer when it has none.
  • previous · string · The stage it had before the call; the same as stage when nothing changed.
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"
    },
    "stage": {
      "type": "string",
      "enum": [
        "prospect",
        "pilot",
        "customer"
      ],
      "description": "The org's stage now: prospect, pilot, or customer when it has none.",
      "x-data-class": "operational"
    },
    "previous": {
      "type": "string",
      "enum": [
        "prospect",
        "pilot",
        "customer"
      ],
      "description": "The stage it had before the call; the same as stage when nothing changed.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "stage",
    "previous"
  ],
  "additionalProperties": false
}

Refusals

  • org_not_customer · 422 · the org is not a customer org: an internal, demo, synthetic or system org reads as Internal in Linear whatever its stage, so it has none
  • org_is_twin · 422 · a test twin follows its live org; set the live org's stage
  • org_has_no_type · 422 · the org has no type row: a ported org nothing has typed yet

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 customer stage
  • Outbound: crosses to no counterparty

Events

Related

None.