set_catalog_price · Set a catalog price

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: keyed
emits: catalog.price_set
MCP tool: set_catalog_price
decision_set: approve, reject, edit
REST: POST https://api.containertradehq.com/v1/cap/set_catalog_price

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose catalog it prices.
group_key	catalog_group_key	optional	The group or split to price, as summarize_catalog answers it: market, size, type and condition (each null where the group's is), and splits, the split values beneath it as [{attribute, value}]. Every line under it is priced. Give this or catalog_id, not both.
catalog_id	text	optional	1 to 1000 characters One catalog line to price. Its price is its own from then on: a later group price skips it unless that call says replace. Give this or group_key, not both.
wholesale	catalog_price	optional	The Wholesale price to set, as a string: up to 11 digits and 4 decimal places. Give this, retail or both.
retail	catalog_price	optional	The Retail price to set, as a string: up to 11 digits and 4 decimal places. Give this, wholesale or both.
replace	boolean	optional	With group_key: also write lines whose price is their own (set on the line, in the popout, or changed since the last group price). Absent or false, those are kept and counted as skipped.

Response

price_set_id · string · This call's id, derived from its Idempotency-Key.
org_id · string · The org whose catalog it priced.
source · string · group (a group or split was priced) or line (one line was).
group_key · objectnull · The group key priced, as read back: {market, size, type, condition, splits}. Null for a line.
catalog_id · stringnull · The line priced. Null for a group.
lines · integer · The catalog lines the call covered.
written · integer · Lines at least one price was written to.
skipped · integer · Lines at least one price was kept on, because the line's price is its own.
replaced · integer · Lines whose own price was replaced, with replace.
prices · value · Per price given (wholesale, retail): the amount set, as a 4-place decimal, and the lines written, skipped and replaced.
set_by · string · Who set it.
set_at · string · When.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "price_set_id": {
      "type": "string",
      "pattern": "^[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}$",
      "format": "uuid",
      "description": "This call's id, derived from its Idempotency-Key.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org whose catalog it priced.",
      "x-data-class": "operational"
    },
    "source": {
      "type": "string",
      "description": "group (a group or split was priced) or line (one line was).",
      "x-data-class": "operational"
    },
    "group_key": {
      "type": [
        "object",
        "null"
      ],
      "description": "The group key priced, as read back: {market, size, type, condition, splits}. Null for a line.",
      "x-data-class": "operational"
    },
    "catalog_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The line priced. Null for a group.",
      "x-data-class": "operational"
    },
    "lines": {
      "type": "integer",
      "minimum": 0,
      "description": "The catalog lines the call covered.",
      "x-data-class": "operational"
    },
    "written": {
      "type": "integer",
      "minimum": 0,
      "description": "Lines at least one price was written to.",
      "x-data-class": "operational"
    },
    "skipped": {
      "type": "integer",
      "minimum": 0,
      "description": "Lines at least one price was kept on, because the line's price is its own.",
      "x-data-class": "operational"
    },
    "replaced": {
      "type": "integer",
      "minimum": 0,
      "description": "Lines whose own price was replaced, with replace.",
      "x-data-class": "operational"
    },
    "prices": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "price": {
                "type": "string",
                "enum": [
                  "wholesale",
                  "retail"
                ]
              },
              "amount": {
                "type": "string",
                "pattern": "^[0-9]+\\.[0-9]{4}$"
              },
              "written": {
                "type": "integer",
                "minimum": 0
              },
              "skipped": {
                "type": "integer",
                "minimum": 0
              },
              "replaced": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "price",
              "amount",
              "written",
              "skipped",
              "replaced"
            ],
            "additionalProperties": false
          }
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "Per price given (wholesale, retail): the amount set, as a 4-place decimal, and the lines written, skipped and replaced.",
      "x-data-class": "commercial"
    },
    "set_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who set it.",
      "x-data-class": "operational"
    },
    "set_at": {
      "type": "string",
      "format": "date-time",
      "description": "When.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "price_set_id",
    "org_id",
    "source",
    "group_key",
    "catalog_id",
    "lines",
    "written",
    "skipped",
    "replaced",
    "prices",
    "set_by",
    "set_at"
  ],
  "additionalProperties": false
}

Refusals

unknown_catalog_line · 422 · catalog_id names no line of this org's catalog
empty_catalog_group · 422 · group_key covers no line of this org's catalog
price_ceiling_reached · 422 · group_key covers more than 10,000 catalog lines, the most one call prices
retry_key_mismatch · 409 · the Idempotency-Key was already used with a different request
retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
retry_key_lost · 409 · another request took over this Idempotency-Key first; nothing was applied

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 catalog price
Outbound: crosses to no counterparty

Events

catalog.price_set planned_webhook

None.