Store
switch_store_units
writeSwitch store units
Change the length and weight units the Store shows, after the merchant has seen the review.
Overview
Applies a unit switch that review_store_unit_switch reviewed: send the same units, the unit_revision and the review_token it returned. The Store then shows lengths and weights in the new units in the merchant admin and on the storefront. No stored quantity changes, but the unit_revision moves on, so unit-bearing writes must read the Store again. The call needs confirm: true. A review that expired or that another connection made is refused; review again. It requires the store:write scope and an idempotency_key, and supports dry_run.
Permission
Requires thestore:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A review from review_store_unit_switch made by this connection less than 15 minutes ago, for the same units.
- The merchant has seen the review examples and agreed to the switch.
- A merchant has connected this store and approved the store:write scope.
Side effects
- Changes the length and weight units the Store shows and moves its unit_revision on.
- Records the switch in the Store unit switch history.
- Claims the idempotency_key for at least 24 hours.
Arguments
The length unit the review named.
One of: cm, in
The weight unit the review named.
One of: kg, lb
The unit_revision the review returned.
The review_token the review returned.
Must be true to apply the change, because the switch changes how every length and weight in the Store displays. Without it the call returns a confirmation_required error and changes nothing.
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.
When true, the review token and the Store revision are checked, the token stays valid, and nothing is switched 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. A dry run does not require the confirm argument.
Result
The Store as get_store reads it, with the new units and unit_revision. A dry run returns the switch verdict and changes nothing.
The Store as get_store reads it, with the new units and unit_revision. Absent on a dry run.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Present and true only when dry_run was requested.
Present only on a dry run, and always true: a failing dry run returns a tool error instead.
Present only on a dry run: the switch verdict.
Error cases
Send confirm: true once the merchant has agreed to the switch.
The connection was approved without store:write. Ask the merchant to reconnect and approve it, or to remove the connector and add it again if the approval screen does not offer it.
The Store units changed after the review. Call review_store_unit_switch again.
The review expired, another connection made it, or it names other units or another revision. Call review_store_unit_switch again.
A unit outside the allowed values, or a missing review_token or unit_revision.
Apply a reviewed switch to metric
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "switch_store_units",
"arguments": {
"measurement_unit": "cm",
"weight_unit": "kg",
"unit_revision": 7,
"review_token": "eyJpdiI6Ik1hY2hpbmVSZXZpZXdUb2tlbiJ9",
"confirm": true,
"idempotency_key": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"store_details": {
"id": 12,
"name": "Demo Signs",
"measurement_unit": "cm",
"weight_unit": "kg",
"unit_revision": 8
},
"idempotent_replay": false
}
}
}The review is no longer valid (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "switch_store_units",
"arguments": {
"measurement_unit": "cm",
"weight_unit": "kg",
"unit_revision": 7,
"review_token": "eyJpdiI6Ik1hY2hpbmVSZXZpZXdUb2tlbiJ9",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "unit_switch_review_invalid",
"title": "Unit switch review invalid",
"detail": "This review is no longer valid. Review the change again with POST /api/v3/stores/me/unit-switch/review.",
"recovery": "The unit switch review expired, belongs to another connection, or names other units or another revision. Call review_store_unit_switch again, show the merchant the new review, then switch with its review_token and unit_revision."
}
}
}
}