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. To create the first record in an empty family, read its public API create reference for the accepted attributes and required values: backboard attributes: createBackboard (https://www.signcustomiser.com/help/api/v3-post-create-a-backboard/); backlight attributes: createBacklight (https://www.signcustomiser.com/help/api/v3-post-create-a-backlight/); colour attributes: createColour (https://www.signcustomiser.com/help/api/v3-post-create-a-colour/); extra attributes: createExtra (https://www.signcustomiser.com/help/api/v3-post-create-an-extra/); font attributes: createFont (https://www.signcustomiser.com/help/api/v3-post-create-a-font/); form attributes: createForm (https://www.signcustomiser.com/help/api/v3-post-create-a-form/); icon attributes: createIcon (https://www.signcustomiser.com/help/api/v3-post-create-an-icon/); jacket attributes: createJacket (https://www.signcustomiser.com/help/api/v3-post-create-a-jacket/); letter_type attributes: createLetterType (https://www.signcustomiser.com/help/api/v3-post-create-a-letter-type/); letter_part attributes: createLetterPartColourSelection (https://www.signcustomiser.com/help/api/v3-post-create-a-letter-part-colour-selection/); letter_part_colour attributes: createLetterPartColour (https://www.signcustomiser.com/help/api/v3-post-create-a-letter-part-s-colour/); material attributes: createMaterial (https://www.signcustomiser.com/help/api/v3-post-create-a-material/); mounting attributes: createMounting (https://www.signcustomiser.com/help/api/v3-post-create-a-mounting/); mounting_colour attributes: createMountingColour (https://www.signcustomiser.com/help/api/v3-post-create-a-mounting-colour/); preset attributes: createPreset (https://www.signcustomiser.com/help/api/v3-post-create-a-preset/); size attributes: createSize (https://www.signcustomiser.com/help/api/v3-post-create-a-size/); support_finish attributes: createSupportFinish (https://www.signcustomiser.com/help/api/v3-post-create-a-support-finish/).

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 public API create reference for the selected option_type, linked in the tool description. It lists accepted attributes and required values even when the family has no records.
When the family already has records, list_customiser_options and get_customiser_option show the field names currently in use.
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. Read the selected option_type public API create reference in the tool description for accepted names and required values. When a record exists, get_customiser_option also shows the fields in use. 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_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.

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. A dry run claims no key.

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.

idempotency_subject_changed

The created option was later deleted. Issue a new key and re-check the resource before writing again.

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.

pricing_model_not_supported

This customiser uses the deprecated fixed-height pricing model. Move it to a current pricing model before creating a size.

rate_limited

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

unknown_field

Remove or rename the field named by pointer. Read the selected family public API create reference from the Overview for its accepted attributes.

unsupported_value

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

validation_failed

An attribute is missing or out of range. 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"
        ]
      }
    }
  }
}