Advanced catalogue

execute_update

destructive write

Execute API update operation

Copy page

Change anything the partner API can change, including the resources no curated tool covers, one operation per call.

Overview

Runs one updating Sign Customiser API operation, named by the stable operation id search_operations returns, applying a merge patch or a replacement document as the operation defines. It reaches every update operation and nothing else: a create, a delete or a read is refused with the tool that does run it. Every call needs confirm: true and an idempotency_key. Setting dry_run: true checks the arguments through the operation validate twin without writing. It requires the mcp:advanced scope plus the write scope the operation itself declares.

Permission

Needs no permission beyond a connected store.

Only visible to a connection grantedmcp:advanced. See theadvanced catalogue guide.

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHinttrue

Prerequisites

An operation id from search_operations, and its request_schema.
A merchant has connected this store and approved mcp:advanced plus the write scope that operation requires.
The merchant has agreed to the change: confirm: true is required on every call.

Side effects

Applies the change to the record the path addresses.
A replacement operation discards every member the document previously held that the body does not repeat.

Arguments

operation_idstringrequired

The stable id of the operation to run, from search_operations. It is the only way to name an operation: this tool accepts no URL, no path and no HTTP method.

pathobject

The operation path parameters, by name, exactly as search_operations lists them under parameters.path. An identifier the operation does not address is refused.

queryobject

The query parameters, by name, as search_operations lists them under parameters.query. Only read operations take any; a nested object such as filter is sent as the API expects it.

bodyobject

The JSON request body, matching the operation request_schema from search_operations. It is passed to the API unchanged, so a member the operation does not accept comes back as unknown_field naming its pointer. A GET or a DELETE operation takes no body and refuses one.

confirmbooleanrequired unless dry_run is true

Must be true to apply the change, because this tool can reach every update operation the API has and cannot judge the consequence of one on its own. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

dry_runboolean

When true, the operation validate twin is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false.

idempotency_keystringrequired unless dry_run is true

A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict. A dry run claims no key.

Result

The operation own response data, unchanged, plus the top-level members the patch carried.

request_idstringalways present

The API request id, for support.

storeobjectalways present

The Store this connection resolved to.

store.idinteger

store.namestring

operation_idstringalways present

The operation that ran.

statusintegeralways present

The HTTP status the operation answered with.

dry_runboolean

Present and true when nothing was written.

validboolean

Present and true on a passing dry run. A failing dry run is a tool error carrying the problem the apply would have raised, never a verdict saying false.

verdictobject

What the validate twin reported about the operation.

dataobject

The operation own response data, unchanged.

changed_fieldsarray of string

The top-level members the request body carried. It is what the call asked to change, not a diff: /api/v3 does not publish one.

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

Error cases

confirmation_required

Send confirm: true, or dry_run: true to check the arguments first.

idempotency_subject_changed

The updated resource changed lifecycle state. Issue a new key and re-check the resource before writing again.

insufficient_scope

The connection holds mcp:advanced but not the write scope this operation needs.

legacy_pricing_model

The operation does not support a legacy fixed-height pricing model. Recreate the customiser as simple_letter with fixed_height sizing.

preset_design_not_supported

The preset has a stored list design that no write can round-trip. Read it before correcting the row outside the API.

resource_state_conflict

The record is not in a state this change allows. Read it first with execute_read.

unsupported_value

The id names an operation of another class, or has no validate twin for the dry run that was asked for.

upload_rejected

The uploaded object was rejected. Correct the reported reason and create a new upload.

validation_failed

The body does not satisfy the operation request_schema; the errors carry the pointer and allowed_values.

Rename a font tier

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_update",
    "arguments": {
      "operation_id": "updateFontTier",
      "path": {
        "customiser_id": 42,
        "font_tier_id": 3
      },
      "body": {
        "name": "Signature"
      },
      "confirm": true,
      "idempotency_key": "7e6d5c4b-3a21-4987-8654-3210fedcba98"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "idempotent_replay": false,
      "operation_id": "updateFontTier",
      "status": 200,
      "data": {
        "object": "font_tier",
        "id": 3,
        "name": "Signature"
      },
      "changed_fields": [
        "name"
      ]
    }
  }
}

A create is refused, and named (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_update",
    "arguments": {
      "operation_id": "createFontTier",
      "path": {
        "customiser_id": 42
      },
      "body": {
        "name": "Premium"
      },
      "confirm": true,
      "idempotency_key": "7e6d5c4b-3a21-4987-8654-3210fedcba98"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "unsupported_value",
        "title": "Operation belongs to another tool",
        "detail": "The operation createFontTier is a create operation, which execute_update does not run. Call execute_create instead.",
        "recovery": "Send one of the values in allowed_values for the field named by pointer or parameter.",
        "parameter": "operation_id",
        "allowed_values": [
          "execute_create"
        ],
        "owning_tool": "execute_create"
      }
    }
  }
}