Pricing

update_customiser_pricing

write

Update customiser pricing

Copy page

Change what a customiser charges: its rates, modifiers, minimums and rounding rules.

Overview

Changes a customiser pricing document, either replacing it wholesale with mode replace or applying a JSON merge patch to it with mode merge. Amounts are integer minor units in the store currency and the document is validated against the customiser pricing model, so a rate the model does not use is refused rather than stored. Read the document with get_customiser_pricing first. It requires the pricing:write scope, takes an optional idempotency_key for replay, and supports dry_run with mode replace.

Permission

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHintfalse

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
The current document from get_customiser_pricing, because a replace must be complete and a patch must be built against what is there now.
A merchant has connected this store and approved the pricing:write scope.

Side effects

Changes what one customiser charges for every future design.
Clears the customiser cached storefront configuration.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

modestringrequired

replace writes the whole document and requires document; merge applies an RFC 7396 merge patch and requires patch.

One of: replace, merge

documentobject

The complete canonical pricing document, required with mode replace. Every amount is an integer in the store currency minor units.

patchobject

The merge patch to apply, required with mode merge. Only the members present change; a member set to null clears a nullable field.

idempotency_keystring

An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one.

dry_runboolean

When true, the document is checked against the customiser pricing model and the records it references 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 whole pricing document as it now stands, in the same shape get_customiser_pricing returns. A dry run returns the validation verdict instead and writes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

pricing_modelstring

The pricing model the document is written against.

One of: simple_letter, advanced_letter, frame_fit

currencystring or null

The ISO 4217 currency every amount in the document is expressed in, as integer minor units.

documentobject

The pricing document as it now stands, the same shape get_customiser_pricing returns. 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 validation verdict.

Error cases

currency_mismatch

Amounts must use the store own currency.

field_not_used_by_pricing_model

Remove the field named by pointer; this customiser pricing model does not use it.

insufficient_scope

The connection was approved without pricing:write.

pricing_model_mismatch

The document is written against a different pricing model than this customiser uses.

unknown_field

The document or patch names a field that is not part of the pricing document.

unsupported_value

dry_run was sent with mode merge, which has no validate twin: apply the patch locally and validate the result with mode replace.

Patch one rate

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_pricing",
    "arguments": {
      "customiser_id": 42,
      "mode": "merge",
      "patch": {
        "base_pricing": {
          "minimum_order_amount": 9900
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "pricing_model": "simple_letter",
      "currency": "USD",
      "document": {
        "customiser_id": 42,
        "pricing_model": "simple_letter",
        "currency": "USD",
        "base_pricing": {
          "minimum_order_amount": 9900
        }
      }
    }
  }
}

A merge dry run has no validate twin (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_pricing",
    "arguments": {
      "customiser_id": 42,
      "mode": "merge",
      "patch": {
        "base_pricing": {
          "minimum_order_amount": 9900
        }
      },
      "dry_run": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "unsupported_value",
        "title": "Unsupported value",
        "detail": "The pricing validate operation checks a complete document, so dry_run is supported with mode replace only.",
        "recovery": "Send one of the values in allowed_values for the field named by pointer or parameter.",
        "parameter": "mode",
        "allowed_values": [
          "replace"
        ]
      }
    }
  }
}