Customisers

update_customiser_option

write

Update customiser option

Copy page

Change one option a shopper picks from, without touching the rest of its family.

Overview

Applies a JSON merge patch to one record in one customiser option family. Only the fields present in the patch change; omitted fields are left alone and a field set to null clears a nullable value. The patch is checked against the family schema and the customiser pricing model, so a field the model does not use is refused rather than stored. Read the record with get_customiser_option first. It requires the customisers:write scope, takes an optional idempotency_key for replay, and supports dry_run.

Permission

Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHintfalse

openWorldHintfalse

Prerequisites

A record id from list_customiser_options.
The record current values from get_customiser_option, so the patch is built against what is there now.
letter_type_id for the letter_part and letter_part_colour families, and letter_part as well for letter_part_colour.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Changes one option record of one customiser, visible to shoppers if the customiser is live.
Clears the customiser cached storefront configuration.
Spends one unit of the store option-write budget.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

option_typestringrequired

Which option family the record belongs to.

One of: backboard, backlight, colour, extra, font, form, icon, jacket, letter_type, letter_part, letter_part_colour, material, mounting, mounting_colour, preset, size, support_finish, legacy_fixed_height_size

option_idinteger or stringrequired

The record identifier from list_customiser_options: an integer for every family except letter_part, which is addressed by its catalogue name such as face or halo.

patchobjectrequired

The RFC 7396 merge patch to apply. Only the members present change; a member set to null clears a nullable field.

letter_type_idinteger

The letter type that owns the record, required for the letter_part and letter_part_colour families.

letter_partstring

The letter part that owns the colour, required for the letter_part_colour family.

One of: face, back, side, top, bottom, left, right, halo, trim, tube

idempotency_keystring

An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one.

dry_runboolean

When true, the patch is checked against the family schema and the customiser pricing model 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. A dry run claims no key.

Result

The patched record with the family own field names. A dry run returns the update verdict instead and writes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

optionobject

The record as it now stands, with the field names the public API publishes for its family. Absent on a dry run.

dry_runboolean

Present and true only when dry_run was requested.

validboolean

Present only on a dry run, and always true: a failing dry run returns a tool error instead.

verdictobject

Present only on a dry run: the update verdict.

idempotent_replayboolean

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

Error cases

field_not_used_by_pricing_model

Remove the field named by pointer; the customiser pricing model does not use it.

idempotency_subject_changed

The option was deleted after the recorded update. Issue a new key and re-check the resource before writing again.

insufficient_scope

The connection was approved without customisers:write.

preset_design_not_supported

Read the preset, replace its stored design with an object, or remove the row outside the API.

resource_not_found

No record with that id exists in that family of that customiser.

unsupported_value

That family has no update operation; allowed_values lists the families that do.

validation_failed

A patched value is out of range, the wrong type, or not a field this family accepts.

Rename a colour

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 7,
      "patch": {
        "name": "Warm White (2700K)"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "idempotent_replay": false,
      "customiser_id": 42,
      "option_type": "colour",
      "option": {
        "id": 7,
        "customiser_id": 42,
        "name": "Warm White (2700K)",
        "colour_type": "single",
        "hexcode": "#FFEEDD",
        "sort_order": 1
      }
    }
  }
}

A family that cannot be updated (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "legacy_fixed_height_size",
      "option_id": 3,
      "patch": {
        "name": "Small"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "unsupported_value",
        "title": "Unsupported value",
        "detail": "The legacy_fixed_height_size option family has no update operation. It supports: delete.",
        "recovery": "Send one of the values in allowed_values for the field named by pointer or parameter.",
        "parameter": "option_type",
        "allowed_values": [
          "backboard",
          "backlight",
          "colour"
        ],
        "supported_verbs": [
          "delete"
        ]
      }
    }
  }
}