Customisers

delete_customiser_option

destructive write

Delete customiser option

Copy page

Take one option off a customiser after the merchant has agreed to it.

Overview

Deletes one record from one customiser option family. The record is removed permanently and any stored file it owned is released, so the call requires confirm true and changes nothing without it. A delete that live records still depend on is refused with resource_in_use; calling with dry_run true first returns the same verdict without deleting anything. It requires the customisers:write scope and an idempotency_key.

Permission

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

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHintfalse

Prerequisites

A record id from list_customiser_options.
The merchant explicit agreement, sent as confirm true.
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

Deletes one option record permanently and releases any stored file it owned.
Removes the option from the storefront if the customiser is live.
Clears the customiser cached storefront configuration.
Claims the idempotency_key for at least 24 hours.

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.

confirmboolean

Must be true to apply the change, because the record and any stored file it owned are removed permanently and cannot be restored through this connector. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

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 deletion is checked against everything that still references the record 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 deleted record id and the record as it was. A dry run returns the delete verdict instead and deletes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

option_idinteger or stringalways present

The record identifier that was addressed.

deletedboolean

True when the record was deleted. Absent on a dry run, where nothing is deleted.

optionobject

The record as it was when it was deleted, from the deletion receipt, so the caller can report what it removed.

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

Error cases

confirmation_required

Send confirm true once the merchant has agreed to the deletion. Nothing was deleted.

insufficient_scope

The connection was approved without customisers:write.

letter_part_cascade_blocked

Records depending on this letter part must be removed first.

missing_idempotency_key

Send idempotency_key. It is required for this write.

resource_in_use

Live records still reference this option. Call again with dry_run true to enumerate them.

resource_not_found

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

Delete a colour the merchant confirmed

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 9,
      "confirm": true,
      "idempotency_key": "b8c9d0e1-2f3a-4b4c-9d5e-6f7081920314"
    }
  }
}

{
  "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,
      "deleted": true,
      "option": {
        "id": 9,
        "customiser_id": 42,
        "name": "Sunset Orange",
        "colour_type": "single",
        "hexcode": "#FF7A18"
      }
    }
  }
}

Without confirmation nothing is deleted (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 9,
      "idempotency_key": "b8c9d0e1-2f3a-4b4c-9d5e-6f7081920314"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting colour record 9 removes it from the storefront permanently and releases any file it owned.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}