Pricing

get_customiser_pricing

read

Get customiser pricing

Copy page

Read the pricing rules a customiser applies, in the exact document shape a pricing replacement takes back.

Overview

Reads one customiser pricing document: its pricing model, the Store currency, and the rates, modifiers, minimums and rounding rules that turn a shopper design into a price. This is the read to make before changing pricing and the reference for interpreting an order total. Amounts are integer minor units. Quantity fields name their unit and report the merchant-authored unit when dual quantities are active. It requires the pricing:read scope, has no side effects and is safe to retry.

Permission

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

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
A merchant has connected this store and approved the pricing:read scope.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

Result

One pricing document. Its fields are those of the customiser own pricing model, so a frame_fit document and a simple_letter document do not carry the same members.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

pricing_modelstringalways present

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.

documentobjectalways present

The canonical pricing document, in the shape update_customiser_pricing takes back with mode replace. Dual-unit fields are present when the Store has that API capability.

document.customiser_idinteger

document.pricing_modelstring

document.pricing_model_display_namestring

document.currencystring or null

document.sizesarray of object

document.sizes[].size_idinteger or null

document.sizes[].namestring or null

document.sizes[].width_cmnumber or null

document.sizes[].width_innumber or null

document.sizes[].height_cmnumber or null

document.sizes[].height_innumber or null

document.sizes[].line_height_cmnumber or null

document.sizes[].line_height_innumber or null

document.sizes[].length_cmnumber or null

document.sizes[].length_innumber or null

document.sizes[].border_margin_cmnumber or null

document.sizes[].border_margin_innumber or null

document.sizes[].authored_unitsobject

document.base_pricingobject

document.base_pricing.modestring

document.base_pricing.rows_revisioninteger

document.base_pricing.rowsarray of object

document.price_listsarray of object

document.price_lists[].price_list_idinteger or null

document.price_lists[].rows_revisioninteger

document.price_lists[].rowsarray of object

document.price_lists[].shippingobject

document.sheet_pricingobject or null

document.sheet_pricing.rows_revisioninteger

document.sheet_pricing.rowsarray of object

Error cases

insufficient_scope

The connection was approved without pricing:read. A connection holding only customisers:read can read the customiser but not its rates.

legacy_pricing_model

This pricing endpoint does not support the legacy fixed-height model. Recreate the customiser as simple_letter with fixed_height sizing.

resource_not_found

No customiser with that id belongs to this store. Call list_customisers to rediscover a valid id.

Read a simple_letter pricing document

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_pricing",
    "arguments": {
      "customiser_id": 42
    }
  }
}

{
  "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",
        "pricing_model_display_name": "Simple Letter",
        "currency": "USD",
        "sizes": [
          {
            "size_id": 7,
            "name": "Small",
            "sort_order": 1,
            "width_cm": 50,
            "width_in": 19.6850394,
            "authored_units": {
              "width_cm": "inches"
            },
            "sizing_strategy": "fixed_width"
          }
        ]
      }
    }
  }
}

A connection that reads customisers but not pricing (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_pricing",
    "arguments": {
      "customiser_id": 42
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [get_customiser_pricing] requires the pricing:read scope, which this connection was not granted.",
        "recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the connector and approve the scope named in required_scopes. Do not retry this call.",
        "required_scopes": [
          "pricing:read"
        ],
        "granted_scopes": [
          "customisers:read"
        ]
      }
    }
  }
}