Customisers

populate_letter_part_demo_colours

write

Populate letter part demo colours

Copy page

Give an empty letter part a ready-made set of colours in one call, instead of creating each colour with create_customiser_option.

Overview

Adds the Sign Customiser demo colours for the customiser sign category to one empty letter part of one letter type, and returns the colours it created. A letter part that already holds colours is refused rather than merged, and a part with no demo colours for its sign category 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

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers and a letter type id from list_customiser_options with option_type letter_type.
A letter part the letter type declares in its letter_parts, and that holds no colours yet.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Creates the letter part colour selection when it does not exist, and adds the demo colours to it.
Clears the customiser cached storefront configuration.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

letter_type_idintegerrequired

The letter type that owns the letter part, from list_customiser_options with option_type letter_type.

letter_partstringrequired

The letter part to fill. It must be one of the letter type own letter_parts and hold no colours yet.

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 letter part is checked for existing colours and for demo colours of the customiser sign category 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

Every colour the call created, in storefront order, with the field names list_customiser_options returns for the letter_part_colour family. A dry run returns the populate verdict instead and writes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

letter_type_idintegeralways present

letter_partstringalways present

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

coloursarray of object

Every colour the call created, in storefront order, with the field names of the letter_part_colour 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 populate 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

demo_colours_not_available

There are no demo colours for this sign category and letter part. Add colours one at a time with create_customiser_option.

idempotency_key_conflict

That key was used for a different letter type or letter part. Re-send the original arguments or issue a new key.

insufficient_scope

The connection was approved without customisers:write.

letter_part_colours_not_empty

The letter part already holds colours. Delete them first, or add colours one at a time with create_customiser_option.

letter_part_not_declared

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

rate_limited

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

resource_not_found

No customiser or letter type with that id exists in this store.

Fill an empty face with demo colours

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "populate_letter_part_demo_colours",
    "arguments": {
      "customiser_id": 42,
      "letter_type_id": 7,
      "letter_part": "face",
      "idempotency_key": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "letter_type_id": 7,
      "letter_part": "face",
      "colours": [
        {
          "id": 301,
          "name": "White",
          "colour_type": "single",
          "hexcode": "#FFFFFF",
          "sort_order": 1
        }
      ],
      "idempotent_replay": false
    }
  }
}

Check the populate without writing

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "populate_letter_part_demo_colours",
    "arguments": {
      "customiser_id": 42,
      "letter_type_id": 7,
      "letter_part": "face",
      "dry_run": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "letter_type_id": 7,
      "letter_part": "face",
      "dry_run": true,
      "valid": true,
      "verdict": {
        "operation": "populate_demo",
        "customiser_id": 42,
        "letter_type_id": 7,
        "letter_part": "face",
        "colour_id": null
      }
    }
  }
}

A letter part that already holds colours (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "populate_letter_part_demo_colours",
    "arguments": {
      "customiser_id": 42,
      "letter_type_id": 7,
      "letter_part": "face",
      "idempotency_key": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "letter_part_colours_not_empty",
        "title": "Letter part colours not empty",
        "detail": "The face letter part already holds colours, so demo colours would mix into them. Delete its colours first, or add colours one at a time.",
        "recovery": "The letter part already holds colours, so demo colours would mix into them. Delete its colours with delete_customiser_option first, or add colours one at a time with create_customiser_option.",
        "pointer": ""
      }
    }
  }
}