Customisers

reorder_customiser_options

write

Reorder customiser options

Copy page

Put one option family in the order the merchant wants shoppers to see.

Overview

Sets the order a shopper sees for one customiser option family by supplying that family record ids in the wanted order. The list must be exactly the family current membership, each id once, which is what makes the call safe to repeat. Families with no shopper-visible ordering — preset, letter_part and legacy_fixed_height_size — are refused with unsupported_value. 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

The family complete current membership from list_customiser_options, paged to the end.
letter_type_id and letter_part for the letter_part_colour family.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Changes the storefront presentation order of one option family.
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 reorder. preset, letter_part and legacy_fixed_height_size carry no shopper-visible order and are refused with unsupported_value.

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

ordered_idsarray of integerrequired

Every record id of the family, each exactly once, in the order to present them. A partial or stale list is refused rather than partially applied.

letter_type_idinteger

The letter type that owns the family, required for the letter_part_colour family.

letter_partstring

The letter part that owns the colours, 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 membership is checked against the family current records 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 family in its new order, and the ids as sent. A dry run returns the reorder verdict instead and changes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

ordered_idsarray of integer

The order that was applied, as sent.

optionsarray of object

The family in its new order, with each record own field names. 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 reorder verdict.

Error cases

insufficient_scope

The connection was approved without customisers:write.

missing_idempotency_key

Send idempotency_key. It is required for this write.

reorder_membership_mismatch

The list is not the family current membership exactly once each. The problem names missing_ids, unknown_ids and duplicate_ids, and its pointer names the family own ids field.

resource_not_found

No customiser with that id exists in this store.

unsupported_value

That family carries no shopper-visible order; allowed_values lists the families that do.

Put Cool White first

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reorder_customiser_options",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "ordered_ids": [
        9,
        7
      ],
      "idempotency_key": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f70819203"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "ordered_ids": [
        9,
        7
      ],
      "options": [
        {
          "id": 9,
          "name": "Cool White",
          "sort_order": 1
        },
        {
          "id": 7,
          "name": "Warm White",
          "sort_order": 2
        }
      ]
    }
  }
}

A partial membership is refused (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reorder_customiser_options",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "ordered_ids": [
        9
      ],
      "idempotency_key": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f70819203"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "reorder_membership_mismatch",
        "title": "Reorder membership mismatch",
        "detail": "A reorder must list the complete current membership of the family exactly once each.",
        "recovery": "The id list must be exactly the family current members, each id once. Read the family first and send its complete membership in the new order.",
        "pointer": "/colour_ids"
      }
    }
  }
}