Customisers

delete_customiser_asset

destructive write

Delete customiser asset

Copy page

Take a file out of one asset slot, leaving the record itself in place.

Overview

Clears one asset slot on one record and releases the stored file: an option image, an extra choice picture, a font TrueType file, a backboard custom SVG shape, one letter part default upload image, or the customiser storefront product image. The removal is permanent and the file cannot be recovered through this API, so the call needs confirm: true. A removal that would leave the record unrenderable is refused. 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

destructiveHinttrue

idempotentHinttrue

openWorldHintfalse

Prerequisites

The record id, from list_customiser_options; letter_type_id and letter_part for the nested targets.
get_customiser_option to confirm the slot currently holds a file.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Clears the slot on the record and deletes the stored file permanently.
Clears the customiser cached storefront configuration.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

asset_targetstringrequired

Which asset slot family to write. Closed set. Each value fixes which of the arguments below are needed and which upload purpose the slot accepts.

One of: backboard_image, backboard_shape, backlight_image, colour_image, extra_image, extra_choice_image, font_file, letter_type_image, letter_part_image, letter_part_colour_image, material_image, mounting_image, mounting_colour_image, support_finish_image, label_product_image

option_idinteger or string

The record that owns the slot. An integer for every target except letter_part_image, which is addressed by the part catalogue name. Omitted for label_product_image, which belongs to the customiser rather than to a record.

letter_type_idinteger

The letter type that owns the record, required for letter_part_image and letter_part_colour_image.

letter_partstring

The letter part that owns the colours, required for letter_part_colour_image. For letter_part_image the part is option_id instead.

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

choice_valuestring

One of an image-choice extra's choice values, required for extra_choice_image.

image_slotstring

Which picture of the record to write. Which slots a target offers is target-specific and reported by get_customiser_option; a slot the target does not offer is refused with allowed_values. Omitted for backboard_shape, font_file and label_product_image, whose paths name the slot. Expected to grow.

One of: image, button_image, example_image, texture_image, default_upload_image, preview_image

confirmboolean

Must be true to apply the change, because the stored file is deleted permanently and cannot be recovered through this API. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

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 removal is checked against what still needs the file 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 slot that was cleared, the file that was removed, and the record as it now stands with the slot empty. A dry run returns the delete verdict and removes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

asset_targetstringalways present

slotstringalways present

The slot that was written. For the three targets whose path names the slot, this is shape, font_file or product_image.

deletedboolean

Present and true when the slot was cleared. Absent on a dry run.

removed_fileobject

The file that was released, so a caller can report what it removed. Absent on a dry run.

removed_file.filenamestring or null

removed_file.urlstring or null

resourceobject

The owning record as it now stands, with the slot empty. 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 delete verdict.

Error cases

confirmation_required

Send confirm: true. The file is deleted permanently and cannot be recovered through this API.

insufficient_scope

The connection was approved without customisers:write.

missing_idempotency_key

Send idempotency_key. It is required for this write.

resource_in_use

Removing the file would leave the record unrenderable; the problem names the constraint. Change the record so it no longer needs the file, then delete it.

resource_not_found

No such customiser or record in this store, or the slot is already empty.

validation_failed

A slot this target does not offer, or a missing nested key; allowed_values lists what the target accepts.

Clear a font TrueType file

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_asset",
    "arguments": {
      "customiser_id": 42,
      "asset_target": "font_file",
      "option_id": 11,
      "confirm": true,
      "idempotency_key": "e5f60718-2a3b-4d1e-8f2a-3b4c5d6e7f80"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "asset_target": "font_file",
      "slot": "font_file",
      "deleted": true,
      "removed_file": {
        "filename": "Signature.ttf",
        "url": "https://cdn.example.com/files/2f1c9c0e.ttf"
      },
      "resource": {
        "id": 11,
        "name": "Signature Script",
        "font_file": {
          "has_font_file": false,
          "family_name": null,
          "ttf_url": null
        }
      }
    }
  }
}

Without confirmation nothing is removed (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_asset",
    "arguments": {
      "customiser_id": 42,
      "asset_target": "font_file",
      "option_id": 11,
      "idempotency_key": "e5f60718-2a3b-4d1e-8f2a-3b4c5d6e7f80"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Clearing the font_file slot of font_file deletes the stored file permanently.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}