Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added Admin SPA settings skeleton + store settings (#13993)

Damian Legawieceb1c1f01b39d
diff --git a/.github/workflows/spelling_lint.yml b/.github/workflows/spelling_lint.yml
index eec6032a53..77d02b380a 100644
--- a/.github/workflows/spelling_lint.yml
+++ b/.github/workflows/spelling_lint.yml
@@ -31,4 +31,4 @@ jobs:
- name: Install
run: wget -O - -q https://git.io/misspell | sh -s -- -b .
- name: Misspell
- run: git ls-files --empty-directory | grep -v "vendor/" | grep -v "docs/api-reference/store.yaml" | grep -v "product_translations.csv" | xargs ./misspell -i 'aircrafts,devels,invertions' -error
+ run: git ls-files --empty-directory | grep -v "vendor/" | grep -v "docs/api-reference/store.yaml" | grep -v "docs/api-reference/admin.yaml" | grep -v "product_translations.csv" | xargs ./misspell -i 'aircrafts,devels,invertions' -error
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index c867ac2855..d4c9b1818b 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -104,8 +104,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-04T21:24:14.648Z'
- updated_at: '2026-05-04T21:24:14.648Z'
+ created_at: '2026-05-06T15:38:39.483Z'
+ updated_at: '2026-05-06T15:38:39.483Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -113,8 +113,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-05-04T21:24:14.651Z'
- updated_at: '2026-05-04T21:24:14.651Z'
+ created_at: '2026-05-06T15:38:39.484Z'
+ updated_at: '2026-05-06T15:38:39.484Z'
meta:
page: 1
limit: 25
@@ -177,8 +177,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-04T21:24:15.346Z'
- updated_at: '2026-05-04T21:24:15.346Z'
+ created_at: '2026-05-06T15:38:40.131Z'
+ updated_at: '2026-05-06T15:38:40.131Z'
requestBody:
content:
application/json:
@@ -261,8 +261,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-04T21:24:15.349Z'
- updated_at: '2026-05-04T21:24:15.349Z'
+ created_at: '2026-05-06T15:38:40.135Z'
+ updated_at: '2026-05-06T15:38:40.135Z'
patch:
summary: Update a custom field definition
tags:
@@ -301,8 +301,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-05-04T21:24:15.694Z'
- updated_at: '2026-05-04T21:24:16.003Z'
+ created_at: '2026-05-06T15:38:40.423Z'
+ updated_at: '2026-05-06T15:38:40.705Z'
requestBody:
content:
application/json:
@@ -424,8 +424,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-04T21:24:16.695Z'
- updated_at: '2026-05-04T21:24:16.695Z'
+ created_at: '2026-05-06T15:38:41.292Z'
+ updated_at: '2026-05-06T15:38:41.292Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -513,8 +513,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-05-04T21:24:18.192Z'
- updated_at: '2026-05-04T21:24:18.192Z'
+ created_at: '2026-05-06T15:38:42.658Z'
+ updated_at: '2026-05-06T15:38:42.658Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -625,8 +625,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-04T21:24:18.481Z'
- updated_at: '2026-05-04T21:24:19.083Z'
+ created_at: '2026-05-06T15:38:42.930Z'
+ updated_at: '2026-05-06T15:38:43.504Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -759,8 +759,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-04T21:24:20.310Z'
- updated_at: '2026-05-04T21:24:20.310Z'
+ created_at: '2026-05-06T15:38:44.711Z'
+ updated_at: '2026-05-06T15:38:44.711Z'
meta:
page: 1
limit: 25
@@ -847,8 +847,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-04T21:24:20.891Z'
- updated_at: '2026-05-04T21:24:20.891Z'
+ created_at: '2026-05-06T15:38:45.281Z'
+ updated_at: '2026-05-06T15:38:45.281Z'
delete:
summary: Delete a customer credit card
tags:
@@ -966,8 +966,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-04T21:24:22.312Z'
- updated_at: '2026-05-04T21:24:22.312Z'
+ created_at: '2026-05-06T15:38:46.675Z'
+ updated_at: '2026-05-06T15:38:46.675Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
meta:
@@ -1039,8 +1039,8 @@ paths:
display_amount_remaining: "$25.00"
currency: USD
metadata: {}
- created_at: '2026-05-04T21:24:23.515Z'
- updated_at: '2026-05-04T21:24:23.515Z'
+ created_at: '2026-05-06T15:38:47.799Z'
+ updated_at: '2026-05-06T15:38:47.799Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
requestBody:
@@ -1128,8 +1128,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-04T21:24:24.077Z'
- updated_at: '2026-05-04T21:24:24.374Z'
+ created_at: '2026-05-06T15:38:48.342Z'
+ updated_at: '2026-05-06T15:38:48.626Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
requestBody:
@@ -1281,8 +1281,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-04T21:24:25.463Z'
- updated_at: '2026-05-04T21:24:25.463Z'
+ created_at: '2026-05-06T15:38:49.750Z'
+ updated_at: '2026-05-06T15:38:49.750Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1365,8 +1365,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-04T21:24:26.342Z'
- updated_at: '2026-05-04T21:24:26.342Z'
+ created_at: '2026-05-06T15:38:50.607Z'
+ updated_at: '2026-05-06T15:38:50.607Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1482,8 +1482,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-04T21:24:26.615Z'
- updated_at: '2026-05-04T21:24:26.615Z'
+ created_at: '2026-05-06T15:38:50.881Z'
+ updated_at: '2026-05-06T15:38:50.881Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1557,8 +1557,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-04T21:24:27.175Z'
- updated_at: '2026-05-04T21:24:27.464Z'
+ created_at: '2026-05-06T15:38:51.517Z'
+ updated_at: '2026-05-06T15:38:51.847Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1658,7 +1658,7 @@ paths:
secretKey: 'sk_xxx',
})
- const me = await client.me.show()
+ const me = await client.me.get()
if (me.permissions.some((r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'))) {
// show "Create product" button
}
@@ -1682,11 +1682,11 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Leighann
- last_name: Carter
- created_at: '2026-05-04T21:24:28.356Z'
- updated_at: '2026-05-04T21:24:28.356Z'
+ first_name: Tyron
+ last_name: Littel
+ created_at: '2026-05-06T15:38:52.838Z'
+ updated_at: '2026-05-06T15:38:52.838Z'
permissions:
- allow: true
actions:
@@ -1832,8 +1832,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-04T21:24:28.401Z'
- updated_at: '2026-05-04T21:24:28.401Z'
+ created_at: '2026-05-06T15:38:52.943Z'
+ updated_at: '2026-05-06T15:38:52.943Z'
option_values: []
meta:
page: 1
@@ -1924,8 +1924,8 @@ paths:
position: 2
kind: dropdown
metadata: {}
- created_at: '2026-05-04T21:24:29.002Z'
- updated_at: '2026-05-04T21:24:29.002Z'
+ created_at: '2026-05-06T15:38:53.629Z'
+ updated_at: '2026-05-06T15:38:53.629Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2046,8 +2046,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-04T21:24:29.290Z'
- updated_at: '2026-05-04T21:24:29.290Z'
+ created_at: '2026-05-06T15:38:53.949Z'
+ updated_at: '2026-05-06T15:38:53.949Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2119,8 +2119,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-04T21:24:29.887Z'
- updated_at: '2026-05-04T21:24:30.170Z'
+ created_at: '2026-05-06T15:38:54.568Z'
+ updated_at: '2026-05-06T15:38:54.853Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2280,7 +2280,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H20624491345
+ number: H46988334888
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2305,8 +2305,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:31.146Z'
- updated_at: '2026-05-04T21:24:31.249Z'
+ created_at: '2026-05-06T15:38:55.814Z'
+ updated_at: '2026-05-06T15:38:55.984Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -2389,7 +2389,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H31746652146
+ number: H14401345119
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2414,8 +2414,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:31.954Z'
- updated_at: '2026-05-04T21:24:32.018Z'
+ created_at: '2026-05-06T15:38:56.799Z'
+ updated_at: '2026-05-06T15:38:56.864Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -2474,7 +2474,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H38052448946
+ number: H03111903140
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -2499,8 +2499,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:32.669Z'
- updated_at: '2026-05-04T21:24:33.036Z'
+ created_at: '2026-05-06T15:38:57.539Z'
+ updated_at: '2026-05-06T15:38:57.916Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -2569,7 +2569,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H28530975062
+ number: H30767646225
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2586,7 +2586,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-05-04T21:24:33Z'
+ fulfilled_at: '2026-05-06T15:38:58Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -2594,8 +2594,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:33.394Z'
- updated_at: '2026-05-04T21:24:33.779Z'
+ created_at: '2026-05-06T15:38:58.297Z'
+ updated_at: '2026-05-06T15:38:58.695Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -2653,7 +2653,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H13858799999
+ number: H04934591932
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2678,8 +2678,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:34.101Z'
- updated_at: '2026-05-04T21:24:34.465Z'
+ created_at: '2026-05-06T15:38:59.022Z'
+ updated_at: '2026-05-06T15:38:59.370Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -2737,7 +2737,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H71375512095
+ number: H77939081440
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2762,8 +2762,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:34.810Z'
- updated_at: '2026-05-04T21:24:35.169Z'
+ created_at: '2026-05-06T15:38:59.707Z'
+ updated_at: '2026-05-06T15:39:00.073Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -2824,7 +2824,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H48267433152
+ number: H78758486575
tracking:
tracking_url:
cost: '10.0'
@@ -2849,8 +2849,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-04T21:24:35.867Z'
- updated_at: '2026-05-04T21:24:35.916Z'
+ created_at: '2026-05-06T15:39:00.970Z'
+ updated_at: '2026-05-06T15:39:01.031Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -2922,7 +2922,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 149AA0940F5ABC58
+ code: 9767CD5982E9E1F3
status: active
currency: USD
amount: '10.0'
@@ -2936,8 +2936,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-05-04T21:24:36.256Z'
- updated_at: '2026-05-04T21:24:36.552Z'
+ created_at: '2026-05-06T15:39:01.377Z'
+ updated_at: '2026-05-06T15:39:01.685Z'
requestBody:
content:
application/json:
@@ -3068,8 +3068,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 104903
- slug: product-104903
+ name: Product 108552
+ slug: product-108552
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -3101,12 +3101,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:24:37.266Z'
- updated_at: '2026-05-04T21:24:37.266Z'
+ created_at: '2026-05-06T15:39:02.412Z'
+ updated_at: '2026-05-06T15:39:02.412Z'
digital_links: []
metadata: {}
- created_at: '2026-05-04T21:24:37.570Z'
- updated_at: '2026-05-04T21:24:37.570Z'
+ created_at: '2026-05-06T15:39:02.771Z'
+ updated_at: '2026-05-06T15:39:02.771Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -3173,8 +3173,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 124752
- slug: product-124752
+ name: Product 122624
+ slug: product-122624
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -3206,12 +3206,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:24:38.582Z'
- updated_at: '2026-05-04T21:24:38.582Z'
+ created_at: '2026-05-06T15:39:03.851Z'
+ updated_at: '2026-05-06T15:39:03.851Z'
digital_links: []
metadata: {}
- created_at: '2026-05-04T21:24:38.612Z'
- updated_at: '2026-05-04T21:24:38.612Z'
+ created_at: '2026-05-06T15:39:03.881Z'
+ updated_at: '2026-05-06T15:39:03.881Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -3300,8 +3300,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 134496
- slug: product-134496
+ name: Product 135474
+ slug: product-135474
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -3333,12 +3333,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:24:38.682Z'
- updated_at: '2026-05-04T21:24:38.682Z'
+ created_at: '2026-05-06T15:39:03.953Z'
+ updated_at: '2026-05-06T15:39:03.953Z'
digital_links: []
metadata: {}
- created_at: '2026-05-04T21:24:38.977Z'
- updated_at: '2026-05-04T21:24:38.977Z'
+ created_at: '2026-05-06T15:39:04.244Z'
+ updated_at: '2026-05-06T15:39:04.244Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -3400,8 +3400,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 142992
- slug: product-142992
+ name: Product 145608
+ slug: product-145608
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -3433,12 +3433,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:24:39.321Z'
- updated_at: '2026-05-04T21:24:39.321Z'
+ created_at: '2026-05-06T15:39:04.600Z'
+ updated_at: '2026-05-06T15:39:04.600Z'
digital_links: []
metadata: {}
- created_at: '2026-05-04T21:24:39.610Z'
- updated_at: '2026-05-04T21:24:39.916Z'
+ created_at: '2026-05-06T15:39:04.899Z'
+ updated_at: '2026-05-06T15:39:05.204Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -3564,8 +3564,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-08730060a26b
- number: PNTFTQ2S
+ response_code: BGS-dca37bbe3b96
+ number: PPD8OIGN
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3583,14 +3583,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-04T21:24:41.011Z'
- updated_at: '2026-05-04T21:24:41.016Z'
+ created_at: '2026-05-06T15:39:06.236Z'
+ updated_at: '2026-05-06T15:39:06.241Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-04T21:24:41.014Z'
- updated_at: '2026-05-04T21:24:41.014Z'
+ created_at: '2026-05-06T15:39:06.239Z'
+ updated_at: '2026-05-06T15:39:06.239Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -3657,7 +3657,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: P37036XF
+ number: PMWHRZFU
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -3668,8 +3668,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-04T21:24:42.452Z'
- updated_at: '2026-05-04T21:24:42.452Z'
+ created_at: '2026-05-06T15:39:07.591Z'
+ updated_at: '2026-05-06T15:39:07.591Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -3759,8 +3759,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-86e2d7ed2954
- number: PJEQV35O
+ response_code: BGS-5f85cd421c84
+ number: PR42HV9C
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3778,14 +3778,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-04T21:24:42.836Z'
- updated_at: '2026-05-04T21:24:42.839Z'
+ created_at: '2026-05-06T15:39:07.961Z'
+ updated_at: '2026-05-06T15:39:07.964Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-04T21:24:42.838Z'
- updated_at: '2026-05-04T21:24:42.838Z'
+ created_at: '2026-05-06T15:39:07.963Z'
+ updated_at: '2026-05-06T15:39:07.963Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -3844,8 +3844,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-c0a28c2acdac
- number: P8RD1A11
+ response_code: BGS-61f5e1a763a1
+ number: PX4QY4MX
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3863,14 +3863,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-04T21:24:43.513Z'
- updated_at: '2026-05-04T21:24:43.515Z'
+ created_at: '2026-05-06T15:39:08.632Z'
+ updated_at: '2026-05-06T15:39:08.634Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-04T21:24:43.514Z'
- updated_at: '2026-05-04T21:24:43.845Z'
+ created_at: '2026-05-06T15:39:08.633Z'
+ updated_at: '2026-05-06T15:39:09.077Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -3939,8 +3939,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-bdb7b6473eee
- number: PCFPE45K
+ response_code: void-BGS-4c991b13915c
+ number: P5O6Q1VP
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -3958,14 +3958,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-04T21:24:44.980Z'
- updated_at: '2026-05-04T21:24:44.982Z'
+ created_at: '2026-05-06T15:39:10.450Z'
+ updated_at: '2026-05-06T15:39:10.456Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-04T21:24:44.981Z'
- updated_at: '2026-05-04T21:24:45.287Z'
+ created_at: '2026-05-06T15:39:10.454Z'
+ updated_at: '2026-05-06T15:39:11.160Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/refunds":
@@ -4093,14 +4093,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-907a611cabd0
+ transaction_id: BGS-46da7c9a4487
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-05-04T21:24:46.718Z'
- updated_at: '2026-05-04T21:24:46.718Z'
+ created_at: '2026-05-06T15:39:12.603Z'
+ updated_at: '2026-05-06T15:39:12.603Z'
requestBody:
content:
application/json:
@@ -4171,8 +4171,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R842709124
+ number: R610855284
customer_note:
currency: USD
locale: en
@@ -4215,8 +4215,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:47.056Z'
- updated_at: '2026-05-04T21:24:47.122Z'
+ created_at: '2026-05-06T15:39:12.910Z'
+ updated_at: '2026-05-06T15:39:12.964Z'
tags: []
internal_note:
approver_id:
@@ -4385,8 +4385,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R926191687
+ number: R100259849
customer_note:
currency: USD
locale: en
@@ -4429,8 +4429,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:48.991Z'
- updated_at: '2026-05-04T21:24:48.991Z'
+ created_at: '2026-05-06T15:39:14.719Z'
+ updated_at: '2026-05-06T15:39:14.719Z'
tags: []
internal_note:
approver_id:
@@ -4559,7 +4559,7 @@ paths:
example:
id: or_gbHJdmfrXB
market_id:
- number: R937095721
+ number: R985800491
customer_note:
currency: USD
@@ -4603,8 +4603,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:50.173Z'
- updated_at: '2026-05-04T21:24:50.177Z'
+ created_at: '2026-05-06T15:39:15.895Z'
+ updated_at: '2026-05-06T15:39:15.899Z'
tags: []
internal_note:
approver_id:
@@ -4776,8 +4776,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R071158324
+ number: R182552732
customer_note:
currency: USD
locale: en
@@ -4820,8 +4820,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:50.465Z'
- updated_at: '2026-05-04T21:24:50.465Z'
+ created_at: '2026-05-06T15:39:16.177Z'
+ updated_at: '2026-05-06T15:39:16.177Z'
tags: []
internal_note:
approver_id:
@@ -4890,7 +4890,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R947632073
+ number: R721111794
customer_note:
currency: USD
@@ -4934,8 +4934,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:51.601Z'
- updated_at: '2026-05-04T21:24:51.895Z'
+ created_at: '2026-05-06T15:39:17.363Z'
+ updated_at: '2026-05-06T15:39:17.730Z'
tags: []
internal_note:
approver_id:
@@ -5106,8 +5106,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R514867057
+ number: R589173215
customer_note:
currency: USD
locale: en
@@ -5134,7 +5134,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-05-04T21:24:52.811Z'
+ completed_at: '2026-05-06T15:39:18.867Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5150,8 +5150,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:52.753Z'
- updated_at: '2026-05-04T21:24:52.856Z'
+ created_at: '2026-05-06T15:39:18.813Z'
+ updated_at: '2026-05-06T15:39:18.893Z'
tags: []
internal_note:
approver_id:
@@ -5230,8 +5230,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R720531937
+ number: R487134515
customer_note:
currency: USD
locale: en
@@ -5258,7 +5258,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-04T21:24:54.180Z'
+ completed_at: '2026-05-06T15:39:20.138Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5272,10 +5272,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-04T21:24:54.469Z'
+ canceled_at: '2026-05-06T15:39:20.436Z'
approved_at:
- created_at: '2026-05-04T21:24:54.124Z'
- updated_at: '2026-05-04T21:24:54.507Z'
+ created_at: '2026-05-06T15:39:20.074Z'
+ updated_at: '2026-05-06T15:39:20.479Z'
tags: []
internal_note:
approver_id:
@@ -5332,8 +5332,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R005206216
+ number: R070365976
customer_note:
currency: USD
locale: en
@@ -5360,7 +5360,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-04T21:24:54.856Z'
+ completed_at: '2026-05-06T15:39:20.831Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5375,9 +5375,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-05-04T21:24:55.150Z'
- created_at: '2026-05-04T21:24:54.802Z'
- updated_at: '2026-05-04T21:24:54.855Z'
+ approved_at: '2026-05-06T15:39:21.123Z'
+ created_at: '2026-05-06T15:39:20.779Z'
+ updated_at: '2026-05-06T15:39:20.831Z'
tags: []
internal_note:
approver_id: admin_UkLWZg9DAJ
@@ -5434,8 +5434,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R003532717
+ number: R215651185
customer_note:
currency: USD
locale: en
@@ -5462,7 +5462,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-04T21:24:55.490Z'
+ completed_at: '2026-05-06T15:39:21.498Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5476,10 +5476,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-04T21:24:55.773Z'
+ canceled_at: '2026-05-06T15:39:21.795Z'
approved_at:
- created_at: '2026-05-04T21:24:55.429Z'
- updated_at: '2026-05-04T21:24:55.865Z'
+ created_at: '2026-05-06T15:39:21.405Z'
+ updated_at: '2026-05-06T15:39:21.906Z'
tags: []
internal_note:
approver_id:
@@ -5536,8 +5536,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R793362812
+ number: R395224525
customer_note:
currency: USD
locale: en
@@ -5564,7 +5564,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-04T21:24:56.200Z'
+ completed_at: '2026-05-06T15:39:22.237Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5580,8 +5580,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-04T21:24:56.145Z'
- updated_at: '2026-05-04T21:24:56.200Z'
+ created_at: '2026-05-06T15:39:22.189Z'
+ updated_at: '2026-05-06T15:39:22.236Z'
tags: []
internal_note:
approver_id:
@@ -5653,8 +5653,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-04T21:24:56.503Z'
- updated_at: '2026-05-04T21:24:56.504Z'
+ created_at: '2026-05-06T15:39:22.538Z'
+ updated_at: '2026-05-06T15:39:22.539Z'
meta:
page: 1
limit: 25
@@ -5734,8 +5734,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-04T21:24:56.788Z'
- updated_at: '2026-05-04T21:24:56.789Z'
+ created_at: '2026-05-06T15:39:22.828Z'
+ updated_at: '2026-05-06T15:39:22.829Z'
"/api/v3/admin/products/{product_id}/custom_fields":
get:
summary: List product custom fields
@@ -5803,8 +5803,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-04T21:24:57.109Z'
- updated_at: '2026-05-04T21:24:57.109Z'
+ created_at: '2026-05-06T15:39:23.144Z'
+ updated_at: '2026-05-06T15:39:23.144Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -5871,8 +5871,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-05-04T21:24:57.733Z'
- updated_at: '2026-05-04T21:24:57.733Z'
+ created_at: '2026-05-06T15:39:23.750Z'
+ updated_at: '2026-05-06T15:39:23.750Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -5956,8 +5956,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-04T21:24:58.096Z'
- updated_at: '2026-05-04T21:24:58.096Z'
+ created_at: '2026-05-06T15:39:24.114Z'
+ updated_at: '2026-05-06T15:39:24.114Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -6004,8 +6004,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-05-04T21:24:58.412Z'
- updated_at: '2026-05-04T21:24:58.691Z'
+ created_at: '2026-05-06T15:39:24.428Z'
+ updated_at: '2026-05-06T15:39:24.708Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -6143,26 +6143,24 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 392083
- slug: product-392083
+ name: Product 394321
+ slug: product-394321
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-04T21:24:59.011Z'
+ available_on: '2025-05-06T15:39:25.028Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Dicta debitis labore cupiditate autem adipisci cumque.
- Quos repudiandae omnis voluptatum veniam nemo. Optio veniam quidem
- deleniti repudiandae excepturi sed. Tempore temporibus fugit vel
- possimus itaque. Ducimus molestiae labore perferendis commodi
- quibusdam aperiam non.
- description_html: Dicta debitis labore cupiditate autem adipisci
- cumque. Quos repudiandae omnis voluptatum veniam nemo. Optio veniam
- quidem deleniti repudiandae excepturi sed. Tempore temporibus
- fugit vel possimus itaque. Ducimus molestiae labore perferendis
- commodi quibusdam aperiam non.
+ description: Eum distinctio hic officiis quam at doloribus porro.
+ Est eius aspernatur soluta laborum expedita exercitationem perspiciatis.
+ Ipsa recusandae fuga a quae quisquam quam. Fuga ipsum cum molestiae
+ pariatur non aut.
+ description_html: Eum distinctio hic officiis quam at doloribus
+ porro. Est eius aspernatur soluta laborum expedita exercitationem
+ perspiciatis. Ipsa recusandae fuga a quae quisquam quam. Fuga
+ ipsum cum molestiae pariatur non aut.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6177,16 +6175,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-04T21:24:59.041Z'
- updated_at: '2026-05-04T21:24:59.041Z'
+ created_at: '2026-05-06T15:39:25.053Z'
+ updated_at: '2026-05-06T15:39:25.053Z'
original_price:
status: active
- make_active_at: '2025-05-04T21:24:59.011Z'
+ make_active_at: '2025-05-06T15:39:25.028Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-04T21:24:59.024Z'
- updated_at: '2026-05-04T21:24:59.042Z'
+ created_at: '2026-05-06T15:39:25.040Z'
+ updated_at: '2026-05-06T15:39:25.055Z'
cost_price: '17.0'
cost_currency: USD
meta:
@@ -6325,16 +6323,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-05-04T21:24:59.703Z'
- updated_at: '2026-05-04T21:24:59.703Z'
+ created_at: '2026-05-06T15:39:25.726Z'
+ updated_at: '2026-05-06T15:39:25.726Z'
original_price:
status: draft
make_active_at:
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-04T21:24:59.701Z'
- updated_at: '2026-05-04T21:24:59.708Z'
+ created_at: '2026-05-06T15:39:25.725Z'
+ updated_at: '2026-05-06T15:39:25.733Z'
cost_price:
cost_currency: USD
schema:
@@ -6521,26 +6519,22 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 432301
- slug: product-432301
+ name: Product 439753
+ slug: product-439753
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-04T21:25:00.049Z'
+ available_on: '2025-05-06T15:39:26.086Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Soluta magnam nesciunt in perferendis officia exercitationem.
- Corrupti neque nostrum necessitatibus amet unde tempore. Consequatur
- laborum id deserunt eveniet perferendis. Blanditiis aut culpa velit
- ducimus adipisci deleniti. Alias fuga tempore dignissimos illo cum
- officia molestiae quasi. Dolorem numquam facere velit culpa. Neque
- aut nobis atque id qui. Soluta quibusdam illo vel placeat repellat
- inventore magnam sapiente.
- description_html: |-
- Soluta magnam nesciunt in perferendis officia exercitationem. Corrupti neque nostrum necessitatibus amet unde tempore. Consequatur laborum id deserunt eveniet perferendis. Blanditiis aut culpa velit ducimus adipisci deleniti.
- Alias fuga tempore dignissimos illo cum officia molestiae quasi. Dolorem numquam facere velit culpa. Neque aut nobis atque id qui. Soluta quibusdam illo vel placeat repellat inventore magnam sapiente.
+ description: Laboriosam accusamus quae voluptatum consequatur. Nostrum
+ quidem rerum dignissimos beatae ut quaerat consectetur. Quia excepturi
+ facilis libero dolor placeat velit vero aspernatur.
+ description_html: Laboriosam accusamus quae voluptatum consequatur.
+ Nostrum quidem rerum dignissimos beatae ut quaerat consectetur.
+ Quia excepturi facilis libero dolor placeat velit vero aspernatur.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6555,16 +6549,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-04T21:25:00.075Z'
- updated_at: '2026-05-04T21:25:00.075Z'
+ created_at: '2026-05-06T15:39:26.110Z'
+ updated_at: '2026-05-06T15:39:26.110Z'
original_price:
status: active
- make_active_at: '2025-05-04T21:25:00.049Z'
+ make_active_at: '2025-05-06T15:39:26.086Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-04T21:25:00.062Z'
- updated_at: '2026-05-04T21:25:00.076Z'
+ created_at: '2026-05-06T15:39:26.098Z'
+ updated_at: '2026-05-06T15:39:26.111Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -6632,34 +6626,26 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-458084
+ slug: product-45396
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-04T21:25:00.742Z'
+ available_on: '2025-05-06T15:39:26.728Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Modi laboriosam assumenda pariatur consequuntur a voluptas
- id sunt. Saepe nihil dolor inventore voluptates voluptate ad libero
- sint. Earum facere ratione architecto cumque dignissimos quaerat.
- Dolorem in esse repudiandae error quidem quasi libero. At iure error
- a porro harum nobis fugiat. Blanditiis beatae dolore quae maxime
- nemo fugit libero. Numquam ipsa aspernatur dicta error blanditiis
- nostrum praesentium molestias. Amet fuga assumenda soluta occaecati
- tempore quam. Delectus optio similique placeat facere debitis. Maxime
- dolorem nostrum fugit nisi. In fugit occaecati blanditiis ex illo
- distinctio voluptates consequuntur. Nulla veritatis aliquam repellat
- quae vero perferendis. Recusandae vero quam commodi libero amet.
- Alias ipsum animi nam excepturi iure. Reiciendis sed sequi aut perspiciatis.
- Distinctio tempore qui ut sequi inventore quisquam consectetur sit.
- Eos aliquam tempora magnam laudantium ea dolore molestiae et.
+ description: Esse ipsa qui mollitia optio facilis. Dolor veritatis
+ nemo odio eaque voluptatem. Natus soluta alias numquam mollitia
+ esse iusto maxime. Illo ea ad maxime a consectetur similique vero.
+ Repudiandae rem voluptatum esse sit excepturi ipsum a. A illo animi
+ sapiente earum modi repudiandae inventore. Pariatur libero dicta
+ odio mollitia. Eum porro vitae quae exercitationem eligendi error
+ optio deserunt. Assumenda saepe nemo doloremque dolor. Ut illum
+ molestiae placeat consequatur totam ea earum possimus.
description_html: |-
- Modi laboriosam assumenda pariatur consequuntur a voluptas id sunt. Saepe nihil dolor inventore voluptates voluptate ad libero sint. Earum facere ratione architecto cumque dignissimos quaerat. Dolorem in esse repudiandae error quidem quasi libero.
- At iure error a porro harum nobis fugiat. Blanditiis beatae dolore quae maxime nemo fugit libero. Numquam ipsa aspernatur dicta error blanditiis nostrum praesentium molestias. Amet fuga assumenda soluta occaecati tempore quam. Delectus optio similique placeat facere debitis.
- Maxime dolorem nostrum fugit nisi. In fugit occaecati blanditiis ex illo distinctio voluptates consequuntur. Nulla veritatis aliquam repellat quae vero perferendis. Recusandae vero quam commodi libero amet.
- Alias ipsum animi nam excepturi iure. Reiciendis sed sequi aut perspiciatis. Distinctio tempore qui ut sequi inventore quisquam consectetur sit. Eos aliquam tempora magnam laudantium ea dolore molestiae et.
+ Esse ipsa qui mollitia optio facilis. Dolor veritatis nemo odio eaque voluptatem. Natus soluta alias numquam mollitia esse iusto maxime. Illo ea ad maxime a consectetur similique vero. Repudiandae rem voluptatum esse sit excepturi ipsum a.
+ A illo animi sapiente earum modi repudiandae inventore. Pariatur libero dicta odio mollitia. Eum porro vitae quae exercitationem eligendi error optio deserunt. Assumenda saepe nemo doloremque dolor. Ut illum molestiae placeat consequatur totam ea earum possimus.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6674,16 +6660,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-04T21:25:00.790Z'
- updated_at: '2026-05-04T21:25:00.790Z'
+ created_at: '2026-05-06T15:39:26.751Z'
+ updated_at: '2026-05-06T15:39:26.751Z'
original_price:
status: active
- make_active_at: '2025-05-04T21:25:00.742Z'
+ make_active_at: '2025-05-06T15:39:26.728Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-04T21:25:00.766Z'
- updated_at: '2026-05-04T21:25:01.099Z'
+ created_at: '2026-05-06T15:39:26.740Z'
+ updated_at: '2026-05-06T15:39:27.040Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -6846,6 +6832,173 @@ paths:
responses:
'204':
description: product deleted
+ "/api/v3/admin/store":
+ get:
+ summary: Get the current store
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const store = await client.store.get()
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ responses:
+ '200':
+ description: current store
+ content:
+ application/json:
+ example:
+ id: store_UkLWZg9DAJ
+ metadata: {}
+ name: Spree Test Store
+ default_currency: USD
+ default_locale: en
+ preferred_admin_locale:
+ preferred_timezone: UTC
+ preferred_weight_unit: lb
+ preferred_unit_system: imperial
+ created_at: '2026-05-06T15:38:39.437Z'
+ updated_at: '2026-05-06T15:39:27.808Z'
+ url: http://www.example.com:3000
+ supported_currencies:
+ - USD
+ supported_locales:
+ - en
+ logo_url:
+ schema:
+ "$ref": "#/components/schemas/Store"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update the current store
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates the current store configuration.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const store = await client.store.update({
+ name: 'My Store'
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ responses:
+ '200':
+ description: store updated
+ content:
+ application/json:
+ example:
+ id: store_UkLWZg9DAJ
+ metadata: {}
+ name: Renamed Store
+ default_currency: USD
+ default_locale: en
+ preferred_admin_locale:
+ preferred_timezone: UTC
+ preferred_weight_unit: lb
+ preferred_unit_system: imperial
+ created_at: '2026-05-06T15:38:39.437Z'
+ updated_at: '2026-05-06T15:39:28.429Z'
+ url: http://www.example.com:3000
+ supported_currencies:
+ - USD
+ supported_locales:
+ - en
+ logo_url:
+ schema:
+ "$ref": "#/components/schemas/Store"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Site Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: My Store
+ preferred_admin_locale:
+ type: string
+ example: en
+ preferred_timezone:
+ type: string
+ example: UTC
+ preferred_weight_unit:
+ type: string
+ example: kg
+ preferred_unit_system:
+ type: string
+ example: metric
"/api/v3/admin/tags":
get:
summary: List tags
@@ -7022,9 +7175,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-04T21:25:02.877Z'
- updated_at: '2026-05-04T21:25:02.888Z'
- product_name: Product 481984
+ created_at: '2026-05-06T15:39:29.848Z'
+ updated_at: '2026-05-06T15:39:29.858Z'
+ product_name: Product 48883
display_price: "$0.00"
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
@@ -7036,10 +7189,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 149.76
- height: 103.73
- width: 124.24
- depth: 68.25
+ weight: 98.2
+ height: 191.7
+ width: 108.27
+ depth: 51.84
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7062,8 +7215,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:25:02.896Z'
- updated_at: '2026-05-04T21:25:02.896Z'
+ created_at: '2026-05-06T15:39:29.867Z'
+ updated_at: '2026-05-06T15:39:29.867Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7071,9 +7224,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-04T21:25:02.894Z'
- updated_at: '2026-05-04T21:25:02.905Z'
- product_name: Product 481984
+ created_at: '2026-05-06T15:39:29.865Z'
+ updated_at: '2026-05-06T15:39:29.885Z'
+ product_name: Product 48883
display_price: "$19.99"
meta:
page: 1
@@ -7185,8 +7338,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:25:03.576Z'
- updated_at: '2026-05-04T21:25:03.576Z'
+ created_at: '2026-05-06T15:39:30.532Z'
+ updated_at: '2026-05-06T15:39:30.532Z'
metadata: {}
position: 3
total_on_hand: 0
@@ -7194,9 +7347,9 @@ paths:
cost_price:
cost_currency: USD
deleted_at:
- created_at: '2026-05-04T21:25:03.579Z'
- updated_at: '2026-05-04T21:25:03.581Z'
- product_name: Product 49122
+ created_at: '2026-05-06T15:39:30.535Z'
+ updated_at: '2026-05-06T15:39:30.536Z'
+ product_name: Product 496338
display_price: "$24.99"
'422':
description: validation error
@@ -7384,10 +7537,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 9.34
- height: 115.57
- width: 11.29
- depth: 135.82
+ weight: 109.61
+ height: 153.88
+ width: 194.6
+ depth: 125.0
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7410,8 +7563,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:25:03.982Z'
- updated_at: '2026-05-04T21:25:03.982Z'
+ created_at: '2026-05-06T15:39:30.926Z'
+ updated_at: '2026-05-06T15:39:30.926Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7419,9 +7572,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-04T21:25:03.979Z'
- updated_at: '2026-05-04T21:25:03.993Z'
- product_name: Product 516843
+ created_at: '2026-05-06T15:39:30.923Z'
+ updated_at: '2026-05-06T15:39:30.936Z'
+ product_name: Product 51961
display_price: "$19.99"
'404':
description: variant not found
@@ -7501,10 +7654,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 131.32
- height: 83.52
- width: 141.52
- depth: 95.22
+ weight: 85.0
+ height: 130.56
+ width: 173.42
+ depth: 12.77
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7527,8 +7680,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-04T21:25:04.649Z'
- updated_at: '2026-05-04T21:25:04.649Z'
+ created_at: '2026-05-06T15:39:31.624Z'
+ updated_at: '2026-05-06T15:39:31.624Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7536,9 +7689,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-04T21:25:04.646Z'
- updated_at: '2026-05-04T21:25:04.943Z'
- product_name: Product 535094
+ created_at: '2026-05-06T15:39:31.622Z'
+ updated_at: '2026-05-06T15:39:31.921Z'
+ product_name: Product 534060
display_price: "$19.99"
requestBody:
content:
@@ -9963,45 +10116,24 @@ components:
type: object
name:
type: string
- url:
- type: string
- code:
- type: string
- mail_from_address:
- type: string
- customer_support_email:
- type: string
- nullable: true
- new_order_notifications_email:
- type: string
- nullable: true
- description:
+ default_currency:
type: string
- nullable: true
- address:
+ default_locale:
type: string
- nullable: true
- contact_phone:
+ preferred_admin_locale:
type: string
nullable: true
- seo_title:
+ preferred_timezone:
type: string
- nullable: true
- meta_keywords:
+ preferred_weight_unit:
type: string
- nullable: true
- meta_description:
+ preferred_unit_system:
type: string
- nullable: true
- default:
- type: boolean
created_at:
type: string
updated_at:
type: string
- default_currency:
- type: string
- default_locale:
+ url:
type: string
supported_currencies:
type: array
@@ -10014,33 +10146,22 @@ components:
logo_url:
type: string
nullable: true
- mailer_logo_url:
- type: string
- nullable: true
required:
- id
- metadata
- name
- - url
- - code
- - mail_from_address
- - customer_support_email
- - new_order_notifications_email
- - description
- - address
- - contact_phone
- - seo_title
- - meta_keywords
- - meta_description
- - default
- - created_at
- - updated_at
- default_currency
- default_locale
+ - preferred_admin_locale
+ - preferred_timezone
+ - preferred_weight_unit
+ - preferred_unit_system
+ - created_at
+ - updated_at
+ - url
- supported_currencies
- supported_locales
- logo_url
- - mailer_logo_url
x-typelizer: true
TaxCategory:
type: object
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index d104e52c85..b392fc872f 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -306,7 +306,7 @@ export class AdminClient {
readonly me = {
/** Get the current admin user profile and their serialized permissions. */
- show: (options?: RequestOptions): Promise<MeResponse> =>
+ get: (options?: RequestOptions): Promise<MeResponse> =>
this.request<MeResponse>('GET', '/me', options),
}
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 9f6bbf4728..47799ae31c 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -3,20 +3,10 @@
export interface StoreUpdateParams {
name?: string
- url?: string
- mail_from_address?: string
- customer_support_email?: string
- new_order_notifications_email?: string
- description?: string
- address?: string
- contact_phone?: string
- seo_title?: string
- meta_keywords?: string
- meta_description?: string
- default_currency?: string
- default_locale?: string
- supported_currencies?: string
- supported_locales?: string
+ preferred_admin_locale?: string
+ preferred_timezone?: string
+ preferred_weight_unit?: string
+ preferred_unit_system?: string
}
export interface OptionTypeCreateParams {
diff --git a/packages/admin-sdk/src/types/generated/Store.ts b/packages/admin-sdk/src/types/generated/Store.ts
index 74ae9c85a9..9c78212839 100644
--- a/packages/admin-sdk/src/types/generated/Store.ts
+++ b/packages/admin-sdk/src/types/generated/Store.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 0658f530ce9dcfb753fa0400270e03ac
+// Typelizer digest 608d58eacf0255764ac3e6ddf74fd87b
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -6,26 +6,18 @@ interface Store {
id: string;
metadata: Record<string, unknown>;
name: string;
- url: string;
- code: string;
- mail_from_address: string;
- customer_support_email: string | null;
- new_order_notifications_email: string | null;
- description: string | null;
- address: string | null;
- contact_phone: string | null;
- seo_title: string | null;
- meta_keywords: string | null;
- meta_description: string | null;
- default: boolean;
- created_at: string;
- updated_at: string;
default_currency: string;
default_locale: string;
+ preferred_admin_locale: string | null;
+ preferred_timezone: string;
+ preferred_weight_unit: string;
+ preferred_unit_system: string;
+ created_at: string;
+ updated_at: string;
+ url: string;
supported_currencies: Array<string>;
supported_locales: Array<string>;
logo_url: string | null;
- mailer_logo_url: string | null;
}
export default Store;
diff --git a/packages/admin/src/components/spree/form-actions.tsx b/packages/admin/src/components/spree/form-actions.tsx
new file mode 100644
index 0000000000..93c58d4e8e
--- /dev/null
+++ b/packages/admin/src/components/spree/form-actions.tsx
@@ -0,0 +1,135 @@
+import { Loader2Icon } from 'lucide-react'
+import { useEffect } from 'react'
+import { type FieldValues, type UseFormReturn, useFormState } from 'react-hook-form'
+import { Button } from '@/components/ui/button'
+
+/**
+ * Submit button wired to a `react-hook-form` instance. Always rendered,
+ * disabled until the form is dirty. Replaces the legacy "footer pops up
+ * when something changes" pattern with the always-visible header pattern
+ * Linear and modern Shopify use.
+ *
+ * Reads `isDirty` and `isSubmitting` from the RHF form state via
+ * `useFormState`, so the button re-renders independently of the parent page
+ * and won't churn on every keystroke.
+ *
+ * Uses `<button type="submit">` and relies on the surrounding `<form>` to
+ * dispatch submission — same flow as the legacy sticky footer. ⌘S keyboard
+ * submission is handled separately by `useFormSubmitShortcut`.
+ */
+export function FormSaveButton<TFieldValues extends FieldValues>({
+ form,
+ label = 'Save',
+ savingLabel = 'Saving…',
+}: {
+ form: UseFormReturn<TFieldValues, any, any>
+ label?: string
+ savingLabel?: string
+}) {
+ const { isDirty, isSubmitting } = useFormState({ control: form.control })
+
+ return (
+ <Button type="submit" size="sm" disabled={!isDirty || isSubmitting}>
+ {isSubmitting && <Loader2Icon className="animate-spin" />}
+ {isSubmitting ? savingLabel : label}
+ </Button>
+ )
+}
+
+/**
+ * Discard button wired to a `react-hook-form` instance. Renders only when
+ * the form is dirty (so the header stays uncluttered for read-only pages).
+ *
+ * Calls `form.reset()` by default — pass `onDiscard` to override (e.g., to
+ * reset to a freshly-fetched server value rather than the original mount
+ * defaults).
+ */
+export function FormDiscardButton<TFieldValues extends FieldValues>({
+ form,
+ label = 'Discard',
+ onDiscard,
+}: {
+ form: UseFormReturn<TFieldValues, any, any>
+ label?: string
+ onDiscard?: () => void
+}) {
+ const { isDirty, isSubmitting } = useFormState({ control: form.control })
+
+ if (!isDirty) return null
+
+ return (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ disabled={isSubmitting}
+ onClick={onDiscard ?? (() => form.reset())}
+ >
+ {label}
+ </Button>
+ )
+}
+
+/**
+ * Convenience: render Discard + Save side-by-side. Most pages just want both.
+ */
+export function FormActions<TFieldValues extends FieldValues>({
+ form,
+ saveLabel,
+ savingLabel,
+ discardLabel,
+ onDiscard,
+}: {
+ form: UseFormReturn<TFieldValues, any, any>
+ saveLabel?: string
+ savingLabel?: string
+ discardLabel?: string
+ onDiscard?: () => void
+}) {
+ return (
+ <>
+ <FormDiscardButton form={form} label={discardLabel} onDiscard={onDiscard} />
+ <FormSaveButton form={form} label={saveLabel} savingLabel={savingLabel} />
+ </>
+ )
+}
+
+/**
+ * Bind ⌘S / Ctrl+S to submit a `react-hook-form` instance. Mount once per
+ * form. Skips when the form is pristine or already submitting — same gate
+ * as the visual Save button. Schema validation still runs inside
+ * `form.handleSubmit`, so invalid input rejects on its own without us
+ * needing to read `isValid` (which is unreliable under the default
+ * `onSubmit` validation mode).
+ *
+ * Also wires `beforeunload` to warn if the user closes the tab or navigates
+ * away while the form is dirty. (TanStack Router internal navigation is not
+ * intercepted — the SPA's own dirty-route guard would belong elsewhere.)
+ */
+export function useFormSubmitShortcut<TFieldValues extends FieldValues>(
+ form: UseFormReturn<TFieldValues, any, any>,
+ onSubmit: (values: TFieldValues) => void | Promise<void>,
+) {
+ const { isDirty, isSubmitting } = useFormState({ control: form.control })
+
+ useEffect(() => {
+ const handler = (event: KeyboardEvent) => {
+ if (event.key !== 's' && event.key !== 'S') return
+ if (!(event.metaKey || event.ctrlKey)) return
+ event.preventDefault()
+ if (!isDirty || isSubmitting) return
+ void form.handleSubmit(onSubmit)()
+ }
+ window.addEventListener('keydown', handler)
+ return () => window.removeEventListener('keydown', handler)
+ }, [form, onSubmit, isDirty, isSubmitting])
+
+ useEffect(() => {
+ if (!isDirty) return
+ const handler = (event: BeforeUnloadEvent) => {
+ event.preventDefault()
+ }
+ window.addEventListener('beforeunload', handler)
+ return () => window.removeEventListener('beforeunload', handler)
+ }, [isDirty])
+}
diff --git a/packages/admin/src/components/spree/nav-main.tsx b/packages/admin/src/components/spree/nav-main.tsx
index c7934104f3..7c883d01d9 100644
--- a/packages/admin/src/components/spree/nav-main.tsx
+++ b/packages/admin/src/components/spree/nav-main.tsx
@@ -28,7 +28,7 @@ export type NavItem = {
items?: { title: string; url: string; subject?: SubjectName }[]
}
-function NavIcon({ icon: Icon, isActive }: { icon: NavItem['icon']; isActive?: boolean }) {
+export function NavIcon({ icon: Icon, isActive }: { icon: NavItem['icon']; isActive?: boolean }) {
return (
<span
className={
diff --git a/packages/admin/src/components/spree/page-header.tsx b/packages/admin/src/components/spree/page-header.tsx
index cae07cff3d..0c84216cc7 100644
--- a/packages/admin/src/components/spree/page-header.tsx
+++ b/packages/admin/src/components/spree/page-header.tsx
@@ -14,6 +14,8 @@ import {
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
+import { useScrolled } from '@/hooks/use-scrolled'
+import { cn } from '@/lib/utils'
// JSON drawer is a developer-only feature; pulling its tree (which includes
// @uiw/react-json-view at ~30KB gzip) into the route bundle is wasteful.
@@ -113,9 +115,30 @@ export function PageHeader({
setJsonOpen(true)
}
const { storeId } = useParams({ strict: false }) as { storeId?: string }
+ const scrolled = useScrolled()
return (
- <header className="flex items-start gap-3">
+ // Sticky below the TopBar (which sticks at `top-0`, height
+ // `--spacing-header-height`) so the title, badges, and primary actions
+ // (notably Save on form pages) stay reachable as the user scrolls long
+ // detail pages. `bg-background` masks the content scrolling behind it;
+ // `-mx-4 px-4 lg:-mx-6 lg:px-6` and `-mt-4 lg:-mt-6 pt-4 lg:pt-6` undo
+ // and re-apply the parent padding so the sticky band runs edge-to-edge
+ // and there's no transparent gap between the TopBar and the header.
+ //
+ // The `::after` pseudo-element is the bottom hairline — it fades in
+ // once the user scrolls (so the header blends at rest, separates when
+ // content slides under it). A horizontal `mask-image` gradient feathers
+ // the hairline's left/right edges to transparent so it doesn't visually
+ // collide with the page edges; the `border-border` color it carries is
+ // the same hairline used elsewhere in the app.
+ <header
+ className={cn(
+ 'sticky top-(--spacing-header-height) z-20 -mx-4 -mt-4 flex items-start gap-3 bg-background px-4 pt-4 pb-3 lg:-mx-6 lg:-mt-6 lg:px-6 lg:pt-6',
+ 'after:pointer-events-none after:absolute after:inset-x-0 after:bottom-0 after:h-px after:bg-border after:opacity-0 after:transition-opacity after:duration-150 after:[mask-image:linear-gradient(to_right,transparent,black_8%,black_92%,transparent)]',
+ scrolled && 'after:opacity-100',
+ )}
+ >
{backTo && <BackButton fallback={backTo} />}
<div className="flex flex-1 flex-wrap items-center gap-x-3 gap-y-1">
diff --git a/packages/admin/src/components/spree/settings-sidebar.tsx b/packages/admin/src/components/spree/settings-sidebar.tsx
new file mode 100644
index 0000000000..90337bdd80
--- /dev/null
+++ b/packages/admin/src/components/spree/settings-sidebar.tsx
@@ -0,0 +1,135 @@
+import { Link, useParams, useRouterState } from '@tanstack/react-router'
+import { PackageIcon } from 'lucide-react'
+import { NavIcon } from '@/components/spree/nav-main'
+import { Badge } from '@/components/ui/badge'
+import {
+ SidebarGroup,
+ SidebarGroupLabel,
+ SidebarMenu,
+ SidebarMenuButton,
+ SidebarMenuItem,
+} from '@/components/ui/sidebar'
+import {
+ type SettingsNavEntry,
+ type SettingsNavSnapshot,
+ useSettingsNav,
+} from '@/lib/settings-nav-registry'
+import { cn } from '@/lib/utils'
+import { type Permissions, usePermissions } from '@/providers/permission-provider'
+
+import '@/nav/settings'
+
+/**
+ * Secondary settings sidebar. Always mounted as a sibling to the primary
+ * sidebar so it can extend full-height (top of viewport to bottom, beside
+ * the TopBar rather than below it). Width animates between `0` and
+ * `--spacing-sidebar-width` driven by the `open` prop, so entering and
+ * leaving the settings area gets a slide-in/slide-out transition.
+ *
+ * Entries reuse the same shadcn primitives (`SidebarMenuButton`, `NavIcon`,
+ * `SidebarGroupLabel`) as the primary sidebar so hover/active states and
+ * spacing stay perfectly consistent.
+ *
+ * Hidden below `lg` regardless of `open` — settings on narrow viewports
+ * still need a separate solution.
+ */
+export function SettingsSidebar({ open }: { open: boolean }) {
+ const { storeId } = useParams({ strict: false }) as { storeId?: string }
+ const id = storeId ?? 'default'
+ const snapshot = useSettingsNav()
+ const { permissions } = usePermissions()
+ const visible = filterByPermissions(snapshot, permissions)
+
+ // `sticky top-0 h-svh` keeps the nav at full viewport height as the page
+ // scrolls. `overflow-hidden` clips the inner fixed-width content while the
+ // outer `width` animates between 0 and `--spacing-sidebar-width`. `aria-hidden`
+ // while closed prevents screen-reader and keyboard access to hidden links.
+ return (
+ <aside
+ aria-label="Settings navigation"
+ aria-hidden={!open}
+ data-state={open ? 'open' : 'closed'}
+ className={cn(
+ 'sticky top-0 z-30 hidden h-svh shrink-0 self-start overflow-hidden bg-sidebar text-sidebar-foreground transition-[width,border-color] duration-200 ease-out lg:block',
+ open
+ ? 'lg:w-(--spacing-sidebar-width) border-r border-sidebar-border'
+ : 'lg:w-0 border-r-0 border-transparent',
+ )}
+ >
+ <div
+ className={cn(
+ 'flex h-full w-(--spacing-sidebar-width) flex-col gap-2 overflow-y-auto py-2 transition-opacity duration-200',
+ open ? 'opacity-100 delay-100' : 'pointer-events-none opacity-0',
+ )}
+ >
+ {visible.groups.map(({ group, entries }) => (
+ <SidebarGroup key={group.key}>
+ <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
+ <SidebarMenu>
+ {entries.map((entry) => (
+ <SettingsItem
+ key={entry.key}
+ entry={entry}
+ storeId={id}
+ // While closed, keep the items out of the tab order — the
+ // `aria-hidden` above does not, by itself, prevent focus.
+ tabIndex={open ? 0 : -1}
+ />
+ ))}
+ </SidebarMenu>
+ </SidebarGroup>
+ ))}
+ </div>
+ </aside>
+ )
+}
+
+function SettingsItem({
+ entry,
+ storeId,
+ tabIndex,
+}: {
+ entry: SettingsNavEntry
+ storeId: string
+ tabIndex: number
+}) {
+ const routerState = useRouterState()
+ const currentPath = routerState.location.pathname
+ const url = `/${storeId}/settings${entry.path}`
+ const isActive = currentPath === url || currentPath.startsWith(`${url}/`)
+ const Icon = entry.icon ?? PackageIcon
+
+ return (
+ <SidebarMenuItem>
+ {/* No `tooltip` prop — it keys off the primary sidebar's collapsed state
+ via `useSidebar()`, which would fire spuriously in this secondary nav. */}
+ <SidebarMenuButton asChild isActive={isActive}>
+ <Link to={url} tabIndex={tabIndex}>
+ <NavIcon icon={Icon} isActive={isActive} />
+ <span>{entry.label}</span>
+ {entry.comingSoon && (
+ <Badge className="ml-auto h-5 bg-sidebar-accent px-1.5 py-0 text-[10px] font-normal text-sidebar-foreground/70">
+ Soon
+ </Badge>
+ )}
+ </Link>
+ </SidebarMenuButton>
+ </SidebarMenuItem>
+ )
+}
+
+function filterByPermissions(
+ snapshot: SettingsNavSnapshot,
+ permissions: Permissions,
+): SettingsNavSnapshot {
+ const groups = snapshot.groups
+ .map(({ group, entries }) => ({
+ group,
+ entries: entries.filter((e) => !e.subject || permissions.can('read', e.subject)),
+ }))
+ .filter((g) => g.entries.length > 0)
+ return {
+ groups,
+ all: groups.flatMap((g) => g.entries),
+ }
+}
diff --git a/packages/admin/src/components/spree/sticky-form-footer.tsx b/packages/admin/src/components/spree/sticky-form-footer.tsx
deleted file mode 100644
index 0a9fde7349..0000000000
--- a/packages/admin/src/components/spree/sticky-form-footer.tsx
+++ /dev/null
@@ -1,61 +0,0 @@
-import type { FieldValues, UseFormReturn } from 'react-hook-form'
-import { Button } from '@/components/ui/button'
-import { cn } from '@/lib/utils'
-
-interface StickyFormFooterProps<TFieldValues extends FieldValues = FieldValues> {
- /** RHF form instance. Reads `formState.isDirty` / `isSubmitting`. */
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- form: UseFormReturn<TFieldValues, any, any>
- /** Save button label. Default "Save". */
- saveLabel?: string
- /** Cancel button label. Default "Discard". */
- cancelLabel?: string
- /** Called when Discard is clicked. Default: `form.reset()`. */
- onCancel?: () => void
- /** Always render the footer (don't gate on isDirty). Useful for "create" forms. */
- alwaysVisible?: boolean
- className?: string
-}
-
-/**
- * Sticky save bar that appears at the bottom of the viewport while the form
- * has unsaved changes. Sits inside the form so its submit button triggers RHF.
- *
- * Replaces the legacy `data-controller="sticky"` save bar. Use in addition to
- * `<PageHeader actions={...}>` when forms are long enough that the top Save
- * button scrolls out of view.
- */
-export function StickyFormFooter<TFieldValues extends FieldValues>({
- form,
- saveLabel = 'Save',
- cancelLabel = 'Discard',
- onCancel,
- alwaysVisible = false,
- className,
-}: StickyFormFooterProps<TFieldValues>) {
- const { isDirty, isSubmitting } = form.formState
-
- if (!alwaysVisible && !isDirty) return null
-
- return (
- <div
- className={cn(
- 'sticky bottom-0 -mx-4 mt-4 flex items-center justify-end gap-2 border-t border-border bg-background/90 px-4 py-3 backdrop-blur supports-[backdrop-filter]:bg-background/75',
- className,
- )}
- >
- <Button
- type="button"
- size="sm"
- variant="outline"
- onClick={onCancel ?? (() => form.reset())}
- disabled={isSubmitting}
- >
- {cancelLabel}
- </Button>
- <Button type="submit" size="sm" disabled={isSubmitting}>
- {isSubmitting ? 'Saving…' : saveLabel}
- </Button>
- </div>
- )
-}
diff --git a/packages/admin/src/hooks/use-scrolled.ts b/packages/admin/src/hooks/use-scrolled.ts
new file mode 100644
index 0000000000..4171735aae
--- /dev/null
+++ b/packages/admin/src/hooks/use-scrolled.ts
@@ -0,0 +1,30 @@
+import * as React from 'react'
+
+/**
+ * Returns true once the document has been scrolled past `threshold` pixels
+ * from the top, false at rest. Used to fade in subtle elevation on sticky
+ * headers, top bars, etc. so they don't look heavy when nothing is scrolled
+ * behind them.
+ *
+ * Listens passively to `window` scroll. Default threshold is 4px to avoid
+ * flickering at the boundary on devices that report fractional scroll
+ * positions. Initial value is computed synchronously on mount so the first
+ * paint matches the actual scroll position (e.g., after browser scroll
+ * restoration on navigation).
+ */
+export function useScrolled(threshold = 4) {
+ // Always start `false` so a future SSR render and the first client paint
+ // agree (no hydration mismatch). The effect below resyncs against the
+ // actual scroll position on mount, so any restored scroll position is
+ // reflected as soon as the effect runs.
+ const [scrolled, setScrolled] = React.useState(false)
+
+ React.useEffect(() => {
+ const onScroll = () => setScrolled(window.scrollY > threshold)
+ onScroll()
+ window.addEventListener('scroll', onScroll, { passive: true })
+ return () => window.removeEventListener('scroll', onScroll)
+ }, [threshold])
+
+ return scrolled
+}
diff --git a/packages/admin/src/hooks/use-store-settings.ts b/packages/admin/src/hooks/use-store-settings.ts
new file mode 100644
index 0000000000..1c3f6aeb68
--- /dev/null
+++ b/packages/admin/src/hooks/use-store-settings.ts
@@ -0,0 +1,24 @@
+import type { StoreUpdateParams } from '@spree/admin-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { adminClient } from '@/client'
+import { useStore } from '@/providers/store-provider'
+
+export function useStoreSettings() {
+ return useQuery({
+ queryKey: ['store-settings'],
+ queryFn: () => adminClient.store.get(),
+ })
+}
+
+export function useUpdateStoreSettings() {
+ const queryClient = useQueryClient()
+ const { refetch } = useStore()
+
+ return useMutation({
+ mutationFn: (params: StoreUpdateParams) => adminClient.store.update(params),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['store-settings'] })
+ refetch()
+ },
+ })
+}
diff --git a/packages/admin/src/lib/permissions.ts b/packages/admin/src/lib/permissions.ts
index 0e0ea52493..b2c152024a 100644
--- a/packages/admin/src/lib/permissions.ts
+++ b/packages/admin/src/lib/permissions.ts
@@ -11,6 +11,7 @@ export const Subject = {
Order: 'Spree::Order',
Customer: 'Spree::User',
AdminUser: 'Spree::AdminUser',
+ ApiKey: 'Spree::ApiKey',
Store: 'Spree::Store',
Taxon: 'Spree::Taxon',
Taxonomy: 'Spree::Taxonomy',
diff --git a/packages/admin/src/lib/settings-nav-registry.ts b/packages/admin/src/lib/settings-nav-registry.ts
new file mode 100644
index 0000000000..f4b1f7e98f
--- /dev/null
+++ b/packages/admin/src/lib/settings-nav-registry.ts
@@ -0,0 +1,140 @@
+import type { LucideIcon } from 'lucide-react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from '@/lib/permissions'
+
+/**
+ * Registry for the settings sub-shell sidebar. Mirrors `nav-registry.ts` but
+ * adds a `group` key so entries cluster under labelled section headers
+ * (Store · Localization · Team & Access · Developer …).
+ *
+ * Plugins extend the settings nav by importing `settingsNav` and calling
+ * `settingsNav.add(...)` from a side-effect module loaded at app boot.
+ */
+
+export interface SettingsNavEntry {
+ /** Stable identifier — used for register/remove/update and as the React key. */
+ key: string
+ /** Visible label. */
+ label: string
+ /**
+ * Path template, prefixed with `/$storeId/settings` at render time. Pass paths
+ * like `'/general'` or `'/staff'`, NOT `/store_abc/settings/general`. The
+ * leading slash is required.
+ */
+ path: string
+ /** Icon shown next to the label. */
+ icon?: LucideIcon
+ /** Group identifier — entries with the same group cluster under one header. */
+ group: string
+ /** Position within the group. Lower numbers render first. Defaults to 100. */
+ position?: number
+ /** CanCanCan subject required to see this item. Omit for always-visible. */
+ subject?: SubjectName
+ /** When true, the page is disabled in the sidebar with a "Soon" badge. */
+ comingSoon?: boolean
+}
+
+export interface SettingsNavGroup {
+ /** Group identifier referenced by entries. */
+ key: string
+ /** Visible header label. */
+ label: string
+ /** Group ordering. Lower numbers render first. Defaults to 100. */
+ position?: number
+}
+
+interface SettingsNavMutator {
+ /** Register an entry. Throws if the key is already registered. */
+ add(entry: SettingsNavEntry): void
+ /** Remove an entry by key. No-op when missing. */
+ remove(key: string): void
+ /** Patch an existing entry. Throws if the key is missing. */
+ update(key: string, patch: Partial<Omit<SettingsNavEntry, 'key'>>): void
+ /** Register a group. Throws if the key is already registered. */
+ addGroup(group: SettingsNavGroup): void
+}
+
+const entries: SettingsNavEntry[] = []
+const groups: SettingsNavGroup[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: SettingsNavSnapshot | null = null
+
+export interface SettingsNavSnapshot {
+ /** Groups, sorted by `position`, each with their entries (also sorted). */
+ groups: Array<{ group: SettingsNavGroup; entries: SettingsNavEntry[] }>
+ /** Flat list of every entry, sorted by group position then entry position. */
+ all: SettingsNavEntry[]
+}
+
+function notify() {
+ snapshotCache = null
+ for (const l of listeners) l()
+}
+
+export const settingsNav: SettingsNavMutator = {
+ add(entry) {
+ if (entries.some((e) => e.key === entry.key)) {
+ throw new Error(`Settings nav entry "${entry.key}" already registered.`)
+ }
+ entries.push(entry)
+ notify()
+ },
+ remove(key) {
+ const i = entries.findIndex((e) => e.key === key)
+ if (i === -1) return
+ entries.splice(i, 1)
+ notify()
+ },
+ update(key, patch) {
+ const e = entries.find((x) => x.key === key)
+ if (!e) throw new Error(`Settings nav entry "${key}" not found.`)
+ Object.assign(e, patch)
+ notify()
+ },
+ addGroup(group) {
+ if (groups.some((g) => g.key === group.key)) {
+ throw new Error(`Settings nav group "${group.key}" already registered.`)
+ }
+ groups.push(group)
+ notify()
+ },
+}
+
+function buildSnapshot(): SettingsNavSnapshot {
+ const sortedGroups = [...groups].sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+ const grouped = sortedGroups
+ .map((group) => ({
+ group,
+ entries: entries
+ .filter((e) => e.group === group.key)
+ .sort((a, b) => (a.position ?? 100) - (b.position ?? 100)),
+ }))
+ .filter((g) => g.entries.length > 0)
+ return {
+ groups: grouped,
+ all: grouped.flatMap((g) => g.entries),
+ }
+}
+
+function subscribe(listener: () => void): () => void {
+ listeners.add(listener)
+ return () => {
+ listeners.delete(listener)
+ }
+}
+
+function getSnapshot() {
+ if (!snapshotCache) snapshotCache = buildSnapshot()
+ return snapshotCache
+}
+
+export function useSettingsNav() {
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Test-only: clear the registry. */
+export function __resetSettingsNavRegistry(): void {
+ entries.length = 0
+ groups.length = 0
+ notify()
+}
diff --git a/packages/admin/src/nav/settings.ts b/packages/admin/src/nav/settings.ts
new file mode 100644
index 0000000000..92c93ecea2
--- /dev/null
+++ b/packages/admin/src/nav/settings.ts
@@ -0,0 +1,38 @@
+import { KeyRoundIcon, StoreIcon, UsersRoundIcon } from 'lucide-react'
+import { Subject } from '@/lib/permissions'
+import { settingsNav } from '@/lib/settings-nav-registry'
+
+settingsNav.addGroup({ key: 'store', label: 'Store', position: 100 })
+settingsNav.addGroup({ key: 'team', label: 'Team & access', position: 200 })
+
+settingsNav.add({
+ key: 'settings.store',
+ label: 'Store',
+ path: '/store',
+ icon: StoreIcon,
+ group: 'store',
+ position: 100,
+ subject: Subject.Store,
+})
+
+settingsNav.add({
+ key: 'settings.staff',
+ label: 'Staff',
+ path: '/staff',
+ icon: UsersRoundIcon,
+ group: 'team',
+ position: 100,
+ subject: Subject.AdminUser,
+ comingSoon: true,
+})
+
+settingsNav.add({
+ key: 'settings.api-keys',
+ label: 'API keys',
+ path: '/api-keys',
+ icon: KeyRoundIcon,
+ group: 'team',
+ position: 200,
+ subject: Subject.ApiKey,
+ comingSoon: true,
+})
diff --git a/packages/admin/src/providers/permission-provider.tsx b/packages/admin/src/providers/permission-provider.tsx
index 4443694d13..a69069e23d 100644
--- a/packages/admin/src/providers/permission-provider.tsx
+++ b/packages/admin/src/providers/permission-provider.tsx
@@ -83,7 +83,7 @@ export function PermissionProvider({ children }: { children: ReactNode }) {
let cancelled = false
setIsLoading(true)
adminClient.me
- .show()
+ .get()
.then((res) => {
if (!cancelled) setRules(res.permissions)
})
diff --git a/packages/admin/src/routeTree.gen.ts b/packages/admin/src/routeTree.gen.ts
index 9ac606d6af..26be91772d 100644
--- a/packages/admin/src/routeTree.gen.ts
+++ b/packages/admin/src/routeTree.gen.ts
@@ -14,9 +14,14 @@ import { Route as AuthenticatedRouteImport } from './routes/_authenticated'
import { Route as AuthenticatedIndexRouteImport } from './routes/_authenticated/index'
import { Route as AuthenticatedStoreIdRouteImport } from './routes/_authenticated/$storeId'
import { Route as AuthenticatedStoreIdIndexRouteImport } from './routes/_authenticated/$storeId/index'
+import { Route as AuthenticatedStoreIdSettingsRouteImport } from './routes/_authenticated/$storeId/settings'
+import { Route as AuthenticatedStoreIdSettingsIndexRouteImport } from './routes/_authenticated/$storeId/settings/index'
import { Route as AuthenticatedStoreIdProductsIndexRouteImport } from './routes/_authenticated/$storeId/products/index'
import { Route as AuthenticatedStoreIdOrdersIndexRouteImport } from './routes/_authenticated/$storeId/orders/index'
import { Route as AuthenticatedStoreIdCustomersIndexRouteImport } from './routes/_authenticated/$storeId/customers/index'
+import { Route as AuthenticatedStoreIdSettingsStoreRouteImport } from './routes/_authenticated/$storeId/settings/store'
+import { Route as AuthenticatedStoreIdSettingsStaffRouteImport } from './routes/_authenticated/$storeId/settings/staff'
+import { Route as AuthenticatedStoreIdSettingsApiKeysRouteImport } from './routes/_authenticated/$storeId/settings/api-keys'
import { Route as AuthenticatedStoreIdProductsProductIdRouteImport } from './routes/_authenticated/$storeId/products/$productId'
import { Route as AuthenticatedStoreIdOrdersNewRouteImport } from './routes/_authenticated/$storeId/orders/new'
import { Route as AuthenticatedStoreIdOrdersDraftsRouteImport } from './routes/_authenticated/$storeId/orders/drafts'
@@ -48,6 +53,18 @@ const AuthenticatedStoreIdIndexRoute =
path: '/',
getParentRoute: () => AuthenticatedStoreIdRoute,
} as any)
+const AuthenticatedStoreIdSettingsRoute =
+ AuthenticatedStoreIdSettingsRouteImport.update({
+ id: '/settings',
+ path: '/settings',
+ getParentRoute: () => AuthenticatedStoreIdRoute,
+ } as any)
+const AuthenticatedStoreIdSettingsIndexRoute =
+ AuthenticatedStoreIdSettingsIndexRouteImport.update({
+ id: '/',
+ path: '/',
+ getParentRoute: () => AuthenticatedStoreIdSettingsRoute,
+ } as any)
const AuthenticatedStoreIdProductsIndexRoute =
AuthenticatedStoreIdProductsIndexRouteImport.update({
id: '/products/',
@@ -66,6 +83,24 @@ const AuthenticatedStoreIdCustomersIndexRoute =
path: '/customers/',
getParentRoute: () => AuthenticatedStoreIdRoute,
} as any)
+const AuthenticatedStoreIdSettingsStoreRoute =
+ AuthenticatedStoreIdSettingsStoreRouteImport.update({
+ id: '/store',
+ path: '/store',
+ getParentRoute: () => AuthenticatedStoreIdSettingsRoute,
+ } as any)
+const AuthenticatedStoreIdSettingsStaffRoute =
+ AuthenticatedStoreIdSettingsStaffRouteImport.update({
+ id: '/staff',
+ path: '/staff',
+ getParentRoute: () => AuthenticatedStoreIdSettingsRoute,
+ } as any)
+const AuthenticatedStoreIdSettingsApiKeysRoute =
+ AuthenticatedStoreIdSettingsApiKeysRouteImport.update({
+ id: '/api-keys',
+ path: '/api-keys',
+ getParentRoute: () => AuthenticatedStoreIdSettingsRoute,
+ } as any)
const AuthenticatedStoreIdProductsProductIdRoute =
AuthenticatedStoreIdProductsProductIdRouteImport.update({
id: '/products/$productId',
@@ -101,15 +136,20 @@ export interface FileRoutesByFullPath {
'/': typeof AuthenticatedIndexRoute
'/login': typeof LoginRoute
'/$storeId': typeof AuthenticatedStoreIdRouteWithChildren
+ '/$storeId/settings': typeof AuthenticatedStoreIdSettingsRouteWithChildren
'/$storeId/': typeof AuthenticatedStoreIdIndexRoute
'/$storeId/customers/$customerId': typeof AuthenticatedStoreIdCustomersCustomerIdRoute
'/$storeId/orders/$orderId': typeof AuthenticatedStoreIdOrdersOrderIdRoute
'/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
+ '/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
+ '/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
'/$storeId/customers/': typeof AuthenticatedStoreIdCustomersIndexRoute
'/$storeId/orders/': typeof AuthenticatedStoreIdOrdersIndexRoute
'/$storeId/products/': typeof AuthenticatedStoreIdProductsIndexRoute
+ '/$storeId/settings/': typeof AuthenticatedStoreIdSettingsIndexRoute
}
export interface FileRoutesByTo {
'/login': typeof LoginRoute
@@ -120,9 +160,13 @@ export interface FileRoutesByTo {
'/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
+ '/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
+ '/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
'/$storeId/customers': typeof AuthenticatedStoreIdCustomersIndexRoute
'/$storeId/orders': typeof AuthenticatedStoreIdOrdersIndexRoute
'/$storeId/products': typeof AuthenticatedStoreIdProductsIndexRoute
+ '/$storeId/settings': typeof AuthenticatedStoreIdSettingsIndexRoute
}
export interface FileRoutesById {
__root__: typeof rootRouteImport
@@ -130,15 +174,20 @@ export interface FileRoutesById {
'/login': typeof LoginRoute
'/_authenticated/$storeId': typeof AuthenticatedStoreIdRouteWithChildren
'/_authenticated/': typeof AuthenticatedIndexRoute
+ '/_authenticated/$storeId/settings': typeof AuthenticatedStoreIdSettingsRouteWithChildren
'/_authenticated/$storeId/': typeof AuthenticatedStoreIdIndexRoute
'/_authenticated/$storeId/customers/$customerId': typeof AuthenticatedStoreIdCustomersCustomerIdRoute
'/_authenticated/$storeId/orders/$orderId': typeof AuthenticatedStoreIdOrdersOrderIdRoute
'/_authenticated/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/_authenticated/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/_authenticated/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/_authenticated/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
+ '/_authenticated/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
+ '/_authenticated/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
'/_authenticated/$storeId/customers/': typeof AuthenticatedStoreIdCustomersIndexRoute
'/_authenticated/$storeId/orders/': typeof AuthenticatedStoreIdOrdersIndexRoute
'/_authenticated/$storeId/products/': typeof AuthenticatedStoreIdProductsIndexRoute
+ '/_authenticated/$storeId/settings/': typeof AuthenticatedStoreIdSettingsIndexRoute
}
export interface FileRouteTypes {
fileRoutesByFullPath: FileRoutesByFullPath
@@ -146,15 +195,20 @@ export interface FileRouteTypes {
| '/'
| '/login'
| '/$storeId'
+ | '/$storeId/settings'
| '/$storeId/'
| '/$storeId/customers/$customerId'
| '/$storeId/orders/$orderId'
| '/$storeId/orders/drafts'
| '/$storeId/orders/new'
| '/$storeId/products/$productId'
+ | '/$storeId/settings/api-keys'
+ | '/$storeId/settings/staff'
+ | '/$storeId/settings/store'
| '/$storeId/customers/'
| '/$storeId/orders/'
| '/$storeId/products/'
+ | '/$storeId/settings/'
fileRoutesByTo: FileRoutesByTo
to:
| '/login'
@@ -165,24 +219,33 @@ export interface FileRouteTypes {
| '/$storeId/orders/drafts'
| '/$storeId/orders/new'
| '/$storeId/products/$productId'
+ | '/$storeId/settings/api-keys'
+ | '/$storeId/settings/staff'
+ | '/$storeId/settings/store'
| '/$storeId/customers'
| '/$storeId/orders'
| '/$storeId/products'
+ | '/$storeId/settings'
id:
| '__root__'
| '/_authenticated'
| '/login'
| '/_authenticated/$storeId'
| '/_authenticated/'
+ | '/_authenticated/$storeId/settings'
| '/_authenticated/$storeId/'
| '/_authenticated/$storeId/customers/$customerId'
| '/_authenticated/$storeId/orders/$orderId'
| '/_authenticated/$storeId/orders/drafts'
| '/_authenticated/$storeId/orders/new'
| '/_authenticated/$storeId/products/$productId'
+ | '/_authenticated/$storeId/settings/api-keys'
+ | '/_authenticated/$storeId/settings/staff'
+ | '/_authenticated/$storeId/settings/store'
| '/_authenticated/$storeId/customers/'
| '/_authenticated/$storeId/orders/'
| '/_authenticated/$storeId/products/'
+ | '/_authenticated/$storeId/settings/'
fileRoutesById: FileRoutesById
}
export interface RootRouteChildren {
@@ -227,6 +290,20 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof AuthenticatedStoreIdIndexRouteImport
parentRoute: typeof AuthenticatedStoreIdRoute
}
+ '/_authenticated/$storeId/settings': {
+ id: '/_authenticated/$storeId/settings'
+ path: '/settings'
+ fullPath: '/$storeId/settings'
+ preLoaderRoute: typeof AuthenticatedStoreIdSettingsRouteImport
+ parentRoute: typeof AuthenticatedStoreIdRoute
+ }
+ '/_authenticated/$storeId/settings/': {
+ id: '/_authenticated/$storeId/settings/'
+ path: '/'
+ fullPath: '/$storeId/settings/'
+ preLoaderRoute: typeof AuthenticatedStoreIdSettingsIndexRouteImport
+ parentRoute: typeof AuthenticatedStoreIdSettingsRoute
+ }
'/_authenticated/$storeId/products/': {
id: '/_authenticated/$storeId/products/'
path: '/products'
@@ -248,6 +325,27 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof AuthenticatedStoreIdCustomersIndexRouteImport
parentRoute: typeof AuthenticatedStoreIdRoute
}
+ '/_authenticated/$storeId/settings/store': {
+ id: '/_authenticated/$storeId/settings/store'
+ path: '/store'
+ fullPath: '/$storeId/settings/store'
+ preLoaderRoute: typeof AuthenticatedStoreIdSettingsStoreRouteImport
+ parentRoute: typeof AuthenticatedStoreIdSettingsRoute
+ }
+ '/_authenticated/$storeId/settings/staff': {
+ id: '/_authenticated/$storeId/settings/staff'
+ path: '/staff'
+ fullPath: '/$storeId/settings/staff'
+ preLoaderRoute: typeof AuthenticatedStoreIdSettingsStaffRouteImport
+ parentRoute: typeof AuthenticatedStoreIdSettingsRoute
+ }
+ '/_authenticated/$storeId/settings/api-keys': {
+ id: '/_authenticated/$storeId/settings/api-keys'
+ path: '/api-keys'
+ fullPath: '/$storeId/settings/api-keys'
+ preLoaderRoute: typeof AuthenticatedStoreIdSettingsApiKeysRouteImport
+ parentRoute: typeof AuthenticatedStoreIdSettingsRoute
+ }
'/_authenticated/$storeId/products/$productId': {
id: '/_authenticated/$storeId/products/$productId'
path: '/products/$productId'
@@ -286,7 +384,32 @@ declare module '@tanstack/react-router' {
}
}
+interface AuthenticatedStoreIdSettingsRouteChildren {
+ AuthenticatedStoreIdSettingsApiKeysRoute: typeof AuthenticatedStoreIdSettingsApiKeysRoute
+ AuthenticatedStoreIdSettingsStaffRoute: typeof AuthenticatedStoreIdSettingsStaffRoute
+ AuthenticatedStoreIdSettingsStoreRoute: typeof AuthenticatedStoreIdSettingsStoreRoute
+ AuthenticatedStoreIdSettingsIndexRoute: typeof AuthenticatedStoreIdSettingsIndexRoute
+}
+
+const AuthenticatedStoreIdSettingsRouteChildren: AuthenticatedStoreIdSettingsRouteChildren =
+ {
+ AuthenticatedStoreIdSettingsApiKeysRoute:
+ AuthenticatedStoreIdSettingsApiKeysRoute,
+ AuthenticatedStoreIdSettingsStaffRoute:
+ AuthenticatedStoreIdSettingsStaffRoute,
+ AuthenticatedStoreIdSettingsStoreRoute:
+ AuthenticatedStoreIdSettingsStoreRoute,
+ AuthenticatedStoreIdSettingsIndexRoute:
+ AuthenticatedStoreIdSettingsIndexRoute,
+ }
+
+const AuthenticatedStoreIdSettingsRouteWithChildren =
+ AuthenticatedStoreIdSettingsRoute._addFileChildren(
+ AuthenticatedStoreIdSettingsRouteChildren,
+ )
+
interface AuthenticatedStoreIdRouteChildren {
+ AuthenticatedStoreIdSettingsRoute: typeof AuthenticatedStoreIdSettingsRouteWithChildren
AuthenticatedStoreIdIndexRoute: typeof AuthenticatedStoreIdIndexRoute
AuthenticatedStoreIdCustomersCustomerIdRoute: typeof AuthenticatedStoreIdCustomersCustomerIdRoute
AuthenticatedStoreIdOrdersOrderIdRoute: typeof AuthenticatedStoreIdOrdersOrderIdRoute
@@ -299,6 +422,8 @@ interface AuthenticatedStoreIdRouteChildren {
}
const AuthenticatedStoreIdRouteChildren: AuthenticatedStoreIdRouteChildren = {
+ AuthenticatedStoreIdSettingsRoute:
+ AuthenticatedStoreIdSettingsRouteWithChildren,
AuthenticatedStoreIdIndexRoute: AuthenticatedStoreIdIndexRoute,
AuthenticatedStoreIdCustomersCustomerIdRoute:
AuthenticatedStoreIdCustomersCustomerIdRoute,
diff --git a/packages/admin/src/routes/_authenticated/$storeId.tsx b/packages/admin/src/routes/_authenticated/$storeId.tsx
index 3215ca73ea..1faf6e5a97 100644
--- a/packages/admin/src/routes/_authenticated/$storeId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId.tsx
@@ -1,8 +1,9 @@
-import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { createFileRoute, Outlet, useRouterState } from '@tanstack/react-router'
import { useEffect } from 'react'
import { adminClient } from '@/client'
import { AppSidebar } from '@/components/spree/app-sidebar'
import { CommandPalette } from '@/components/spree/command-palette/command-palette'
+import { SettingsSidebar } from '@/components/spree/settings-sidebar'
import { TopBar } from '@/components/spree/top-bar'
import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar'
import { CommandPaletteProvider } from '@/hooks/use-command-palette'
@@ -14,6 +15,8 @@ export const Route = createFileRoute('/_authenticated/$storeId')({
function StoreLayout() {
const { storeId } = Route.useParams()
+ const pathname = useRouterState({ select: (s) => s.location.pathname })
+ const inSettings = pathname.startsWith(`/${storeId}/settings`)
useEffect(() => {
adminClient.setStore(storeId)
@@ -24,10 +27,20 @@ function StoreLayout() {
<CommandPaletteProvider>
<SidebarProvider>
<AppSidebar />
- <SidebarInset>
- <TopBar />
- <div className="container mx-auto flex flex-1 flex-col gap-4 p-4">
- <Outlet />
+ {/* `flex-row` so the secondary sidebar can sit flush against the
+ primary and span full height. The TopBar moves into the content
+ column so the secondary sidebar can extend above it. */}
+ <SidebarInset className="flex-row">
+ <SettingsSidebar open={inSettings} />
+ <div className="flex min-w-0 flex-1 flex-col">
+ <TopBar />
+ {inSettings ? (
+ <Outlet />
+ ) : (
+ <div className="container mx-auto flex flex-1 flex-col gap-4 p-4 lg:p-6">
+ <Outlet />
+ </div>
+ )}
</div>
</SidebarInset>
</SidebarProvider>
diff --git a/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
index e45377ad45..29b16252e4 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -15,21 +15,20 @@ type Product = Omit<BaseProduct, 'default_variant' | 'variants'> & {
import { zodResolver } from '@hookform/resolvers/zod'
import { createFileRoute, useRouter } from '@tanstack/react-router'
-import { ImagePlusIcon, Loader2Icon, SaveIcon, XIcon } from 'lucide-react'
+import { ImagePlusIcon, Loader2Icon, XIcon } from 'lucide-react'
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { Controller, type UseFormReturn, useForm } from 'react-hook-form'
import { toast } from 'sonner'
import { adminClient } from '@/client'
import { useConfirm } from '@/components/spree/confirm-dialog'
import { CustomFieldsCard } from '@/components/spree/custom-fields/custom-fields-card'
+import { FormActions, useFormSubmitShortcut } from '@/components/spree/form-actions'
import { MetadataCard } from '@/components/spree/metadata/metadata-card'
import { PageHeader } from '@/components/spree/page-header'
import { ResourceLayout } from '@/components/spree/resource-layout'
import { ErrorState } from '@/components/spree/route-error-boundary'
-import { StickyFormFooter } from '@/components/spree/sticky-form-footer'
import { TagCombobox } from '@/components/spree/tag-combobox'
import { StatusBadge } from '@/components/ui/badge'
-import { Button } from '@/components/ui/button'
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
import {
Combobox,
@@ -172,6 +171,8 @@ function ProductForm({ product }: { product: Product }) {
}
}
+ useFormSubmitShortcut(form, onSubmit)
+
const handleDelete = async () => {
const confirmed = await confirm({
message: 'Are you sure you want to delete this product?',
@@ -192,17 +193,6 @@ function ProductForm({ product }: { product: Product }) {
}
}
- const saveButton = (
- <Button type="submit" size="sm" disabled={updateProduct.isPending || !form.formState.isDirty}>
- {updateProduct.isPending ? (
- <Loader2Icon className="size-4 animate-spin" />
- ) : (
- <SaveIcon className="size-4" />
- )}
- Save
- </Button>
- )
-
return (
<form onSubmit={form.handleSubmit(onSubmit)}>
<ResourceLayout
@@ -211,7 +201,7 @@ function ProductForm({ product }: { product: Product }) {
title={product.name}
backTo="products"
badges={<StatusBadge status={product.status} />}
- actions={saveButton}
+ actions={<FormActions form={form} saveLabel="Save product" />}
resource={{ id: product.id }}
onDelete={handleDelete}
deleteLabel="Delete product"
@@ -247,7 +237,6 @@ function ProductForm({ product }: { product: Product }) {
</>
}
/>
- <StickyFormFooter form={form} saveLabel="Save product" />
</form>
)
}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings.tsx
new file mode 100644
index 0000000000..5b8bb1690b
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings.tsx
@@ -0,0 +1,18 @@
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings')({
+ component: SettingsLayout,
+})
+
+/**
+ * Settings content padding. The secondary sidebar lives one level up, in
+ * `_authenticated/$storeId.tsx`, so it can extend full-height beside the
+ * TopBar. This layout owns only the right-side content padding.
+ */
+function SettingsLayout() {
+ return (
+ <div className="container mx-auto flex flex-1 flex-col gap-4 p-4 lg:p-6">
+ <Outlet />
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx
new file mode 100644
index 0000000000..40b430b1aa
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx
@@ -0,0 +1,38 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { ConstructionIcon } from 'lucide-react'
+import { EmptyState } from '@/components/spree/empty-state'
+import { PageHeader } from '@/components/spree/page-header'
+import { Card, CardContent } from '@/components/ui/card'
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings/api-keys')({
+ component: ApiKeysSettingsPage,
+})
+
+// TODO: replace placeholder once the Admin API exposes CRUD for `Spree::ApiKey`
+// - controller: spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
+// (model exists, with KEY_TYPES, SCOPES, revoke!, plaintext_token surfacing)
+// - serializer: needs to be built. Mind: never serialize `token`/`token_digest`;
+// only the `token_prefix` (12 chars) for display. `plaintext_token` is one-shot
+// in the create response.
+// - sdk methods: client.apiKeys.{list,get,create,revoke}
+// - UX: scope picker on create (multiselect against ApiKey::SCOPES); show
+// plaintext token exactly once with a "copy and store securely" warning.
+function ApiKeysSettingsPage() {
+ return (
+ <div className="flex flex-col gap-6">
+ <PageHeader
+ title="API keys"
+ subtitle="Publishable and secret keys for the Storefront and Admin APIs."
+ />
+ <Card>
+ <CardContent className="p-0">
+ <EmptyState
+ icon={<ConstructionIcon />}
+ title="API key management is coming soon"
+ description="Storefront and Admin keys are managed in the legacy Rails admin while the Admin API endpoints are being finalized."
+ />
+ </CardContent>
+ </Card>
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/index.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/index.tsx
new file mode 100644
index 0000000000..c28f019d29
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/index.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings/')({
+ beforeLoad: ({ params }) => {
+ throw redirect({
+ to: '/$storeId/settings/store',
+ params: { storeId: params.storeId },
+ replace: true,
+ })
+ },
+})
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx
new file mode 100644
index 0000000000..42c33c3167
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx
@@ -0,0 +1,34 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { ConstructionIcon } from 'lucide-react'
+import { EmptyState } from '@/components/spree/empty-state'
+import { PageHeader } from '@/components/spree/page-header'
+import { Card, CardContent } from '@/components/ui/card'
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings/staff')({
+ component: StaffSettingsPage,
+})
+
+// TODO: replace placeholder once the Admin API exposes CRUD for `Spree.admin_user_class`
+// - controller: spree/api/app/controllers/spree/api/v3/admin/admin_users_controller.rb
+// - serializer already exists at spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb
+// - sdk methods: client.adminUsers.{list,get,create,update,delete}
+// - role assignment via Spree::RoleUser (scoped to current_store as resource)
+function StaffSettingsPage() {
+ return (
+ <div className="flex flex-col gap-6">
+ <PageHeader
+ title="Staff"
+ subtitle="Invite teammates and manage their access to this store."
+ />
+ <Card>
+ <CardContent className="p-0">
+ <EmptyState
+ icon={<ConstructionIcon />}
+ title="Staff management is coming soon"
+ description="The Admin API endpoints for inviting and managing staff are next on the roadmap. In the meantime, manage staff via the legacy Rails admin."
+ />
+ </CardContent>
+ </Card>
+ </div>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/store.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/store.tsx
new file mode 100644
index 0000000000..5a54087e9d
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/store.tsx
@@ -0,0 +1,278 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { Store } from '@spree/admin-sdk'
+import { createFileRoute } from '@tanstack/react-router'
+import { useEffect } from 'react'
+import { Controller, useForm } from 'react-hook-form'
+import { toast } from 'sonner'
+import { FormActions, useFormSubmitShortcut } from '@/components/spree/form-actions'
+import { PageHeader } from '@/components/spree/page-header'
+import { ResourceLayout } from '@/components/spree/resource-layout'
+import { ErrorState } from '@/components/spree/route-error-boundary'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Field, FieldGroup, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@/components/ui/select'
+import { Skeleton } from '@/components/ui/skeleton'
+import { useStoreSettings, useUpdateStoreSettings } from '@/hooks/use-store-settings'
+import {
+ ADMIN_LOCALE_OPTIONS,
+ type StoreSettingsFormValues,
+ storeSettingsFormSchema,
+ UNIT_SYSTEM_OPTIONS,
+ WEIGHT_UNIT_OPTIONS,
+} from '@/schemas/store'
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings/store')({
+ component: StoreSettingsPage,
+})
+
+const TIMEZONES: string[] = (() => {
+ try {
+ return Intl.supportedValuesOf('timeZone')
+ } catch {
+ // Fallback for older browsers — a small representative set.
+ return [
+ 'UTC',
+ 'America/New_York',
+ 'America/Chicago',
+ 'America/Denver',
+ 'America/Los_Angeles',
+ 'Europe/London',
+ 'Europe/Paris',
+ 'Europe/Berlin',
+ 'Asia/Tokyo',
+ 'Australia/Sydney',
+ ]
+ }
+})()
+
+function storeToFormValues(store: Store): StoreSettingsFormValues {
+ return {
+ name: store.name,
+ preferred_admin_locale: store.preferred_admin_locale ?? '',
+ preferred_timezone: store.preferred_timezone,
+ preferred_unit_system: (store.preferred_unit_system as 'metric' | 'imperial') ?? 'metric',
+ preferred_weight_unit: store.preferred_weight_unit,
+ }
+}
+
+function StoreSettingsPage() {
+ const { data: store, isLoading, error, refetch } = useStoreSettings()
+
+ if (isLoading || !store) {
+ return (
+ <div className="flex flex-col gap-6">
+ <Skeleton className="h-8 w-48" />
+ <Skeleton className="h-64 w-full" />
+ <Skeleton className="h-64 w-full" />
+ </div>
+ )
+ }
+
+ if (error) {
+ return (
+ <ErrorState
+ title="Failed to load store settings"
+ description={error instanceof Error ? error.message : undefined}
+ onRetry={() => refetch()}
+ />
+ )
+ }
+
+ // Mounted only once `store` is loaded so `useForm` initializes with concrete
+ // defaults — never `undefined`. Keeps the underlying Selects controlled from
+ // the first render.
+ return <StoreSettingsForm store={store} />
+}
+
+function StoreSettingsForm({ store }: { store: Store }) {
+ const updateMutation = useUpdateStoreSettings()
+
+ const form = useForm<StoreSettingsFormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(storeSettingsFormSchema) as any,
+ defaultValues: storeToFormValues(store),
+ })
+
+ // When unit_system flips, reset weight_unit to the first valid option for
+ // that system so the form never holds an inconsistent pair.
+ const unitSystem = form.watch('preferred_unit_system')
+ useEffect(() => {
+ const validUnits = WEIGHT_UNIT_OPTIONS[unitSystem]?.map((u) => u.value) ?? []
+ const current = form.getValues('preferred_weight_unit')
+ if (current && !validUnits.includes(current)) {
+ form.setValue('preferred_weight_unit', validUnits[0] ?? '', { shouldDirty: true })
+ }
+ }, [unitSystem, form])
+
+ const onSubmit = async (values: StoreSettingsFormValues) => {
+ try {
+ await updateMutation.mutateAsync({
+ name: values.name,
+ preferred_admin_locale: values.preferred_admin_locale || undefined,
+ preferred_timezone: values.preferred_timezone,
+ preferred_unit_system: values.preferred_unit_system,
+ preferred_weight_unit: values.preferred_weight_unit,
+ })
+ toast.success('Store settings updated')
+ form.reset(values)
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to update store settings')
+ }
+ }
+
+ useFormSubmitShortcut(form, onSubmit)
+
+ return (
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <ResourceLayout
+ header={
+ <PageHeader
+ title="Store settings"
+ subtitle="General configuration for this store."
+ actions={<FormActions form={form} />}
+ />
+ }
+ main={
+ <>
+ <Card>
+ <CardHeader>
+ <CardTitle>General</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <FieldGroup>
+ <Field>
+ <FieldLabel htmlFor="name">Store name</FieldLabel>
+ <Input
+ id="name"
+ {...form.register('name')}
+ aria-invalid={!!form.formState.errors.name}
+ />
+ {form.formState.errors.name && (
+ <p className="text-sm text-destructive">
+ {form.formState.errors.name.message}
+ </p>
+ )}
+ </Field>
+ </FieldGroup>
+ </CardContent>
+ </Card>
+
+ <Card>
+ <CardHeader>
+ <CardTitle>Standards and formats</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <FieldGroup>
+ <Field>
+ <FieldLabel htmlFor="preferred_admin_locale">Admin language</FieldLabel>
+ <Controller
+ name="preferred_admin_locale"
+ control={form.control}
+ render={({ field }) => (
+ <Select
+ value={field.value ?? ''}
+ onValueChange={(v) => field.onChange(v || null)}
+ >
+ <SelectTrigger id="preferred_admin_locale">
+ <SelectValue placeholder="Use the default language" />
+ </SelectTrigger>
+ <SelectContent>
+ {ADMIN_LOCALE_OPTIONS.map((opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="preferred_timezone">Timezone</FieldLabel>
+ <Controller
+ name="preferred_timezone"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="preferred_timezone">
+ <SelectValue placeholder="Select a timezone" />
+ </SelectTrigger>
+ <SelectContent className="max-h-80">
+ {TIMEZONES.map((tz) => (
+ <SelectItem key={tz} value={tz}>
+ {tz}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ {form.formState.errors.preferred_timezone && (
+ <p className="text-sm text-destructive">
+ {form.formState.errors.preferred_timezone.message}
+ </p>
+ )}
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="preferred_unit_system">Unit system</FieldLabel>
+ <Controller
+ name="preferred_unit_system"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="preferred_unit_system">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {UNIT_SYSTEM_OPTIONS.map((opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="preferred_weight_unit">Weight unit</FieldLabel>
+ <Controller
+ name="preferred_weight_unit"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="preferred_weight_unit">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {(WEIGHT_UNIT_OPTIONS[unitSystem] ?? WEIGHT_UNIT_OPTIONS.metric).map(
+ (opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ),
+ )}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+ </FieldGroup>
+ </CardContent>
+ </Card>
+ </>
+ }
+ />
+ </form>
+ )
+}
diff --git a/packages/admin/src/schemas/store.ts b/packages/admin/src/schemas/store.ts
new file mode 100644
index 0000000000..db57fb2a39
--- /dev/null
+++ b/packages/admin/src/schemas/store.ts
@@ -0,0 +1,43 @@
+import { z } from 'zod/v4'
+
+export const storeSettingsFormSchema = z.object({
+ name: z.string().min(1, 'Name is required'),
+ preferred_admin_locale: z.string().nullable().optional(),
+ preferred_timezone: z.string().min(1, 'Timezone is required'),
+ preferred_unit_system: z.enum(['metric', 'imperial']),
+ preferred_weight_unit: z.string().min(1, 'Weight unit is required'),
+})
+
+export type StoreSettingsFormValues = z.infer<typeof storeSettingsFormSchema>
+
+export const ADMIN_LOCALE_OPTIONS: Array<{ value: string; label: string }> = [
+ { value: 'en', label: 'English' },
+ { value: 'fr', label: 'Français' },
+ { value: 'de', label: 'Deutsch' },
+ { value: 'es', label: 'Español' },
+ { value: 'it', label: 'Italiano' },
+ { value: 'pt-BR', label: 'Português (Brasil)' },
+ { value: 'pl', label: 'Polski' },
+ { value: 'nl', label: 'Nederlands' },
+ { value: 'ja', label: '日本語' },
+ { value: 'zh-CN', label: '中文 (简体)' },
+]
+
+export const UNIT_SYSTEM_OPTIONS: Array<{ value: 'metric' | 'imperial'; label: string }> = [
+ { value: 'metric', label: 'Metric' },
+ { value: 'imperial', label: 'Imperial' },
+]
+
+export const WEIGHT_UNIT_OPTIONS: Record<
+ 'metric' | 'imperial',
+ Array<{ value: string; label: string }>
+> = {
+ metric: [
+ { value: 'kg', label: 'Kilogram (kg)' },
+ { value: 'g', label: 'Gram (g)' },
+ ],
+ imperial: [
+ { value: 'lb', label: 'Pound (lb)' },
+ { value: 'oz', label: 'Ounce (oz)' },
+ ],
+}
diff --git a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
index f801eb314f..495ab82bc9 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
@@ -34,17 +34,11 @@ module Spree
def permitted_params
params.permit(
- :name, :url, :seo_title, :code, :meta_keywords, :meta_description,
- :default_currency, :default_country_iso, :default_locale,
- :mail_from_address, :customer_support_email,
- :description, :address, :contact_phone,
- :supported_locales, :supported_currencies,
- :new_order_notifications_email,
- :preferred_admin_locale, :preferred_timezone,
- :preferred_weight_unit, :preferred_unit_system,
- :preferred_digital_asset_authorized_clicks, :preferred_digital_asset_authorized_days,
- :preferred_limit_digital_download_count, :preferred_limit_digital_download_days,
- :preferred_digital_asset_link_expire_time
+ :name,
+ :preferred_admin_locale,
+ :preferred_timezone,
+ :preferred_weight_unit,
+ :preferred_unit_system
)
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
index 03ee1a6036..41be6a5452 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
@@ -3,54 +3,37 @@ module Spree
module V3
module Admin
class StoreSerializer < V3::BaseSerializer
- typelize name: :string, url: :string, code: :string,
+ typelize name: :string, url: :string,
default_currency: :string, default_locale: :string,
supported_currencies: [:string, multi: true],
supported_locales: [:string, multi: true],
- mail_from_address: :string,
- customer_support_email: [:string, nullable: true],
- new_order_notifications_email: [:string, nullable: true],
- description: [:string, nullable: true],
- address: [:string, nullable: true],
- contact_phone: [:string, nullable: true],
- seo_title: [:string, nullable: true],
- meta_keywords: [:string, nullable: true],
- meta_description: [:string, nullable: true],
- default: :boolean,
logo_url: [:string, nullable: true],
- mailer_logo_url: [:string, nullable: true],
+ preferred_admin_locale: [:string, nullable: true],
+ preferred_timezone: :string,
+ preferred_weight_unit: :string,
+ preferred_unit_system: :string,
metadata: 'Record<string, unknown>'
- attributes :metadata, :id, :name, :url, :code,
- :mail_from_address, :customer_support_email,
- :new_order_notifications_email,
- :description, :address, :contact_phone,
- :seo_title, :meta_keywords, :meta_description,
- :default,
+ attributes :metadata,
+ :name,
+ :default_currency,
+ :default_locale,
+ :preferred_admin_locale,
+ :preferred_timezone,
+ :preferred_weight_unit,
+ :preferred_unit_system,
created_at: :iso8601, updated_at: :iso8601
- attribute :default_currency do |store|
- store.default_market&.currency
- end
-
- attribute :default_locale do |store|
- store.default_market&.default_locale
- end
+ attribute :url, &:storefront_url
attribute :supported_currencies do |store|
store.supported_currencies_list.map(&:iso_code)
end
- attribute :supported_locales do |store|
- store.supported_locales_list
- end
+ attribute :supported_locales, &:supported_locales_list
attribute :logo_url do |store|
- store.logo.attached? ? Rails.application.routes.url_helpers.url_for(store.logo) : nil
- end
-
- attribute :mailer_logo_url do |store|
- store.mailer_logo.attached? ? Rails.application.routes.url_helpers.url_for(store.mailer_logo) : nil
+ image_url_for(store.logo)
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
new file mode 100644
index 0000000000..1f94cdfd05
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
@@ -0,0 +1,123 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::StoreController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ # `@default_store` is a shared in-memory object across the suite; reload it
+ # so each example starts from the persisted state and isn't tripped up by
+ # AR change tracking from earlier rolled-back updates.
+ before { store.reload }
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #show' do
+ subject { get :show, as: :json }
+
+ it 'returns ok' do
+ subject
+ expect(response).to have_http_status(:ok)
+ end
+
+ it 'serializes the prefixed id, not the raw integer DB id' do
+ # Regression: a previous version of the serializer listed `:id` in
+ # `attributes`, which overrode `BaseSerializer#id` and exposed the
+ # raw integer primary key.
+ subject
+ expect(json_response['id']).to eq(store.prefixed_id)
+ expect(json_response['id']).to start_with('store_')
+ expect(json_response['id']).not_to eq(store.id)
+ expect(json_response['id']).not_to eq(store.id.to_s)
+ end
+
+ it 'returns the store name' do
+ subject
+ expect(json_response['name']).to eq(store.name)
+ end
+
+ context 'when the store has no allowed origins' do
+ it 'serializes url from storefront_url (falling back to formatted_url)' do
+ # Regression: the previous serializer exposed the raw `url` column,
+ # not the customer-facing storefront URL.
+ subject
+ expect(json_response['url']).to eq(store.storefront_url)
+ expect(json_response['url']).to eq(store.formatted_url)
+ end
+ end
+
+ context 'when the store has an allowed origin' do
+ before do
+ store.allowed_origins.create!(origin: 'https://shop.example.com')
+ end
+
+ it 'serializes url from the first allowed origin' do
+ subject
+ expect(json_response['url']).to eq('https://shop.example.com')
+ end
+ end
+
+ it 'includes computed default_currency, default_locale and supported lists' do
+ subject
+ expect(json_response).to include(
+ 'default_currency' => store.default_currency,
+ 'default_locale' => store.default_locale
+ )
+ expect(json_response['supported_currencies']).to be_an(Array)
+ expect(json_response['supported_locales']).to be_an(Array)
+ end
+
+ context 'without authentication' do
+ let(:headers) { {} }
+
+ it 'returns unauthorized' do
+ subject
+ expect(response).to have_http_status(:unauthorized)
+ end
+ end
+ end
+
+ describe 'PATCH #update' do
+ subject { patch :update, params: params, as: :json }
+
+ context 'with valid params' do
+ let(:params) { { name: 'Renamed Store' } }
+
+ it 'updates the store and returns ok' do
+ subject
+ expect(response).to have_http_status(:ok)
+ expect(store.reload.name).to eq('Renamed Store')
+ end
+
+ it 'returns the prefixed id in the response (not the raw DB id)' do
+ subject
+ expect(json_response['id']).to eq(store.prefixed_id)
+ expect(json_response['id']).to start_with('store_')
+ end
+
+ it 'returns the storefront_url in the url field' do
+ subject
+ expect(json_response['url']).to eq(store.reload.storefront_url)
+ end
+ end
+
+ context 'with invalid params' do
+ let(:params) { { name: '' } }
+
+ it 'returns a validation error' do
+ subject
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['code']).to eq('validation_error')
+ end
+ end
+
+ context 'without authentication' do
+ let(:headers) { {} }
+ let(:params) { { name: 'Renamed Store' } }
+
+ it 'returns unauthorized' do
+ subject
+ expect(response).to have_http_status(:unauthorized)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb
index e6b3be0d57..069352f78c 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb
@@ -13,7 +13,7 @@ RSpec.describe 'Admin Me API', type: :request, swagger_doc: 'api-reference/admin
description 'Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.'
admin_sdk_example <<~JS
- const me = await client.me.show()
+ const me = await client.me.get()
if (me.permissions.some((r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'))) {
// show "Create product" button
}
diff --git a/spree/api/spec/integration/spree/api/v3/admin/store_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/store_spec.rb
new file mode 100644
index 0000000000..86ffbc7642
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/store_spec.rb
@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Store API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ let(:store) { @default_store }
+ let!(:market) { create(:market, store: store) }
+
+ # Reload to drop any in-memory mutations left over from earlier rolled-back
+ # examples (the shared `@default_store` AR instance survives the suite).
+ before { store.reload }
+
+ path '/api/v3/admin/store' do
+ get 'Get the current store' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const store = await client.store.get()
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+
+ response '200', 'current store' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema '$ref' => '#/components/schemas/Store'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(store.prefixed_id)
+ expect(data['id']).to start_with('store_')
+ expect(data['name']).to eq(store.name)
+ expect(data['url']).to eq(store.storefront_url)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update the current store' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates the current store configuration.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const store = await client.store.update({
+ name: 'My Store'
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string, example: 'My Store' },
+ preferred_admin_locale: { type: :string, example: 'en' },
+ preferred_timezone: { type: :string, example: 'UTC' },
+ preferred_weight_unit: { type: :string, example: 'kg' },
+ preferred_unit_system: { type: :string, example: 'metric' }
+ }
+ }
+
+ response '200', 'store updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { name: 'Renamed Store' } }
+
+ schema '$ref' => '#/components/schemas/Store'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Renamed Store')
+ expect(data['id']).to eq(store.prefixed_id)
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { name: '' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end