Stores
Switch the store units
Applies a reviewed unit switch and returns the Store with its new units
and unit_revision. Review first with
POST/api/v3/stores/me/unit-switch/review, then send the same units,
the review's unit_revision and its review_token.
Overview
Requires the
store:write scope and an Idempotency-Key.
Only the units the merchant admin and the storefront show change. No
stored quantity changes. A unit-bearing write that sends the old
unit_revision afterwards answers 409 stale_revision. Switching to
the units the Store already has returns the Store unchanged.
A token that expired, was issued to another API key, or names other
units or another revision answers 409 unit_switch_review_invalid, and
a Store whose units changed after the review answers 409
stale_revision. Review again in both cases.
Authorisation
Bearer token required. Include it in the Authorization header.
Required scope: store:write
Request body
Request body example
{
"measurement_unit": "cm",
"weight_unit": "kg",
"unit_revision": 7,
"review_token": "eyJpdiI6Ik1hY2hpbmVSZXZpZXdUb2tlbiJ9"
}curl https://web.signcustomiser.com/api/v3/stores/me/unit-switch \
--request POST \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"measurement_unit": "cm",
"weight_unit": "kg",
"unit_revision": 7,
"review_token": "eyJpdiI6Ik1hY2hpbmVSZXZpZXdUb2tlbiJ9"
}'{
"data": {
"object": "store",
"id": 1,
"name": "Demo Signs",
"platform": "universal",
"plan": "starter",
"currency": "GBP",
"integrations": [
{
"object": "integration",
"id": 17,
"type": "custom",
"name": "Warehouse bridge",
"enabled": true,
"accepts_writes": true
},
{
"object": "integration",
"id": 9,
"type": "woocommerce",
"name": "Old WooCommerce shop",
"enabled": false,
"accepts_writes": false
}
],
"scopes": [
"store:read",
"pricing:read",
"pricing:write"
],
"created_at": "2026-01-12T03:14:15Z",
"measurement_unit": "in",
"weight_unit": "lb",
"unit_revision": 7,
"contact_email": "hello@demosigns.example",
"website_url": "https://demosigns.example",
"primary_colour": "#1A73E8",
"use_branding_for_emails": true,
"logo_url": "https://cdn.signcustomiser.com/files/2f6c0b9e.png",
"currency_format_with_code": "£{{amount}} GBP",
"currency_format_without_code": "£{{amount}}",
"prevent_zero_price_products": true
},
"links": {
"self": "https://web.signcustomiser.com/api/v3/stores/me/unit-switch",
"documentation": "https://www.signcustomiser.com/help/api/"
},
"meta": {
"api_version": "v3",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
}{
"type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
"title": "Missing idempotency key",
"status": 400,
"code": "missing_idempotency_key",
"detail": "Provide an Idempotency-Key header for this write.",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
"title": "Missing API key",
"status": 401,
"code": "missing_api_key",
"detail": "Provide a store API key as a bearer token.",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
"title": "Insufficient scope",
"status": 403,
"code": "insufficient_scope",
"detail": "This operation requires the store:write scope.",
"required_scopes": [
"store:write"
],
"granted_scopes": [
"store:read"
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/unit_switch_review_invalid",
"title": "Unit switch review invalid",
"status": 409,
"code": "unit_switch_review_invalid",
"detail": "This review is no longer valid. Review the change again with POST /api/v3/stores/me/unit-switch/review.",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/stale_revision",
"title": "Stale revision",
"status": 409,
"code": "stale_revision",
"detail": "unit_revision 7 is stale; the current Store revision is 8.",
"expected_revision": 8,
"submitted_revision": 7,
"errors": [
{
"pointer": "/unit_revision",
"code": "stale_revision",
"detail": "unit_revision 7 is stale; the current Store revision is 8."
}
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
"title": "Validation failed",
"status": 422,
"code": "validation_failed",
"detail": "The request payload failed validation. Correct the fields listed in errors and retry.",
"errors": [
{
"pointer": "/review_token",
"code": "required",
"detail": "The review token field is required."
}
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"detail": "You have exceeded the request limit for this API key.",
"retry_after": 60,
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}