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 Stock Locations Admin API (#14002)

Damian Legawiecc3ebdf1e0f64
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 1a9ead526f..416115064a 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -82,11 +82,11 @@ paths:
example:
data:
- id: admin_UkLWZg9DAJ
- first_name: Charmaine
- last_name: Rosenbaum
- created_at: '2026-05-07T13:39:14.442Z'
- updated_at: '2026-05-07T13:39:14.442Z'
+ first_name: Kris
+ last_name: Jenkins
+ created_at: '2026-05-08T17:04:49.733Z'
+ updated_at: '2026-05-08T17:04:49.733Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -144,11 +144,11 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
- first_name: Twanna
- last_name: Bruen
- created_at: '2026-05-07T13:39:14.784Z'
- updated_at: '2026-05-07T13:39:14.784Z'
+ first_name: Laveta
+ last_name: Hermiston
+ created_at: '2026-05-08T17:04:50.086Z'
+ updated_at: '2026-05-08T17:04:50.086Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -201,11 +201,11 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
first_name: Renamed
- last_name: Legros
- created_at: '2026-05-07T13:39:15.114Z'
- updated_at: '2026-05-07T13:39:15.136Z'
+ last_name: Rowe
+ created_at: '2026-05-08T17:04:50.402Z'
+ updated_at: '2026-05-08T17:04:50.422Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -314,32 +314,32 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-05-07T13:39:15.437Z'
- updated_at: '2026-05-07T13:39:15.437Z'
+ created_at: '2026-05-08T17:04:50.716Z'
+ updated_at: '2026-05-08T17:04:50.716Z'
revoked_at:
last_used_at:
- plaintext_token: pk_V52ATyQ8rdp7T8Wx68nb9CcV
+ plaintext_token: pk_uLmLYrMQKp1oCuQ5nzxQSRKc
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_uiwy9MQ3e
+ token_prefix: sk_RXnTPSiED
scopes:
- write_all
- created_at: '2026-05-07T13:39:15.438Z'
- updated_at: '2026-05-07T13:39:15.438Z'
+ created_at: '2026-05-08T17:04:50.717Z'
+ updated_at: '2026-05-08T17:04:50.717Z'
revoked_at:
last_used_at:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: reprehenderit
+ name: perferendis
key_type: secret
- token_prefix: sk_7jzuAdSda
+ token_prefix: sk_1tx3PgUhr
scopes:
- write_all
- created_at: '2026-05-07T13:39:15.439Z'
- updated_at: '2026-05-07T13:39:15.439Z'
+ created_at: '2026-05-08T17:04:50.717Z'
+ updated_at: '2026-05-08T17:04:50.717Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -402,15 +402,15 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_gwpZWTy3x
+ token_prefix: sk_YoaBkX2P2
scopes:
- read_orders
- created_at: '2026-05-07T13:39:16.006Z'
- updated_at: '2026-05-07T13:39:16.006Z'
+ created_at: '2026-05-08T17:04:51.284Z'
+ updated_at: '2026-05-08T17:04:51.284Z'
revoked_at:
last_used_at:
- plaintext_token: sk_gwpZWTy3xWycvbs6fnBqQrdv
- created_by_email: [email protected]
+ plaintext_token: sk_YoaBkX2P2whE2JJ4QhfDyM4Y
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -496,11 +496,11 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-05-07T13:39:16.311Z'
- updated_at: '2026-05-07T13:39:16.311Z'
+ created_at: '2026-05-08T17:04:51.573Z'
+ updated_at: '2026-05-08T17:04:51.573Z'
revoked_at:
last_used_at:
- plaintext_token: pk_7n8XLJnPRDVctnzavKYtLjSw
+ plaintext_token: pk_Nw6QvFHhu7ouqdxfC75kcmsp
created_by_email:
delete:
summary: Delete an API key
@@ -590,12 +590,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_ixBGz16c7
+ token_prefix: sk_36iKwwRy6
scopes:
- write_all
- created_at: '2026-05-07T13:39:16.918Z'
- updated_at: '2026-05-07T13:39:17.217Z'
- revoked_at: '2026-05-07T13:39:17.215Z'
+ created_at: '2026-05-08T17:04:52.169Z'
+ updated_at: '2026-05-08T17:04:52.467Z'
+ revoked_at: '2026-05-08T17:04:52.465Z'
last_used_at:
plaintext_token:
created_by_email:
@@ -664,8 +664,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-07T13:39:17.236Z'
- updated_at: '2026-05-07T13:39:17.236Z'
+ created_at: '2026-05-08T17:04:52.487Z'
+ updated_at: '2026-05-08T17:04:52.487Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -673,8 +673,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-05-07T13:39:17.239Z'
- updated_at: '2026-05-07T13:39:17.239Z'
+ created_at: '2026-05-08T17:04:52.489Z'
+ updated_at: '2026-05-08T17:04:52.489Z'
meta:
page: 1
limit: 25
@@ -737,8 +737,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-07T13:39:17.864Z'
- updated_at: '2026-05-07T13:39:17.864Z'
+ created_at: '2026-05-08T17:04:53.097Z'
+ updated_at: '2026-05-08T17:04:53.097Z'
requestBody:
content:
application/json:
@@ -821,8 +821,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-07T13:39:17.868Z'
- updated_at: '2026-05-07T13:39:17.868Z'
+ created_at: '2026-05-08T17:04:53.100Z'
+ updated_at: '2026-05-08T17:04:53.100Z'
patch:
summary: Update a custom field definition
tags:
@@ -861,8 +861,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-05-07T13:39:18.160Z'
- updated_at: '2026-05-07T13:39:18.442Z'
+ created_at: '2026-05-08T17:04:53.387Z'
+ updated_at: '2026-05-08T17:04:53.667Z'
requestBody:
content:
application/json:
@@ -984,8 +984,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-07T13:39:19.033Z'
- updated_at: '2026-05-07T13:39:19.033Z'
+ created_at: '2026-05-08T17:04:54.241Z'
+ updated_at: '2026-05-08T17:04:54.241Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -1073,8 +1073,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-05-07T13:39:20.397Z'
- updated_at: '2026-05-07T13:39:20.397Z'
+ created_at: '2026-05-08T17:04:55.603Z'
+ updated_at: '2026-05-08T17:04:55.603Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -1185,8 +1185,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-07T13:39:20.674Z'
- updated_at: '2026-05-07T13:39:21.234Z'
+ created_at: '2026-05-08T17:04:55.874Z'
+ updated_at: '2026-05-08T17:04:56.416Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -1319,8 +1319,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-07T13:39:22.416Z'
- updated_at: '2026-05-07T13:39:22.416Z'
+ created_at: '2026-05-08T17:04:57.546Z'
+ updated_at: '2026-05-08T17:04:57.546Z'
meta:
page: 1
limit: 25
@@ -1407,8 +1407,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-07T13:39:22.972Z'
- updated_at: '2026-05-07T13:39:22.972Z'
+ created_at: '2026-05-08T17:04:58.106Z'
+ updated_at: '2026-05-08T17:04:58.106Z'
delete:
summary: Delete a customer credit card
tags:
@@ -1526,8 +1526,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-07T13:39:24.386Z'
- updated_at: '2026-05-07T13:39:24.386Z'
+ created_at: '2026-05-08T17:04:59.480Z'
+ updated_at: '2026-05-08T17:04:59.480Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
meta:
@@ -1599,8 +1599,8 @@ paths:
display_amount_remaining: "$25.00"
currency: USD
metadata: {}
- created_at: '2026-05-07T13:39:25.562Z'
- updated_at: '2026-05-07T13:39:25.562Z'
+ created_at: '2026-05-08T17:05:00.590Z'
+ updated_at: '2026-05-08T17:05:00.590Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
requestBody:
@@ -1688,8 +1688,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-07T13:39:26.121Z'
- updated_at: '2026-05-07T13:39:26.408Z'
+ created_at: '2026-05-08T17:05:01.128Z'
+ updated_at: '2026-05-08T17:05:01.409Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
requestBody:
@@ -1841,8 +1841,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-07T13:39:27.536Z'
- updated_at: '2026-05-07T13:39:27.536Z'
+ created_at: '2026-05-08T17:05:02.504Z'
+ updated_at: '2026-05-08T17:05:02.504Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1925,8 +1925,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-07T13:39:28.386Z'
- updated_at: '2026-05-07T13:39:28.386Z'
+ created_at: '2026-05-08T17:05:03.352Z'
+ updated_at: '2026-05-08T17:05:03.352Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2042,8 +2042,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-07T13:39:28.665Z'
- updated_at: '2026-05-07T13:39:28.665Z'
+ created_at: '2026-05-08T17:05:03.624Z'
+ updated_at: '2026-05-08T17:05:03.624Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2117,8 +2117,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-07T13:39:29.268Z'
- updated_at: '2026-05-07T13:39:29.638Z'
+ created_at: '2026-05-08T17:05:04.168Z'
+ updated_at: '2026-05-08T17:05:04.447Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2240,11 +2240,11 @@ paths:
example:
data:
- id: exp_UkLWZg9DAJ
- number: EF112212968
+ number: EF959038168
type: Spree::Exports::Products
format: csv
- created_at: '2026-05-07T13:39:30.547Z'
- updated_at: '2026-05-07T13:39:30.547Z'
+ created_at: '2026-05-08T17:05:05.286Z'
+ updated_at: '2026-05-08T17:05:05.286Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -2311,11 +2311,11 @@ paths:
application/json:
example:
id: exp_gbHJdmfrXB
- number: EF083996482
+ number: EF786537545
type: Spree::Exports::Products
format: csv
- created_at: '2026-05-07T13:39:30.906Z'
- updated_at: '2026-05-07T13:39:30.906Z'
+ created_at: '2026-05-08T17:05:05.589Z'
+ updated_at: '2026-05-08T17:05:05.589Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -2402,11 +2402,11 @@ paths:
application/json:
example:
id: exp_UkLWZg9DAJ
- number: EF749423618
+ number: EF935360668
type: Spree::Exports::Products
format: csv
- created_at: '2026-05-07T13:39:31.192Z'
- updated_at: '2026-05-07T13:39:31.192Z'
+ created_at: '2026-05-08T17:05:05.864Z'
+ updated_at: '2026-05-08T17:05:05.864Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -2557,15 +2557,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-05-07T13:39:32.080Z'
- updated_at: '2026-05-07T13:39:32.080Z'
- expires_at: '2026-05-21T13:39:32.077Z'
+ created_at: '2026-05-08T17:05:06.742Z'
+ updated_at: '2026-05-08T17:05:06.742Z'
+ expires_at: '2026-05-22T17:05:06.739Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=FxWAYtT2p63WCdDuJUyv5Dej"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=8WkeKnb64AViTut2Y7zzGPWw"
meta:
page: 1
limit: 25
@@ -2622,13 +2622,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-05-07T13:39:32.404Z'
- updated_at: '2026-05-07T13:39:32.404Z'
- expires_at: '2026-05-21T13:39:32.400Z'
+ created_at: '2026-05-08T17:05:07.070Z'
+ updated_at: '2026-05-08T17:05:07.070Z'
+ expires_at: '2026-05-22T17:05:07.065Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=4LBvXu2SuxL2qBCXk6Ms4tqe"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=hnrB4QPYaYF1N931uTqfvSPK"
requestBody:
content:
application/json:
@@ -2731,15 +2731,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-05-07T13:39:33.000Z'
- updated_at: '2026-05-07T13:39:33.000Z'
- expires_at: '2026-05-21T13:39:32.996Z'
+ created_at: '2026-05-08T17:05:07.668Z'
+ updated_at: '2026-05-08T17:05:07.668Z'
+ expires_at: '2026-05-22T17:05:07.665Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=a88JaJJAu5qDfp4D5tsTZv6F"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=7JqRugHjvpuNTPzKyjQXfNWA"
"/api/v3/admin/me":
get:
summary: Get current admin user and permissions
@@ -2785,11 +2785,11 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Sunny
- last_name: Kohler
- created_at: '2026-05-07T13:39:33.285Z'
- updated_at: '2026-05-07T13:39:33.285Z'
+ first_name: Annie
+ last_name: Huels
+ created_at: '2026-05-08T17:05:07.951Z'
+ updated_at: '2026-05-08T17:05:07.951Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -2938,8 +2938,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-07T13:39:33.332Z'
- updated_at: '2026-05-07T13:39:33.332Z'
+ created_at: '2026-05-08T17:05:07.996Z'
+ updated_at: '2026-05-08T17:05:07.996Z'
option_values: []
meta:
page: 1
@@ -3030,8 +3030,8 @@ paths:
position: 2
kind: dropdown
metadata: {}
- created_at: '2026-05-07T13:39:33.916Z'
- updated_at: '2026-05-07T13:39:33.916Z'
+ created_at: '2026-05-08T17:05:08.572Z'
+ updated_at: '2026-05-08T17:05:08.572Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -3152,8 +3152,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-07T13:39:34.201Z'
- updated_at: '2026-05-07T13:39:34.201Z'
+ created_at: '2026-05-08T17:05:08.859Z'
+ updated_at: '2026-05-08T17:05:08.859Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -3225,8 +3225,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-07T13:39:34.764Z'
- updated_at: '2026-05-07T13:39:35.044Z'
+ created_at: '2026-05-08T17:05:09.419Z'
+ updated_at: '2026-05-08T17:05:09.698Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -3386,7 +3386,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H75338635909
+ number: H62539658744
tracking: U10000
tracking_url:
cost: '10.0'
@@ -3411,8 +3411,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:36.013Z'
- updated_at: '2026-05-07T13:39:36.142Z'
+ created_at: '2026-05-08T17:05:10.644Z'
+ updated_at: '2026-05-08T17:05:10.763Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -3495,7 +3495,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H00929181921
+ number: H30268522235
tracking: U10000
tracking_url:
cost: '10.0'
@@ -3520,8 +3520,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:36.778Z'
- updated_at: '2026-05-07T13:39:36.843Z'
+ created_at: '2026-05-08T17:05:11.393Z'
+ updated_at: '2026-05-08T17:05:11.456Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -3580,7 +3580,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H55672113063
+ number: H87833720446
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -3605,8 +3605,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:37.444Z'
- updated_at: '2026-05-07T13:39:37.790Z'
+ created_at: '2026-05-08T17:05:12.044Z'
+ updated_at: '2026-05-08T17:05:12.387Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -3675,7 +3675,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H98294370858
+ number: H11201080374
tracking: U10000
tracking_url:
cost: '10.0'
@@ -3692,7 +3692,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-05-07T13:39:38Z'
+ fulfilled_at: '2026-05-08T17:05:13Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -3700,8 +3700,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:38.116Z'
- updated_at: '2026-05-07T13:39:38.481Z'
+ created_at: '2026-05-08T17:05:12.716Z'
+ updated_at: '2026-05-08T17:05:13.066Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -3759,7 +3759,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H43565339771
+ number: H11200800987
tracking: U10000
tracking_url:
cost: '10.0'
@@ -3784,8 +3784,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:38.820Z'
- updated_at: '2026-05-07T13:39:39.165Z'
+ created_at: '2026-05-08T17:05:13.388Z'
+ updated_at: '2026-05-08T17:05:13.728Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -3843,7 +3843,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H90988617804
+ number: H75947002641
tracking: U10000
tracking_url:
cost: '10.0'
@@ -3868,8 +3868,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:39.497Z'
- updated_at: '2026-05-07T13:39:39.859Z'
+ created_at: '2026-05-08T17:05:14.057Z'
+ updated_at: '2026-05-08T17:05:14.424Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -3930,7 +3930,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H68390199147
+ number: H15948722408
tracking:
tracking_url:
cost: '10.0'
@@ -3955,8 +3955,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-07T13:39:40.559Z'
- updated_at: '2026-05-07T13:39:40.608Z'
+ created_at: '2026-05-08T17:05:15.107Z'
+ updated_at: '2026-05-08T17:05:15.152Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -4028,7 +4028,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 44B94AB9D43BC417
+ code: 58A0FA2403BDB2DE
status: active
currency: USD
amount: '10.0'
@@ -4042,8 +4042,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-05-07T13:39:40.954Z'
- updated_at: '2026-05-07T13:39:41.257Z'
+ created_at: '2026-05-08T17:05:15.552Z'
+ updated_at: '2026-05-08T17:05:15.878Z'
requestBody:
content:
application/json:
@@ -4174,8 +4174,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 102182
- slug: product-102182
+ name: Product 105047
+ slug: product-105047
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -4207,12 +4207,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:39:41.965Z'
- updated_at: '2026-05-07T13:39:41.965Z'
+ created_at: '2026-05-08T17:05:16.600Z'
+ updated_at: '2026-05-08T17:05:16.600Z'
digital_links: []
metadata: {}
- created_at: '2026-05-07T13:39:42.252Z'
- updated_at: '2026-05-07T13:39:42.252Z'
+ created_at: '2026-05-08T17:05:16.912Z'
+ updated_at: '2026-05-08T17:05:16.912Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -4279,8 +4279,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 122810
- slug: product-122810
+ name: Product 128532
+ slug: product-128532
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -4312,12 +4312,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:39:43.332Z'
- updated_at: '2026-05-07T13:39:43.332Z'
+ created_at: '2026-05-08T17:05:17.846Z'
+ updated_at: '2026-05-08T17:05:17.846Z'
digital_links: []
metadata: {}
- created_at: '2026-05-07T13:39:43.375Z'
- updated_at: '2026-05-07T13:39:43.375Z'
+ created_at: '2026-05-08T17:05:17.876Z'
+ updated_at: '2026-05-08T17:05:17.876Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -4406,8 +4406,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 139601
- slug: product-139601
+ name: Product 13657
+ slug: product-13657
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -4439,12 +4439,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:39:43.514Z'
- updated_at: '2026-05-07T13:39:43.514Z'
+ created_at: '2026-05-08T17:05:17.952Z'
+ updated_at: '2026-05-08T17:05:17.952Z'
digital_links: []
metadata: {}
- created_at: '2026-05-07T13:39:43.821Z'
- updated_at: '2026-05-07T13:39:43.821Z'
+ created_at: '2026-05-08T17:05:18.242Z'
+ updated_at: '2026-05-08T17:05:18.242Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -4506,8 +4506,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 145190
- slug: product-145190
+ name: Product 144958
+ slug: product-144958
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -4539,12 +4539,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:39:44.159Z'
- updated_at: '2026-05-07T13:39:44.159Z'
+ created_at: '2026-05-08T17:05:18.571Z'
+ updated_at: '2026-05-08T17:05:18.571Z'
digital_links: []
metadata: {}
- created_at: '2026-05-07T13:39:44.446Z'
- updated_at: '2026-05-07T13:39:44.745Z'
+ created_at: '2026-05-08T17:05:18.856Z'
+ updated_at: '2026-05-08T17:05:19.151Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -4670,8 +4670,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-b9c02ebf95ca
- number: PA2Z1OGS
+ response_code: BGS-d91b171f4cef
+ number: PYSH2ORF
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -4689,14 +4689,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-07T13:39:45.736Z'
- updated_at: '2026-05-07T13:39:45.739Z'
+ created_at: '2026-05-08T17:05:20.124Z'
+ updated_at: '2026-05-08T17:05:20.126Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-07T13:39:45.738Z'
- updated_at: '2026-05-07T13:39:45.738Z'
+ created_at: '2026-05-08T17:05:20.125Z'
+ updated_at: '2026-05-08T17:05:20.125Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -4763,7 +4763,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: PDDFESIE
+ number: PD7LQ602
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -4774,8 +4774,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-07T13:39:47.146Z'
- updated_at: '2026-05-07T13:39:47.146Z'
+ created_at: '2026-05-08T17:05:21.433Z'
+ updated_at: '2026-05-08T17:05:21.433Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -4865,8 +4865,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-326401616af8
- number: PSJ3I98K
+ response_code: BGS-afbd1dc6eb29
+ number: P5DKDVAP
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -4884,14 +4884,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-07T13:39:47.520Z'
- updated_at: '2026-05-07T13:39:47.522Z'
+ created_at: '2026-05-08T17:05:21.802Z'
+ updated_at: '2026-05-08T17:05:21.805Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-07T13:39:47.521Z'
- updated_at: '2026-05-07T13:39:47.521Z'
+ created_at: '2026-05-08T17:05:21.803Z'
+ updated_at: '2026-05-08T17:05:21.803Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -4950,8 +4950,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-b724905736e0
- number: PO4WKVSI
+ response_code: BGS-aae90e6a4a7b
+ number: PD08CEGM
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -4969,14 +4969,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-07T13:39:48.184Z'
- updated_at: '2026-05-07T13:39:48.187Z'
+ created_at: '2026-05-08T17:05:22.459Z'
+ updated_at: '2026-05-08T17:05:22.461Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-07T13:39:48.186Z'
- updated_at: '2026-05-07T13:39:48.516Z'
+ created_at: '2026-05-08T17:05:22.460Z'
+ updated_at: '2026-05-08T17:05:22.797Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -5045,8 +5045,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-2f2887a4dcf8
- number: PNE7W24P
+ response_code: void-BGS-1b769fee9947
+ number: PXWBO4NP
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -5064,14 +5064,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-07T13:39:49.566Z'
- updated_at: '2026-05-07T13:39:49.569Z'
+ created_at: '2026-05-08T17:05:23.973Z'
+ updated_at: '2026-05-08T17:05:23.976Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-07T13:39:49.568Z'
- updated_at: '2026-05-07T13:39:49.876Z'
+ created_at: '2026-05-08T17:05:23.975Z'
+ updated_at: '2026-05-08T17:05:24.288Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/refunds":
@@ -5199,14 +5199,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-dc3ac7486198
+ transaction_id: BGS-fe8641cee9bd
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-05-07T13:39:51.234Z'
- updated_at: '2026-05-07T13:39:51.234Z'
+ created_at: '2026-05-08T17:05:25.608Z'
+ updated_at: '2026-05-08T17:05:25.608Z'
requestBody:
content:
application/json:
@@ -5277,8 +5277,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R169796219
+ number: R192149700
customer_note:
currency: USD
locale: en
@@ -5321,8 +5321,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:51.528Z'
- updated_at: '2026-05-07T13:39:51.584Z'
+ created_at: '2026-05-08T17:05:25.902Z'
+ updated_at: '2026-05-08T17:05:25.965Z'
tags: []
internal_note:
approver_id:
@@ -5491,8 +5491,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R547242231
+ number: R764455447
customer_note:
currency: USD
locale: en
@@ -5535,8 +5535,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:53.339Z'
- updated_at: '2026-05-07T13:39:53.339Z'
+ created_at: '2026-05-08T17:05:27.714Z'
+ updated_at: '2026-05-08T17:05:27.714Z'
tags: []
internal_note:
approver_id:
@@ -5665,7 +5665,7 @@ paths:
example:
id: or_gbHJdmfrXB
market_id:
- number: R845060014
+ number: R913209503
customer_note:
currency: USD
@@ -5709,8 +5709,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:54.549Z'
- updated_at: '2026-05-07T13:39:54.552Z'
+ created_at: '2026-05-08T17:05:28.843Z'
+ updated_at: '2026-05-08T17:05:28.846Z'
tags: []
internal_note:
approver_id:
@@ -5882,8 +5882,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R406122509
+ number: R941432887
customer_note:
currency: USD
locale: en
@@ -5926,8 +5926,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:54.842Z'
- updated_at: '2026-05-07T13:39:54.842Z'
+ created_at: '2026-05-08T17:05:29.120Z'
+ updated_at: '2026-05-08T17:05:29.120Z'
tags: []
internal_note:
approver_id:
@@ -5996,7 +5996,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R335768882
+ number: R245983770
customer_note:
currency: USD
@@ -6040,8 +6040,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:56.035Z'
- updated_at: '2026-05-07T13:39:56.351Z'
+ created_at: '2026-05-08T17:05:30.219Z'
+ updated_at: '2026-05-08T17:05:30.508Z'
tags: []
internal_note:
approver_id:
@@ -6212,8 +6212,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R868799164
+ number: R898432079
customer_note:
currency: USD
locale: en
@@ -6240,7 +6240,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-05-07T13:39:57.265Z'
+ completed_at: '2026-05-08T17:05:31.423Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6256,8 +6256,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:39:57.212Z'
- updated_at: '2026-05-07T13:39:57.289Z'
+ created_at: '2026-05-08T17:05:31.367Z'
+ updated_at: '2026-05-08T17:05:31.450Z'
tags: []
internal_note:
approver_id:
@@ -6336,8 +6336,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R735653505
+ number: R542275026
customer_note:
currency: USD
locale: en
@@ -6364,7 +6364,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-07T13:39:58.543Z'
+ completed_at: '2026-05-08T17:05:32.702Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6378,10 +6378,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-07T13:39:58.834Z'
+ canceled_at: '2026-05-08T17:05:32.999Z'
approved_at:
- created_at: '2026-05-07T13:39:58.493Z'
- updated_at: '2026-05-07T13:39:58.885Z'
+ created_at: '2026-05-08T17:05:32.648Z'
+ updated_at: '2026-05-08T17:05:33.044Z'
tags: []
internal_note:
approver_id:
@@ -6438,8 +6438,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R839879088
+ number: R912095046
customer_note:
currency: USD
locale: en
@@ -6466,7 +6466,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-07T13:39:59.242Z'
+ completed_at: '2026-05-08T17:05:33.434Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6481,9 +6481,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-05-07T13:39:59.533Z'
- created_at: '2026-05-07T13:39:59.185Z'
- updated_at: '2026-05-07T13:39:59.242Z'
+ approved_at: '2026-05-08T17:05:33.735Z'
+ created_at: '2026-05-08T17:05:33.369Z'
+ updated_at: '2026-05-08T17:05:33.434Z'
tags: []
internal_note:
approver_id: admin_UkLWZg9DAJ
@@ -6540,8 +6540,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R048120637
+ number: R316764648
customer_note:
currency: USD
locale: en
@@ -6568,7 +6568,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-07T13:39:59.871Z'
+ completed_at: '2026-05-08T17:05:34.081Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6582,10 +6582,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-07T13:40:00.151Z'
+ canceled_at: '2026-05-08T17:05:34.358Z'
approved_at:
- created_at: '2026-05-07T13:39:59.816Z'
- updated_at: '2026-05-07T13:40:00.233Z'
+ created_at: '2026-05-08T17:05:34.024Z'
+ updated_at: '2026-05-08T17:05:34.466Z'
tags: []
internal_note:
approver_id:
@@ -6642,8 +6642,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R012387799
+ number: R949053309
customer_note:
currency: USD
locale: en
@@ -6670,7 +6670,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-07T13:40:00.564Z'
+ completed_at: '2026-05-08T17:05:34.852Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6686,8 +6686,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-07T13:40:00.513Z'
- updated_at: '2026-05-07T13:40:00.564Z'
+ created_at: '2026-05-08T17:05:34.760Z'
+ updated_at: '2026-05-08T17:05:34.852Z'
tags: []
internal_note:
approver_id:
@@ -6759,8 +6759,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-07T13:40:00.878Z'
- updated_at: '2026-05-07T13:40:00.879Z'
+ created_at: '2026-05-08T17:05:35.159Z'
+ updated_at: '2026-05-08T17:05:35.161Z'
meta:
page: 1
limit: 25
@@ -6840,8 +6840,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-07T13:40:01.169Z'
- updated_at: '2026-05-07T13:40:01.170Z'
+ created_at: '2026-05-08T17:05:35.452Z'
+ updated_at: '2026-05-08T17:05:35.453Z'
"/api/v3/admin/products/{product_id}/custom_fields":
get:
summary: List product custom fields
@@ -6909,8 +6909,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-07T13:40:01.490Z'
- updated_at: '2026-05-07T13:40:01.490Z'
+ created_at: '2026-05-08T17:05:35.775Z'
+ updated_at: '2026-05-08T17:05:35.775Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -6977,8 +6977,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-05-07T13:40:02.099Z'
- updated_at: '2026-05-07T13:40:02.099Z'
+ created_at: '2026-05-08T17:05:36.439Z'
+ updated_at: '2026-05-08T17:05:36.439Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -7062,8 +7062,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-07T13:40:02.453Z'
- updated_at: '2026-05-07T13:40:02.453Z'
+ created_at: '2026-05-08T17:05:36.802Z'
+ updated_at: '2026-05-08T17:05:36.802Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -7110,8 +7110,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-05-07T13:40:02.768Z'
- updated_at: '2026-05-07T13:40:03.050Z'
+ created_at: '2026-05-08T17:05:37.124Z'
+ updated_at: '2026-05-08T17:05:37.415Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -7249,35 +7249,31 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 397563
- slug: product-397563
+ name: Product 398623
+ slug: product-398623
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-07T13:40:03.380Z'
+ available_on: '2025-05-08T17:05:37.757Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Sequi excepturi autem eveniet provident. Quidem soluta
- fugit fugiat sapiente fuga. Ab a dolores ea magnam voluptatum
- ipsa. Non recusandae ducimus voluptatibus velit mollitia porro
- est dolorem. Sapiente provident nihil eveniet recusandae. Pariatur
- modi officia maiores omnis nostrum. Quasi a quo ex amet. Quidem
- dicta voluptatibus autem ut reiciendis ad sapiente aliquam. Consequuntur
- est sit ad necessitatibus facilis sed. Quasi esse consectetur
- ut porro ipsa temporibus. Perferendis necessitatibus distinctio
- blanditiis repudiandae quibusdam ea. Sed asperiores harum assumenda
- explicabo unde. Pariatur sapiente assumenda eaque nam numquam
- quod consectetur. Dicta commodi temporibus tenetur sed similique
- repudiandae modi. Laudantium impedit asperiores quibusdam eum
- nulla quis quasi. Id impedit cumque similique reprehenderit officiis
- quia.
+ description: Aliquid iste possimus commodi blanditiis excepturi
+ fuga pariatur beatae. Porro inventore esse earum quidem tenetur
+ alias. Eligendi commodi fuga odio quos quibusdam inventore. A
+ voluptate facilis ipsum consequatur vel assumenda. Eos inventore
+ mollitia illo nam recusandae delectus molestias. Cum in excepturi
+ fuga maxime voluptatem modi. Quas voluptatem placeat eos hic.
+ Optio culpa rem tenetur vero sapiente. Qui vitae tempore excepturi
+ recusandae libero doloremque temporibus. Adipisci quos perspiciatis
+ animi eaque quod ab veritatis. Repellendus suscipit vel voluptates
+ sed debitis ipsam. Quasi eveniet ad modi quia voluptate. Sequi
+ vel totam officia corrupti optio nam.
description_html: |-
- Sequi excepturi autem eveniet provident. Quidem soluta fugit fugiat sapiente fuga. Ab a dolores ea magnam voluptatum ipsa.
- Non recusandae ducimus voluptatibus velit mollitia porro est dolorem. Sapiente provident nihil eveniet recusandae. Pariatur modi officia maiores omnis nostrum. Quasi a quo ex amet. Quidem dicta voluptatibus autem ut reiciendis ad sapiente aliquam.
- Consequuntur est sit ad necessitatibus facilis sed. Quasi esse consectetur ut porro ipsa temporibus. Perferendis necessitatibus distinctio blanditiis repudiandae quibusdam ea. Sed asperiores harum assumenda explicabo unde.
- Pariatur sapiente assumenda eaque nam numquam quod consectetur. Dicta commodi temporibus tenetur sed similique repudiandae modi. Laudantium impedit asperiores quibusdam eum nulla quis quasi. Id impedit cumque similique reprehenderit officiis quia.
+ Aliquid iste possimus commodi blanditiis excepturi fuga pariatur beatae. Porro inventore esse earum quidem tenetur alias. Eligendi commodi fuga odio quos quibusdam inventore. A voluptate facilis ipsum consequatur vel assumenda.
+ Eos inventore mollitia illo nam recusandae delectus molestias. Cum in excepturi fuga maxime voluptatem modi. Quas voluptatem placeat eos hic. Optio culpa rem tenetur vero sapiente. Qui vitae tempore excepturi recusandae libero doloremque temporibus.
+ Adipisci quos perspiciatis animi eaque quod ab veritatis. Repellendus suscipit vel voluptates sed debitis ipsam. Quasi eveniet ad modi quia voluptate. Sequi vel totam officia corrupti optio nam.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -7292,16 +7288,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-07T13:40:03.412Z'
- updated_at: '2026-05-07T13:40:03.412Z'
+ created_at: '2026-05-08T17:05:37.785Z'
+ updated_at: '2026-05-08T17:05:37.785Z'
original_price:
status: active
- make_active_at: '2025-05-07T13:40:03.380Z'
+ make_active_at: '2025-05-08T17:05:37.757Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-07T13:40:03.395Z'
- updated_at: '2026-05-07T13:40:03.413Z'
+ created_at: '2026-05-08T17:05:37.772Z'
+ updated_at: '2026-05-08T17:05:37.786Z'
cost_price: '17.0'
cost_currency: USD
meta:
@@ -7440,16 +7436,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-05-07T13:40:04.083Z'
- updated_at: '2026-05-07T13:40:04.083Z'
+ created_at: '2026-05-08T17:05:38.472Z'
+ updated_at: '2026-05-08T17:05:38.472Z'
original_price:
status: draft
make_active_at:
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-07T13:40:04.081Z'
- updated_at: '2026-05-07T13:40:04.088Z'
+ created_at: '2026-05-08T17:05:38.470Z'
+ updated_at: '2026-05-08T17:05:38.476Z'
cost_price:
cost_currency: USD
schema:
@@ -7636,35 +7632,25 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 43541
- slug: product-43541
+ name: Product 435715
+ slug: product-435715
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-07T13:40:04.486Z'
+ available_on: '2025-05-08T17:05:38.886Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Quos magni occaecati ratione ullam expedita possimus
- consectetur vel. At magnam earum aperiam illo labore ipsum reiciendis.
- Libero nisi hic ea placeat beatae accusantium est repudiandae. Iusto
- est nobis commodi nemo unde quia. Optio ipsum sapiente exercitationem
- accusantium corporis vel et alias. Excepturi sapiente officia earum
- eveniet amet at ea pariatur. Laborum rerum veniam quo blanditiis
- illum amet numquam. Dicta amet commodi deleniti natus autem non
- itaque. Error asperiores a laudantium aperiam amet sit iusto nisi.
- Eius autem fuga cum in consequuntur beatae quisquam natus. Quasi
- quibusdam sequi assumenda molestias maxime itaque ex. Numquam nemo
- quaerat pariatur omnis iste vel. Voluptatum non officia quia ipsa
- in. Nostrum voluptas ut consectetur neque. Nam numquam eligendi
- nulla provident amet optio. Autem voluptatum itaque impedit cum
- iste facilis totam quisquam.
+ description: Laboriosam iure incidunt blanditiis mollitia necessitatibus
+ tempore a nisi. Voluptates commodi sit nihil eligendi provident
+ officiis sequi adipisci. Quo recusandae possimus cupiditate quidem
+ porro odit beatae. Iusto illo odit rerum animi ipsa. Deserunt voluptatem
+ praesentium doloribus fugit laboriosam neque asperiores. Veritatis
+ recusandae doloribus quisquam necessitatibus alias.
description_html: |-
- Quos magni occaecati ratione ullam expedita possimus consectetur vel. At magnam earum aperiam illo labore ipsum reiciendis. Libero nisi hic ea placeat beatae accusantium est repudiandae. Iusto est nobis commodi nemo unde quia. Optio ipsum sapiente exercitationem accusantium corporis vel et alias.
- Excepturi sapiente officia earum eveniet amet at ea pariatur. Laborum rerum veniam quo blanditiis illum amet numquam. Dicta amet commodi deleniti natus autem non itaque.
- Error asperiores a laudantium aperiam amet sit iusto nisi. Eius autem fuga cum in consequuntur beatae quisquam natus. Quasi quibusdam sequi assumenda molestias maxime itaque ex.
- Numquam nemo quaerat pariatur omnis iste vel. Voluptatum non officia quia ipsa in. Nostrum voluptas ut consectetur neque. Nam numquam eligendi nulla provident amet optio. Autem voluptatum itaque impedit cum iste facilis totam quisquam.
+ Laboriosam iure incidunt blanditiis mollitia necessitatibus tempore a nisi. Voluptates commodi sit nihil eligendi provident officiis sequi adipisci. Quo recusandae possimus cupiditate quidem porro odit beatae.
+ Iusto illo odit rerum animi ipsa. Deserunt voluptatem praesentium doloribus fugit laboriosam neque asperiores. Veritatis recusandae doloribus quisquam necessitatibus alias.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -7679,16 +7665,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-07T13:40:04.539Z'
- updated_at: '2026-05-07T13:40:04.539Z'
+ created_at: '2026-05-08T17:05:38.925Z'
+ updated_at: '2026-05-08T17:05:38.925Z'
original_price:
status: active
- make_active_at: '2025-05-07T13:40:04.486Z'
+ make_active_at: '2025-05-08T17:05:38.886Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-07T13:40:04.512Z'
- updated_at: '2026-05-07T13:40:04.540Z'
+ created_at: '2026-05-08T17:05:38.912Z'
+ updated_at: '2026-05-08T17:05:38.926Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -7756,23 +7742,23 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-456072
+ slug: product-456883
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-07T13:40:05.198Z'
+ available_on: '2025-05-08T17:05:39.574Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Iure quis sequi cumque odit quidem assumenda. Fuga recusandae
- numquam aliquam totam aperiam commodi nobis. Tempora adipisci illum
- rerum deleniti numquam tenetur sunt aut. Sapiente quis temporibus
- sed exercitationem quibusdam nostrum. Architecto mollitia eaque
- modi minus. Illum beatae sed nihil officia corrupti facilis dolorum.
- description_html: |-
- Iure quis sequi cumque odit quidem assumenda. Fuga recusandae numquam aliquam totam aperiam commodi nobis. Tempora adipisci illum rerum deleniti numquam tenetur sunt aut.
- Sapiente quis temporibus sed exercitationem quibusdam nostrum. Architecto mollitia eaque modi minus. Illum beatae sed nihil officia corrupti facilis dolorum.
+ description: Eveniet alias minus perspiciatis dolorum quis. Natus
+ quia beatae quae itaque officia autem rerum non. Repellat porro
+ maiores officiis perspiciatis ratione. Voluptatem molestias accusantium
+ molestiae dolore sunt libero provident. Maxime ab sed sint maiores.
+ description_html: Eveniet alias minus perspiciatis dolorum quis. Natus
+ quia beatae quae itaque officia autem rerum non. Repellat porro
+ maiores officiis perspiciatis ratione. Voluptatem molestias accusantium
+ molestiae dolore sunt libero provident. Maxime ab sed sint maiores.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -7787,16 +7773,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-07T13:40:05.223Z'
- updated_at: '2026-05-07T13:40:05.223Z'
+ created_at: '2026-05-08T17:05:39.600Z'
+ updated_at: '2026-05-08T17:05:39.600Z'
original_price:
status: active
- make_active_at: '2025-05-07T13:40:05.199Z'
+ make_active_at: '2025-05-08T17:05:39.574Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-07T13:40:05.212Z'
- updated_at: '2026-05-07T13:40:05.513Z'
+ created_at: '2026-05-08T17:05:39.587Z'
+ updated_at: '2026-05-08T17:05:39.887Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -8003,8 +7989,144 @@ paths:
data:
- id: role_UkLWZg9DAJ
name: admin
- created_at: '2026-05-07T13:40:06.196Z'
- updated_at: '2026-05-07T13:40:06.196Z'
+ created_at: '2026-05-08T17:05:40.594Z'
+ updated_at: '2026-05-08T17:05:40.594Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/stock_locations":
+ get:
+ summary: List stock locations
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the configured stock locations. Stock locations are global
+ (shared across stores). Filter with Ransack predicates such as
+ `q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or
+ `q[name_cont]`.
+
+ Pickup-related attributes (`kind`, `pickup_enabled`,
+ `pickup_stock_policy`, `pickup_ready_in_minutes`,
+ `pickup_instructions`) drive merchant pickup support at checkout —
+ customers can collect orders from any active location with
+ `pickup_enabled: true`.
+
+
+ **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 { data: stockLocations } = await client.stockLocations.list()
+ 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
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Number of records per page
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active status
+ schema:
+ type: boolean
+ - name: q[kind_eq]
+ in: query
+ required: false
+ description: 'Filter by kind (built-in: ''warehouse'', ''store'', ''fulfillment_center'')'
+ schema:
+ type: string
+ - name: q[pickup_enabled_eq]
+ in: query
+ required: false
+ description: Filter by pickup-enabled flag
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include. id is always included.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: stock locations found
+ content:
+ application/json:
+ example:
+ data:
+ - id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_21
+ name: Brooklyn warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_21
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: false
+ pickup_stock_policy: local
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ created_at: '2026-05-08T17:05:40.895Z'
+ updated_at: '2026-05-08T17:05:40.895Z'
meta:
page: 1
limit: 25
@@ -8015,6 +8137,491 @@ paths:
in: 1
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/StockLocation"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create a stock location
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Creates a new stock location.
+
+ Setting `default: true` automatically demotes the previous default
+ location.
+
+
+ **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 stockLocation = await client.stockLocations.create({
+ name: 'Brooklyn warehouse',
+ kind: 'warehouse',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ city: 'Brooklyn',
+ zipcode: '11201',
+ pickup_enabled: true,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: 60,
+ })
+ 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:
+ '201':
+ description: stock location created
+ content:
+ application/json:
+ example:
+ id: sloc_gbHJdmfrXB
+ state_abbr:
+ name: Manhattan store
+ address1:
+ city:
+ zipcode:
+ country_iso:
+ country_name:
+ state_text:
+ admin_name:
+ address2:
+ state_name:
+ phone:
+ company:
+ active: true
+ default: false
+ backorderable_default: false
+ propagate_all_variants: false
+ kind: store
+ pickup_enabled: true
+ pickup_stock_policy: local
+ pickup_ready_in_minutes: 30
+ pickup_instructions:
+ created_at: '2026-05-08T17:05:41.553Z'
+ updated_at: '2026-05-08T17:05:41.553Z'
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: 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: Brooklyn warehouse
+ admin_name:
+ type: string
+ nullable: true
+ description: Internal name shown only in the admin
+ active:
+ type: boolean
+ example: true
+ default:
+ type: boolean
+ description: Setting to true demotes the previous default.
+ kind:
+ type: string
+ enum:
+ - warehouse
+ - store
+ - fulfillment_center
+ description: Categorizes the location.
+ example: warehouse
+ propagate_all_variants:
+ type: boolean
+ backorderable_default:
+ type: boolean
+ address1:
+ type: string
+ nullable: true
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ nullable: true
+ zipcode:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ company:
+ type: string
+ nullable: true
+ country_iso:
+ type: string
+ nullable: true
+ description: ISO-3166 alpha-2 country code (e.g. "US").
+ state_abbr:
+ type: string
+ nullable: true
+ description: State / province abbreviation (e.g. "NY"). Resolved
+ against the selected country.
+ state_name:
+ type: string
+ nullable: true
+ description: Free-text state for countries without a states list.
+ pickup_enabled:
+ type: boolean
+ pickup_stock_policy:
+ type: string
+ enum:
+ - local
+ - any
+ description: "'local' = items at this location only; 'any' = transfer-eligible
+ (ship-to-store)."
+ pickup_ready_in_minutes:
+ type: number
+ nullable: true
+ minimum: 0
+ pickup_instructions:
+ type: string
+ nullable: true
+ required:
+ - name
+ "/api/v3/admin/stock_locations/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: Stock location ID
+ schema:
+ type: string
+ get:
+ summary: Get a stock location
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns a single stock location by prefixed ID.
+
+ **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 stockLocation = await client.stockLocations.get('sloc_UkLWZg9DAJ')
+ 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
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include. id is always included.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: stock location found
+ content:
+ application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_25
+ name: Brooklyn warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_25
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: false
+ pickup_stock_policy: local
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ created_at: '2026-05-08T17:05:41.855Z'
+ updated_at: '2026-05-08T17:05:41.855Z'
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '404':
+ description: stock location not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Stock location not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a stock location
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates an existing stock location. Same address-field conventions as
+ the create endpoint.
+
+ Setting `default: true` automatically demotes the previous default.
+
+
+ **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 stockLocation = await client.stockLocations.update('sloc_UkLWZg9DAJ', {
+ pickup_enabled: true,
+ pickup_ready_in_minutes: 45,
+ pickup_instructions: 'Enter through the back door, ring the bell.',
+ })
+ 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: stock location updated
+ content:
+ application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_27
+ name: Renamed warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_27
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: true
+ pickup_stock_policy: local
+ pickup_ready_in_minutes: 45
+ pickup_instructions:
+ created_at: '2026-05-08T17:05:42.432Z'
+ updated_at: '2026-05-08T17:05:42.726Z'
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Pickup stock policy is not included in the list
+ details:
+ pickup_stock_policy:
+ - is not included in the list
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ admin_name:
+ type: string
+ nullable: true
+ active:
+ type: boolean
+ default:
+ type: boolean
+ kind:
+ type: string
+ enum:
+ - warehouse
+ - store
+ - fulfillment_center
+ propagate_all_variants:
+ type: boolean
+ backorderable_default:
+ type: boolean
+ address1:
+ type: string
+ nullable: true
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ nullable: true
+ zipcode:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ company:
+ type: string
+ nullable: true
+ country_iso:
+ type: string
+ nullable: true
+ state_abbr:
+ type: string
+ nullable: true
+ state_name:
+ type: string
+ nullable: true
+ pickup_enabled:
+ type: boolean
+ pickup_stock_policy:
+ type: string
+ enum:
+ - local
+ - any
+ pickup_ready_in_minutes:
+ type: number
+ nullable: true
+ minimum: 0
+ pickup_instructions:
+ type: string
+ nullable: true
+ delete:
+ summary: Delete a stock location
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Soft-deletes the stock location (sets `deleted_at`). Existing
+ fulfillments that referenced it keep the historical record via
+ `Spree::StockLocation.with_deleted`.
+
+
+ **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',
+ })
+
+ await client.stockLocations.delete('sloc_UkLWZg9DAJ')
+ 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:
+ '204':
+ description: stock location deleted
"/api/v3/admin/store":
get:
summary: Get the current store
@@ -8066,8 +8673,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-05-07T13:39:14.132Z'
- updated_at: '2026-05-07T13:40:06.502Z'
+ created_at: '2026-05-08T17:04:49.415Z'
+ updated_at: '2026-05-08T17:05:43.346Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -8138,8 +8745,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-05-07T13:39:14.132Z'
- updated_at: '2026-05-07T13:40:07.189Z'
+ created_at: '2026-05-08T17:04:49.415Z'
+ updated_at: '2026-05-08T17:05:43.986Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -8358,9 +8965,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-07T13:40:08.595Z'
- updated_at: '2026-05-07T13:40:08.608Z'
- product_name: Product 4887
+ created_at: '2026-05-08T17:05:45.437Z'
+ updated_at: '2026-05-08T17:05:45.452Z'
+ product_name: Product 483776
display_price: "$0.00"
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
@@ -8372,10 +8979,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 198.27
- height: 0.22
- width: 99.24
- depth: 175.9
+ weight: 190.6
+ height: 53.17
+ width: 1.72
+ depth: 27.22
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -8398,8 +9005,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:40:08.619Z'
- updated_at: '2026-05-07T13:40:08.619Z'
+ created_at: '2026-05-08T17:05:45.462Z'
+ updated_at: '2026-05-08T17:05:45.462Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -8407,9 +9014,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-07T13:40:08.616Z'
- updated_at: '2026-05-07T13:40:08.629Z'
- product_name: Product 4887
+ created_at: '2026-05-08T17:05:45.460Z'
+ updated_at: '2026-05-08T17:05:45.473Z'
+ product_name: Product 483776
display_price: "$19.99"
meta:
page: 1
@@ -8521,8 +9128,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:40:09.266Z'
- updated_at: '2026-05-07T13:40:09.266Z'
+ created_at: '2026-05-08T17:05:46.133Z'
+ updated_at: '2026-05-08T17:05:46.133Z'
metadata: {}
position: 3
total_on_hand: 0
@@ -8530,9 +9137,9 @@ paths:
cost_price:
cost_currency: USD
deleted_at:
- created_at: '2026-05-07T13:40:09.269Z'
- updated_at: '2026-05-07T13:40:09.271Z'
- product_name: Product 496423
+ created_at: '2026-05-08T17:05:46.136Z'
+ updated_at: '2026-05-08T17:05:46.138Z'
+ product_name: Product 497140
display_price: "$24.99"
'422':
description: validation error
@@ -8720,10 +9327,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 115.3
- height: 21.47
- width: 135.36
- depth: 176.53
+ weight: 17.54
+ height: 67.2
+ width: 185.2
+ depth: 97.63
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -8746,8 +9353,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:40:09.682Z'
- updated_at: '2026-05-07T13:40:09.682Z'
+ created_at: '2026-05-08T17:05:46.546Z'
+ updated_at: '2026-05-08T17:05:46.546Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -8755,9 +9362,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-07T13:40:09.680Z'
- updated_at: '2026-05-07T13:40:09.692Z'
- product_name: Product 517973
+ created_at: '2026-05-08T17:05:46.544Z'
+ updated_at: '2026-05-08T17:05:46.564Z'
+ product_name: Product 51501
display_price: "$19.99"
'404':
description: variant not found
@@ -8837,10 +9444,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 0.89
- height: 91.57
- width: 55.68
- depth: 125.5
+ weight: 32.1
+ height: 188.18
+ width: 104.62
+ depth: 143.14
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -8863,8 +9470,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-07T13:40:10.350Z'
- updated_at: '2026-05-07T13:40:10.350Z'
+ created_at: '2026-05-08T17:05:47.265Z'
+ updated_at: '2026-05-08T17:05:47.265Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -8872,9 +9479,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-07T13:40:10.347Z'
- updated_at: '2026-05-07T13:40:10.645Z'
- product_name: Product 539379
+ created_at: '2026-05-08T17:05:47.263Z'
+ updated_at: '2026-05-08T17:05:47.564Z'
+ product_name: Product 531142
display_price: "$19.99"
requestBody:
content:
@@ -11380,6 +11987,21 @@ components:
state_text:
type: string
nullable: true
+ admin_name:
+ type: string
+ nullable: true
+ address2:
+ type: string
+ nullable: true
+ state_name:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ company:
+ type: string
+ nullable: true
active:
type: boolean
default:
@@ -11388,6 +12010,18 @@ components:
type: boolean
propagate_all_variants:
type: boolean
+ kind:
+ type: string
+ pickup_enabled:
+ type: boolean
+ pickup_stock_policy:
+ type: string
+ pickup_ready_in_minutes:
+ type: number
+ nullable: true
+ pickup_instructions:
+ type: string
+ nullable: true
created_at:
type: string
updated_at:
@@ -11402,10 +12036,20 @@ components:
- country_iso
- country_name
- state_text
+ - admin_name
+ - address2
+ - state_name
+ - phone
+ - company
- active
- default
- backorderable_default
- propagate_all_variants
+ - kind
+ - pickup_enabled
+ - pickup_stock_policy
+ - pickup_ready_in_minutes
+ - pickup_instructions
- created_at
- updated_at
x-typelizer: true
diff --git a/packages/admin-sdk/.changeset/admin-stock-locations.md b/packages/admin-sdk/.changeset/admin-stock-locations.md
new file mode 100644
index 0000000000..a8cdb59890
--- /dev/null
+++ b/packages/admin-sdk/.changeset/admin-stock-locations.md
@@ -0,0 +1,10 @@
+---
+'@spree/admin-sdk': minor
+---
+
+Stock location management.
+
+- New `client.stockLocations` accessor with `list / get / create / update / delete`. Backed by `/api/v3/admin/stock_locations`. Listing supports the standard Ransack filters (`name_cont`, `active_eq`, `kind_eq`, `pickup_enabled_eq`, etc.) plus default ordering by `default desc, name asc` so the default location surfaces first.
+- New params types: `StockLocationCreateParams`, `StockLocationUpdateParams`. Address fields use `country_iso` (ISO-3166 alpha-2 country code, e.g. `'US'`) and `state_abbr` (state/province abbreviation, e.g. `'NY'`) — the same opaque handles used everywhere else in the API for countries and states.
+- The `StockLocation` entity gains the 6.0 fulfillment-and-delivery columns: `kind` (`'warehouse' | 'store' | 'fulfillment_center'`, open string — plugins can register custom kinds), `pickup_enabled`, `pickup_stock_policy` (`'local'` keeps stock at the location only; `'any'` allows transfer-in / ship-to-store), `pickup_ready_in_minutes`, and `pickup_instructions`. These are the storefront-facing fields the upcoming pickup-fulfillment flow surfaces at checkout. See `docs/plans/6.0-fulfillment-and-delivery.md` for the wider context.
+- Admin serializer now also exposes `admin_name`, `address2`, `state_name`, `phone`, `company`, plus `created_at` / `updated_at`.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index d58063d1bc..553b8e95a7 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -120,6 +120,8 @@ import type {
OrderUpdateParams,
PaymentCreateParams,
ProductUpdateParams,
+ StockLocationCreateParams,
+ StockLocationUpdateParams,
StoreCreditApplyParams,
StoreUpdateParams,
VariantCreateParams,
@@ -148,6 +150,7 @@ import type {
Product,
Refund,
Role,
+ StockLocation,
Store,
StoreCredit,
TaxCategory,
@@ -1153,6 +1156,44 @@ export class AdminClient {
}),
}
+ // ============================================
+ // Stock Locations
+ // ============================================
+
+ readonly stockLocations = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<StockLocation>> =>
+ this.request<PaginatedResponse<StockLocation>>('GET', '/stock_locations', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<StockLocation> =>
+ this.request<StockLocation>('GET', `/stock_locations/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: StockLocationCreateParams, options?: RequestOptions): Promise<StockLocation> =>
+ this.request<StockLocation>('POST', '/stock_locations', { ...options, body: params }),
+
+ update: (
+ id: string,
+ params: StockLocationUpdateParams,
+ options?: RequestOptions,
+ ): Promise<StockLocation> =>
+ this.request<StockLocation>('PATCH', `/stock_locations/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/stock_locations/${id}`, options),
+ }
+
// ============================================
// Countries
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index e5fcd51033..b9dac6a696 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -384,6 +384,57 @@ export interface AdminUserUpdateParams {
role_ids?: string[]
}
+export interface StockLocationCreateParams {
+ name: string
+ admin_name?: string | null
+ active?: boolean
+ default?: boolean
+ /** Built-in values: 'warehouse' | 'store' | 'fulfillment_center'. Open string — plugins can register custom kinds. */
+ kind?: string
+ propagate_all_variants?: boolean
+ backorderable_default?: boolean
+ address1?: string | null
+ address2?: string | null
+ city?: string | null
+ zipcode?: string | null
+ phone?: string | null
+ company?: string | null
+ /** ISO-3166 alpha-2 country code (e.g. 'US'). */
+ country_iso?: string | null
+ /** State / province abbreviation (e.g. 'NY'). Resolved against the selected country's states. */
+ state_abbr?: string | null
+ /** Free-text state for countries that don't have a states list. */
+ state_name?: string | null
+ pickup_enabled?: boolean
+ /** 'local' = items at this location only; 'any' = transfer-eligible (ship-to-store). */
+ pickup_stock_policy?: 'local' | 'any'
+ pickup_ready_in_minutes?: number | null
+ pickup_instructions?: string | null
+}
+
+export interface StockLocationUpdateParams {
+ name?: string
+ admin_name?: string | null
+ active?: boolean
+ default?: boolean
+ kind?: string
+ propagate_all_variants?: boolean
+ backorderable_default?: boolean
+ address1?: string | null
+ address2?: string | null
+ city?: string | null
+ zipcode?: string | null
+ phone?: string | null
+ company?: string | null
+ country_iso?: string | null
+ state_abbr?: string | null
+ state_name?: string | null
+ pickup_enabled?: boolean
+ pickup_stock_policy?: 'local' | 'any'
+ pickup_ready_in_minutes?: number | null
+ pickup_instructions?: string | null
+}
+
/**
* Built-in `Spree::Export` subclasses. The server validates `type` against
* the configured allowlist (`Spree::Export.available_types`); a plugin can
diff --git a/packages/admin-sdk/src/types/generated/StockLocation.ts b/packages/admin-sdk/src/types/generated/StockLocation.ts
index 4ae06cfc9b..c7dd5b476a 100644
--- a/packages/admin-sdk/src/types/generated/StockLocation.ts
+++ b/packages/admin-sdk/src/types/generated/StockLocation.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 9ce15c973e21212880564b6123117e09
+// Typelizer digest e8dcf00c900cd785112284de5d9faaa6
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -12,10 +12,20 @@ interface StockLocation {
country_iso: string | null;
country_name: string | null;
state_text: string | null;
+ admin_name: string | null;
+ address2: string | null;
+ state_name: string | null;
+ phone: string | null;
+ company: string | null;
active: boolean;
default: boolean;
backorderable_default: boolean;
propagate_all_variants: boolean;
+ kind: string;
+ pickup_enabled: boolean;
+ pickup_stock_policy: string;
+ pickup_ready_in_minutes: number | null;
+ pickup_instructions: string | null;
created_at: string;
updated_at: string;
}
diff --git a/packages/admin/src/hooks/use-stock-locations.ts b/packages/admin/src/hooks/use-stock-locations.ts
new file mode 100644
index 0000000000..3223336145
--- /dev/null
+++ b/packages/admin/src/hooks/use-stock-locations.ts
@@ -0,0 +1,70 @@
+import type {
+ StockLocation,
+ StockLocationCreateParams,
+ StockLocationUpdateParams,
+} from '@spree/admin-sdk'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { adminClient } from '@/client'
+import { useResourceMutation } from '@/hooks/use-resource-mutation'
+
+export const stockLocationsQueryKey = ['stock-locations'] as const
+
+export function stockLocationQueryKey(id: string) {
+ return ['stock-locations', id] as const
+}
+
+interface UseStockLocationsParams {
+ page?: number
+ limit?: number
+}
+
+// API caps `limit` at 100. The page is configurable so callers with more
+// than 100 locations can paginate; the typical merchant has a handful.
+export function useStockLocations({ page = 1, limit = 100 }: UseStockLocationsParams = {}) {
+ return useQuery({
+ queryKey: [...stockLocationsQueryKey, { page, limit }],
+ queryFn: () => adminClient.stockLocations.list({ page, limit }),
+ })
+}
+
+export function useStockLocation(id: string | undefined) {
+ return useQuery({
+ queryKey: id ? stockLocationQueryKey(id) : ['stock-locations', 'noop'],
+ queryFn: () => adminClient.stockLocations.get(id as string),
+ enabled: !!id,
+ })
+}
+
+export function useCreateStockLocation() {
+ return useResourceMutation<StockLocation, Error, StockLocationCreateParams>({
+ mutationFn: (params) => adminClient.stockLocations.create(params),
+ invalidate: [stockLocationsQueryKey],
+ successMessage: 'Stock location created',
+ errorMessage: 'Failed to create stock location',
+ })
+}
+
+export function useUpdateStockLocation(id: string) {
+ return useResourceMutation<StockLocation, Error, StockLocationUpdateParams>({
+ mutationFn: (params) => adminClient.stockLocations.update(id, params),
+ invalidate: [stockLocationsQueryKey, stockLocationQueryKey(id)],
+ successMessage: 'Stock location updated',
+ errorMessage: 'Failed to update stock location',
+ })
+}
+
+export function useDeleteStockLocation() {
+ const queryClient = useQueryClient()
+
+ return useResourceMutation<void, Error, string>({
+ mutationFn: (id) => adminClient.stockLocations.delete(id),
+ invalidate: [stockLocationsQueryKey],
+ successMessage: 'Stock location deleted',
+ errorMessage: 'Failed to delete stock location',
+ onSuccess: (_data, id) => {
+ // Drop the individual-resource cache so any open detail view stops
+ // showing stale data after the row is gone.
+ queryClient.removeQueries({ queryKey: stockLocationQueryKey(id) })
+ },
+ })
+}
diff --git a/packages/admin/src/routeTree.gen.ts b/packages/admin/src/routeTree.gen.ts
index 593e6e7672..81ed88691c 100644
--- a/packages/admin/src/routeTree.gen.ts
+++ b/packages/admin/src/routeTree.gen.ts
@@ -23,6 +23,7 @@ import { Route as AuthenticatedStoreIdCustomersIndexRouteImport } from './routes
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 AuthenticatedStoreIdProductsStockRouteImport } from './routes/_authenticated/$storeId/products/stock'
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'
@@ -108,6 +109,12 @@ const AuthenticatedStoreIdSettingsApiKeysRoute =
path: '/api-keys',
getParentRoute: () => AuthenticatedStoreIdSettingsRoute,
} as any)
+const AuthenticatedStoreIdProductsStockRoute =
+ AuthenticatedStoreIdProductsStockRouteImport.update({
+ id: '/products/stock',
+ path: '/products/stock',
+ getParentRoute: () => AuthenticatedStoreIdRoute,
+ } as any)
const AuthenticatedStoreIdProductsProductIdRoute =
AuthenticatedStoreIdProductsProductIdRouteImport.update({
id: '/products/$productId',
@@ -151,6 +158,7 @@ export interface FileRoutesByFullPath {
'/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/$storeId/products/stock': typeof AuthenticatedStoreIdProductsStockRoute
'/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
'/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
'/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
@@ -169,6 +177,7 @@ export interface FileRoutesByTo {
'/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/$storeId/products/stock': typeof AuthenticatedStoreIdProductsStockRoute
'/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
'/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
'/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
@@ -191,6 +200,7 @@ export interface FileRoutesById {
'/_authenticated/$storeId/orders/drafts': typeof AuthenticatedStoreIdOrdersDraftsRoute
'/_authenticated/$storeId/orders/new': typeof AuthenticatedStoreIdOrdersNewRoute
'/_authenticated/$storeId/products/$productId': typeof AuthenticatedStoreIdProductsProductIdRoute
+ '/_authenticated/$storeId/products/stock': typeof AuthenticatedStoreIdProductsStockRoute
'/_authenticated/$storeId/settings/api-keys': typeof AuthenticatedStoreIdSettingsApiKeysRoute
'/_authenticated/$storeId/settings/staff': typeof AuthenticatedStoreIdSettingsStaffRoute
'/_authenticated/$storeId/settings/store': typeof AuthenticatedStoreIdSettingsStoreRoute
@@ -213,6 +223,7 @@ export interface FileRouteTypes {
| '/$storeId/orders/drafts'
| '/$storeId/orders/new'
| '/$storeId/products/$productId'
+ | '/$storeId/products/stock'
| '/$storeId/settings/api-keys'
| '/$storeId/settings/staff'
| '/$storeId/settings/store'
@@ -231,6 +242,7 @@ export interface FileRouteTypes {
| '/$storeId/orders/drafts'
| '/$storeId/orders/new'
| '/$storeId/products/$productId'
+ | '/$storeId/products/stock'
| '/$storeId/settings/api-keys'
| '/$storeId/settings/staff'
| '/$storeId/settings/store'
@@ -252,6 +264,7 @@ export interface FileRouteTypes {
| '/_authenticated/$storeId/orders/drafts'
| '/_authenticated/$storeId/orders/new'
| '/_authenticated/$storeId/products/$productId'
+ | '/_authenticated/$storeId/products/stock'
| '/_authenticated/$storeId/settings/api-keys'
| '/_authenticated/$storeId/settings/staff'
| '/_authenticated/$storeId/settings/store'
@@ -367,6 +380,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof AuthenticatedStoreIdSettingsApiKeysRouteImport
parentRoute: typeof AuthenticatedStoreIdSettingsRoute
}
+ '/_authenticated/$storeId/products/stock': {
+ id: '/_authenticated/$storeId/products/stock'
+ path: '/products/stock'
+ fullPath: '/$storeId/products/stock'
+ preLoaderRoute: typeof AuthenticatedStoreIdProductsStockRouteImport
+ parentRoute: typeof AuthenticatedStoreIdRoute
+ }
'/_authenticated/$storeId/products/$productId': {
id: '/_authenticated/$storeId/products/$productId'
path: '/products/$productId'
@@ -437,6 +457,7 @@ interface AuthenticatedStoreIdRouteChildren {
AuthenticatedStoreIdOrdersDraftsRoute: typeof AuthenticatedStoreIdOrdersDraftsRoute
AuthenticatedStoreIdOrdersNewRoute: typeof AuthenticatedStoreIdOrdersNewRoute
AuthenticatedStoreIdProductsProductIdRoute: typeof AuthenticatedStoreIdProductsProductIdRoute
+ AuthenticatedStoreIdProductsStockRoute: typeof AuthenticatedStoreIdProductsStockRoute
AuthenticatedStoreIdCustomersIndexRoute: typeof AuthenticatedStoreIdCustomersIndexRoute
AuthenticatedStoreIdOrdersIndexRoute: typeof AuthenticatedStoreIdOrdersIndexRoute
AuthenticatedStoreIdProductsIndexRoute: typeof AuthenticatedStoreIdProductsIndexRoute
@@ -454,6 +475,8 @@ const AuthenticatedStoreIdRouteChildren: AuthenticatedStoreIdRouteChildren = {
AuthenticatedStoreIdOrdersNewRoute: AuthenticatedStoreIdOrdersNewRoute,
AuthenticatedStoreIdProductsProductIdRoute:
AuthenticatedStoreIdProductsProductIdRoute,
+ AuthenticatedStoreIdProductsStockRoute:
+ AuthenticatedStoreIdProductsStockRoute,
AuthenticatedStoreIdCustomersIndexRoute:
AuthenticatedStoreIdCustomersIndexRoute,
AuthenticatedStoreIdOrdersIndexRoute: AuthenticatedStoreIdOrdersIndexRoute,
diff --git a/packages/admin/src/routes/_authenticated/$storeId/products/stock.tsx b/packages/admin/src/routes/_authenticated/$storeId/products/stock.tsx
new file mode 100644
index 0000000000..8c686d71d6
--- /dev/null
+++ b/packages/admin/src/routes/_authenticated/$storeId/products/stock.tsx
@@ -0,0 +1,695 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type {
+ StockLocation,
+ StockLocationCreateParams,
+ StockLocationUpdateParams,
+} from '@spree/admin-sdk'
+import { createFileRoute, useNavigate } from '@tanstack/react-router'
+import { PlusIcon } from 'lucide-react'
+import { useEffect } from 'react'
+import { Controller, useForm } from 'react-hook-form'
+import { z } from 'zod/v4'
+import { adminClient } from '@/client'
+import { Can } from '@/components/spree/can'
+import { useConfirm } from '@/components/spree/confirm-dialog'
+import { ResourceTable, resourceSearchSchema } from '@/components/spree/resource-table'
+import { Button } from '@/components/ui/button'
+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 {
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetFooter,
+ SheetHeader,
+ SheetTitle,
+} from '@/components/ui/sheet'
+import { Switch } from '@/components/ui/switch'
+import { Textarea } from '@/components/ui/textarea'
+import { useCountries } from '@/hooks/use-countries'
+import {
+ useCreateStockLocation,
+ useDeleteStockLocation,
+ useStockLocation,
+ useUpdateStockLocation,
+} from '@/hooks/use-stock-locations'
+import { Subject } from '@/lib/permissions'
+import '@/tables/stock-locations'
+
+// Adds `?edit=<id>` and `?new=1` on top of the standard table search schema
+// so we can deep-link to the create / edit sheet.
+const stockSearchSchema = resourceSearchSchema.extend({
+ edit: z.string().optional(),
+ new: z.coerce.boolean().optional(),
+})
+
+export const Route = createFileRoute('/_authenticated/$storeId/products/stock')({
+ validateSearch: stockSearchSchema,
+ component: StockLocationsPage,
+})
+
+const KIND_OPTIONS = [
+ { value: 'warehouse', label: 'Warehouse' },
+ { value: 'store', label: 'Store' },
+ { value: 'fulfillment_center', label: 'Fulfillment center' },
+] as const
+
+const PICKUP_POLICY_OPTIONS = [
+ { value: 'local', label: 'Only items at this location' },
+ { value: 'any', label: 'Allow transfers from other locations' },
+] as const
+
+function StockLocationsPage() {
+ // Cast: Route.useSearch's inferred type unions with the parent layout's
+ // search shape, which doesn't know about our `edit`/`new` keys. The runtime
+ // schema (`stockSearchSchema`) is still the source of truth — this just
+ // gets us past the parent-union narrowing.
+ const search = Route.useSearch() as z.infer<typeof stockSearchSchema>
+ const navigate = useNavigate()
+
+ const editId = search.edit
+ const isCreating = !!search.new
+
+ function closeSheet() {
+ navigate({
+ search: (prev: Record<string, unknown>) => {
+ const { edit: _e, new: _n, ...rest } = prev
+ return rest as never
+ },
+ })
+ }
+
+ function openCreate() {
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, new: true }) as never })
+ }
+
+ function openEdit(id: string) {
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, edit: id }) as never })
+ }
+
+ return (
+ <>
+ <ResourceTable<StockLocation>
+ tableKey="stock-locations"
+ queryKey="stock-locations"
+ queryFn={(params) => adminClient.stockLocations.list(params)}
+ searchParams={search}
+ actions={
+ <Can I="create" a={Subject.StockLocation}>
+ <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>
+ <PlusIcon className="size-4" />
+ Add stock location
+ </Button>
+ </Can>
+ }
+ />
+
+ {/* Row "click to edit" — surfaced as a delegated handler on the table
+ container so we don't need ResourceTable to understand row callbacks.
+ Each row renders the resource id as a data attribute via the Name
+ column below. */}
+ <RowClickBridge onEdit={openEdit} />
+
+ {isCreating && <CreateStockLocationSheet open onOpenChange={(o) => !o && closeSheet()} />}
+ {editId && (
+ <EditStockLocationSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />
+ )}
+ </>
+ )
+}
+
+// ResourceTable doesn't expose a per-row click handler, so we delegate clicks
+// from cells that mark themselves with `data-stock-location-id`. Keeps the
+// table generic — only this page knows what a click means.
+function RowClickBridge({ onEdit }: { onEdit: (id: string) => void }) {
+ useEffect(() => {
+ function handler(e: MouseEvent) {
+ const target = e.target as HTMLElement | null
+ const cell = target?.closest('[data-stock-location-id]') as HTMLElement | null
+ if (!cell) return
+ const id = cell.dataset.stockLocationId
+ if (!id) return
+ e.preventDefault()
+ onEdit(id)
+ }
+ document.addEventListener('click', handler)
+ return () => document.removeEventListener('click', handler)
+ }, [onEdit])
+ return null
+}
+
+// ============================================================================
+// Form
+// ============================================================================
+
+const formSchema = z.object({
+ name: z.string().min(1, 'Name is required'),
+ admin_name: z.string().optional(),
+ kind: z.string().min(1),
+ active: z.boolean(),
+ default: z.boolean(),
+ propagate_all_variants: z.boolean(),
+ backorderable_default: z.boolean(),
+ address1: z.string().optional(),
+ address2: z.string().optional(),
+ city: z.string().optional(),
+ zipcode: z.string().optional(),
+ phone: z.string().optional(),
+ company: z.string().optional(),
+ country_iso: z.string().optional(),
+ state_abbr: z.string().optional(),
+ state_name: z.string().optional(),
+ pickup_enabled: z.boolean(),
+ pickup_stock_policy: z.enum(['local', 'any']),
+ pickup_ready_in_minutes: z.coerce.number().int().min(0).optional().nullable(),
+ pickup_instructions: z.string().optional(),
+})
+
+type FormValues = z.infer<typeof formSchema>
+
+const DEFAULT_VALUES: FormValues = {
+ name: '',
+ admin_name: '',
+ kind: 'warehouse',
+ active: true,
+ default: false,
+ propagate_all_variants: false,
+ backorderable_default: false,
+ address1: '',
+ address2: '',
+ city: '',
+ zipcode: '',
+ phone: '',
+ company: '',
+ country_iso: '',
+ state_abbr: '',
+ state_name: '',
+ pickup_enabled: false,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: null,
+ pickup_instructions: '',
+}
+
+function stockLocationToFormValues(sl: StockLocation): FormValues {
+ return {
+ name: sl.name,
+ admin_name: sl.admin_name ?? '',
+ kind: sl.kind ?? 'warehouse',
+ active: sl.active,
+ default: sl.default,
+ propagate_all_variants: sl.propagate_all_variants,
+ backorderable_default: sl.backorderable_default,
+ address1: sl.address1 ?? '',
+ address2: sl.address2 ?? '',
+ city: sl.city ?? '',
+ zipcode: sl.zipcode ?? '',
+ phone: sl.phone ?? '',
+ company: sl.company ?? '',
+ country_iso: sl.country_iso ?? '',
+ state_abbr: sl.state_abbr ?? '',
+ state_name: sl.state_name ?? '',
+ pickup_enabled: sl.pickup_enabled,
+ pickup_stock_policy: (sl.pickup_stock_policy as 'local' | 'any') ?? 'local',
+ pickup_ready_in_minutes: sl.pickup_ready_in_minutes ?? null,
+ pickup_instructions: sl.pickup_instructions ?? '',
+ }
+}
+
+// Drops blank strings → undefined so we don't overwrite null fields with "".
+function formValuesToParams(v: FormValues): StockLocationCreateParams & StockLocationUpdateParams {
+ const blank = (s: string | null | undefined) => (s && s.length > 0 ? s : undefined)
+ return {
+ name: v.name,
+ admin_name: blank(v.admin_name),
+ kind: v.kind,
+ active: v.active,
+ default: v.default,
+ propagate_all_variants: v.propagate_all_variants,
+ backorderable_default: v.backorderable_default,
+ address1: blank(v.address1),
+ address2: blank(v.address2),
+ city: blank(v.city),
+ zipcode: blank(v.zipcode),
+ phone: blank(v.phone),
+ company: blank(v.company),
+ country_iso: blank(v.country_iso),
+ state_abbr: blank(v.state_abbr),
+ state_name: blank(v.state_name),
+ pickup_enabled: v.pickup_enabled,
+ pickup_stock_policy: v.pickup_stock_policy,
+ pickup_ready_in_minutes: v.pickup_ready_in_minutes ?? null,
+ pickup_instructions: blank(v.pickup_instructions),
+ }
+}
+
+// ============================================================================
+// Create Sheet
+// ============================================================================
+
+function CreateStockLocationSheet({
+ open,
+ onOpenChange,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const createMutation = useCreateStockLocation()
+
+ const form = useForm<FormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(formSchema) as any,
+ defaultValues: DEFAULT_VALUES,
+ })
+
+ async function onSubmit(values: FormValues) {
+ const params = formValuesToParams(values) as StockLocationCreateParams
+ await createMutation.mutateAsync(params)
+ form.reset(DEFAULT_VALUES)
+ onOpenChange(false)
+ }
+
+ return (
+ <Sheet
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) form.reset(DEFAULT_VALUES)
+ onOpenChange(next)
+ }}
+ >
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>Add stock location</SheetTitle>
+ <SheetDescription>
+ A place where inventory lives — a warehouse, store, or third-party fulfillment center.
+ </SheetDescription>
+ </SheetHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <StockLocationFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ Cancel
+ </Button>
+ <Button type="submit" size="sm" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting ? 'Creating…' : 'Create stock location'}
+ </Button>
+ </SheetFooter>
+ </form>
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+// ============================================================================
+// Edit Sheet
+// ============================================================================
+
+function EditStockLocationSheet({
+ id,
+ open,
+ onOpenChange,
+}: {
+ id: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { data: stockLocation, isLoading } = useStockLocation(id)
+ const updateMutation = useUpdateStockLocation(id)
+ const deleteMutation = useDeleteStockLocation()
+ const confirm = useConfirm()
+
+ const form = useForm<FormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(formSchema) as any,
+ defaultValues: DEFAULT_VALUES,
+ })
+
+ // Reset form when the loaded resource arrives — keeps the inputs in sync
+ // with whatever the server last persisted (including external edits).
+ useEffect(() => {
+ if (stockLocation) {
+ form.reset(stockLocationToFormValues(stockLocation))
+ }
+ }, [stockLocation, form])
+
+ async function onSubmit(values: FormValues) {
+ const params = formValuesToParams(values) as StockLocationUpdateParams
+ await updateMutation.mutateAsync(params)
+ form.reset(values)
+ onOpenChange(false)
+ }
+
+ async function onDelete() {
+ const ok = await confirm({
+ title: 'Delete stock location?',
+ message: `${stockLocation?.name ?? 'This location'} will be removed. Any orders that referenced it will keep the historical record.`,
+ variant: 'destructive',
+ confirmLabel: 'Delete',
+ })
+ if (!ok) return
+ await deleteMutation.mutateAsync(id)
+ onOpenChange(false)
+ }
+
+ return (
+ <Sheet open={open} onOpenChange={onOpenChange}>
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>{stockLocation?.name ?? 'Edit stock location'}</SheetTitle>
+ <SheetDescription>
+ Update inventory location, address, and pickup options.
+ </SheetDescription>
+ </SheetHeader>
+ {isLoading ? (
+ <div className="p-4 text-sm text-muted-foreground">Loading…</div>
+ ) : (
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <StockLocationFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Can I="destroy" a={Subject.StockLocation}>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ onClick={onDelete}
+ disabled={form.formState.isSubmitting || deleteMutation.isPending}
+ className="mr-auto text-destructive hover:bg-destructive/10 hover:text-destructive"
+ >
+ Delete
+ </Button>
+ </Can>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ Cancel
+ </Button>
+ <Button
+ type="submit"
+ size="sm"
+ disabled={form.formState.isSubmitting || !form.formState.isDirty}
+ >
+ {form.formState.isSubmitting ? 'Saving…' : 'Save'}
+ </Button>
+ </SheetFooter>
+ </form>
+ )}
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+// ============================================================================
+// Shared form fields
+// ============================================================================
+
+function StockLocationFormFields({
+ form,
+}: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ form: any
+}) {
+ const { countries, isLoading: countriesLoading } = useCountries()
+
+ const countryIso = form.watch('country_iso')
+ const selectedCountry = countries.find((c) => c.iso === countryIso)
+ const states = selectedCountry?.states ?? []
+
+ const pickupEnabled = form.watch('pickup_enabled')
+
+ return (
+ <FieldGroup>
+ <Field>
+ <FieldLabel htmlFor="name">Name</FieldLabel>
+ <Input
+ id="name"
+ autoFocus
+ placeholder="Brooklyn warehouse"
+ {...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>
+
+ <Field>
+ <FieldLabel htmlFor="admin_name">Internal name</FieldLabel>
+ <Input
+ id="admin_name"
+ placeholder="Optional — shown only in the admin"
+ {...form.register('admin_name')}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel>Kind</FieldLabel>
+ <Controller
+ name="kind"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {KIND_OPTIONS.map((opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+
+ <ToggleField
+ form={form}
+ name="active"
+ label="Active"
+ description="Inactive locations don't appear in fulfillment selection."
+ />
+ <ToggleField
+ form={form}
+ name="default"
+ label="Default location"
+ description="New stock items propagate here. Only one location can be default."
+ />
+ <ToggleField
+ form={form}
+ name="backorderable_default"
+ label="Backorderable by default"
+ description="New stock items at this location allow backorders."
+ />
+ <ToggleField
+ form={form}
+ name="propagate_all_variants"
+ label="Auto-create stock items for all variants"
+ description="When a new variant is added anywhere, create a zero-quantity stock item here."
+ />
+
+ <div className="border-t border-border pt-4">
+ <h3 className="mb-3 text-sm font-medium">Address</h3>
+ <FieldGroup>
+ <Field>
+ <FieldLabel htmlFor="address1">Address line 1</FieldLabel>
+ <Input id="address1" {...form.register('address1')} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="address2">Address line 2</FieldLabel>
+ <Input id="address2" {...form.register('address2')} />
+ </Field>
+ <div className="grid grid-cols-2 gap-3">
+ <Field>
+ <FieldLabel htmlFor="city">City</FieldLabel>
+ <Input id="city" {...form.register('city')} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="zipcode">Postal code</FieldLabel>
+ <Input id="zipcode" {...form.register('zipcode')} />
+ </Field>
+ </div>
+ <Field>
+ <FieldLabel>Country</FieldLabel>
+ <Controller
+ name="country_iso"
+ control={form.control}
+ render={({ field }) => (
+ <Select
+ value={field.value || ''}
+ onValueChange={(v) => {
+ field.onChange(v)
+ // Clear both shapes so a previously-typed free-text state
+ // doesn't bleed across countries.
+ form.setValue('state_abbr', '', { shouldDirty: true })
+ form.setValue('state_name', '', { shouldDirty: true })
+ }}
+ disabled={countriesLoading}
+ >
+ <SelectTrigger>
+ <SelectValue placeholder="Select a country" />
+ </SelectTrigger>
+ <SelectContent className="max-h-80">
+ {countries.map((c) => (
+ <SelectItem key={c.iso} value={c.iso}>
+ {c.name}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+ {states.length > 0 ? (
+ <Field>
+ <FieldLabel>State / Province</FieldLabel>
+ <Controller
+ name="state_abbr"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value || ''} onValueChange={field.onChange}>
+ <SelectTrigger>
+ <SelectValue placeholder="Select a state" />
+ </SelectTrigger>
+ <SelectContent className="max-h-80">
+ {states.map((s) => (
+ <SelectItem key={s.abbr ?? s.name} value={s.abbr ?? ''}>
+ {s.name}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+ ) : (
+ <Field>
+ <FieldLabel htmlFor="state_name">State / Province</FieldLabel>
+ <Input id="state_name" {...form.register('state_name')} />
+ </Field>
+ )}
+ <Field>
+ <FieldLabel htmlFor="phone">Phone</FieldLabel>
+ <Input id="phone" {...form.register('phone')} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="company">Company</FieldLabel>
+ <Input id="company" {...form.register('company')} />
+ </Field>
+ </FieldGroup>
+ </div>
+
+ <div className="border-t border-border pt-4">
+ <h3 className="mb-3 text-sm font-medium">Pickup</h3>
+ <FieldGroup>
+ <ToggleField
+ form={form}
+ name="pickup_enabled"
+ label="Allow customer pickup"
+ description="Show this location to customers as a pickup option at checkout."
+ />
+ {pickupEnabled && (
+ <>
+ <Field>
+ <FieldLabel>Stock policy</FieldLabel>
+ <Controller
+ name="pickup_stock_policy"
+ control={form.control}
+ render={({ field }) => (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {PICKUP_POLICY_OPTIONS.map((opt) => (
+ <SelectItem key={opt.value} value={opt.value}>
+ {opt.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="pickup_ready_in_minutes">Ready in (minutes)</FieldLabel>
+ <Input
+ id="pickup_ready_in_minutes"
+ type="number"
+ min={0}
+ step={5}
+ placeholder="60"
+ {...form.register('pickup_ready_in_minutes', {
+ setValueAs: (v: unknown) => (v === '' || v == null ? null : Number(v)),
+ })}
+ />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="pickup_instructions">Pickup instructions</FieldLabel>
+ <Textarea
+ id="pickup_instructions"
+ placeholder="Where the customer should go to collect their order."
+ rows={3}
+ {...form.register('pickup_instructions')}
+ />
+ </Field>
+ </>
+ )}
+ </FieldGroup>
+ </div>
+ </FieldGroup>
+ )
+}
+
+function ToggleField({
+ form,
+ name,
+ label,
+ description,
+}: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ form: any
+ name: keyof FormValues
+ label: string
+ description?: string
+}) {
+ return (
+ <Field>
+ <div className="flex items-start justify-between gap-4">
+ <div className="flex flex-col">
+ <FieldLabel htmlFor={String(name)} className="cursor-pointer">
+ {label}
+ </FieldLabel>
+ {description && <span className="text-xs text-muted-foreground">{description}</span>}
+ </div>
+ <Controller
+ name={name as string}
+ control={form.control}
+ render={({ field }) => (
+ <Switch id={String(name)} checked={!!field.value} onCheckedChange={field.onChange} />
+ )}
+ />
+ </div>
+ </Field>
+ )
+}
diff --git a/packages/admin/src/tables/stock-locations.tsx b/packages/admin/src/tables/stock-locations.tsx
new file mode 100644
index 0000000000..30896e69e9
--- /dev/null
+++ b/packages/admin/src/tables/stock-locations.tsx
@@ -0,0 +1,92 @@
+import type { StockLocation } from '@spree/admin-sdk'
+import { WarehouseIcon } from 'lucide-react'
+import { Badge } from '@/components/ui/badge'
+import { defineTable } from '@/lib/table-registry'
+
+defineTable<StockLocation>('stock-locations', {
+ title: 'Stock Locations',
+ searchParam: 'name_cont',
+ searchPlaceholder: 'Search by name…',
+ defaultSort: { field: 'name', direction: 'asc' },
+ emptyIcon: <WarehouseIcon className="size-8 text-muted-foreground/50" />,
+ emptyMessage: 'No stock locations yet',
+ columns: [
+ {
+ key: 'name',
+ label: 'Name',
+ sortable: true,
+ filterable: true,
+ default: true,
+ // The button carries `data-stock-location-id`. The route page mounts a
+ // delegated click listener (RowClickBridge) that opens the edit Sheet
+ // when any descendant marked with that attribute is clicked.
+ render: (sl) => (
+ <button
+ type="button"
+ data-stock-location-id={sl.id}
+ className="flex flex-col items-start text-left hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded"
+ >
+ <span className="font-medium">{sl.name}</span>
+ {sl.admin_name && (
+ <span data-stock-location-id={sl.id} className="text-xs text-muted-foreground">
+ {sl.admin_name}
+ </span>
+ )}
+ </button>
+ ),
+ },
+ {
+ key: 'kind',
+ label: 'Type',
+ sortable: true,
+ filterable: true,
+ default: true,
+ filterType: 'status',
+ filterOptions: [
+ { value: 'warehouse', label: 'Warehouse' },
+ { value: 'store', label: 'Store' },
+ { value: 'fulfillment_center', label: 'Fulfillment center' },
+ ],
+ render: (sl) => <span className="capitalize">{sl.kind.replace('_', ' ')}</span>,
+ },
+ {
+ key: 'city',
+ label: 'Location',
+ default: true,
+ render: (sl) => {
+ const parts = [sl.city, sl.state_text || sl.state_abbr, sl.country_iso]
+ .filter(Boolean)
+ .join(', ')
+ return parts || '—'
+ },
+ },
+ {
+ key: 'pickup_enabled',
+ label: 'Pickup',
+ sortable: true,
+ filterable: true,
+ default: true,
+ filterType: 'boolean',
+ render: (sl) =>
+ sl.pickup_enabled ? <Badge variant="secondary">Enabled</Badge> : <span>—</span>,
+ },
+ {
+ key: 'active',
+ label: 'Active',
+ sortable: true,
+ filterable: true,
+ default: true,
+ filterType: 'boolean',
+ render: (sl) =>
+ sl.active ? <Badge variant="secondary">Active</Badge> : <Badge>Inactive</Badge>,
+ },
+ {
+ key: 'default',
+ label: 'Default',
+ default: true,
+ filterable: true,
+ filterType: 'boolean',
+ render: (sl) => (sl.default ? <Badge>Default</Badge> : '—'),
+ },
+ ],
+})
diff --git a/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb
new file mode 100644
index 0000000000..2d4f02be94
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb
@@ -0,0 +1,36 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ class StockLocationsController < ResourceController
+ scoped_resource :settings
+
+ protected
+
+ def model_class
+ Spree::StockLocation
+ end
+
+ def serializer_class
+ Spree.api.admin_stock_location_serializer
+ end
+
+ def scope
+ super.order_default
+ end
+
+ def permitted_params
+ params.permit(
+ :name, :admin_name, :active, :default,
+ :kind, :propagate_all_variants, :backorderable_default,
+ :address1, :address2, :city, :zipcode, :phone, :company,
+ :country_iso, :state_abbr, :state_name,
+ :pickup_enabled, :pickup_stock_policy,
+ :pickup_ready_in_minutes, :pickup_instructions
+ )
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/stock_location_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/stock_location_serializer.rb
index 3f22522d45..fd395b3b14 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/stock_location_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/stock_location_serializer.rb
@@ -4,9 +4,18 @@ module Spree
module Admin
class StockLocationSerializer < V3::StockLocationSerializer
typelize active: :boolean, default: :boolean, backorderable_default: :boolean,
- propagate_all_variants: :boolean
+ propagate_all_variants: :boolean, pickup_enabled: :boolean,
+ admin_name: [:string, nullable: true],
+ address2: [:string, nullable: true], state_name: [:string, nullable: true],
+ phone: [:string, nullable: true], company: [:string, nullable: true],
+ kind: :string, pickup_stock_policy: :string,
+ pickup_ready_in_minutes: [:number, nullable: true],
+ pickup_instructions: [:string, nullable: true]
- attributes :active, :default, :backorderable_default, :propagate_all_variants,
+ attributes :admin_name, :address2, :state_name, :phone, :company,
+ :active, :default, :backorderable_default, :propagate_all_variants,
+ :kind, :pickup_enabled, :pickup_stock_policy,
+ :pickup_ready_in_minutes, :pickup_instructions,
created_at: :iso8601, updated_at: :iso8601
end
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 5ed57599c5..1d81a3485f 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -166,6 +166,9 @@ Spree::Core::Engine.add_routes do
# Tax Categories
resources :tax_categories, only: [:index, :show]
+ # Stock Locations
+ resources :stock_locations
+
# Payment Methods
resources :payment_methods, only: [:index, :show]
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/stock_locations_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/stock_locations_controller_spec.rb
new file mode 100644
index 0000000000..6bf929ddcd
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/stock_locations_controller_spec.rb
@@ -0,0 +1,192 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::StockLocationsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:stock_location) { create(:stock_location, name: 'Warehouse A') }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ let!(:other_location) { create(:stock_location, name: 'Warehouse B', active: false) }
+
+ it 'returns all stock locations ordered by default desc, name asc' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+
+ ids = json_response['data'].map { |sl| sl['id'] }
+ expect(ids).to include(stock_location.prefixed_id, other_location.prefixed_id)
+ end
+
+ it 'includes the new pickup attributes' do
+ get :index, as: :json
+
+ sl = json_response['data'].find { |s| s['id'] == stock_location.prefixed_id }
+ expect(sl).to include(
+ 'kind' => 'warehouse',
+ 'pickup_enabled' => false,
+ 'pickup_stock_policy' => 'local',
+ 'pickup_ready_in_minutes' => nil,
+ 'pickup_instructions' => nil
+ )
+ end
+
+ context 'with ransack filters' do
+ it 'filters by active' do
+ get :index, params: { q: { active_eq: true } }, as: :json
+
+ ids = json_response['data'].map { |sl| sl['id'] }
+ expect(ids).to include(stock_location.prefixed_id)
+ expect(ids).not_to include(other_location.prefixed_id)
+ end
+
+ it 'filters by kind' do
+ stock_location.update!(kind: 'store')
+ get :index, params: { q: { kind_eq: 'store' } }, as: :json
+
+ ids = json_response['data'].map { |sl| sl['id'] }
+ expect(ids).to eq([stock_location.prefixed_id])
+ end
+ end
+ end
+
+ describe 'GET #show' do
+ it 'returns the stock location' do
+ get :show, params: { id: stock_location.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(stock_location.prefixed_id)
+ expect(json_response['name']).to eq(stock_location.name)
+ expect(json_response).to have_key('kind')
+ expect(json_response).to have_key('pickup_enabled')
+ end
+
+ it 'returns 404 for unknown id' do
+ get :show, params: { id: 'sloc_doesnotexist' }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'POST #create' do
+ let(:country) { Spree::Country.first || create(:country) }
+
+ let(:valid_params) do
+ {
+ name: 'New York Store',
+ admin_name: 'NYC',
+ address1: '350 5th Ave',
+ city: 'New York',
+ zipcode: '10118',
+ country_iso: country.iso,
+ kind: 'store',
+ pickup_enabled: true,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: 60,
+ pickup_instructions: 'Pick up at the front desk.'
+ }
+ end
+
+ it 'creates a stock location' do
+ expect {
+ post :create, params: valid_params, as: :json
+ }.to change(Spree::StockLocation, :count).by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response).to include(
+ 'name' => 'New York Store',
+ 'kind' => 'store',
+ 'pickup_enabled' => true,
+ 'pickup_ready_in_minutes' => 60,
+ 'pickup_instructions' => 'Pick up at the front desk.'
+ )
+ end
+
+ it 'resolves country_iso and state_abbr to the right associations' do
+ state = country.states.find_by(abbr: 'NY') ||
+ create(:state, country: country, abbr: 'NY', name: 'New York')
+
+ post :create, params: valid_params.merge(state_abbr: state.abbr), as: :json
+
+ expect(response).to have_http_status(:created)
+ created = Spree::StockLocation.find_by_prefix_id!(json_response['id'])
+ expect(created.country_id).to eq(country.id)
+ expect(created.state_id).to eq(state.id)
+ end
+
+ context 'with invalid params' do
+ it 'returns validation errors when name is missing' do
+ post :create, params: valid_params.merge(name: ''), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['code']).to eq('validation_error')
+ end
+
+ it 'rejects unknown pickup_stock_policy' do
+ post :create, params: valid_params.merge(pickup_stock_policy: 'bogus'), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['details']).to have_key('pickup_stock_policy')
+ end
+ end
+ end
+
+ describe 'PATCH #update' do
+ it 'updates basic attributes' do
+ patch :update, params: {
+ id: stock_location.prefixed_id,
+ name: 'Renamed Warehouse',
+ pickup_enabled: true,
+ pickup_ready_in_minutes: 30
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['name']).to eq('Renamed Warehouse')
+ expect(json_response['pickup_enabled']).to be true
+ expect(json_response['pickup_ready_in_minutes']).to eq(30)
+
+ stock_location.reload
+ expect(stock_location.name).to eq('Renamed Warehouse')
+ expect(stock_location.pickup_enabled).to be true
+ end
+
+ it 'promotes a non-default location to default and demotes the previous default' do
+ previous_default = create(:stock_location, name: 'Old default', default: true)
+ expect(previous_default.reload.default).to be true
+
+ patch :update, params: {
+ id: stock_location.prefixed_id,
+ default: true
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(stock_location.reload.default).to be true
+ expect(previous_default.reload.default).to be false
+ end
+
+ it 'returns validation errors for invalid pickup_stock_policy' do
+ patch :update, params: {
+ id: stock_location.prefixed_id,
+ pickup_stock_policy: 'invalid'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['code']).to eq('validation_error')
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'soft-deletes the stock location' do
+ expect {
+ delete :destroy, params: { id: stock_location.prefixed_id }, as: :json
+ }.to change { Spree::StockLocation.where(id: stock_location.id).count }.from(1).to(0)
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::StockLocation.with_deleted.find(stock_location.id).deleted_at).not_to be_nil
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb
new file mode 100644
index 0000000000..c9f168570c
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb
@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:stock_location) { create(:stock_location, name: 'Brooklyn warehouse') }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/stock_locations' do
+ get 'List stock locations' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Returns the configured stock locations. Stock locations are global
+ (shared across stores). Filter with Ransack predicates such as
+ `q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or
+ `q[name_cont]`.
+
+ Pickup-related attributes (`kind`, `pickup_enabled`,
+ `pickup_stock_policy`, `pickup_ready_in_minutes`,
+ `pickup_instructions`) drive merchant pickup support at checkout —
+ customers can collect orders from any active location with
+ `pickup_enabled: true`.
+ DESC
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const { data: stockLocations } = await client.stockLocations.list()
+ 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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ parameter name: :'q[name_cont]', in: :query, type: :string, required: false,
+ description: 'Filter by name (contains)'
+ parameter name: :'q[active_eq]', in: :query, type: :boolean, required: false,
+ description: 'Filter by active status'
+ parameter name: :'q[kind_eq]', in: :query, type: :string, required: false,
+ description: "Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')"
+ parameter name: :'q[pickup_enabled_eq]', in: :query, type: :boolean, required: false,
+ description: 'Filter by pickup-enabled flag'
+ parameter name: :sort, in: :query, type: :string, required: false,
+ description: 'Sort by field. Prefix with `-` for descending (e.g., `-created_at`).'
+ parameter name: :fields, in: :query, type: :string, required: false,
+ description: 'Comma-separated list of fields to include. id is always included.'
+
+ response '200', 'stock locations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('StockLocation')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].map { |sl| sl['id'] }).to include(stock_location.prefixed_id)
+ 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
+
+ post 'Create a stock location' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Creates a new stock location.
+
+ Setting `default: true` automatically demotes the previous default
+ location.
+ DESC
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const stockLocation = await client.stockLocations.create({
+ name: 'Brooklyn warehouse',
+ kind: 'warehouse',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ city: 'Brooklyn',
+ zipcode: '11201',
+ pickup_enabled: true,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: 60,
+ })
+ 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: 'Brooklyn warehouse' },
+ admin_name: { type: :string, nullable: true, description: 'Internal name shown only in the admin' },
+ active: { type: :boolean, example: true },
+ default: { type: :boolean, description: 'Setting to true demotes the previous default.' },
+ kind: {
+ type: :string,
+ enum: Spree::StockLocation::KINDS,
+ description: 'Categorizes the location.',
+ example: 'warehouse'
+ },
+ propagate_all_variants: { type: :boolean },
+ backorderable_default: { type: :boolean },
+ address1: { type: :string, nullable: true },
+ address2: { type: :string, nullable: true },
+ city: { type: :string, nullable: true },
+ zipcode: { type: :string, nullable: true },
+ phone: { type: :string, nullable: true },
+ company: { type: :string, nullable: true },
+ country_iso: { type: :string, nullable: true, description: 'ISO-3166 alpha-2 country code (e.g. "US").' },
+ state_abbr: { type: :string, nullable: true, description: 'State / province abbreviation (e.g. "NY"). Resolved against the selected country.' },
+ state_name: { type: :string, nullable: true, description: 'Free-text state for countries without a states list.' },
+ pickup_enabled: { type: :boolean },
+ pickup_stock_policy: {
+ type: :string,
+ enum: Spree::StockLocation::PICKUP_STOCK_POLICIES,
+ description: "'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."
+ },
+ pickup_ready_in_minutes: { type: :number, nullable: true, minimum: 0 },
+ pickup_instructions: { type: :string, nullable: true }
+ },
+ required: %w[name]
+ }
+
+ response '201', 'stock location created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) do
+ {
+ name: 'Manhattan store',
+ kind: 'store',
+ pickup_enabled: true,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: 30
+ }
+ end
+
+ schema '$ref' => '#/components/schemas/StockLocation'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Manhattan store')
+ expect(data['kind']).to eq('store')
+ expect(data['pickup_enabled']).to be true
+ 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
+
+ path '/api/v3/admin/stock_locations/{id}' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Stock location ID'
+
+ get 'Get a stock location' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns a single stock location by prefixed ID.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const stockLocation = await client.stockLocations.get('sloc_UkLWZg9DAJ')
+ 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: :fields, in: :query, type: :string, required: false,
+ description: 'Comma-separated list of fields to include. id is always included.'
+
+ response '200', 'stock location found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { stock_location.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/StockLocation'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(stock_location.prefixed_id)
+ end
+ end
+
+ response '404', 'stock location not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'sloc_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update a stock location' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Updates an existing stock location. Same address-field conventions as
+ the create endpoint.
+
+ Setting `default: true` automatically demotes the previous default.
+ DESC
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const stockLocation = await client.stockLocations.update('sloc_UkLWZg9DAJ', {
+ pickup_enabled: true,
+ pickup_ready_in_minutes: 45,
+ pickup_instructions: 'Enter through the back door, ring the bell.',
+ })
+ 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 },
+ admin_name: { type: :string, nullable: true },
+ active: { type: :boolean },
+ default: { type: :boolean },
+ kind: { type: :string, enum: Spree::StockLocation::KINDS },
+ propagate_all_variants: { type: :boolean },
+ backorderable_default: { type: :boolean },
+ address1: { type: :string, nullable: true },
+ address2: { type: :string, nullable: true },
+ city: { type: :string, nullable: true },
+ zipcode: { type: :string, nullable: true },
+ phone: { type: :string, nullable: true },
+ company: { type: :string, nullable: true },
+ country_iso: { type: :string, nullable: true },
+ state_abbr: { type: :string, nullable: true },
+ state_name: { type: :string, nullable: true },
+ pickup_enabled: { type: :boolean },
+ pickup_stock_policy: { type: :string, enum: Spree::StockLocation::PICKUP_STOCK_POLICIES },
+ pickup_ready_in_minutes: { type: :number, nullable: true, minimum: 0 },
+ pickup_instructions: { type: :string, nullable: true }
+ }
+ }
+
+ response '200', 'stock location updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { stock_location.prefixed_id }
+ let(:body) { { name: 'Renamed warehouse', pickup_enabled: true, pickup_ready_in_minutes: 45 } }
+
+ schema '$ref' => '#/components/schemas/StockLocation'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Renamed warehouse')
+ expect(data['pickup_enabled']).to be true
+ expect(data['pickup_ready_in_minutes']).to eq(45)
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { stock_location.prefixed_id }
+ let(:body) { { pickup_stock_policy: 'invalid' } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ delete 'Delete a stock location' do
+ tags 'Configuration'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Soft-deletes the stock location (sets `deleted_at`). Existing
+ fulfillments that referenced it keep the historical record via
+ `Spree::StockLocation.with_deleted`.
+ DESC
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ await client.stockLocations.delete('sloc_UkLWZg9DAJ')
+ 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 '204', 'stock location deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { stock_location.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/stock_location.rb b/spree/core/app/models/spree/stock_location.rb
index 32855009de..b3b41efc14 100644
--- a/spree/core/app/models/spree/stock_location.rb
+++ b/spree/core/app/models/spree/stock_location.rb
@@ -2,6 +2,15 @@ module Spree
class StockLocation < Spree.base_class
has_prefix_id :sloc # Spree-specific: stock location
+ # Categorizes the location. Open string — extensible by setting any value;
+ # KINDS lists the built-in options used by the admin UI dropdown.
+ KINDS = %w[warehouse store fulfillment_center].freeze
+
+ # Pickup stock policy: 'local' = only items physically at this location are
+ # collectable; 'any' = items can be transferred from other locations
+ # (ship-to-store). See docs/plans/6.0-fulfillment-and-delivery.md.
+ PICKUP_STOCK_POLICIES = %w[local any].freeze
+
include Spree::UniqueName
if defined?(Spree::Security::StockLocations)
include Spree::Security::StockLocations
@@ -20,14 +29,41 @@ module Spree
belongs_to :state, class_name: 'Spree::State', optional: true
belongs_to :country, class_name: 'Spree::Country'
+ validates :kind, presence: true
+ validates :pickup_stock_policy, inclusion: { in: PICKUP_STOCK_POLICIES }
+ validates :pickup_ready_in_minutes,
+ numericality: { only_integer: true, greater_than_or_equal_to: 0 },
+ allow_nil: true
+
+ self.whitelisted_ransackable_attributes = %w[
+ name active default kind pickup_enabled
+ country_id state_id created_at updated_at
+ ]
+
scope :active, -> { where(active: true) }
+ scope :pickup_enabled, -> { where(pickup_enabled: true) }
scope :order_default, -> { order(default: :desc, name: :asc) }
+ before_validation :normalize_country
+ before_validation :normalize_state
+
after_create :create_stock_items, if: :propagate_all_variants?
after_save :ensure_one_default
after_update :conditional_touch_records
delegate :name, :iso3, :iso, :iso_name, to: :country, prefix: true, allow_nil: true
+ delegate :abbr, to: :state, prefix: true, allow_nil: true
+
+ # Writer methods for API convenience — accept ISO/abbr codes instead of FK IDs.
+ # Mirrors Spree::Address: SDK clients use country_iso/state_abbr because
+ # Country/State don't expose prefixed IDs (their `iso` is the public handle).
+ def country_iso=(value)
+ @country_iso_input = value
+ end
+
+ def state_abbr=(value)
+ @state_abbr_input = value
+ end
def state_text
state.try(:abbr) || state.try(:name) || state_name
@@ -168,6 +204,22 @@ module Spree
private
+ def normalize_country
+ iso = @country_iso_input
+ return if iso.blank?
+
+ self.country = Spree::Country.by_iso(iso)
+ @country_iso_input = nil
+ end
+
+ def normalize_state
+ abbr = @state_abbr_input
+ return if abbr.blank? || country.blank?
+
+ self.state = country.states.find_by(abbr: abbr)
+ @state_abbr_input = nil
+ end
+
def create_stock_items
Spree::StockLocations::StockItems::CreateJob.perform_later(self)
end
diff --git a/spree/core/db/migrate/20260508175303_add_pickup_to_spree_stock_locations.rb b/spree/core/db/migrate/20260508175303_add_pickup_to_spree_stock_locations.rb
new file mode 100644
index 0000000000..21404f1bba
--- /dev/null
+++ b/spree/core/db/migrate/20260508175303_add_pickup_to_spree_stock_locations.rb
@@ -0,0 +1,12 @@
+class AddPickupToSpreeStockLocations < ActiveRecord::Migration[7.2]
+ def change
+ add_column :spree_stock_locations, :kind, :string, null: false, default: 'warehouse'
+ add_column :spree_stock_locations, :pickup_enabled, :boolean, null: false, default: false
+ add_column :spree_stock_locations, :pickup_stock_policy, :string, null: false, default: 'local'
+ add_column :spree_stock_locations, :pickup_ready_in_minutes, :integer
+ add_column :spree_stock_locations, :pickup_instructions, :text
+
+ add_index :spree_stock_locations, :pickup_enabled
+ add_index :spree_stock_locations, :kind
+ end
+end
diff --git a/spree/core/spec/models/spree/stock_location_spec.rb b/spree/core/spec/models/spree/stock_location_spec.rb
index 9634e55295..e56dc01b02 100644
--- a/spree/core/spec/models/spree/stock_location_spec.rb
+++ b/spree/core/spec/models/spree/stock_location_spec.rb
@@ -353,5 +353,112 @@ module Spree
it { expect(subject.country_iso3).to be_nil }
it { expect(subject.country_iso_name).to be_nil }
end
+
+ describe 'KINDS / PICKUP_STOCK_POLICIES constants' do
+ it 'lists the built-in kinds' do
+ expect(StockLocation::KINDS).to eq(%w[warehouse store fulfillment_center])
+ end
+
+ it 'lists the pickup stock policies' do
+ expect(StockLocation::PICKUP_STOCK_POLICIES).to eq(%w[local any])
+ end
+ end
+
+ describe 'pickup defaults' do
+ subject { build(:stock_location) }
+
+ it 'defaults kind to warehouse' do
+ expect(subject.kind).to eq('warehouse')
+ end
+
+ it 'defaults pickup_enabled to false' do
+ expect(subject.pickup_enabled).to be false
+ end
+
+ it 'defaults pickup_stock_policy to local' do
+ expect(subject.pickup_stock_policy).to eq('local')
+ end
+ end
+
+ describe 'validations' do
+ it 'requires a kind' do
+ sl = build(:stock_location, kind: nil)
+ expect(sl).not_to be_valid
+ expect(sl.errors[:kind]).to be_present
+ end
+
+ it 'rejects an invalid pickup_stock_policy' do
+ sl = build(:stock_location, pickup_stock_policy: 'bogus')
+ expect(sl).not_to be_valid
+ expect(sl.errors[:pickup_stock_policy]).to be_present
+ end
+
+ it 'accepts a valid pickup_stock_policy' do
+ expect(build(:stock_location, pickup_stock_policy: 'any')).to be_valid
+ end
+
+ it 'rejects a negative pickup_ready_in_minutes' do
+ sl = build(:stock_location, pickup_ready_in_minutes: -1)
+ expect(sl).not_to be_valid
+ expect(sl.errors[:pickup_ready_in_minutes]).to be_present
+ end
+
+ it 'allows nil pickup_ready_in_minutes' do
+ expect(build(:stock_location, pickup_ready_in_minutes: nil)).to be_valid
+ end
+ end
+
+ describe '.pickup_enabled scope' do
+ let!(:enabled) { create(:stock_location, pickup_enabled: true) }
+ let!(:disabled) { create(:stock_location, pickup_enabled: false) }
+
+ it 'returns only locations with pickup enabled' do
+ expect(StockLocation.pickup_enabled).to include(enabled)
+ expect(StockLocation.pickup_enabled).not_to include(disabled)
+ end
+ end
+
+ describe '#country_iso=' do
+ let(:country) { Spree::Country.first || create(:country, iso: 'US') }
+ let(:stock_location) { build(:stock_location, country: nil, state: nil) }
+
+ it 'resolves the country from an ISO code on validation' do
+ stock_location.country_iso = country.iso
+ stock_location.valid?
+ expect(stock_location.country).to eq(country)
+ end
+
+ it 'is a no-op when blank' do
+ stock_location.country = country
+ stock_location.country_iso = ''
+ stock_location.valid?
+ expect(stock_location.country).to eq(country)
+ end
+ end
+
+ describe '#state_abbr=' do
+ let(:country) { Spree::Country.first || create(:country, iso: 'US') }
+ let!(:state) { country.states.find_by(abbr: 'NY') || create(:state, country: country, abbr: 'NY', name: 'New York') }
+ let(:stock_location) { build(:stock_location, country: country, state: nil) }
+
+ it 'resolves the state from an abbreviation scoped to the country' do
+ stock_location.state_abbr = 'NY'
+ stock_location.valid?
+ expect(stock_location.state).to eq(state)
+ end
+
+ it 'leaves state nil when no matching abbreviation exists for the country' do
+ stock_location.state_abbr = 'ZZ'
+ stock_location.valid?
+ expect(stock_location.state).to be_nil
+ end
+
+ it 'is a no-op when no country is set' do
+ stock_location.country = nil
+ stock_location.state_abbr = 'NY'
+ stock_location.valid?
+ expect(stock_location.state).to be_nil
+ end
+ end
end
end