# Switch store units (`switch_store_units`)

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.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/switch_store_units/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/switch_store_units.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `store:write`
- Behaviour: write

## Purpose

Change the length and weight units the Store shows, after the merchant has seen the review.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | false |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## 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

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `measurement_unit` | string | yes | The length unit the review named. One of: `cm`, `in`. |
| `weight_unit` | string | yes | The weight unit the review named. One of: `kg`, `lb`. |
| `unit_revision` | integer | yes | The unit_revision the review returned. |
| `review_token` | string | yes | The review_token the review returned. |
| `confirm` | boolean | unless `dry_run` is true | 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. |
| `idempotency_key` | string | 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_run` | boolean | no | 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.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `store_details` | object | no | The Store as get_store reads it, with the new units and unit_revision. Absent on a dry run. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |
| `dry_run` | boolean | no | Present and true only when dry_run was requested. |
| `valid` | boolean | no | Present only on a dry run, and always true: a failing dry run returns a tool error instead. |
| `verdict` | object | no | Present only on a dry run: the switch verdict. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm: true once the merchant has agreed to the switch. |
| `insufficient_scope` | 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. |
| `stale_revision` | The Store units changed after the review. Call review_store_unit_switch again. |
| `unit_switch_review_invalid` | The review expired, another connection made it, or it names other units or another revision. Call review_store_unit_switch again. |
| `validation_failed` | A unit outside the allowed values, or a missing review_token or unit_revision. |

## Example: Apply a reviewed switch to metric

Request:

```json
{
  "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"
    }
  }
}
```

Response:

```json
{
  "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
    }
  }
}
```

## Example: The review is no longer valid (error)

Request:

```json
{
  "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
    }
  }
}
```

Response:

```json
{
  "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."
      }
    }
  }
}
```
