Customisers

create_customiser_option

write

Create customiser option

Copy page

Add one option a shopper can pick from — a colour, a font, a size, a mounting — to one customiser.

Overview

Creates one record in one customiser option family: a colour, a font, a size band, a material, a backboard, a mounting, a letter type, a letter part or another family named by option_type. Exactly one family is written per call, which is the same per-family boundary the public API enforces. Attributes are validated against that family schema and the customiser pricing model, so a field the model does not use is refused rather than stored. It requires the customisers:write scope and an idempotency_key, and supports dry_run.

Permission

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
The family current records from list_customiser_options, and one of them from get_customiser_option, so attributes are shaped like the family real fields.
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

Creates one record in one option family 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.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

option_typestringrequired

Which option family to create the record in. One family per call.

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

attributesobjectrequired

The record fields, using the family own names as get_customiser_option publishes them. Creating a letter_part names the part here, as letter_part.

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

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.

dry_runboolean

When true, the attributes are 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.

Result

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

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

optionobject

The created record, with the field names the public API publishes for its family. Absent on a dry run.

idempotent_replayboolean

True when this call replayed an earlier write carrying the same idempotency_key rather than creating a second record.

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 create verdict.

Error cases

field_not_used_by_pricing_model

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

insufficient_scope

The connection was approved without customisers:write.

letter_part_not_declared

The letter type does not declare that part. Read the letter type and use one of its declared letter_parts.

letter_part_taken

That letter part already has a record on this letter type. Update the existing one instead.

missing_idempotency_key

Send idempotency_key. It is required for this write.

rate_limited

The store option-write budget is spent. Wait retry_after seconds.

unsupported_value

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

validation_failed

An attribute is missing, out of range, or not a field this family accepts. The pointer names it.

Add a neon colour

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "attributes": {
        "name": "Sunset Orange",
        "colour_type": "single",
        "hexcode": "#FF7A18"
      },
      "idempotency_key": "f6a7b8c9-0d1e-4f2a-8b3c-4d5e6f708192"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "option": {
        "id": 9,
        "customiser_id": 42,
        "name": "Sunset Orange",
        "colour_type": "single",
        "hexcode": "#FF7A18",
        "sort_order": 2
      },
      "idempotent_replay": false
    }
  }
}

A family that cannot be created (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "legacy_fixed_height_size",
      "attributes": {
        "name": "Small"
      },
      "idempotency_key": "f6a7b8c9-0d1e-4f2a-8b3c-4d5e6f708192"
    }
  }
}

{
  "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 create 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"
        ]
      }
    }
  }
}