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.

Custom Fields support for Admin API / SDK

Damian Legawiecd8792db56c40
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 5eb0a31d4c..12ec62d974 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -39,6 +39,282 @@ info:
```
version: v3
paths:
+ "/api/v3/admin/custom_field_definitions":
+ get:
+ summary: List custom field definitions
+ tags:
+ - Custom Fields
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.
+
+ **Required scope:** `read_custom_field_definitions` (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: definitions } = await client.customFieldDefinitions.list({
+ q: { resource_type_eq: 'Spree::Product' },
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: definitions returned
+ content:
+ application/json:
+ example:
+ data:
+ - id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Title
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ created_at: '2026-05-04T08:17:58.117Z'
+ updated_at: '2026-05-04T08:17:58.117Z'
+ - id: cfdef_gbHJdmfrXB
+ namespace: custom
+ key: order_notes
+ label: Order Notes
+ field_type: short_text
+ resource_type: Spree::Order
+ storefront_visible: true
+ created_at: '2026-05-04T08:17:58.118Z'
+ updated_at: '2026-05-04T08:17:58.118Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ post:
+ summary: Create a custom field definition
+ tags:
+ - Custom Fields
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_custom_field_definitions` (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 definition = await client.customFieldDefinitions.create({
+ namespace: 'specs',
+ key: 'origin',
+ label: 'Country of Origin',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true,
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: definition created
+ content:
+ application/json:
+ example:
+ id: cfdef_EfhxLZ9ck8
+ namespace: specs
+ key: origin
+ label: Country of Origin
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ created_at: '2026-05-04T08:17:58.844Z'
+ updated_at: '2026-05-04T08:17:58.844Z'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - key
+ - field_type
+ - resource_type
+ properties:
+ namespace:
+ type: string
+ description: Defaults to `custom`
+ key:
+ type: string
+ label:
+ type: string
+ description: Human-readable name; defaults to titleized `key`
+ field_type:
+ type: string
+ description: Custom field type identifier (one of the registered
+ field-type class names).
+ resource_type:
+ type: string
+ description: Owner class, e.g. `Spree::Product`
+ storefront_visible:
+ type: boolean
+ description: 'When false, definition is admin-only (was `display_on:
+ back_end`)'
+ "/api/v3/admin/custom_field_definitions/{id}":
+ get:
+ summary: Show a custom field definition
+ tags:
+ - Custom Fields
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `read_custom_field_definitions` (for API-key
+ authentication)."
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: definition found
+ content:
+ application/json:
+ example:
+ id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Title
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ created_at: '2026-05-04T08:17:58.848Z'
+ updated_at: '2026-05-04T08:17:58.848Z'
+ patch:
+ summary: Update a custom field definition
+ tags:
+ - Custom Fields
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_custom_field_definitions` (for API-key
+ authentication)."
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: definition updated
+ content:
+ application/json:
+ example:
+ id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Fabric Composition
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: false
+ created_at: '2026-05-04T08:17:59.132Z'
+ updated_at: '2026-05-04T08:17:59.450Z'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ label:
+ type: string
+ storefront_visible:
+ type: boolean
+ delete:
+ summary: Delete a custom field definition
+ tags:
+ - Custom Fields
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Deletes the definition and cascades to all custom field values referencing it.
+
+ **Required scope:** `write_custom_field_definitions` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: definition deleted
"/api/v3/admin/customers/{customer_id}/addresses":
get:
summary: List customer addresses
@@ -105,8 +381,8 @@ paths:
is_default_shipping: false
state_name: New York
label:
- created_at: '2026-04-30T17:39:05.070Z'
- updated_at: '2026-04-30T17:39:05.070Z'
+ created_at: '2026-05-04T08:18:00.053Z'
+ updated_at: '2026-05-04T08:18:00.053Z'
customer_id: cus_UkLWZg9DAJ
metadata:
meta:
@@ -194,8 +470,8 @@ paths:
is_default_shipping: false
state_name: New York
label: Office
- created_at: '2026-04-30T17:39:06.467Z'
- updated_at: '2026-04-30T17:39:06.467Z'
+ created_at: '2026-05-04T08:18:01.810Z'
+ updated_at: '2026-05-04T08:18:01.810Z'
customer_id: cus_UkLWZg9DAJ
metadata:
requestBody:
@@ -306,8 +582,8 @@ paths:
is_default_shipping: false
state_name: New York
label:
- created_at: '2026-04-30T17:39:06.736Z'
- updated_at: '2026-04-30T17:39:07.306Z'
+ created_at: '2026-05-04T08:18:02.180Z'
+ updated_at: '2026-05-04T08:18:02.991Z'
customer_id: cus_UkLWZg9DAJ
metadata:
requestBody:
@@ -426,8 +702,8 @@ paths:
gateway_payment_profile_id:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- created_at: '2026-04-30T17:39:08.412Z'
- updated_at: '2026-04-30T17:39:08.412Z'
+ created_at: '2026-05-04T08:18:04.636Z'
+ updated_at: '2026-05-04T08:18:04.636Z'
meta:
page: 1
limit: 25
@@ -499,8 +775,8 @@ paths:
gateway_payment_profile_id:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- created_at: '2026-04-30T17:39:08.961Z'
- updated_at: '2026-04-30T17:39:08.961Z'
+ created_at: '2026-05-04T08:18:05.241Z'
+ updated_at: '2026-05-04T08:18:05.241Z'
delete:
summary: Delete a customer credit card
tags:
@@ -603,8 +879,8 @@ paths:
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
currency: USD
- created_at: '2026-04-30T17:39:10.332Z'
- updated_at: '2026-04-30T17:39:10.332Z'
+ created_at: '2026-05-04T08:18:06.904Z'
+ updated_at: '2026-05-04T08:18:06.904Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
metadata:
@@ -676,8 +952,8 @@ paths:
display_amount_used: "$0.00"
display_amount_remaining: "$25.00"
currency: USD
- created_at: '2026-04-30T17:39:11.495Z'
- updated_at: '2026-04-30T17:39:11.495Z'
+ created_at: '2026-05-04T08:18:08.110Z'
+ updated_at: '2026-05-04T08:18:08.110Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
metadata:
@@ -765,8 +1041,8 @@ paths:
display_amount_used: "$0.00"
display_amount_remaining: "$50.00"
currency: USD
- created_at: '2026-04-30T17:39:12.038Z'
- updated_at: '2026-04-30T17:39:12.321Z'
+ created_at: '2026-05-04T08:18:08.775Z'
+ updated_at: '2026-05-04T08:18:09.069Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
metadata:
@@ -904,8 +1180,8 @@ paths:
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-04-30T17:39:13.403Z'
- updated_at: '2026-04-30T17:39:13.403Z'
+ created_at: '2026-05-04T08:18:10.185Z'
+ updated_at: '2026-05-04T08:18:10.185Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -988,8 +1264,8 @@ paths:
login:
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-04-30T17:39:14.231Z'
- updated_at: '2026-04-30T17:39:14.231Z'
+ created_at: '2026-05-04T08:18:11.164Z'
+ updated_at: '2026-05-04T08:18:11.164Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1098,8 +1374,8 @@ paths:
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-04-30T17:39:14.500Z'
- updated_at: '2026-04-30T17:39:14.500Z'
+ created_at: '2026-05-04T08:18:11.443Z'
+ updated_at: '2026-05-04T08:18:11.443Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1173,8 +1449,8 @@ paths:
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-04-30T17:39:15.046Z'
- updated_at: '2026-04-30T17:39:15.324Z'
+ created_at: '2026-05-04T08:18:12.010Z'
+ updated_at: '2026-05-04T08:18:12.291Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1299,11 +1575,11 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Eugena
- last_name: Schinner
- created_at: '2026-04-30T17:39:16.150Z'
- updated_at: '2026-04-30T17:39:16.150Z'
+ first_name: Brice
+ last_name: Wunsch
+ created_at: '2026-05-04T08:18:13.278Z'
+ updated_at: '2026-05-04T08:18:13.278Z'
permissions:
- allow: true
actions:
@@ -1434,8 +1710,8 @@ paths:
label: Size
position: 1
kind: dropdown
- created_at: '2026-04-30T17:39:16.218Z'
- updated_at: '2026-04-30T17:39:16.218Z'
+ created_at: '2026-05-04T08:18:13.355Z'
+ updated_at: '2026-05-04T08:18:13.355Z'
option_values: []
meta:
page: 1
@@ -1525,8 +1801,8 @@ paths:
label: Material
position: 2
kind: dropdown
- created_at: '2026-04-30T17:39:16.787Z'
- updated_at: '2026-04-30T17:39:16.787Z'
+ created_at: '2026-05-04T08:18:14.016Z'
+ updated_at: '2026-05-04T08:18:14.016Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -1632,8 +1908,8 @@ paths:
label: Size
position: 1
kind: dropdown
- created_at: '2026-04-30T17:39:17.074Z'
- updated_at: '2026-04-30T17:39:17.074Z'
+ created_at: '2026-05-04T08:18:14.303Z'
+ updated_at: '2026-05-04T08:18:14.303Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -1704,8 +1980,8 @@ paths:
label: Updated Presentation
position: 1
kind: dropdown
- created_at: '2026-04-30T17:39:17.633Z'
- updated_at: '2026-04-30T17:39:17.922Z'
+ created_at: '2026-05-04T08:18:14.892Z'
+ updated_at: '2026-05-04T08:18:15.186Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -1850,7 +2126,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H65400446366
+ number: H91580344267
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1874,8 +2150,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:18.859Z'
- updated_at: '2026-04-30T17:39:18.965Z'
+ created_at: '2026-05-04T08:18:16.285Z'
+ updated_at: '2026-05-04T08:18:16.430Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -1944,7 +2220,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H66722024407
+ number: H45072272093
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1968,8 +2244,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:19.631Z'
- updated_at: '2026-04-30T17:39:19.711Z'
+ created_at: '2026-05-04T08:18:17.142Z'
+ updated_at: '2026-05-04T08:18:17.204Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2029,7 +2305,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H26951071944
+ number: H05567524152
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -2053,8 +2329,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:20.306Z'
- updated_at: '2026-04-30T17:39:20.643Z'
+ created_at: '2026-05-04T08:18:17.839Z'
+ updated_at: '2026-05-04T08:18:18.250Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2124,7 +2400,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H59010085771
+ number: H32361035715
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2141,15 +2417,15 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-04-30T17:39:21Z'
+ fulfilled_at: '2026-05-04T08:18:18Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:20.964Z'
- updated_at: '2026-04-30T17:39:21.307Z'
+ created_at: '2026-05-04T08:18:18.582Z'
+ updated_at: '2026-05-04T08:18:18.930Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2208,7 +2484,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H11062995371
+ number: H50596003602
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2232,8 +2508,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:21.622Z'
- updated_at: '2026-04-30T17:39:21.959Z'
+ created_at: '2026-05-04T08:18:19.249Z'
+ updated_at: '2026-05-04T08:18:19.592Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2292,7 +2568,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H73917570309
+ number: H37273886452
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2316,8 +2592,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:22.285Z'
- updated_at: '2026-04-30T17:39:22.649Z'
+ created_at: '2026-05-04T08:18:19.914Z'
+ updated_at: '2026-05-04T08:18:20.284Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2379,7 +2655,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H45144705822
+ number: H23393483302
tracking:
tracking_url:
cost: '10.0'
@@ -2403,8 +2679,8 @@ paths:
quantity: 1
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-04-30T17:39:23.313Z'
- updated_at: '2026-04-30T17:39:23.358Z'
+ created_at: '2026-05-04T08:18:20.974Z'
+ updated_at: '2026-05-04T08:18:21.027Z'
metadata:
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
@@ -2477,7 +2753,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: A606124B200C4A08
+ code: 7DBCEEFC73F9FF66
status: active
currency: USD
amount: '10.0'
@@ -2491,8 +2767,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-04-30T17:39:23.690Z'
- updated_at: '2026-04-30T17:39:23.983Z'
+ created_at: '2026-05-04T08:18:21.370Z'
+ updated_at: '2026-05-04T08:18:21.666Z'
requestBody:
content:
application/json:
@@ -2609,8 +2885,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 105238
- slug: product-105238
+ name: Product 102336
+ slug: product-102336
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -2641,11 +2917,11 @@ paths:
option_type_name: foo-size-10
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:24.667Z'
- updated_at: '2026-04-30T17:39:24.667Z'
+ created_at: '2026-05-04T08:18:22.373Z'
+ updated_at: '2026-05-04T08:18:22.373Z'
digital_links: []
- created_at: '2026-04-30T17:39:24.955Z'
- updated_at: '2026-04-30T17:39:24.955Z'
+ created_at: '2026-05-04T08:18:22.676Z'
+ updated_at: '2026-05-04T08:18:22.676Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -2713,8 +2989,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 123429
- slug: product-123429
+ name: Product 123967
+ slug: product-123967
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -2745,11 +3021,11 @@ paths:
option_type_name: foo-size-12
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:25.871Z'
- updated_at: '2026-04-30T17:39:25.871Z'
+ created_at: '2026-05-04T08:18:23.600Z'
+ updated_at: '2026-05-04T08:18:23.600Z'
digital_links: []
- created_at: '2026-04-30T17:39:25.899Z'
- updated_at: '2026-04-30T17:39:25.899Z'
+ created_at: '2026-05-04T08:18:23.629Z'
+ updated_at: '2026-05-04T08:18:23.629Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -2825,8 +3101,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 132800
- slug: product-132800
+ name: Product 138668
+ slug: product-138668
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -2857,11 +3133,11 @@ paths:
option_type_name: foo-size-13
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:25.970Z'
- updated_at: '2026-04-30T17:39:25.970Z'
+ created_at: '2026-05-04T08:18:23.699Z'
+ updated_at: '2026-05-04T08:18:23.699Z'
digital_links: []
- created_at: '2026-04-30T17:39:26.257Z'
- updated_at: '2026-04-30T17:39:26.257Z'
+ created_at: '2026-05-04T08:18:24.002Z'
+ updated_at: '2026-05-04T08:18:24.002Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -2924,8 +3200,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 146018
- slug: product-146018
+ name: Product 144376
+ slug: product-144376
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -2956,11 +3232,11 @@ paths:
option_type_name: foo-size-14
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:26.593Z'
- updated_at: '2026-04-30T17:39:26.593Z'
+ created_at: '2026-05-04T08:18:24.347Z'
+ updated_at: '2026-05-04T08:18:24.347Z'
digital_links: []
- created_at: '2026-04-30T17:39:26.875Z'
- updated_at: '2026-04-30T17:39:27.167Z'
+ created_at: '2026-05-04T08:18:24.646Z'
+ updated_at: '2026-05-04T08:18:24.941Z'
metadata:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
@@ -3073,8 +3349,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-a12cd90aafd6
- number: PMY93VR3
+ response_code: BGS-4ca27ab05995
+ number: PKEYJ1FF
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3091,13 +3367,13 @@ paths:
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
- created_at: '2026-04-30T17:39:28.159Z'
- updated_at: '2026-04-30T17:39:28.162Z'
+ created_at: '2026-05-04T08:18:25.998Z'
+ updated_at: '2026-05-04T08:18:26.003Z'
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-04-30T17:39:28.161Z'
- updated_at: '2026-04-30T17:39:28.161Z'
+ created_at: '2026-05-04T08:18:26.001Z'
+ updated_at: '2026-05-04T08:18:26.001Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -3165,7 +3441,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: P3FUVY7V
+ number: PDCYMWJU
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -3175,8 +3451,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-04-30T17:39:29.453Z'
- updated_at: '2026-04-30T17:39:29.453Z'
+ created_at: '2026-05-04T08:18:27.313Z'
+ updated_at: '2026-05-04T08:18:27.313Z'
metadata:
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
@@ -3253,8 +3529,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-b1cb046b71ce
- number: PQJOW62R
+ response_code: BGS-488350fca4f5
+ number: PTHXUWEQ
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3271,13 +3547,13 @@ paths:
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
- created_at: '2026-04-30T17:39:29.817Z'
- updated_at: '2026-04-30T17:39:29.820Z'
+ created_at: '2026-05-04T08:18:27.695Z'
+ updated_at: '2026-05-04T08:18:27.698Z'
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-04-30T17:39:29.819Z'
- updated_at: '2026-04-30T17:39:29.819Z'
+ created_at: '2026-05-04T08:18:27.697Z'
+ updated_at: '2026-05-04T08:18:27.697Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -3337,8 +3613,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-1a8085888edb
- number: P3PJS3ID
+ response_code: BGS-d953f655065f
+ number: PJR0AOH3
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3355,13 +3631,13 @@ paths:
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
- created_at: '2026-04-30T17:39:30.479Z'
- updated_at: '2026-04-30T17:39:30.481Z'
+ created_at: '2026-05-04T08:18:28.505Z'
+ updated_at: '2026-05-04T08:18:28.507Z'
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-04-30T17:39:30.480Z'
- updated_at: '2026-04-30T17:39:30.806Z'
+ created_at: '2026-05-04T08:18:28.506Z'
+ updated_at: '2026-05-04T08:18:28.839Z'
metadata:
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
@@ -3431,8 +3707,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-078ef0f90fcc
- number: PY30IHFO
+ response_code: void-BGS-f1e2ddbf894b
+ number: PHWYXVBU
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -3449,13 +3725,13 @@ paths:
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
- created_at: '2026-04-30T17:39:31.868Z'
- updated_at: '2026-04-30T17:39:31.871Z'
+ created_at: '2026-05-04T08:18:30.162Z'
+ updated_at: '2026-05-04T08:18:30.166Z'
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-04-30T17:39:31.870Z'
- updated_at: '2026-04-30T17:39:32.170Z'
+ created_at: '2026-05-04T08:18:30.164Z'
+ updated_at: '2026-05-04T08:18:30.493Z'
metadata:
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
@@ -3570,13 +3846,13 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-e9861fbb0f09
+ transaction_id: BGS-82fec6976642
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
- created_at: '2026-04-30T17:39:33.504Z'
- updated_at: '2026-04-30T17:39:33.504Z'
+ created_at: '2026-05-04T08:18:31.824Z'
+ updated_at: '2026-05-04T08:18:31.824Z'
requestBody:
content:
application/json:
@@ -3647,8 +3923,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R934946092
+ number: R427865406
customer_note:
currency: USD
locale: en
@@ -3690,8 +3966,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:33.802Z'
- updated_at: '2026-04-30T17:39:33.856Z'
+ created_at: '2026-05-04T08:18:32.121Z'
+ updated_at: '2026-05-04T08:18:32.174Z'
tags: []
internal_note:
metadata:
@@ -3846,8 +4122,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R073320480
+ number: R572553723
customer_note:
currency: USD
locale: en
@@ -3889,8 +4165,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:35.582Z'
- updated_at: '2026-04-30T17:39:35.582Z'
+ created_at: '2026-05-04T08:18:33.909Z'
+ updated_at: '2026-05-04T08:18:33.909Z'
tags: []
internal_note:
metadata:
@@ -4020,7 +4296,7 @@ paths:
example:
id: or_gbHJdmfrXB
market_id:
- number: R246782549
+ number: R234115124
customer_note:
currency: USD
@@ -4063,8 +4339,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:36.715Z'
- updated_at: '2026-04-30T17:39:36.715Z'
+ created_at: '2026-05-04T08:18:35.028Z'
+ updated_at: '2026-05-04T08:18:35.028Z'
tags: []
internal_note:
metadata:
@@ -4228,8 +4504,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R910724152
+ number: R209363898
customer_note:
currency: USD
locale: en
@@ -4271,8 +4547,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:36.994Z'
- updated_at: '2026-04-30T17:39:36.994Z'
+ created_at: '2026-05-04T08:18:35.310Z'
+ updated_at: '2026-05-04T08:18:35.310Z'
tags: []
internal_note:
metadata:
@@ -4342,7 +4618,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R310689257
+ number: R829346308
customer_note:
currency: USD
@@ -4385,8 +4661,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:38.096Z'
- updated_at: '2026-04-30T17:39:38.424Z'
+ created_at: '2026-05-04T08:18:36.426Z'
+ updated_at: '2026-05-04T08:18:36.709Z'
tags: []
internal_note:
metadata:
@@ -4558,8 +4834,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R273023523
+ number: R135201417
customer_note:
currency: USD
locale: en
@@ -4586,7 +4862,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-04-30T17:39:39.314Z'
+ completed_at: '2026-05-04T08:18:37.589Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4601,8 +4877,8 @@ paths:
display_payment_total: "$110.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:39.262Z'
- updated_at: '2026-04-30T17:39:39.338Z'
+ created_at: '2026-05-04T08:18:37.543Z'
+ updated_at: '2026-05-04T08:18:37.612Z'
tags: []
internal_note:
metadata:
@@ -4682,8 +4958,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R833529851
+ number: R080643573
customer_note:
currency: USD
locale: en
@@ -4710,7 +4986,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-04-30T17:39:40.620Z'
+ completed_at: '2026-05-04T08:18:38.915Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4723,10 +4999,10 @@ paths:
store_owner_notification_delivered:
payment_total: '0.0'
display_payment_total: "$0.00"
- canceled_at: '2026-04-30T17:39:40.921Z'
+ canceled_at: '2026-05-04T08:18:39.205Z'
approved_at:
- created_at: '2026-04-30T17:39:40.569Z'
- updated_at: '2026-04-30T17:39:40.973Z'
+ created_at: '2026-05-04T08:18:38.867Z'
+ updated_at: '2026-05-04T08:18:39.245Z'
tags: []
internal_note:
metadata:
@@ -4784,8 +5060,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R829205283
+ number: R019437152
customer_note:
currency: USD
locale: en
@@ -4812,7 +5088,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-30T17:39:41.328Z'
+ completed_at: '2026-05-04T08:18:39.589Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4826,9 +5102,9 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
canceled_at:
- approved_at: '2026-04-30T17:39:41.617Z'
- created_at: '2026-04-30T17:39:41.271Z'
- updated_at: '2026-04-30T17:39:41.328Z'
+ approved_at: '2026-05-04T08:18:39.878Z'
+ created_at: '2026-05-04T08:18:39.538Z'
+ updated_at: '2026-05-04T08:18:39.589Z'
tags: []
internal_note:
metadata:
@@ -4886,8 +5162,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R399512921
+ number: R431218252
customer_note:
currency: USD
locale: en
@@ -4914,7 +5190,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-04-30T17:39:41.948Z'
+ completed_at: '2026-05-04T08:18:40.205Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -4927,10 +5203,10 @@ paths:
store_owner_notification_delivered:
payment_total: '0.0'
display_payment_total: "$0.00"
- canceled_at: '2026-04-30T17:39:42.226Z'
+ canceled_at: '2026-05-04T08:18:40.490Z'
approved_at:
- created_at: '2026-04-30T17:39:41.895Z'
- updated_at: '2026-04-30T17:39:42.306Z'
+ created_at: '2026-05-04T08:18:40.154Z'
+ updated_at: '2026-05-04T08:18:40.577Z'
tags: []
internal_note:
metadata:
@@ -4988,8 +5264,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R549593036
+ number: R238735286
customer_note:
currency: USD
locale: en
@@ -5016,7 +5292,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-30T17:39:42.634Z'
+ completed_at: '2026-05-04T08:18:40.909Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5031,8 +5307,8 @@ paths:
display_payment_total: "$0.00"
canceled_at:
approved_at:
- created_at: '2026-04-30T17:39:42.585Z'
- updated_at: '2026-04-30T17:39:42.634Z'
+ created_at: '2026-05-04T08:18:40.859Z'
+ updated_at: '2026-05-04T08:18:40.909Z'
tags: []
internal_note:
metadata:
@@ -5090,8 +5366,8 @@ paths:
source_required: false
active: true
auto_capture:
- created_at: '2026-04-30T17:39:42.931Z'
- updated_at: '2026-04-30T17:39:42.932Z'
+ created_at: '2026-05-04T08:18:41.205Z'
+ updated_at: '2026-05-04T08:18:41.206Z'
meta:
page: 1
limit: 25
@@ -5156,8 +5432,294 @@ paths:
source_required: false
active: true
auto_capture:
- created_at: '2026-04-30T17:39:43.214Z'
- updated_at: '2026-04-30T17:39:43.215Z'
+ created_at: '2026-05-04T08:18:41.491Z'
+ updated_at: '2026-05-04T08:18:41.493Z'
+ "/api/v3/admin/products/{product_id}/custom_fields":
+ get:
+ summary: List product custom fields
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the product's custom field values.
+
+ **Required scope:** `read_products` (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: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: custom fields found
+ content:
+ application/json:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::Metafields::ShortText
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-05-04T08:18:41.804Z'
+ updated_at: '2026-05-04T08:18:41.804Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a product custom field
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.
+
+ **Required scope:** `write_products` (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 customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
+ custom_field_definition_id: 'cfdef_AbC123XyZ',
+ value: 'wool',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: custom field created
+ content:
+ application/json:
+ example:
+ id: cf_gbHJdmfrXB
+ label: Description
+ type: Spree::Metafields::LongText
+ field_type: long_text
+ key: custom.description
+ value: A longer description
+ created_at: '2026-05-04T08:18:42.393Z'
+ updated_at: '2026-05-04T08:18:42.393Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_gbHJdmfrXB
+ '422':
+ description: duplicate definition for the same product
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Metafield definition has already been taken
+ details:
+ metafield_definition_id:
+ - has already been taken
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - custom_field_definition_id
+ - value
+ properties:
+ custom_field_definition_id:
+ type: string
+ description: Prefixed `cfdef_…` id
+ value:
+ description: Value matching the definition's `field_type`
+ "/api/v3/admin/products/{product_id}/custom_fields/{id}":
+ get:
+ summary: Show a product custom field
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `read_products` (for API-key authentication)."
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: custom field found
+ content:
+ application/json:
+ example:
+ id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::Metafields::ShortText
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-05-04T08:18:42.755Z'
+ updated_at: '2026-05-04T08:18:42.755Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ patch:
+ summary: Update a product custom field
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.
+
+ **Required scope:** `write_products` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: custom field updated
+ content:
+ application/json:
+ example:
+ id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::Metafields::ShortText
+ field_type: short_text
+ key: custom.title
+ value: cotton
+ created_at: '2026-05-04T08:18:43.069Z'
+ updated_at: '2026-05-04T08:18:43.353Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - value
+ properties:
+ value:
+ description: New value
+ delete:
+ summary: Delete a product custom field
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_products` (for API-key authentication)."
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: custom field deleted
"/api/v3/admin/products":
get:
summary: List products
@@ -5243,33 +5805,24 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 339195
- slug: product-339195
+ name: Product 391435
+ slug: product-391435
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-30T17:39:43.506Z'
+ available_on: '2025-05-04T08:18:43.678Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Provident reiciendis perspiciatis iste ea. Ad distinctio
- deserunt blanditiis ipsa neque. Voluptate beatae perferendis neque
- nam cumque. Autem porro illum adipisci nulla quas. Ipsa occaecati
- dicta enim voluptatum illo ea. Ratione reprehenderit ipsa fugiat
- natus aliquam nam. Consequuntur eaque unde corporis provident
- rerum. Recusandae unde soluta inventore aut voluptates nisi enim.
- Facilis natus quas aspernatur nisi ad quidem. Aliquid assumenda
- rem accusamus temporibus saepe ea architecto exercitationem. Facere
- est laudantium veniam minus tempora consectetur. Quidem iusto
- pariatur quasi nobis consequatur doloremque alias commodi. Sequi
- cum inventore porro atque veritatis rem. Perspiciatis sit sunt
- totam quis.
+ description: Impedit dolorem assumenda quia occaecati sequi saepe.
+ Inventore totam excepturi ut voluptates facere. Dignissimos consequatur
+ aut culpa odit repellat eius eligendi incidunt. Aut maxime qui
+ minima ab. Nemo expedita fuga repudiandae quidem illo alias ab
+ voluptatum. Aperiam illum a ducimus odio commodi nisi corporis.
description_html: |-
- Provident reiciendis perspiciatis iste ea. Ad distinctio deserunt blanditiis ipsa neque. Voluptate beatae perferendis neque nam cumque. Autem porro illum adipisci nulla quas.
- Ipsa occaecati dicta enim voluptatum illo ea. Ratione reprehenderit ipsa fugiat natus aliquam nam. Consequuntur eaque unde corporis provident rerum.
- Recusandae unde soluta inventore aut voluptates nisi enim. Facilis natus quas aspernatur nisi ad quidem. Aliquid assumenda rem accusamus temporibus saepe ea architecto exercitationem.
- Facere est laudantium veniam minus tempora consectetur. Quidem iusto pariatur quasi nobis consequatur doloremque alias commodi. Sequi cum inventore porro atque veritatis rem. Perspiciatis sit sunt totam quis.
+ Impedit dolorem assumenda quia occaecati sequi saepe. Inventore totam excepturi ut voluptates facere. Dignissimos consequatur aut culpa odit repellat eius eligendi incidunt.
+ Aut maxime qui minima ab. Nemo expedita fuga repudiandae quidem illo alias ab voluptatum. Aperiam illum a ducimus odio commodi nisi corporis.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -5284,15 +5837,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-04-30T17:39:43.537Z'
- updated_at: '2026-04-30T17:39:43.537Z'
+ created_at: '2026-05-04T08:18:43.707Z'
+ updated_at: '2026-05-04T08:18:43.707Z'
original_price:
status: active
- make_active_at: '2025-04-30T17:39:43.506Z'
+ make_active_at: '2025-05-04T08:18:43.678Z'
discontinue_on:
deleted_at:
- created_at: '2026-04-30T17:39:43.521Z'
- updated_at: '2026-04-30T17:39:43.538Z'
+ created_at: '2026-05-04T08:18:43.693Z'
+ updated_at: '2026-05-04T08:18:43.708Z'
cost_price: '17.0'
cost_currency: USD
meta:
@@ -5431,15 +5984,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-04-30T17:39:44.197Z'
- updated_at: '2026-04-30T17:39:44.197Z'
+ created_at: '2026-05-04T08:18:44.379Z'
+ updated_at: '2026-05-04T08:18:44.379Z'
original_price:
status: draft
make_active_at:
discontinue_on:
deleted_at:
- created_at: '2026-04-30T17:39:44.195Z'
- updated_at: '2026-04-30T17:39:44.201Z'
+ created_at: '2026-05-04T08:18:44.377Z'
+ updated_at: '2026-05-04T08:18:44.383Z'
cost_price:
cost_currency: USD
schema:
@@ -5618,27 +6171,36 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 379711
- slug: product-379711
+ name: Product 433377
+ slug: product-433377
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-30T17:39:44.540Z'
+ available_on: '2025-05-04T08:18:44.721Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Doloribus neque dolorum iusto numquam ut amet sed. Ipsam
- consequatur similique ullam corrupti quas adipisci. Tenetur voluptatem
- ipsa quod inventore accusantium. Aliquam similique optio labore
- autem iusto nisi. Consequuntur enim aliquid minus error dolores
- architecto officiis. Harum voluptates a nobis culpa officia id nesciunt
- delectus. Corporis culpa adipisci consectetur eos repellat. Laudantium
- suscipit veritatis molestias tenetur aut non vitae distinctio. Autem
- sit est magni sed.
+ description: Atque praesentium possimus ipsa voluptates eveniet. Tempora
+ quod sequi quisquam nisi vero perspiciatis odio. Eius laudantium
+ ratione illo similique nam. Quia qui hic eos quasi omnis asperiores
+ ut animi. Beatae itaque earum at rem corrupti deserunt repudiandae.
+ Doloremque blanditiis sit mollitia enim aliquid nulla. Rerum architecto
+ officiis excepturi doloribus eius. Quidem vitae velit eum quibusdam
+ eaque tempore perferendis quasi. Non commodi asperiores nisi sunt
+ unde voluptatum. Minus nulla in dignissimos aperiam sint commodi.
+ Fuga tenetur maiores voluptates numquam dolore. Exercitationem rerum
+ soluta maiores sed optio deserunt sunt. Eveniet dolore nesciunt
+ illum asperiores. Explicabo amet natus dolorem cum porro. Quo dolore
+ a optio atque cum eveniet animi. Nihil sapiente aspernatur pariatur
+ nesciunt blanditiis ut ducimus eum. Dolores illum dolorum odit eligendi
+ ut.
description_html: |-
- Doloribus neque dolorum iusto numquam ut amet sed. Ipsam consequatur similique ullam corrupti quas adipisci. Tenetur voluptatem ipsa quod inventore accusantium. Aliquam similique optio labore autem iusto nisi.
- Consequuntur enim aliquid minus error dolores architecto officiis. Harum voluptates a nobis culpa officia id nesciunt delectus. Corporis culpa adipisci consectetur eos repellat. Laudantium suscipit veritatis molestias tenetur aut non vitae distinctio. Autem sit est magni sed.
+ Atque praesentium possimus ipsa voluptates eveniet. Tempora quod sequi quisquam nisi vero perspiciatis odio. Eius laudantium ratione illo similique nam. Quia qui hic eos quasi omnis asperiores ut animi. Beatae itaque earum at rem corrupti deserunt repudiandae.
+ Doloremque blanditiis sit mollitia enim aliquid nulla. Rerum architecto officiis excepturi doloribus eius. Quidem vitae velit eum quibusdam eaque tempore perferendis quasi.
+ Non commodi asperiores nisi sunt unde voluptatum. Minus nulla in dignissimos aperiam sint commodi. Fuga tenetur maiores voluptates numquam dolore.
+ Exercitationem rerum soluta maiores sed optio deserunt sunt. Eveniet dolore nesciunt illum asperiores. Explicabo amet natus dolorem cum porro.
+ Quo dolore a optio atque cum eveniet animi. Nihil sapiente aspernatur pariatur nesciunt blanditiis ut ducimus eum. Dolores illum dolorum odit eligendi ut.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -5653,15 +6215,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-04-30T17:39:44.564Z'
- updated_at: '2026-04-30T17:39:44.564Z'
+ created_at: '2026-05-04T08:18:44.742Z'
+ updated_at: '2026-05-04T08:18:44.742Z'
original_price:
status: active
- make_active_at: '2025-04-30T17:39:44.540Z'
+ make_active_at: '2025-05-04T08:18:44.721Z'
discontinue_on:
deleted_at:
- created_at: '2026-04-30T17:39:44.552Z'
- updated_at: '2026-04-30T17:39:44.565Z'
+ created_at: '2026-05-04T08:18:44.731Z'
+ updated_at: '2026-05-04T08:18:44.743Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -5729,21 +6291,37 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-399957
+ slug: product-458439
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-30T17:39:45.168Z'
+ available_on: '2025-05-04T08:18:45.378Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Rem porro hic minima aliquam culpa repellendus dolorum.
- Cumque ipsa impedit officia soluta voluptates. Tempora excepturi
- totam vel adipisci sint dolores facilis ratione.
- description_html: Rem porro hic minima aliquam culpa repellendus dolorum.
- Cumque ipsa impedit officia soluta voluptates. Tempora excepturi
- totam vel adipisci sint dolores facilis ratione.
+ description: Tempore ab qui architecto quos. Ea nobis suscipit tempore
+ quos eligendi dolores. Eum quod libero tempore nihil minus praesentium.
+ Fuga impedit adipisci ea ab quibusdam culpa. Consectetur sequi tenetur
+ natus sapiente itaque. Ullam laboriosam a incidunt culpa quidem
+ delectus. Odio atque vero quos asperiores vel. Ad unde veritatis
+ aspernatur assumenda recusandae eius. Atque culpa doloribus officiis
+ provident repudiandae eaque. Ad perspiciatis dolores soluta dignissimos
+ possimus maiores deserunt voluptates. Quas quam eum corporis voluptate
+ quos cupiditate rem vel. Unde amet beatae quae minus ea. Ab voluptates
+ vitae ipsam consectetur eligendi debitis cum deserunt. Accusantium
+ recusandae architecto suscipit repellendus dolores. Quis unde molestias
+ aut ipsam incidunt cum. Iusto iure at vitae consectetur odio quia.
+ Labore officia tenetur libero suscipit laboriosam ad nihil similique.
+ Eum quisquam explicabo quaerat aliquam nesciunt. Unde voluptatum
+ dignissimos consectetur eum perspiciatis voluptatem voluptas quidem.
+ A iste possimus iusto labore dignissimos enim.
+ description_html: |-
+ Tempore ab qui architecto quos. Ea nobis suscipit tempore quos eligendi dolores. Eum quod libero tempore nihil minus praesentium.
+ Fuga impedit adipisci ea ab quibusdam culpa. Consectetur sequi tenetur natus sapiente itaque. Ullam laboriosam a incidunt culpa quidem delectus. Odio atque vero quos asperiores vel.
+ Ad unde veritatis aspernatur assumenda recusandae eius. Atque culpa doloribus officiis provident repudiandae eaque. Ad perspiciatis dolores soluta dignissimos possimus maiores deserunt voluptates. Quas quam eum corporis voluptate quos cupiditate rem vel.
+ Unde amet beatae quae minus ea. Ab voluptates vitae ipsam consectetur eligendi debitis cum deserunt. Accusantium recusandae architecto suscipit repellendus dolores. Quis unde molestias aut ipsam incidunt cum.
+ Iusto iure at vitae consectetur odio quia. Labore officia tenetur libero suscipit laboriosam ad nihil similique. Eum quisquam explicabo quaerat aliquam nesciunt. Unde voluptatum dignissimos consectetur eum perspiciatis voluptatem voluptas quidem. A iste possimus iusto labore dignissimos enim.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -5758,15 +6336,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-04-30T17:39:45.191Z'
- updated_at: '2026-04-30T17:39:45.191Z'
+ created_at: '2026-05-04T08:18:45.429Z'
+ updated_at: '2026-05-04T08:18:45.429Z'
original_price:
status: active
- make_active_at: '2025-04-30T17:39:45.168Z'
+ make_active_at: '2025-05-04T08:18:45.379Z'
discontinue_on:
deleted_at:
- created_at: '2026-04-30T17:39:45.178Z'
- updated_at: '2026-04-30T17:39:45.478Z'
+ created_at: '2026-05-04T08:18:45.403Z'
+ updated_at: '2026-05-04T08:18:45.733Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -6067,7 +6645,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-48
+ sku: SKU-54
options_text: ''
track_inventory: true
media_count: 0
@@ -6097,13 +6675,13 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-04-30T17:39:47.259Z'
- updated_at: '2026-04-30T17:39:47.272Z'
- product_name: Product 422668
+ created_at: '2026-05-04T08:18:47.495Z'
+ updated_at: '2026-05-04T08:18:47.507Z'
+ product_name: Product 487682
display_price: "$0.00"
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-49
+ sku: SKU-55
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -6111,10 +6689,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 70.1
- height: 190.68
- width: 110.11
- depth: 158.34
+ weight: 121.22
+ height: 104.22
+ width: 183.8
+ depth: 112.31
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -6136,17 +6714,17 @@ paths:
option_type_name: foo-size-16
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:47.282Z'
- updated_at: '2026-04-30T17:39:47.282Z'
+ created_at: '2026-05-04T08:18:47.516Z'
+ updated_at: '2026-05-04T08:18:47.516Z'
position: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-04-30T17:39:47.280Z'
- updated_at: '2026-04-30T17:39:47.292Z'
- product_name: Product 422668
+ created_at: '2026-05-04T08:18:47.514Z'
+ updated_at: '2026-05-04T08:18:47.526Z'
+ product_name: Product 487682
display_price: "$19.99"
meta:
page: 1
@@ -6257,17 +6835,17 @@ paths:
option_type_name: size
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:47.990Z'
- updated_at: '2026-04-30T17:39:47.990Z'
+ created_at: '2026-05-04T08:18:48.164Z'
+ updated_at: '2026-05-04T08:18:48.164Z'
position: 3
total_on_hand: 0
tax_category_id: 1
cost_price:
cost_currency: USD
deleted_at:
- created_at: '2026-04-30T17:39:47.997Z'
- updated_at: '2026-04-30T17:39:47.999Z'
- product_name: Product 431643
+ created_at: '2026-05-04T08:18:48.168Z'
+ updated_at: '2026-05-04T08:18:48.169Z'
+ product_name: Product 499403
display_price: "$24.99"
'422':
description: validation error
@@ -6440,7 +7018,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-55
+ sku: SKU-61
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -6448,10 +7026,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 24.34
- height: 38.8
- width: 37.45
- depth: 130.76
+ weight: 51.48
+ height: 25.56
+ width: 36.76
+ depth: 55.9
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -6473,17 +7051,17 @@ paths:
option_type_name: foo-size-19
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:48.448Z'
- updated_at: '2026-04-30T17:39:48.448Z'
+ created_at: '2026-05-04T08:18:48.557Z'
+ updated_at: '2026-05-04T08:18:48.557Z'
position: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-04-30T17:39:48.446Z'
- updated_at: '2026-04-30T17:39:48.460Z'
- product_name: Product 45890
+ created_at: '2026-05-04T08:18:48.555Z'
+ updated_at: '2026-05-04T08:18:48.567Z'
+ product_name: Product 518260
display_price: "$19.99"
'404':
description: variant not found
@@ -6563,10 +7141,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 149.67
- height: 190.8
- width: 68.1
- depth: 71.17
+ weight: 57.69
+ height: 194.68
+ width: 92.41
+ depth: 68.65
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -6588,17 +7166,17 @@ paths:
option_type_name: foo-size-21
option_type_label: Size
image_url:
- created_at: '2026-04-30T17:39:49.120Z'
- updated_at: '2026-04-30T17:39:49.120Z'
+ created_at: '2026-05-04T08:18:49.214Z'
+ updated_at: '2026-05-04T08:18:49.214Z'
position: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-04-30T17:39:49.118Z'
- updated_at: '2026-04-30T17:39:49.415Z'
- product_name: Product 475888
+ created_at: '2026-05-04T08:18:49.212Z'
+ updated_at: '2026-05-04T08:18:49.517Z'
+ product_name: Product 531666
display_price: "$19.99"
requestBody:
content:
@@ -7347,6 +7925,45 @@ components:
- created_at
- updated_at
x-typelizer: true
+ CustomFieldDefinition:
+ type: object
+ properties:
+ id:
+ type: string
+ namespace:
+ type: string
+ key:
+ type: string
+ label:
+ type: string
+ field_type:
+ type: string
+ enum:
+ - short_text
+ - long_text
+ - rich_text
+ - number
+ - boolean
+ - json
+ resource_type:
+ type: string
+ storefront_visible:
+ type: boolean
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - namespace
+ - key
+ - label
+ - field_type
+ - resource_type
+ - storefront_visible
+ - created_at
+ - updated_at
+ x-typelizer: true
CustomField:
type: object
properties:
@@ -7356,6 +7973,16 @@ components:
type: string
type:
type: string
+ deprecated: true
+ field_type:
+ type: string
+ enum:
+ - short_text
+ - long_text
+ - rich_text
+ - number
+ - boolean
+ - json
key:
type: string
value:
@@ -7366,15 +7993,19 @@ components:
type: string
storefront_visible:
type: boolean
+ custom_field_definition_id:
+ type: string
required:
- id
- label
- type
+ - field_type
- key
- value
- created_at
- updated_at
- storefront_visible
+ - custom_field_definition_id
x-typelizer: true
Customer:
type: object
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index fe5bad1acb..cbe98219ad 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -102,7 +102,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 65 Lovely Street
+ address1: 71 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -120,7 +120,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 64 Lovely Street
+ address1: 70 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -138,7 +138,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 63 Lovely Street
+ address1: 69 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -387,7 +387,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 77 Lovely Street
+ address1: 83 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -462,7 +462,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 83 Lovely Street
+ address1: 89 Lovely Street
address2: Northwest
postal_code: '10118'
city: Los Angeles
@@ -590,16 +590,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjUyMWQ1YzAxLWZkZjgtNDQ3My04MDk2LTBhNmIyYzlhMzQyNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjU1fQ.REJwQWqlzarNd_TADKFBUnuFk7HCQJPoCCBcaQIV2pE
- refresh_token: XPJQbpb99u3n8mfatXsiPygL
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImExM2U3ZDc1LTM0ZTMtNDE3Ni1hZWZmLTI5YWUwMDM2YTY3ZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3ODg2MzM1fQ.ycgE7nPpvVrjC-dY5YVS1ULTNSneBeoLPR4TMScSGdI
+ refresh_token: 8rovZTJMREzNzgUStfy9pgKu
user:
id: cus_UkLWZg9DAJ
- first_name: Mathew
- last_name: Bayer
+ first_name: Malisa
+ last_name: Leuschke
phone:
accepts_email_marketing: false
- full_name: Mathew Bayer
+ full_name: Malisa Leuschke
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -672,16 +672,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjU2ZTA2YmZiLTQ2MTQtNGYxNC05YmFmLWJiOTY3OWU0N2QwYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjU2fQ.Y_B6-QarGKzxJu4d76m-B489kmJ9fXBpbgXo9HnLA0Y
- refresh_token: VzP8jvcXUsAmMAXyYLGxjqde
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjQ2MDRhNjg5LTAwNDQtNGMyYS1iOGM5LWE3ZDk1MTYwYzJhMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3ODg2MzM2fQ.h2SgrmNk88Vmbf7DMy7gRx_JwCBtWBvt3MO578_cAwE
+ refresh_token: FHiHaeJnXuFSAvh9LRvQL3bB
user:
id: cus_UkLWZg9DAJ
- first_name: Ahmad
- last_name: Grady
+ first_name: Anneliese
+ last_name: Balistreri
phone:
accepts_email_marketing: false
- full_name: Ahmad Grady
+ full_name: Anneliese Balistreri
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -845,9 +845,9 @@ paths:
data:
- id: cart_gbHJdmfrXB
market_id:
- number: R182881602
- token: 7xmFzBupB64Eqt1AJrjxAZshQ6hpfxqeukX
+ number: R618887686
+ token: SdM2BkjKUA6XPWqzhwZoZvmBGHFfGaXRpfK
customer_note:
currency: USD
locale: en
@@ -889,8 +889,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 477312
- slug: product-477312
+ name: Product 565163
+ slug: product-565163
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -915,7 +915,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H50238594154
+ number: H29558440573
tracking: U10000
tracking_url:
cost: '100.0'
@@ -944,7 +944,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rashida Ward
+ name: Evelyne Stiedemann
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -976,7 +976,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 98 Lovely Street
+ address1: 104 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -995,7 +995,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 99 Lovely Street
+ address1: 105 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1014,9 +1014,9 @@ paths:
market:
- id: cart_UkLWZg9DAJ
market_id:
- number: R180174120
- token: M8LpDgv8esPyaFgerorVBCzTNxbbRBiBcH6
+ number: R580209874
+ token: 258t3vNeWcMi9BBqqiFH1xsnLaWrH2kZSzt
customer_note:
currency: USD
locale: en
@@ -1058,8 +1058,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 466677
- slug: product-466677
+ name: Product 557480
+ slug: product-557480
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1084,7 +1084,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H72269460516
+ number: H03632429641
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1113,7 +1113,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rashida Ward
+ name: Evelyne Stiedemann
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1145,7 +1145,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 96 Lovely Street
+ address1: 102 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1164,7 +1164,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 97 Lovely Street
+ address1: 103 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1256,8 +1256,8 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R019335701
- token: gt4CxjNxUGXa3c8guMYCXPvRMWBbpKPSDCy
+ number: R512988572
+ token: Jzia2KJwSNKSxQVpnDvKMfaxuHvVkmmHrhT
email:
customer_note:
currency: USD
@@ -1412,9 +1412,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R136520724
- token: RDTgrgyzKwVcNA6uExX2tPfK9FiT5RiXg5X
+ number: R832102444
+ token: ouoSYizfBMrzkSPKEgu8QUVvWQ9HDHYa7FA
customer_note:
currency: USD
locale: en
@@ -1441,7 +1441,7 @@ paths:
display_delivery_total: "$0.00"
warnings:
- code: line_item_removed
- message: Product 517886 was removed because it was sold out
+ message: Product 604133 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
store_credit_total: '0.0'
@@ -1466,7 +1466,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 106 Lovely Street
+ address1: 112 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1485,7 +1485,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 107 Lovely Street
+ address1: 113 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1583,9 +1583,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R589446831
- token: 5jpsbFd46zdFZnxX83WMCjoaVuRUz5NjNCv
+ number: R906855847
+ token: YXZMcqYT6ywxEpj9S5GPjFRnUPpJrqVLaCn
customer_note: Leave at door
currency: USD
locale: en
@@ -1629,8 +1629,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 52369
- slug: product-52369
+ name: Product 613243
+ slug: product-613243
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -1655,7 +1655,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H91438962756
+ number: H78556410272
tracking:
tracking_url:
cost: '10.0'
@@ -1684,7 +1684,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Ike Schumm
+ name: Angla Cassin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1716,7 +1716,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 110 Lovely Street
+ address1: 116 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1735,7 +1735,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 111 Lovely Street
+ address1: 117 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1921,9 +1921,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R265003786
- token: aFhxuJ1gwfZ9RxSPHFyEdgDesj1URBDnDwg
+ number: R931173712
+ token: 7uLnCxRpQs3Sa1DMRyojktddwi1E4dueJZU
customer_note:
currency: USD
locale: en
@@ -1965,8 +1965,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 545852
- slug: product-545852
+ name: Product 631338
+ slug: product-631338
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1991,7 +1991,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H27932063184
+ number: H42747051940
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2020,7 +2020,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Hiram Schmidt
+ name: Tana Runolfsdottir
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2052,7 +2052,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 116 Lovely Street
+ address1: 122 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2071,7 +2071,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 117 Lovely Street
+ address1: 123 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2154,8 +2154,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R600375601
+ number: R719386816
customer_note:
currency: USD
locale: en
@@ -2182,7 +2182,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-04-29T20:31:02.835Z'
+ completed_at: '2026-05-04T08:19:02.460Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2192,8 +2192,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 566923
- slug: product-566923
+ name: Product 654923
+ slug: product-654923
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2218,7 +2218,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H21719438891
+ number: H79182010537
tracking:
tracking_url:
cost: '10.0'
@@ -2247,7 +2247,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Zella Flatley
+ name: Sunday Nicolas
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2276,8 +2276,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-3cd8d54d3a63
- number: P5SEJH2N
+ response_code: BGS-a3e2563c9b7a
+ number: P8OVW6DM
amount: '29.99'
display_amount: "$29.99"
status: completed
@@ -2304,7 +2304,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 124 Lovely Street
+ address1: 130 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2323,7 +2323,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 125 Lovely Street
+ address1: 131 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2625,7 +2625,7 @@ paths:
example:
data:
- iso: DE
- iso3: IS32
+ iso3: IS35
name: Germany
states_required: false
zipcode_required: true
@@ -3133,16 +3133,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNlZTBlMmVlLTVjYTMtNGNmNy1hYjRkLWFlNzY3MWE0ODAyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjY5fQ.b_0Zzjl18__wi6pnjPBGIzu7aE8I1LJ-7Uz5vg2e-_4
- refresh_token: NYmxCAw5u8FtKDzarLk2VB1A
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijg5YTBiOTc4LWY1N2ItNDY3NS04YmVmLTY4YTdlNzRjZDExNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3ODg2MzQ4fQ.-FGWXSNp-4ISSXmKEgFL8v0E2Kh-e_EmZ9Fk6aimgTM
+ refresh_token: Rij6tnvCbRznq1sSJzoSGiUK
user:
id: cus_UkLWZg9DAJ
- first_name: Katlyn
- last_name: Kuhn
+ first_name: Stasia
+ last_name: Daniel
phone:
accepts_email_marketing: false
- full_name: Katlyn Kuhn
+ full_name: Stasia Daniel
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -3312,8 +3312,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R270430768
+ number: R035435259
customer_note:
currency: USD
locale: en
@@ -3340,7 +3340,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-29T20:31:10.038Z'
+ completed_at: '2026-05-04T08:19:09.595Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3350,8 +3350,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 653038
- slug: product-653038
+ name: Product 746357
+ slug: product-746357
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3376,7 +3376,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H02369830101
+ number: H28466111211
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3405,7 +3405,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Shayla Gerlach
+ name: Deandrea Wilkinson
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3437,7 +3437,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 144 Lovely Street
+ address1: 150 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3456,7 +3456,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 145 Lovely Street
+ address1: 151 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3567,8 +3567,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R634795563
+ number: R460046994
customer_note:
currency: USD
locale: en
@@ -3595,7 +3595,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-29T20:31:10.734Z'
+ completed_at: '2026-05-04T08:19:10.292Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -3605,8 +3605,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 673736
- slug: product-673736
+ name: Product 762732
+ slug: product-762732
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3631,7 +3631,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H68508572865
+ number: H17519938428
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3660,7 +3660,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rivka Harvey
+ name: Erlinda Ferry
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3692,7 +3692,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 150 Lovely Street
+ address1: 156 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3711,7 +3711,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 151 Lovely Street
+ address1: 157 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3780,8 +3780,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImEwYjExODAyLTY3ZWEtNGUzNy04M2Q4LTg1MTQ2YTVhNGIwMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjcxfQ.5idDO7ASyl4HrqvrIOBrurfHFjFFGZl-jjAwtgtiP7o
- refresh_token: 2AobsjUHtC2zLJjrBGx7jc5z
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjAzMTE0NThjLWJkYzctNGU4OC1iY2YwLWQ1MjMyNGM0ZTE0ZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3ODg2MzUxfQ.H9YYGr4aXBMrbWFE9Kyi2IyPoJUaY0A8O9yEWAxQqbg
+ refresh_token: amBVTCe49MBLT5yVXcTP7rJD
user:
id: cus_UkLWZg9DAJ
@@ -3895,12 +3895,12 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Manuela
- last_name: O'Kon
+ first_name: Lynell
+ last_name: West
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Manuela O'Kon
+ full_name: Lynell West
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -3908,7 +3908,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 157 Lovely Street
+ address1: 163 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3926,7 +3926,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 156 Lovely Street
+ address1: 162 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3945,7 +3945,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 157 Lovely Street
+ address1: 163 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3964,7 +3964,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 156 Lovely Street
+ address1: 162 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4034,7 +4034,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -4047,7 +4047,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 159 Lovely Street
+ address1: 165 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4065,7 +4065,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 158 Lovely Street
+ address1: 164 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4084,7 +4084,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 159 Lovely Street
+ address1: 165 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4103,7 +4103,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 158 Lovely Street
+ address1: 164 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4274,9 +4274,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R686751507
- token: PfLkSHCKhzw3ZFoT3Evj6bX72KEAePEERfW
+ number: R215796217
+ token: BBdNFUTVzy83u24enuPFKhbgh5dk51wWWEB
customer_note:
currency: USD
locale: en
@@ -4325,8 +4325,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 755782
- slug: product-755782
+ name: Product 848009
+ slug: product-848009
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4351,7 +4351,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H81703772553
+ number: H98606593694
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4380,7 +4380,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Larita Lakin
+ name: Mana Hirthe
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4412,7 +4412,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 176 Lovely Street
+ address1: 182 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4431,7 +4431,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 177 Lovely Street
+ address1: 183 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4534,9 +4534,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R666419309
- token: nc7Dy8DuA7PFHd5sn1zM2b8gpHDPfgEp1tt
+ number: R769106477
+ token: 4o4VZZGUXJmyKLQSe9KN1cJm9pcrfd9gqQ7
customer_note:
currency: USD
locale: en
@@ -4578,8 +4578,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 772017
- slug: product-772017
+ name: Product 862500
+ slug: product-862500
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4604,7 +4604,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H42154252733
+ number: H13342204637
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4633,7 +4633,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Margarett Hoeger
+ name: Dolly Koepp
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4665,7 +4665,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 184 Lovely Street
+ address1: 190 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4684,7 +4684,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 185 Lovely Street
+ address1: 191 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4776,9 +4776,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R679060655
- token: gePNeiWirzf2J7y37iBdarBX4qVLfs3eEgi
+ number: R557817101
+ token: 9xquwSgjHp1uzfydK6j3c8w1VSA9E9VKQxZ
customer_note:
currency: USD
locale: en
@@ -4822,8 +4822,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 796254
- slug: product-796254
+ name: Product 886097
+ slug: product-886097
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4848,7 +4848,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H02184977229
+ number: H98772230904
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4877,7 +4877,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Bridget Heller
+ name: Cedrick Smitham
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4909,7 +4909,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 192 Lovely Street
+ address1: 198 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4928,7 +4928,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 193 Lovely Street
+ address1: 199 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5034,9 +5034,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R134922089
- token: v2NsykGGYJxbRhYHnN1wb62cK4Q7KNoBxYx
+ number: R726947393
+ token: Khad7phz9S8A5xjfqQw38waD9HfpEyNKnHV
customer_note:
currency: USD
locale: en
@@ -5075,8 +5075,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 813626
- slug: product-813626
+ name: Product 903701
+ slug: product-903701
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5101,7 +5101,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H20006652345
+ number: H17628770254
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5130,7 +5130,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Taisha Koch
+ name: Abbie Nitzsche
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5159,8 +5159,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429203120465620
- number: PYZM56EO
+ response_code: 1-SC-20260504081919984006
+ number: P0XK3WL3
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -5187,7 +5187,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 200 Lovely Street
+ address1: 206 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5206,7 +5206,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 201 Lovely Street
+ address1: 207 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5339,9 +5339,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R739841957
- token: Zsmwu1S5EBR4ua9KCtREh1LboGrdYxeCjXh
+ number: R773580298
+ token: SCQJkkKqTF1VQmLY8oHgueJuWw6TZnxiv73
customer_note:
currency: USD
locale: en
@@ -5383,8 +5383,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 856826
- slug: product-856826
+ name: Product 945451
+ slug: product-945451
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5409,7 +5409,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H08780625784
+ number: H38060487694
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5438,7 +5438,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Lynsey Bode
+ name: Aide O'Connell
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5467,8 +5467,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429203123363868
- number: P605ZYX4
+ response_code: 1-SC-20260504081922520413
+ number: P1T1EVFA
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -5495,7 +5495,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 216 Lovely Street
+ address1: 222 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5514,7 +5514,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 217 Lovely Street
+ address1: 223 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5592,7 +5592,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 49492AAAF001FBB7
+ code: 2EEC2C0A144AA41E
status: active
currency: USD
amount: '10.0'
@@ -5688,7 +5688,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 7C8C28BE6FE5ECDE
+ code: B032500DFD566D52
status: active
currency: USD
amount: '10.0'
@@ -5779,9 +5779,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R160774453
- token: VshV5k2uUhjKTJj8apmDPv31xd5qkh3sh5Y
+ number: R215627740
+ token: ukn3dovsVnSmp7ZzUQAXcU9Uy5L6KPcUgJ4
customer_note:
currency: USD
locale: en
@@ -5829,8 +5829,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 888823
- slug: product-888823
+ name: Product 972562
+ slug: product-972562
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5857,8 +5857,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 895490
- slug: product-895490
+ name: Product 98775
+ slug: product-98775
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -5888,7 +5888,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 231 Lovely Street
+ address1: 237 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6001,9 +6001,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R417441624
- token: 6fGMJoT6FeteiGKiWb7Awm5ZSeEZGUYFXPT
+ number: R770436707
+ token: oZ4bd4hojS9S32t8AhgeYNmdy2RWDt3q8z4
customer_note:
currency: USD
locale: en
@@ -6048,8 +6048,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 925658
- slug: product-925658
+ name: Product 101922
+ slug: product-101922
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6079,7 +6079,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 240 Lovely Street
+ address1: 246 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6172,9 +6172,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R327511489
- token: vz6NujDsYszBfSh8snFmiUjv4XN8jV22n8D
+ number: R959911711
+ token: fGLqoT7RVigFuCMbZQ64wR7nZdt6mV8bLj6
customer_note:
currency: USD
locale: en
@@ -6225,7 +6225,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 243 Lovely Street
+ address1: 249 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6386,12 +6386,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS59
+ iso3: IS62
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS60
+ iso3: IS63
name: France
states_required: false
zipcode_required: true
@@ -6470,12 +6470,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS63
+ iso3: IS66
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS64
+ iso3: IS67
name: France
states_required: false
zipcode_required: true
@@ -6550,12 +6550,12 @@ paths:
- fr
countries:
- iso: DE
- iso3: IS67
+ iso3: IS70
name: Germany
states_required: false
zipcode_required: true
- iso: FR
- iso3: IS68
+ iso3: IS71
name: France
states_required: false
zipcode_required: true
@@ -6619,12 +6619,12 @@ paths:
example:
data:
- iso: FR
- iso3: IS72
+ iso3: IS75
name: France
states_required: false
zipcode_required: true
- iso: DE
- iso3: IS71
+ iso3: IS74
name: Germany
states_required: false
zipcode_required: true
@@ -6775,7 +6775,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R773500111
+ number: R099312823
customer_note:
currency: USD
@@ -6803,7 +6803,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-04-29T20:31:31.385Z'
+ completed_at: '2026-05-04T08:19:30.457Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6813,8 +6813,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 966442
- slug: product-966442
+ name: Product 1051611
+ slug: product-1051611
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6839,7 +6839,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H86313255182
+ number: H29105448841
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6868,7 +6868,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Tandra Weber
+ name: Lupe Welch
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6900,7 +6900,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 251 Lovely Street
+ address1: 257 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6919,7 +6919,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 252 Lovely Street
+ address1: 258 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7013,9 +7013,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_5be4f6882cb65c798b36044b
+ external_id: bogus_1cd883ef85a581926b812bf5
external_data:
- client_secret: bogus_secret_83acefba58c748fa
+ client_secret: bogus_secret_c7d9d655c9959cd8
customer_external_id:
expires_at:
amount: '110.0'
@@ -7113,7 +7113,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_eea6b836764131d01d8930c3
+ external_id: bogus_d12a4c4449ea25cafcca4b0b
external_data:
client_secret: secret_123
customer_external_id:
@@ -7175,7 +7175,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_c42d7bb8c46ce77865501174
+ external_id: bogus_3906af62cca5c291d50963e3
external_data:
client_secret: secret_123
customer_external_id:
@@ -7277,7 +7277,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_da9af71a978676085b99ce61
+ external_id: bogus_d18c75a6fd035f585624d7fa
external_data:
client_secret: secret_123
customer_external_id:
@@ -7362,8 +7362,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_69d0c0fba541cf751511c029
- external_client_secret: bogus_seti_secret_e91402dff84ebb58
+ external_id: bogus_seti_f561720992e188ca83fe6437
+ external_client_secret: bogus_seti_secret_99f60ae80c94b07b
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7462,8 +7462,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_c9f7f791cdf7b9c36dea5ae9
- external_client_secret: seti_secret_e7cca325c5d0792f378adc51
+ external_id: seti_test_ac2adbf49a51de7bbd63247f
+ external_client_secret: seti_secret_4632ebeed41691d82c291f4c
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7539,8 +7539,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_73a3566842a3d01db9a800e0
- external_client_secret: seti_secret_2f94274fab6af1dfb46b5b39
+ external_id: seti_test_336c94146c6a51ba0194f2e3
+ external_client_secret: seti_secret_90f14bb01966cba00ff4b199
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7634,7 +7634,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: PHAY8LI4
+ number: PIIEW65X
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -7730,7 +7730,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-24a44547-bd29-493a-9028-25e30b0c6417
+ slug: privacy-policy-96e1ecce-0357-480b-909e-d684265f3ec5
body: We respect your privacy.
body_html: |
<div class="trix-content">
@@ -7974,12 +7974,12 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1066950
- slug: product-1066950
+ name: Product 1158874
+ slug: product-1158874
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-29T20:31:41.571Z'
+ available_on: '2025-05-04T08:19:40.720Z'
purchasable: true
in_stock: false
backorderable: true
@@ -8001,40 +8001,22 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 1078704
- slug: product-1078704
+ name: Product 1162830
+ slug: product-1162830
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-29T20:31:41.632Z'
+ available_on: '2025-05-04T08:19:40.780Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Id qui consequatur sapiente dolor eveniet ipsum. Quidem
- vel possimus corporis aut a porro doloremque. Quasi sint totam
- placeat quos vel dicta iusto sapiente. Amet non tempora perferendis
- saepe. Nesciunt distinctio accusantium vitae tempore. Aut et id
- odio qui sapiente minima nemo ipsum. Et veniam nesciunt minus
- itaque quam. Aspernatur ipsum facere aut dignissimos. Ullam natus
- commodi magnam quisquam aperiam laudantium ut asperiores. Quis
- facere dolorum deserunt soluta. Commodi ut in harum rem maiores
- dolore. Facilis ex vel saepe cupiditate. Cumque molestias esse
- nulla odio itaque. Non velit cumque reprehenderit eaque iste.
- Fugit quidem deserunt quisquam accusamus sed sequi dolorum. Repellat
- voluptatum perferendis doloribus culpa quibusdam at voluptas.
- Sed deserunt perspiciatis ea temporibus. Eaque veniam necessitatibus
- inventore dicta reiciendis doloremque. Cupiditate officia illo
- impedit assumenda. Consequuntur commodi inventore quidem molestiae
- laborum. Quaerat voluptatem maiores quos veniam neque molestias.
- Eaque unde officiis illo dignissimos voluptate laboriosam ad enim.
- Et accusamus adipisci dolor facere tempore itaque.
- description_html: |-
- Id qui consequatur sapiente dolor eveniet ipsum. Quidem vel possimus corporis aut a porro doloremque. Quasi sint totam placeat quos vel dicta iusto sapiente. Amet non tempora perferendis saepe.
- Nesciunt distinctio accusantium vitae tempore. Aut et id odio qui sapiente minima nemo ipsum. Et veniam nesciunt minus itaque quam. Aspernatur ipsum facere aut dignissimos.
- Ullam natus commodi magnam quisquam aperiam laudantium ut asperiores. Quis facere dolorum deserunt soluta. Commodi ut in harum rem maiores dolore. Facilis ex vel saepe cupiditate. Cumque molestias esse nulla odio itaque.
- Non velit cumque reprehenderit eaque iste. Fugit quidem deserunt quisquam accusamus sed sequi dolorum. Repellat voluptatum perferendis doloribus culpa quibusdam at voluptas. Sed deserunt perspiciatis ea temporibus. Eaque veniam necessitatibus inventore dicta reiciendis doloremque.
- Cupiditate officia illo impedit assumenda. Consequuntur commodi inventore quidem molestiae laborum. Quaerat voluptatem maiores quos veniam neque molestias. Eaque unde officiis illo dignissimos voluptate laboriosam ad enim. Et accusamus adipisci dolor facere tempore itaque.
+ description: Minus earum explicabo amet nihil pariatur. Saepe sint
+ molestias at vero animi sequi cumque quis. Nam temporibus tempora
+ quam libero.
+ description_html: Minus earum explicabo amet nihil pariatur. Saepe
+ sint molestias at vero animi sequi cumque quis. Nam temporibus
+ tempora quam libero.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -8136,12 +8118,12 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1341741
- slug: product-1341741
+ name: Product 1434230
+ slug: product-1434230
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-29T20:31:43.333Z'
+ available_on: '2025-05-04T08:19:42.365Z'
purchasable: true
in_stock: false
backorderable: true
@@ -8168,7 +8150,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-04-14T20:31:43Z'
+ recorded_at: '2026-04-19T08:19:42Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -8543,9 +8525,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R702444710
- token: KKKKz15uUX3wLs3WeMci3aiDUn8NLgjRMRd
+ number: R945566384
+ token: pd95wgtA8uoLj2dVyav9nBsjUbopiEtiouS
customer_note:
currency: USD
locale: en
@@ -8584,8 +8566,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1546874
- slug: product-1546874
+ name: Product 1631788
+ slug: product-1631788
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8610,7 +8592,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H03249355163
+ number: H72649836525
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8639,7 +8621,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Nada Hettinger
+ name: Natividad Hamill
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -8668,8 +8650,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429203148434892
- number: POQWOLDS
+ response_code: 1-SC-20260504081947644571
+ number: PH7LEI1P
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -8696,7 +8678,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 315 Lovely Street
+ address1: 321 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8715,7 +8697,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 316 Lovely Street
+ address1: 322 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8812,9 +8794,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R968281647
- token: vyW18bBrgGcr9BHW4DWLGKxUtYnnhyyRGVG
+ number: R971986124
+ token: EBUj579M5ZLmTAozTeeFz1UkKUo1PqYU51o
customer_note:
currency: USD
locale: en
@@ -8856,8 +8838,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1567335
- slug: product-1567335
+ name: Product 1658215
+ slug: product-1658215
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8882,7 +8864,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H34150382243
+ number: H95990973054
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8911,7 +8893,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Kylee Jones
+ name: Linh Casper
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -8943,7 +8925,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 323 Lovely Street
+ address1: 329 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8962,7 +8944,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 324 Lovely Street
+ address1: 330 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9041,7 +9023,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: NtdmeixQzCBf9oTPYdxpf9Sv
+ token: XVznyCqcTCE652qaPsdvEiUB
is_default: false
is_private: true
meta:
@@ -9117,7 +9099,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: 8cXeJyppojDAcyKGtrqEhahv
+ token: QovG4j4AcaMhZU8SaUvXcLaj
is_default: false
is_private: true
schema:
@@ -9213,7 +9195,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: 7kZxgV92WcKPHpXSc1Cn695L
+ token: P35Ve31uYuQ4ciNbAx4u3yLw
is_default: false
is_private: true
schema:
@@ -9275,7 +9257,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: zTmZe61pQGipm76nbGax6Wii
+ token: rWAv6WURLxPYHfpCnTFLKUKi
is_default: false
is_private: true
schema:
@@ -9390,7 +9372,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-191
+ sku: SKU-200
options_text: ''
track_inventory: true
media_count: 0
@@ -10159,6 +10141,16 @@ components:
type: string
type:
type: string
+ deprecated: true
+ field_type:
+ type: string
+ enum:
+ - short_text
+ - long_text
+ - rich_text
+ - number
+ - boolean
+ - json
key:
type: string
value:
@@ -10167,6 +10159,7 @@ components:
- id
- label
- type
+ - field_type
- key
- value
x-typelizer: true
diff --git a/docs/plans/5.4-6.0-custom-fields-rename.md b/docs/plans/5.5-6.0-custom-fields-rename.md
similarity index 51%
rename from docs/plans/5.4-6.0-custom-fields-rename.md
rename to docs/plans/5.5-6.0-custom-fields-rename.md
index ca692025de..a5402ec175 100644
--- a/docs/plans/5.4-6.0-custom-fields-rename.md
+++ b/docs/plans/5.5-6.0-custom-fields-rename.md
@@ -1,10 +1,10 @@
# Metafields → Custom Fields Rename
-**Status:** Draft
-**Target:** 5.4 (API bridge) + 6.0 (model rename + visibility simplification)
-**Depends on:** None — 5.4 changes are serializer/prefix renames. 6.0 rename is part of the model rename wave.
+**Status:** In Progress — 5.4 serializer bridge shipped; 5.5 CRUD API + SDK + alias classes shipping; 6.0 model rename pending
+**Target:** 5.4 (Store API serializer bridge, shipped) + 5.5 (Admin CRUD API + SDK + `Spree::CustomField` constant alias) + 6.0 (model/table rename + visibility simplification + STI rename)
+**Depends on:** None — 5.4/5.5 changes are additive. 6.0 rename is part of the model rename wave.
**Author:** Damian + Claude
-**Last updated:** 2026-04-08
+**Last updated:** 2026-05-04
## Summary
@@ -15,9 +15,10 @@ In 6.0, simplify the three-way `display_on` (both/front_end/back_end) to a singl
- **Custom Fields** — public structured data (storefront-visible by default, toggle off for admin-only)
- **Metadata** — private developer-owned data (never exposed to customers)
-The rename ships in two phases:
-1. **5.4** — Bridge the Store API surface: prefix IDs, expand parameter, serializer response keys, Admin API endpoint paths. Pure serializer-layer changes, no schema changes.
-2. **6.0** — Rename models, tables, concerns, STI types, visibility simplification, and all internal code.
+The rename ships in three phases:
+1. **5.4 (shipped)** — Bridge the Store API surface: prefix IDs, expand parameter, serializer response keys, Admin API endpoint paths. Pure serializer-layer changes, no schema changes.
+2. **5.5 (shipping)** — Admin CRUD API + SDK + `Spree::CustomField` / `Spree::CustomFieldDefinition` constant aliases so controllers, serializers, and 5.5+ extensions reference the model by its 6.0-bound name. Plus model-level `alias_attribute`s for the API field names (`custom_field_definition_id`, `field_type`, `label`, `storefront_visible`). No schema changes; no deprecation warnings yet.
+3. **6.0** — Rename models, tables, concerns, STI types, visibility simplification, and all internal code. Drop the constant aliases and the `alias_attribute` shims.
## Key Decisions (do not deviate without discussion)
@@ -26,6 +27,7 @@ The rename ships in two phases:
- **`public_metadata` is deprecated** — never was exposed in Store API, served same purpose as `private_metadata`. Single `metadata` accessor going forward. Deprecation warning when writing to `public_metadata` in 5.4, column dropped in 6.0.
- **Visibility simplifies to a boolean in 6.0** — `display_on` (both/front_end/back_end) → `storefront_visible` (boolean, default: true). The `front_end`-only option was already excluded from MetafieldDefinition::DISPLAY and never made sense. This is a schema change and ships with the 6.0 model rename wave.
- **5.4 is a clean break on API surface** — no aliases, no deprecation on API naming. Same approach as the 5.4-store-api-bridges plan. The underlying `display_on` column stays until 6.0.
+- **5.5 keeps the API surface stable AND introduces `Spree::CustomField`/`Spree::CustomFieldDefinition` as constant aliases** for the existing models. This lets controllers, serializers, and extensions reference the 6.0-bound name today. No schema changes, no deprecation warnings — the rename is a constant-level shim until 6.0 ships the actual class/table rename.
- **Two systems, clear boundary:**
- **Metadata** — for machines. Schemaless JSON. Developer-owned. Private. Think: Stripe's `metadata`.
- **Custom Fields** — for humans. Typed, validated, schema-defined. Merchant-managed. Public by default, with opt-out for admin-only fields. Think: Salesforce custom fields.
@@ -121,22 +123,24 @@ scope :storefront_visible, -> { joins(:custom_field_definition).where(spree_cust
The Store API surface is **very small** — metafields have no dedicated endpoints, only expand-based inclusion on 3 serializers:
-| Layer | Files to change | Nature of change |
-|-------|:--------------:|-----------------|
-| Store API serializers | 4 | Rename expand param + response key + serializer class |
-| Admin API serializers | 4 | Same, keep `display_on` as-is |
-| Admin API controllers | 1 | Rename endpoint path |
-| Dependencies registry | 1 | Rename keys |
-| Prefix IDs (models) | 2 | Change prefix strings |
-| Integration specs | 1 | Update expand param |
-| Serializer unit tests | 2 | Update assertions |
-| SDK types (auto-generated) | 4 | Regenerated |
-| SDK Zod schemas (auto-generated) | 3 | Regenerated |
-| OpenAPI spec (auto-generated) | 1 | Regenerated |
-| **Total** | **~23** | |
+| Layer | Files to change | Nature of change | Status |
+|-------|:--------------:|-----------------|:------:|
+| Store API serializers | 4 | Rename expand param + response key + serializer class | ✅ shipped |
+| Admin API serializers | 4 | Same, keep `display_on` as-is | ✅ shipped |
+| Admin API controllers | 1 | Rename endpoint path | ⏳ pending — see CRUD section |
+| Dependencies registry | 1 | Rename keys | ✅ shipped |
+| Prefix IDs (models) | 2 | Change prefix strings | ✅ shipped |
+| Integration specs | 1 | Update expand param | ✅ shipped |
+| Serializer unit tests | 2 | Update assertions | ✅ shipped |
+| SDK types (auto-generated) | 4 | Regenerated | ✅ shipped |
+| SDK Zod schemas (auto-generated) | 3 | Regenerated | ✅ shipped |
+| OpenAPI spec (auto-generated) | 1 | Regenerated | ✅ shipped |
+| **Total** | **~23** | | |
No migrations. No Store API controllers touch metafields — all access is via `?expand=` on products, variants, and categories. Zero client SDK methods to rename (no CRUD endpoints for metafields in Store API).
+**CRUD API for the Admin** ships separately as part of 5.4 — see [Custom Fields CRUD API + SDK](#custom-fields-crud-api--sdk-54) below.
+
#### Prefix ID changes
| Model | Old prefix | New prefix |
@@ -324,6 +328,111 @@ Update docs to advise using only the `metadata` accessor.
- Admin UI (uses internal model layer, not API naming)
- CSV export headers (internal, not API surface)
+### Phase 1.5: 5.5 Constant Aliases + `alias_attribute`s
+
+Two thin shims ship in 5.5 so that controllers, serializers, and any 5.5+ extension code can use the new names today without waiting for the 6.0 model/table rename:
+
+#### Constant aliases (model-level)
+
+```ruby
+# spree/core/app/models/spree/custom_field.rb
+module Spree
+ CustomField = Metafield
+end
+
+# spree/core/app/models/spree/custom_field_definition.rb
+module Spree
+ CustomFieldDefinition = MetafieldDefinition
+end
+```
+
+A constant alias means `Spree::CustomField.equal?(Spree::Metafield)` is `true` — same class, two names. STI works (the parent's `type` column still resolves to `Spree::Metafields::ShortText` etc.), `find_by_prefix_id!` works, all associations work. This explicitly is **not** a subclass — earlier exploration confirmed that subclassing fights STI (`Spree::Metafields::ShortText` would not be `< Spree::CustomField`).
+
+What you get:
+- Controllers reference `Spree::CustomField` / `Spree::CustomFieldDefinition` directly
+- New extensions don't write `Spree::Metafield` in their own code
+- 6.0 cleanup: delete the alias files, replace each reference's `Metafield` with `CustomField` (mechanical), do the table/class rename in one wave
+
+What you don't get (intentional):
+- `model_name.name` still says `'Spree::Metafield'` — URL helpers, error messages, I18n keys all use the legacy name. That's a 6.0 concern.
+- `Spree::Metafields::ShortText` STI subclasses keep their namespace until 6.0.
+- No deprecation warnings on `Spree::Metafield` references — 5.5 is a soft introduction, not a deprecation.
+
+#### `alias_attribute` for API field names
+
+The model exposes the API-facing field names as `alias_attribute`s pointing at the existing columns:
+
+```ruby
+class Spree::Metafield
+ alias_attribute :custom_field_definition_id, :metafield_definition_id
+end
+
+class Spree::MetafieldDefinition
+ alias_attribute :label, :name
+ alias_attribute :field_type, :metafield_type
+ # `display_on` is an enum string ('both'/'front_end'/'back_end'); expose
+ # `storefront_visible` as a boolean accessor.
+ def storefront_visible; available_on_front_end?; end
+ def storefront_visible=(value)
+ self.display_on = ActiveModel::Type::Boolean.new.cast(value) ? 'both' : 'back_end'
+ end
+end
+```
+
+The `Spree::PrefixedId` concern automatically resolves prefixed-ID values through `alias_attribute` (it walks `attribute_aliases` when assigning), so a controller can do `params.permit(:custom_field_definition_id, :value)` and have AR's `assign_attributes` write to the correct column with the prefixed ID decoded.
+
+This is the entire alias surface. Keep controllers thin permit-and-pass; the API ↔ DB rename lives in the model.
+
+#### `field_type` tokens (5.5)
+
+Both 5.4 serializers shipped `Spree::Metafields::ShortText`-style class strings via the AR `type` column and the `metafield_type` column. That leaks Ruby internals across both Store and Admin APIs and breaks every SDK consumer in 6.0 when the STI namespace renames to `Spree::CustomFields::*`. Every major competitor (Shopify, Saleor, Vendure, commercetools) exposes abstract tokens, not class names — Shopify migrated explicitly in 2022.
+
+5.5 introduces a **token vocabulary** for custom-field types:
+
+| API token | Internal STI class |
+|-----------|-------------------|
+| `short_text` | `Spree::Metafields::ShortText` |
+| `long_text` | `Spree::Metafields::LongText` |
+| `rich_text` | `Spree::Metafields::RichText` |
+| `number` | `Spree::Metafields::Number` |
+| `boolean` | `Spree::Metafields::Boolean` |
+| `json` | `Spree::Metafields::Json` |
+
+Implementation:
+
+```ruby
+class Spree::Metafield
+ TYPE_TOKENS = { 'short_text' => 'Spree::Metafields::ShortText', ... }.freeze
+ TYPE_CLASS_TO_TOKEN = TYPE_TOKENS.invert.freeze
+ FIELD_TYPE_TS_UNION = TYPE_TOKENS.keys.map { |t| "'#{t}'" }.join(' | ').freeze
+
+ def field_type
+ TYPE_CLASS_TO_TOKEN[self[:type]] || self[:type]
+ end
+end
+
+class Spree::MetafieldDefinition
+ def field_type
+ Spree::Metafield::TYPE_CLASS_TO_TOKEN[metafield_type] || metafield_type
+ end
+
+ def field_type=(value)
+ self.metafield_type = Spree::Metafield::TYPE_TOKENS[value.to_s] || value
+ end
+end
+```
+
+Reads always emit the token. Writes accept either the token (`short_text`) **or** the legacy class string (`Spree::Metafields::ShortText`) for back-compat — external integrations that wrote the old form keep working. Fall-through preserves plugin-defined types (e.g. `MyExt::Metafields::Color`) until a registration API lands in 6.0.
+
+Wire-format changes in 5.5 (all additive — no breaking changes):
+- **Store API `Spree::Api::V3::CustomFieldSerializer`** — adds `field_type` (token) alongside the legacy `type` (class string). Both ship.
+- **Admin API `Admin::CustomFieldSerializer`** — same: adds `field_type`, keeps `type`.
+- **Admin API `Admin::CustomFieldDefinitionSerializer`** — `field_type` value changed from class string → token (field name was already `field_type`). This is the one shape change consumers must adapt to.
+
+Removal of the legacy `type` field on `CustomFieldSerializer` ships in a follow-up minor (deprecation removed once consumers have migrated to `field_type`).
+
+The SDK type `field_type` becomes a discriminated union (`'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json'`) so storefront and admin consumers get type-narrowable values.
+
### Phase 2: 6.0 Model Rename + Visibility Simplification
Full internal rename. Part of the 6.0 model rename wave alongside Shipment→Fulfillment, ShippingMethod→DeliveryMethod, etc.
@@ -377,6 +486,197 @@ Full internal rename. Part of the 6.0 model rename wave alongside Shipment→Ful
`metafield.custom.id` → `custom_field.custom.id`
+### Custom Fields CRUD API + SDK (5.4)
+
+The 5.4 serializer bridge exposes custom fields as a read-only `?expand=custom_fields` payload, but no CRUD endpoints exist. The admin SPA's `<CustomFieldsDrawer>` (per `6.0-admin-spa.md` Tier 2) is gated on these endpoints. This section scopes them.
+
+#### Why now
+
+29 models include `Spree::Metafields` today (Variant, Order, Product, Customer, Category, OptionType, Taxon, Shipment, Payment, Refund, GiftCard, StoreCredit, Address, LineItem, Store, Promotion, ShippingMethod, TaxRate, StockItem, StockTransfer, CustomerReturn, CreditCard, PaymentMethod, PaymentSource, NewsletterSubscriber, PaymentSession, PaymentSetupSession, Asset, Taxonomy). Every one of those resources benefits from in-admin CRUD. Building the API once + SDK once means every detail page in the SPA can opt into custom fields with a single `<PageHeader>` prop.
+
+#### Routing — Rails route concern
+
+**Two routing surfaces because the data is two-tiered:**
+
+- **Custom fields** are per-resource-instance (this product has a `material: "wool"` value). They mount under each parent that includes `Spree::Metafields`.
+- **Custom field definitions** are per-resource-type (every `Spree::Product` shares the same definitions). They live at a flat endpoint, filtered by `?resource_type=`.
+
+```ruby
+# spree/api/config/routes.rb (admin namespace)
+
+concern :custom_fieldable do
+ resources :custom_fields, controller: 'custom_fields'
+end
+
+namespace :admin do
+ resources :custom_field_definitions # flat — definitions are per resource type
+
+ resources :products, concerns: :custom_fieldable do; ...; end
+ resources :variants, concerns: :custom_fieldable, only: %i[index show]
+ resources :orders, concerns: :custom_fieldable do; ...; end
+ resources :customers, concerns: :custom_fieldable do; ...; end
+ resources :categories, concerns: :custom_fieldable, only: %i[index show]
+ resources :option_types, concerns: :custom_fieldable
+ # …extend to remaining `Spree::Metafields`-bearing parents incrementally
+end
+```
+
+URLs:
+
+```
+# Per-instance custom field values (nested)
+GET /api/v3/admin/products/prod_xxx/custom_fields
+POST /api/v3/admin/products/prod_xxx/custom_fields
+PATCH /api/v3/admin/products/prod_xxx/custom_fields/cf_xxx
+DELETE /api/v3/admin/products/prod_xxx/custom_fields/cf_xxx
+
+# Per-type custom field definitions (flat, filter by resource_type)
+GET /api/v3/admin/custom_field_definitions?resource_type=Spree::Product
+POST /api/v3/admin/custom_field_definitions
+PATCH /api/v3/admin/custom_field_definitions/cfdef_xxx
+DELETE /api/v3/admin/custom_field_definitions/cfdef_xxx
+```
+
+**Why the concern over polymorphic `/custom_fields?owner_type=...&owner_id=...`:** consistent with the rest of the Admin API (orders/items, customers/addresses, products/media all use nested resources). Keeps URLs human-readable. Plugin parents apply the concern in their own routes file — zero core changes when a plugin adds a new metafield-bearing model.
+
+#### Controllers
+
+One `Admin::CustomFieldsController` and one `Admin::CustomFieldDefinitionsController`, both inheriting from the existing `Spree::Api::V3::Admin::ResourceController`. They infer the parent class from whichever `:<parent>_id` param is present in the route, then scope all reads/writes through the parent's `metafields` association (or `metafield_definitions` for definitions). Authorization uses CanCanCan against the parent — `authorize! :update, parent` for create/update/delete, `authorize! :show, parent` for index/show.
+
+```ruby
+module Spree::Api::V3::Admin
+ class CustomFieldsController < ResourceController
+ protected
+
+ def model_class
+ Spree::Metafield
+ end
+
+ def serializer_class
+ Spree.api.admin_custom_field_serializer
+ end
+
+ def scope
+ parent.metafields
+ end
+
+ # Inferred from the first `:<parent>_id` param present.
+ def parent
+ @parent ||= load_parent_from_route
+ end
+
+ # Permits only the API-facing fields; `key` and `type` are derived from
+ # the linked CustomFieldDefinition via the model's before_validation
+ # callback. Permitting `:type` would let API clients pick STI subclasses
+ # directly — unsafe.
+ #
+ # `custom_field_definition_id` is an `alias_attribute` on `Spree::Metafield`
+ # for the internal `metafield_definition_id` column. AR's `assign_attributes`
+ # also resolves the prefixed-ID through the alias automatically.
+ def permitted_params
+ params.permit(:custom_field_definition_id, :value)
+ end
+ end
+end
+```
+
+**Naming aliases live in the models, not in controllers.** The controller stays a thin permit-and-pass layer; the API ↔ DB column rename is encoded once on `Spree::Metafield` and `Spree::MetafieldDefinition`:
+
+```ruby
+class Spree::Metafield
+ alias_attribute :custom_field_definition_id, :metafield_definition_id
+end
+
+class Spree::MetafieldDefinition
+ alias_attribute :label, :name
+ alias_attribute :field_type, :metafield_type
+
+ # `display_on` is an enum string ('both'/'front_end'/'back_end'); expose a
+ # boolean as the API surface.
+ def storefront_visible
+ available_on_front_end?
+ end
+
+ def storefront_visible=(value)
+ self.display_on = ActiveModel::Type::Boolean.new.cast(value) ? 'both' : 'back_end'
+ end
+end
+```
+
+Drops cleanly in 6.0 when the columns rename: delete the `alias_attribute` lines, replace `display_on`/`storefront_visible` with the boolean column.
+
+`load_parent_from_route` walks a small map of `param_name → model_class`, picks the first one present, calls `find_by_prefix_id!`. Same pattern any future polymorphic admin controller will use.
+
+#### Validation rules
+
+- A `custom_field_definition_id` is required — `Spree::Metafield` validates `metafield_definition` presence. There is no free-form mode (clients can't supply `key` + `type` without a definition).
+- The custom field's STI `type` is auto-set from the linked definition's `metafield_type` in a `before_validation` callback. Clients never supply it.
+- `(metafield_definition_id, resource_type, resource_id)` is unique — DB-enforced. Updating an existing custom field's `value` is the upsert path; there is no "patch the definition link" operation (delete and re-create instead).
+- `value` is validated by the type's STI subclass (`ShortText`, `Number`, etc.).
+
+No new validation logic at the controller layer — the model and the database carry it.
+
+#### SDK — first-class six + generic escape hatch
+
+Hand-write SDK methods on the **six most-used parents** in the SPA. Plugins extend the SDK via the same TS pattern — they import `createCustomFieldsApi` and attach it to their own resource client. Everything else uses a generic.
+
+**First-class parents (6):**
+
+```ts
+adminClient.products.customFields // .list, .get, .create, .update, .delete
+adminClient.variants.customFields // (when variants get a top-level admin route)
+adminClient.orders.customFields
+adminClient.customers.customFields
+adminClient.categories.customFields
+adminClient.optionTypes.customFields
+```
+
+Same pattern for definitions:
+
+```ts
+adminClient.products.customFieldDefinitions
+adminClient.orders.customFieldDefinitions
+…
+```
+
+**Generic escape hatch:**
+
+```ts
+adminClient.customFields(ownerType: 'Spree::Product', ownerId: 'prod_xxx').list()
+```
+
+Internally, the generic is a tiny URL builder that maps `ownerType` → admin URL segment (`Spree::Product` → `products`). Plugins can also call this directly without registering a first-class binding. Used sparingly — most SPA pages use the first-class methods because they read better.
+
+**Why six and not all 29:** the SPA's detail-page surface is products, orders, customers (live today) plus variants, categories, option_types (Phase 4 of `6.0-admin-spa.md`). The remaining 23 are configuration-screen owners (StockItem, ShippingMethod, etc.) — when they need custom-field UI, the generic works fine, and we can promote them to first-class when the second consumer asks.
+
+**SDK file structure:**
+
+```
+packages/admin-sdk/src/
+├── resources/
+│ ├── custom-fields.ts # createCustomFieldsApi(client, parentPath)
+│ ├── custom-field-definitions.ts # createCustomFieldDefinitionsApi(...)
+│ ├── products.ts # adds .customFields = createCustomFieldsApi(client, `/products/${id}`)
+│ ├── orders.ts
+│ └── …
+├── admin-client.ts # exposes generic .customFields(ownerType, ownerId)
+```
+
+Each first-class binding is one line in its parent's resource file: `customFields: createCustomFieldsApi(client, ...)`. Adding a seventh first-class parent later is a one-line change.
+
+#### Deferred: definitions admin
+
+Definitions are managed in a separate UI surface (Settings → Custom Field Definitions, similar to the Rails admin's existing `metafield_definitions` page). The CRUD endpoints above support it; the SPA page is Phase 4 of `6.0-admin-spa.md`. The drawer reads definitions to type-aware-render the editor but doesn't manage them.
+
+#### Order of work
+
+1. Backend route concern + controllers (custom_fields + custom_field_definitions)
+2. Integration specs covering the six first-class parents (one parent's spec serves as the template; the rest are near-copies)
+3. SDK first-class bindings on the six parents + generic escape hatch
+4. SDK tests (MSW-based, mirror integration specs)
+5. SPA: `<CustomFieldsDrawer>` consumes the six bindings, gated by `<PageHeader jsonPreview>`-style prop
+6. SPA: extend drawer to use the `customFieldDefinitions` endpoint for type-aware editor
+
## Migration Path
### For storefront developers (5.4)
diff --git a/docs/plans/6.0-admin-spa.md b/docs/plans/6.0-admin-spa.md
index 8d78ea566c..20c9111cda 100644
--- a/docs/plans/6.0-admin-spa.md
+++ b/docs/plans/6.0-admin-spa.md
@@ -386,7 +386,7 @@ All drawer-based, opened from `<PageHeader>`'s actions dropdown.
| Component | Backed by |
|---|---|
| `<JsonPreviewDrawer>` | Pretty-prints the resource via Admin SDK serializer + copy-to-clipboard. Replaces `json_previews/show.html.erb`. |
-| `<MetafieldsDrawer>` | Per-resource custom fields editor. Supports text/longtext/rich_text/number/date/select/json kinds (see `5.4-6.0-custom-fields-rename.md`). |
+| `<CustomFieldsDrawer>` | Per-resource custom fields editor. Supports text/longtext/rich_text/number/date/select/json kinds. Depends on the Custom Fields CRUD API in `5.4-6.0-custom-fields-rename.md`. |
| `<TranslationsDrawer>` | Locale tabs + side-by-side editor (see `5.4-centralized-translations-admin.md`). |
| `<AuditLogDrawer>` | Compact timeline of resource changes via the Audit Log API endpoint. |
| `<InternalNoteCard>` | Card with rich text body + edit drawer. Reused for orders, customers, returns. Replaces `shared/_internal_note.html.erb`. |
@@ -484,7 +484,7 @@ packages/admin/
│ │ ├── route-error-boundary.tsx
│ │ ├── slot.tsx # <Slot name="..." context={...} />
│ │ ├── json-preview-drawer.tsx # Tier 2
-│ │ ├── metafields-drawer.tsx
+│ │ ├── custom-fields-drawer.tsx
│ │ ├── translations-drawer.tsx
│ │ ├── audit-log-drawer.tsx
│ │ ├── internal-note-card.tsx
@@ -531,7 +531,7 @@ Highest-leverage work. Every detail page reuses the same chrome and gains the le
### Phase 3 — resource meta tooling (Tier 2)
- ⏳ `<JsonPreviewDrawer>` (cheapest, biggest debug payoff)
-- ⏳ `<MetafieldsDrawer>` — unblocks the SPA half of `5.4-6.0-custom-fields-rename.md`
+- ⏳ `<CustomFieldsDrawer>` — depends on Custom Fields CRUD API + SDK (`5.4-6.0-custom-fields-rename.md`)
- ⏳ `<TranslationsDrawer>` — per `5.4-centralized-translations-admin.md`
- ⏳ `<AuditLogDrawer>`
- ⏳ `<InternalNoteCard>` extracted from inline order code
diff --git a/packages/admin-sdk/.changeset/admin-custom-fields-crud.md b/packages/admin-sdk/.changeset/admin-custom-fields-crud.md
new file mode 100644
index 0000000000..4aa9eee316
--- /dev/null
+++ b/packages/admin-sdk/.changeset/admin-custom-fields-crud.md
@@ -0,0 +1,13 @@
+---
+'@spree/admin-sdk': minor
+---
+
+Custom Fields CRUD API + token-based `field_type`.
+
+- New `client.{products,variants,orders,customers,categories,optionTypes}.customFields` accessors with `list / get / create / update / delete`.
+- New top-level `client.customFieldDefinitions` accessor with full CRUD.
+- New generic escape hatch `client.customFields(ownerType, ownerId)` for plugin-defined parents that don't have a first-class accessor.
+- `CustomField.field_type` and `CustomFieldDefinition.field_type` are now string-literal unions (`'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json' | (string & {})`) instead of plain `string`. Built-ins narrow + autocomplete; plugin tokens still type-check.
+- `CustomField` retains the legacy `type` field (Ruby STI class name) alongside the new `field_type` token. The TypeScript type is annotated with `@deprecated` so editors surface the migration tip on hover; eslint with `no-deprecated` will flag references. Migrate to `field_type`; `type` will be removed in a future minor.
+- New `CustomFieldDefinition` type exported from the package.
+- Includes the `Spree::CustomField` / `Spree::CustomFieldDefinition` constant aliases on the server side; no naming changes to existing models or table layout.
diff --git a/packages/admin-sdk/package.json b/packages/admin-sdk/package.json
index abe19e622d..31073af11a 100644
--- a/packages/admin-sdk/package.json
+++ b/packages/admin-sdk/package.json
@@ -75,6 +75,7 @@
"@spree/sdk-core": "workspace:*",
"@types/node": "^25.6.0",
"@vitest/coverage-v8": "^4.1.5",
+ "msw": "^2.14.2",
"tsup": "^8.0.0",
"tsx": "^4.0.0",
"typescript": "^6.0.3",
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index f1b98d27e3..ce3d4dd1d7 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -75,6 +75,11 @@ import type {
CustomerStoreCreditCreateParams,
CustomerStoreCreditUpdateParams,
CustomerUpdateParams,
+ CustomFieldCreateParams,
+ CustomFieldDefinitionCreateParams,
+ CustomFieldDefinitionUpdateParams,
+ CustomFieldOwnerType,
+ CustomFieldUpdateParams,
DirectUploadCreateParams,
FulfillmentUpdateParams,
GiftCardApplyParams,
@@ -103,6 +108,8 @@ import type {
Country,
CreditCard,
Customer,
+ CustomField,
+ CustomFieldDefinition,
Fulfillment,
LineItem,
Media,
@@ -118,6 +125,26 @@ import type {
Variant,
} from './types'
+/**
+ * Maps a built-in CustomField owner type (e.g. `Spree::Product`) to its admin
+ * route segment. The generic `client.customFields(ownerType, ownerId)` escape
+ * hatch reads this map; plugin owners that aren't registered here hit the
+ * runtime "Unknown owner type" error and should use the first-class accessor
+ * exposed by their plugin.
+ *
+ * `satisfies` here keeps the map keys as a subset of the strict-literal arm of
+ * `CustomFieldOwnerType`. Adding a built-in owner means updating both this map
+ * and the union in `params.ts`; the type system flags the map side.
+ */
+const CUSTOM_FIELD_OWNER_PATHS = {
+ 'Spree::Product': '/products',
+ 'Spree::Variant': '/variants',
+ 'Spree::Order': '/orders',
+ 'Spree::User': '/customers',
+ 'Spree::Category': '/categories',
+ 'Spree::OptionType': '/option_types',
+} as const satisfies Record<Exclude<CustomFieldOwnerType, string & {}>, string>
+
export class AdminClient {
/** @internal */
readonly request: RequestFn
@@ -126,6 +153,126 @@ export class AdminClient {
this.request = request
}
+ /**
+ * Builds a `customFields` accessor whose methods expect the parent ID as
+ * their first argument. Inlined by each first-class resource (`products`,
+ * `orders`, …) so callers can write `client.products.customFields.list(id)`.
+ * The generic `customFields(ownerType, ownerId)` escape hatch curries the
+ * parent ID up front and returns the same shape minus the leading `parentId`.
+ * @internal
+ */
+ private parentScopedCustomFields(basePath: string) {
+ return {
+ list: (
+ parentId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CustomField>> =>
+ this.request<PaginatedResponse<CustomField>>(
+ 'GET',
+ `${basePath}/${parentId}/custom_fields`,
+ { ...options, params: params ? transformListParams(params) : undefined },
+ ),
+
+ get: (parentId: string, id: string, options?: RequestOptions): Promise<CustomField> =>
+ this.request<CustomField>('GET', `${basePath}/${parentId}/custom_fields/${id}`, options),
+
+ create: (
+ parentId: string,
+ params: CustomFieldCreateParams,
+ options?: RequestOptions,
+ ): Promise<CustomField> =>
+ this.request<CustomField>('POST', `${basePath}/${parentId}/custom_fields`, {
+ ...options,
+ body: params,
+ }),
+
+ update: (
+ parentId: string,
+ id: string,
+ params: CustomFieldUpdateParams,
+ options?: RequestOptions,
+ ): Promise<CustomField> =>
+ this.request<CustomField>('PATCH', `${basePath}/${parentId}/custom_fields/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ delete: (parentId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `${basePath}/${parentId}/custom_fields/${id}`, options),
+ }
+ }
+
+ /**
+ * Generic accessor for any custom-field-bearing resource. Use the
+ * first-class accessors (`client.products.customFields`, etc.) when
+ * available — they're more discoverable. Use this when the owner is a
+ * plugin-registered resource without a dedicated accessor.
+ *
+ * ```ts
+ * await client.customFields('Spree::Product', 'prod_xxx').list()
+ * ```
+ */
+ customFields(ownerType: CustomFieldOwnerType, ownerId: string) {
+ const ownerPath = (CUSTOM_FIELD_OWNER_PATHS as Record<string, string>)[ownerType]
+ if (!ownerPath) {
+ throw new Error(
+ `Unknown custom-field owner type: ${ownerType}. Add it to CUSTOM_FIELD_OWNER_PATHS.`,
+ )
+ }
+ const scoped = this.parentScopedCustomFields(ownerPath)
+ return {
+ list: (params?: ListParams & Record<string, unknown>, options?: RequestOptions) =>
+ scoped.list(ownerId, params, options),
+ get: (id: string, options?: RequestOptions) => scoped.get(ownerId, id, options),
+ create: (params: CustomFieldCreateParams, options?: RequestOptions) =>
+ scoped.create(ownerId, params, options),
+ update: (id: string, params: CustomFieldUpdateParams, options?: RequestOptions) =>
+ scoped.update(ownerId, id, params, options),
+ delete: (id: string, options?: RequestOptions) => scoped.delete(ownerId, id, options),
+ }
+ }
+
+ // ============================================
+ // Custom Field Definitions (per resource type)
+ // ============================================
+
+ readonly customFieldDefinitions = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CustomFieldDefinition>> =>
+ this.request<PaginatedResponse<CustomFieldDefinition>>('GET', '/custom_field_definitions', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, options?: RequestOptions): Promise<CustomFieldDefinition> =>
+ this.request<CustomFieldDefinition>('GET', `/custom_field_definitions/${id}`, options),
+
+ create: (
+ params: CustomFieldDefinitionCreateParams,
+ options?: RequestOptions,
+ ): Promise<CustomFieldDefinition> =>
+ this.request<CustomFieldDefinition>('POST', '/custom_field_definitions', {
+ ...options,
+ body: params,
+ }),
+
+ update: (
+ id: string,
+ params: CustomFieldDefinitionUpdateParams,
+ options?: RequestOptions,
+ ): Promise<CustomFieldDefinition> =>
+ this.request<CustomFieldDefinition>('PATCH', `/custom_field_definitions/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/custom_field_definitions/${id}`, options),
+ }
+
// ============================================
// Authentication
// ============================================
@@ -332,6 +479,8 @@ export class AdminClient {
),
},
},
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::Product']),
}
// ============================================
@@ -589,6 +738,8 @@ export class AdminClient {
get: (orderId: string, id: string, options?: RequestOptions): Promise<Adjustment> =>
this.request<Adjustment>('GET', `/orders/${orderId}/adjustments/${id}`, options),
},
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::Order']),
}
// ============================================
@@ -627,6 +778,8 @@ export class AdminClient {
delete: (id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/option_types/${id}`, options),
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::OptionType']),
}
// ============================================
@@ -833,6 +986,8 @@ export class AdminClient {
delete: (customerId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/customers/${customerId}/store_credits/${id}`, options),
},
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::User']),
}
// ============================================
@@ -848,6 +1003,8 @@ export class AdminClient {
...options,
params: params ? transformListParams(params) : undefined,
}),
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::Category']),
}
// ============================================
@@ -869,6 +1026,8 @@ export class AdminClient {
...options,
params: getParams(params),
}),
+
+ customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::Variant']),
}
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index c2e14e5a4a..9f6bbf4728 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -329,3 +329,44 @@ export interface VariantUpdateParams {
prices?: VariantPrice[]
stock_items?: VariantStockItem[]
}
+
+export interface CustomFieldCreateParams {
+ custom_field_definition_id: string
+ value: unknown
+}
+
+export interface CustomFieldUpdateParams {
+ value: unknown
+}
+
+export interface CustomFieldDefinitionCreateParams {
+ namespace?: string
+ key: string
+ label?: string
+ field_type: string
+ resource_type: string
+ storefront_visible?: boolean
+}
+
+export interface CustomFieldDefinitionUpdateParams {
+ namespace?: string
+ key?: string
+ label?: string
+ field_type?: string
+ storefront_visible?: boolean
+}
+
+/**
+ * Owner type passed to the generic `client.customFields(ownerType, ownerId)`
+ * escape hatch. The first-class six (products, variants, orders, customers,
+ * categories, option_types) have dedicated `client.<resource>.customFields`
+ * accessors and don't need this.
+ */
+export type CustomFieldOwnerType =
+ | 'Spree::Product'
+ | 'Spree::Variant'
+ | 'Spree::Order'
+ | 'Spree::User'
+ | 'Spree::Category'
+ | 'Spree::OptionType'
+ | (string & {})
diff --git a/packages/admin-sdk/src/types/generated/CustomField.ts b/packages/admin-sdk/src/types/generated/CustomField.ts
index 3edcecf0fd..479277a3b1 100644
--- a/packages/admin-sdk/src/types/generated/CustomField.ts
+++ b/packages/admin-sdk/src/types/generated/CustomField.ts
@@ -1,16 +1,19 @@
-// Typelizer digest ac72a53500229d0024f9135125d0ca22
+// Typelizer digest faa4fda8999ba5b715e8304148c4fa66
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface CustomField {
id: string;
label: string;
+ /** @deprecated Use `field_type` instead. The legacy `type` field returns the Ruby STI class name (e.g. `Spree::Metafields::ShortText`) and will be removed in a future minor. */
type: string;
+ field_type: 'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json';
key: string;
value: any;
created_at: string;
updated_at: string;
storefront_visible: boolean;
+ custom_field_definition_id: string;
}
export default CustomField;
diff --git a/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts b/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts
new file mode 100644
index 0000000000..c6170aef6e
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/CustomFieldDefinition.ts
@@ -0,0 +1,17 @@
+// Typelizer digest e4af80d6144d122b646f8f57cbbe910f
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface CustomFieldDefinition {
+ id: string;
+ namespace: string;
+ key: string;
+ label: string;
+ field_type: 'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json';
+ resource_type: string;
+ storefront_visible: boolean;
+ created_at: string;
+ updated_at: string;
+}
+
+export default CustomFieldDefinition;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index 222318a4d5..f056db6e1e 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest f06581f4deb5822d41b29acfdb441494
+// Typelizer digest f21ed7aed461a77dbdf7485b9b652c5e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -9,6 +9,7 @@ export type { default as Asset } from './Asset'
export type { default as Category } from './Category'
export type { default as Country } from './Country'
export type { default as CreditCard } from './CreditCard'
+export type { default as CustomFieldDefinition } from './CustomFieldDefinition'
export type { default as CustomField } from './CustomField'
export type { default as Customer } from './Customer'
export type { default as DeliveryMethod } from './DeliveryMethod'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 25800467aa..07b7b71a6f 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -18,6 +18,7 @@ export type { default as Country } from './generated/Country'
export type { default as CreditCard } from './generated/CreditCard'
export type { default as Customer } from './generated/Customer'
export type { default as CustomField } from './generated/CustomField'
+export type { default as CustomFieldDefinition } from './generated/CustomFieldDefinition'
export type { default as DeliveryMethod } from './generated/DeliveryMethod'
export type { default as DeliveryRate } from './generated/DeliveryRate'
export type { default as DigitalLink } from './generated/DigitalLink'
diff --git a/packages/admin-sdk/tests/custom-fields.test.ts b/packages/admin-sdk/tests/custom-fields.test.ts
new file mode 100644
index 0000000000..68e02c02f0
--- /dev/null
+++ b/packages/admin-sdk/tests/custom-fields.test.ts
@@ -0,0 +1,134 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import type { Client } from '../src'
+import { createTestClient } from './helpers'
+
+describe('custom fields', () => {
+ let client: Client
+ beforeAll(() => {
+ client = createTestClient()
+ })
+
+ describe('first-class parent: products', () => {
+ it('lists', async () => {
+ const result = await client.products.customFields.list('prod_1')
+ expect(result.data).toHaveLength(1)
+ expect(result.data[0].id).toBe('cf_1')
+ expect(result.data[0].custom_field_definition_id).toBe('cfdef_1')
+ const echoed = (result.data[0] as { _route?: { parent: string; parent_id: string } })._route
+ expect(echoed).toEqual({ parent: 'products', parent_id: 'prod_1' })
+ })
+
+ it('gets a single custom field', async () => {
+ const cf = await client.products.customFields.get('prod_1', 'cf_1')
+ expect(cf.value).toBe('wool')
+ })
+
+ it('creates a custom field', async () => {
+ const cf = await client.products.customFields.create('prod_1', {
+ custom_field_definition_id: 'cfdef_1',
+ value: 'wool',
+ })
+ expect(cf.id).toBe('cf_1')
+ })
+
+ it('updates a custom field', async () => {
+ const cf = await client.products.customFields.update('prod_1', 'cf_1', { value: 'cotton' })
+ expect(cf.value).toBe('cotton')
+ })
+
+ it('deletes a custom field', async () => {
+ await expect(client.products.customFields.delete('prod_1', 'cf_1')).resolves.toBeUndefined()
+ })
+ })
+
+ describe.each([
+ ['orders', 'or_1', 'orders'],
+ ['customers', 'cus_1', 'customers'],
+ ['variants', 'variant_1', 'variants'],
+ ['categories', 'ctg_1', 'categories'],
+ ['optionTypes', 'opt_1', 'option_types'],
+ ] as const)('first-class parent: %s', (resource, parentId, routeSegment) => {
+ it('lists via the dedicated accessor and hits the matching route', async () => {
+ const accessor = client[resource].customFields
+ const result = await accessor.list(parentId)
+ expect(result.data[0].id).toBe('cf_1')
+ // The mock echoes the matched route + parentId so we catch wiring bugs:
+ // a wrong nesting (e.g. `client.orders.customFields` hitting /products/...)
+ // would surface as a parent-segment mismatch here.
+ const echoed = (result.data[0] as { _route?: { parent: string; parent_id: string } })._route
+ expect(echoed).toEqual({ parent: routeSegment, parent_id: parentId })
+ })
+ })
+
+ describe('top-level customFieldDefinitions', () => {
+ it('lists definitions', async () => {
+ const result = await client.customFieldDefinitions.list()
+ expect(result.data).toHaveLength(1)
+ expect(result.data[0].field_type).toBe('short_text')
+ })
+
+ it('gets a definition', async () => {
+ const defn = await client.customFieldDefinitions.get('cfdef_1')
+ expect(defn.key).toBe('fabric')
+ })
+
+ it('creates a definition', async () => {
+ const defn = await client.customFieldDefinitions.create({
+ namespace: 'specs',
+ key: 'fabric',
+ label: 'Fabric',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true,
+ })
+ expect(defn.id).toBe('cfdef_1')
+ })
+
+ it('updates a definition', async () => {
+ const defn = await client.customFieldDefinitions.update('cfdef_1', {
+ label: 'Updated label',
+ })
+ expect(defn.label).toBe('Updated label')
+ })
+
+ it('deletes a definition', async () => {
+ await expect(client.customFieldDefinitions.delete('cfdef_1')).resolves.toBeUndefined()
+ })
+ })
+
+ describe('generic escape hatch — customFields(ownerType, ownerId)', () => {
+ it('routes Spree::Product to /products', async () => {
+ const accessor = client.customFields('Spree::Product', 'prod_1')
+ const result = await accessor.list()
+ expect(result.data[0].id).toBe('cf_1')
+ const echoed = (result.data[0] as { _route?: { parent: string; parent_id: string } })._route
+ expect(echoed).toEqual({ parent: 'products', parent_id: 'prod_1' })
+ })
+
+ it('routes Spree::User to /customers (not /users)', async () => {
+ const accessor = client.customFields('Spree::User', 'cus_1')
+ const result = await accessor.list()
+ expect(result.data[0].id).toBe('cf_1')
+ const echoed = (result.data[0] as { _route?: { parent: string; parent_id: string } })._route
+ expect(echoed).toEqual({ parent: 'customers', parent_id: 'cus_1' })
+ })
+
+ it('supports CRUD via the curried accessor', async () => {
+ const accessor = client.customFields('Spree::Order', 'or_1')
+
+ const cf = await accessor.create({ custom_field_definition_id: 'cfdef_1', value: 'wool' })
+ expect(cf.id).toBe('cf_1')
+
+ const updated = await accessor.update('cf_1', { value: 'cotton' })
+ expect(updated.value).toBe('cotton')
+
+ await expect(accessor.delete('cf_1')).resolves.toBeUndefined()
+ })
+
+ it('throws on unknown owner type', () => {
+ expect(() => client.customFields('Spree::Sasquatch' as never, 'sas_1')).toThrow(
+ /Unknown custom-field owner type/,
+ )
+ })
+ })
+})
diff --git a/packages/admin-sdk/tests/helpers.ts b/packages/admin-sdk/tests/helpers.ts
new file mode 100644
index 0000000000..1f20989503
--- /dev/null
+++ b/packages/admin-sdk/tests/helpers.ts
@@ -0,0 +1,11 @@
+import { createAdminClient } from '../src'
+
+export const TEST_BASE_URL = 'https://demo.spreecommerce.org'
+export const TEST_API_KEY = 'sk_test'
+
+export function createTestClient() {
+ return createAdminClient({
+ baseUrl: TEST_BASE_URL,
+ secretKey: TEST_API_KEY,
+ })
+}
diff --git a/packages/admin-sdk/tests/mocks/handlers.ts b/packages/admin-sdk/tests/mocks/handlers.ts
new file mode 100644
index 0000000000..ee71574930
--- /dev/null
+++ b/packages/admin-sdk/tests/mocks/handlers.ts
@@ -0,0 +1,120 @@
+import { HttpResponse, http } from 'msw'
+
+const BASE_URL = 'https://demo.spreecommerce.org'
+const API_PREFIX = `${BASE_URL}/api/v3/admin`
+
+export const fixtures = {
+ customField: {
+ id: 'cf_1',
+ label: 'Fabric',
+ type: 'Spree::Metafields::ShortText',
+ field_type: 'short_text',
+ key: 'specs.fabric',
+ value: 'wool',
+ created_at: '2026-05-01T00:00:00.000Z',
+ updated_at: '2026-05-01T00:00:00.000Z',
+ storefront_visible: true,
+ custom_field_definition_id: 'cfdef_1',
+ },
+ customFieldDefinition: {
+ id: 'cfdef_1',
+ namespace: 'specs',
+ key: 'fabric',
+ resource_type: 'Spree::Product',
+ label: 'Fabric',
+ field_type: 'short_text',
+ storefront_visible: true,
+ created_at: '2026-05-01T00:00:00.000Z',
+ updated_at: '2026-05-01T00:00:00.000Z',
+ },
+}
+
+const PARENT_PATHS = [
+ 'products',
+ 'variants',
+ 'orders',
+ 'customers',
+ 'categories',
+ 'option_types',
+] as const
+
+// Echo the matched route segment + parent ID into the response under `_route`
+// so SDK routing tests can assert on which path actually fired. Without this,
+// every parent returned the same fixture and a wiring bug would slip through.
+const echoRoute = (parent: string, params: Record<string, string | readonly string[]>) => ({
+ parent,
+ parent_id: params.parentId as string,
+})
+
+const customFieldHandlersForParent = (parent: string) => [
+ http.get(`${API_PREFIX}/${parent}/:parentId/custom_fields`, ({ params }) =>
+ HttpResponse.json({
+ data: [{ ...fixtures.customField, _route: echoRoute(parent, params) }],
+ meta: {
+ count: 1,
+ page: 1,
+ limit: 25,
+ pages: 1,
+ from: 1,
+ to: 1,
+ in: 1,
+ previous: null,
+ next: null,
+ },
+ }),
+ ),
+ http.get(`${API_PREFIX}/${parent}/:parentId/custom_fields/:id`, ({ params }) =>
+ HttpResponse.json({ ...fixtures.customField, _route: echoRoute(parent, params) }),
+ ),
+ http.post(`${API_PREFIX}/${parent}/:parentId/custom_fields`, ({ params }) =>
+ HttpResponse.json(
+ { ...fixtures.customField, _route: echoRoute(parent, params) },
+ { status: 201 },
+ ),
+ ),
+ http.patch(`${API_PREFIX}/${parent}/:parentId/custom_fields/:id`, ({ params }) =>
+ HttpResponse.json({
+ ...fixtures.customField,
+ value: 'cotton',
+ _route: echoRoute(parent, params),
+ }),
+ ),
+ http.delete(
+ `${API_PREFIX}/${parent}/:parentId/custom_fields/:id`,
+ () => new HttpResponse(null, { status: 204 }),
+ ),
+]
+
+export const handlers = [
+ ...PARENT_PATHS.flatMap(customFieldHandlersForParent),
+
+ http.get(`${API_PREFIX}/custom_field_definitions`, () =>
+ HttpResponse.json({
+ data: [fixtures.customFieldDefinition],
+ meta: {
+ count: 1,
+ page: 1,
+ limit: 25,
+ pages: 1,
+ from: 1,
+ to: 1,
+ in: 1,
+ previous: null,
+ next: null,
+ },
+ }),
+ ),
+ http.get(`${API_PREFIX}/custom_field_definitions/:id`, () =>
+ HttpResponse.json(fixtures.customFieldDefinition),
+ ),
+ http.post(`${API_PREFIX}/custom_field_definitions`, () =>
+ HttpResponse.json(fixtures.customFieldDefinition, { status: 201 }),
+ ),
+ http.patch(`${API_PREFIX}/custom_field_definitions/:id`, () =>
+ HttpResponse.json({ ...fixtures.customFieldDefinition, label: 'Updated label' }),
+ ),
+ http.delete(
+ `${API_PREFIX}/custom_field_definitions/:id`,
+ () => new HttpResponse(null, { status: 204 }),
+ ),
+]
diff --git a/packages/admin-sdk/tests/mocks/server.ts b/packages/admin-sdk/tests/mocks/server.ts
new file mode 100644
index 0000000000..86f7d6154a
--- /dev/null
+++ b/packages/admin-sdk/tests/mocks/server.ts
@@ -0,0 +1,4 @@
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
diff --git a/packages/admin-sdk/tests/setup.ts b/packages/admin-sdk/tests/setup.ts
new file mode 100644
index 0000000000..e7d6d1a8fe
--- /dev/null
+++ b/packages/admin-sdk/tests/setup.ts
@@ -0,0 +1,6 @@
+import { afterAll, afterEach, beforeAll } from 'vitest'
+import { server } from './mocks/server'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
diff --git a/packages/admin-sdk/vitest.config.ts b/packages/admin-sdk/vitest.config.ts
index e2145082eb..bfe3e781da 100644
--- a/packages/admin-sdk/vitest.config.ts
+++ b/packages/admin-sdk/vitest.config.ts
@@ -10,6 +10,7 @@ export default defineConfig({
test: {
globals: true,
environment: 'node',
+ setupFiles: ['./tests/setup.ts'],
coverage: {
provider: 'v8',
include: ['src/**/*.ts'],
diff --git a/packages/sdk/.changeset/storefront-custom-field-tokens.md b/packages/sdk/.changeset/storefront-custom-field-tokens.md
new file mode 100644
index 0000000000..499fda4e9c
--- /dev/null
+++ b/packages/sdk/.changeset/storefront-custom-field-tokens.md
@@ -0,0 +1,8 @@
+---
+'@spree/sdk': minor
+---
+
+Custom field `field_type` token.
+
+- `CustomField` now exposes `field_type` as a string-literal union (`'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json' | (string & {})`) — abstract token instead of the Ruby STI class name. Aligns with how Shopify, Saleor, Vendure, and commercetools expose typed custom fields.
+- The legacy `type` field (e.g. `'Spree::Metafields::ShortText'`) is unchanged and still emitted alongside the new `field_type` for back-compat. The TypeScript type is annotated with `@deprecated` so editors surface the migration tip on hover; eslint with `no-deprecated` will flag references. Storefronts should switch to `field_type`; `type` will be removed in a future minor.
diff --git a/packages/sdk/src/types/generated/CustomField.ts b/packages/sdk/src/types/generated/CustomField.ts
index 578f383235..9845503528 100644
--- a/packages/sdk/src/types/generated/CustomField.ts
+++ b/packages/sdk/src/types/generated/CustomField.ts
@@ -1,11 +1,13 @@
-// Typelizer digest bf1a183ba12220f3ff56dafa12252c55
+// Typelizer digest ff1e6016f1b576b10d24ee23ac110163
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface CustomField {
id: string;
label: string;
+ /** @deprecated Use `field_type` instead. The legacy `type` field returns the Ruby STI class name (e.g. `Spree::Metafields::ShortText`) and will be removed in a future minor. */
type: string;
+ field_type: 'short_text' | 'long_text' | 'rich_text' | 'number' | 'boolean' | 'json';
key: string;
value: any;
}
diff --git a/packages/sdk/src/zod/generated/CustomField.ts b/packages/sdk/src/zod/generated/CustomField.ts
index 1cca6a3047..736fc80f1e 100644
--- a/packages/sdk/src/zod/generated/CustomField.ts
+++ b/packages/sdk/src/zod/generated/CustomField.ts
@@ -6,6 +6,7 @@ export const CustomFieldSchema = z.object({
label: z.string(),
type: z.string(),
key: z.string(),
+ field_type: z.any(),
value: z.any(),
});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index eb330d0fd9..5b19740977 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -151,6 +151,9 @@ importers:
'@vitest/coverage-v8':
specifier: ^4.1.5
version: 4.1.5([email protected])
+ msw:
+ specifier: ^2.14.2
+ version: 2.14.2(@types/[email protected])([email protected])
tsup:
specifier: ^8.0.0
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
index 92926d6258..c66509c895 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
@@ -51,11 +51,13 @@ module Spree
return unless current_api_key
return if self.class._scope_check_skipped
+ resource = scoped_resource_name
# Fail closed: a controller authenticated by API key MUST declare
- # either `scoped_resource :name` or `skip_scope_check!`.
- raise MissingScopedResource, self.class unless self.class._scoped_resource
+ # either `scoped_resource :name`, override `scoped_resource_name`,
+ # or `skip_scope_check!`.
+ raise MissingScopedResource, self.class unless resource
- required = "#{action_kind}_#{self.class._scoped_resource}"
+ required = "#{action_kind}_#{resource}"
return if current_api_key.has_scope?(required)
render_error(
@@ -66,6 +68,15 @@ module Spree
)
end
+ # The resource name used in scope strings (`read_<name>` / `write_<name>`).
+ # Defaults to the class-level `scoped_resource :name` declaration.
+ # Override in controllers that resolve scope at request time (e.g. the
+ # nested-on-many-parents `CustomFieldsController` returns the parent's
+ # route segment).
+ def scoped_resource_name
+ self.class._scoped_resource
+ end
+
# Override in controllers with non-REST custom actions (e.g. dashboard
# `analytics` should map to a read).
def action_kind
diff --git a/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
new file mode 100644
index 0000000000..98c49ba8a8
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
@@ -0,0 +1,34 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Schema-side metadata for custom fields. Definitions are per resource
+ # *type* (every Spree::Product shares the same definitions), so this is
+ # a flat top-level endpoint. Filter by `?resource_type=Spree::Product`
+ # (or any other registered custom-field-bearing resource) to scope the
+ # list to one parent type.
+ class CustomFieldDefinitionsController < ResourceController
+ scoped_resource :custom_field_definitions
+
+ protected
+
+ def model_class
+ Spree::CustomFieldDefinition
+ end
+
+ def serializer_class
+ Spree.api.admin_custom_field_definition_serializer
+ end
+
+ # `label`, `field_type`, `storefront_visible` are model-side aliases
+ # (alias_attribute / accessors) on Spree::CustomFieldDefinition. The
+ # API → DB column rename lands in 6.0 and this controller stays flat.
+ def permitted_params
+ params.permit(:namespace, :key, :label, :field_type,
+ :resource_type, :storefront_visible)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb
new file mode 100644
index 0000000000..7e04fb57b3
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb
@@ -0,0 +1,108 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Custom field values for any parent that includes the custom-fields
+ # concern. Mounted via the `:custom_fieldable` route concern; the parent
+ # class is inferred from whichever `<segment>_id` route param matches a
+ # registered owner.
+ class CustomFieldsController < ResourceController
+ # POST /api/v3/admin/<parent>/<parent_id>/custom_fields
+ def create
+ @resource = @parent.metafields.new(permitted_params)
+ authorize_resource!(@resource, :create)
+
+ if @resource.save
+ render json: serialize_resource(@resource), status: :created
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+
+ # PATCH /api/v3/admin/<parent>/<parent_id>/custom_fields/:id
+ # Only `value` is mutable. Switching the linked definition is a
+ # delete-and-create — the model rejects it (definition + resource
+ # uniqueness) and the type wouldn't match.
+ def update
+ authorize_resource!(@resource)
+
+ if @resource.update(update_permitted_params)
+ render json: serialize_resource(@resource)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::CustomField
+ end
+
+ def serializer_class
+ Spree.api.admin_custom_field_serializer
+ end
+
+ def parent_association
+ :metafields
+ end
+
+ def set_parent
+ # Routes always mount this controller under a recognized parent, so
+ # `parent_lookup` matches in normal flows. The explicit raise is a
+ # defensive guard against a future route nesting that doesn't.
+ raise ActiveRecord::RecordNotFound, 'Parent resource not found' unless parent_lookup
+
+ @parent = parent_lookup.klass.find_by_prefix_id!(parent_lookup.value)
+ end
+
+ # Per-parent scope check: a key holding `write_products` may write a
+ # product's custom fields, `write_orders` may write an order's, etc.
+ # Resolves the parent at request time rather than via the static
+ # `scoped_resource` declaration.
+ def scoped_resource_name
+ parent_lookup&.segment&.pluralize&.to_sym
+ end
+
+ # `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
+ # AR resolves the prefixed-ID and the alias to the canonical FK on assign.
+ def permitted_params
+ params.permit(:custom_field_definition_id, :value)
+ end
+
+ def update_permitted_params
+ params.permit(:value)
+ end
+
+ private
+
+ ParentLookup = Struct.new(:klass, :value, :segment)
+
+ # `Spree.user_class.model_name.element` is `'user'`, but the route
+ # segment is `customer_id` — alias here so both resolve to user_class.
+ def parent_route_map
+ @parent_route_map ||= Spree.metafields.enabled_resources.each_with_object({}) do |klass, m|
+ m[klass.model_name.element.to_s] = klass
+ end.tap do |map|
+ map['customer'] = Spree.user_class if Spree.metafields.enabled_resources.include?(Spree.user_class)
+ end
+ end
+
+ # Returns the first segment whose `<segment>_id` is present in params,
+ # paired with its class and the raw id value, or nil. Memoized — read
+ # by both `set_parent` and `scoped_resource_name`.
+ def parent_lookup
+ return @parent_lookup if defined?(@parent_lookup)
+
+ match = parent_route_map.find { |segment, _| params[:"#{segment}_id"].present? }
+ @parent_lookup =
+ if match
+ segment, klass = match
+ ParentLookup.new(klass, params[:"#{segment}_id"], segment)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb
new file mode 100644
index 0000000000..180cbd9a63
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/custom_field_definition_serializer.rb
@@ -0,0 +1,21 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Admin API Custom Field Definition Serializer
+ # Schema-side metadata for custom fields (per resource type).
+ class CustomFieldDefinitionSerializer < BaseSerializer
+ typelize namespace: :string,
+ key: :string,
+ label: :string,
+ field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
+ resource_type: :string,
+ storefront_visible: :boolean
+
+ attributes :namespace, :key, :label, :field_type, :resource_type, :storefront_visible,
+ created_at: :iso8601, updated_at: :iso8601
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/custom_field_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/custom_field_serializer.rb
index 6910fd7028..dc70e9c270 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/custom_field_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/custom_field_serializer.rb
@@ -5,12 +5,17 @@ module Spree
# Admin API Custom Field Serializer
# Full custom field data including admin-only fields
class CustomFieldSerializer < V3::CustomFieldSerializer
- typelize storefront_visible: :boolean
+ typelize storefront_visible: :boolean,
+ custom_field_definition_id: :string
attributes created_at: :iso8601, updated_at: :iso8601
- attribute :storefront_visible do |metafield|
- metafield.display_on.in?(%w[both front_end])
+ attribute :storefront_visible do |custom_field|
+ custom_field.metafield_definition.available_on_front_end?
+ end
+
+ attribute :custom_field_definition_id do |custom_field|
+ custom_field.metafield_definition.prefixed_id
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rb b/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rb
index 2d8120ab2f..187b8f15f2 100644
--- a/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rb
@@ -2,19 +2,18 @@ module Spree
module Api
module V3
# Store API Custom Field Serializer
- # Customer-facing custom field data (public metafields only)
+ # Customer-facing custom field data (storefront-visible only)
class CustomFieldSerializer < BaseSerializer
- typelize key: :string, label: :string, type: :string, value: :any
+ typelize key: :string,
+ label: :string,
+ type: [:string, deprecated: 'Use `field_type` instead. The legacy `type` field returns the Ruby STI class name (e.g. `Spree::Metafields::ShortText`) and will be removed in a future minor.'],
+ field_type: Spree::Metafield::FIELD_TYPE_TOKENS,
+ value: :any
- attributes :label, :type
+ attributes :label, :type, :field_type
- attribute :key do |metafield|
- metafield.full_key
- end
-
- attribute :value do |metafield|
- metafield.serialize_value
- end
+ attribute :key, &:full_key
+ attribute :value, &:serialize_value
end
end
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 3f2712da3f..d462f2c154 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -91,6 +91,15 @@ Spree::Core::Engine.add_routes do
end
namespace :admin do
+ # Mounts a nested `custom_fields` resource on parents that include
+ # Spree::Metafields. See docs/plans/5.4-6.0-custom-fields-rename.md.
+ concern :custom_fieldable do
+ resources :custom_fields
+ end
+
+ # Definitions are per resource type, not per instance.
+ resources :custom_field_definitions
+
# Authentication
post 'auth/login', to: 'auth#create'
post 'auth/refresh', to: 'auth#refresh'
@@ -110,7 +119,7 @@ Spree::Core::Engine.add_routes do
resources :direct_uploads, only: [:create]
# Products
- resources :products do
+ resources :products, concerns: :custom_fieldable do
member do
post :clone
end
@@ -121,10 +130,10 @@ Spree::Core::Engine.add_routes do
end
# Categories
- resources :categories, only: [:index, :show]
+ resources :categories, only: [:index, :show], concerns: :custom_fieldable
# Option Types (with nested option_values in payload)
- resources :option_types
+ resources :option_types, concerns: :custom_fieldable
# Tax Categories
resources :tax_categories, only: [:index, :show]
@@ -136,20 +145,20 @@ Spree::Core::Engine.add_routes do
resources :tags, only: [:index]
# Customers
- resources :customers do
+ resources :customers, concerns: :custom_fieldable do
resources :addresses, controller: 'customers/addresses'
resources :credit_cards, controller: 'customers/credit_cards', only: [:index, :show, :destroy]
resources :store_credits, controller: 'customers/store_credits'
end
# Variants (top-level, for search/autocomplete across all products)
- resources :variants, only: [:index, :show]
+ resources :variants, only: [:index, :show], concerns: :custom_fieldable
# Countries (with ?expand=states for state/province dropdown)
resources :countries, only: [:index, :show]
# Orders
- resources :orders do
+ resources :orders, concerns: :custom_fieldable do
member do
patch :complete
patch :cancel
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index 85b24a7fa5..15ddf5ce3c 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -166,6 +166,7 @@ module Spree
admin_price_serializer: 'Spree::Api::V3::Admin::PriceSerializer',
admin_price_history_serializer: 'Spree::Api::V3::Admin::PriceHistorySerializer',
admin_custom_field_serializer: 'Spree::Api::V3::Admin::CustomFieldSerializer',
+ admin_custom_field_definition_serializer: 'Spree::Api::V3::Admin::CustomFieldDefinitionSerializer',
admin_category_serializer: 'Spree::Api::V3::Admin::CategorySerializer',
admin_line_item_serializer: 'Spree::Api::V3::Admin::LineItemSerializer',
admin_option_type_serializer: 'Spree::Api::V3::Admin::OptionTypeSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
new file mode 100644
index 0000000000..642725c35f
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
@@ -0,0 +1,196 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::CustomFieldDefinitionsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:product_definition) do
+ create(:metafield_definition, :short_text_field, namespace: 'specs', key: 'fabric')
+ end
+ let!(:order_definition) { create(:metafield_definition, :for_order) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'returns all definitions across resource types' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ keys = json_response['data'].map { |d| d['key'] }
+ expect(keys).to include('fabric', order_definition.key)
+ end
+
+ it 'filters by resource_type via Ransack' do
+ get :index, params: { q: { resource_type_eq: 'Spree::Product' } }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ types = json_response['data'].map { |d| d['resource_type'] }.uniq
+ expect(types).to eq(['Spree::Product'])
+ end
+
+ it 'exposes computed fields with their API names' do
+ get :index, params: { q: { key_eq: 'fabric' } }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ item = json_response['data'].find { |d| d['key'] == 'fabric' }
+ expect(item).to include(
+ 'namespace' => 'specs',
+ 'field_type' => 'short_text',
+ 'storefront_visible' => true
+ )
+ end
+ end
+
+ describe 'POST #create' do
+ let(:create_params) do
+ {
+ namespace: 'specs',
+ key: 'origin',
+ label: 'Country of Origin',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true
+ }
+ end
+
+ it 'creates a definition' do
+ expect { post :create, params: create_params, as: :json }.
+ to change(Spree::CustomFieldDefinition, :count).by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['key']).to eq('origin')
+ expect(json_response['label']).to eq('Country of Origin')
+ expect(json_response['field_type']).to eq('short_text')
+ expect(json_response['storefront_visible']).to eq(true)
+ end
+
+ context 'with storefront_visible: false' do
+ it 'maps to display_on: back_end internally' do
+ post :create, params: create_params.merge(storefront_visible: false), as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['storefront_visible']).to eq(false)
+
+ defn = Spree::CustomFieldDefinition.find_by_prefix_id(json_response['id'])
+ expect(defn.display_on).to eq('back_end')
+ end
+ end
+
+ context 'when key collides with an existing definition for the same resource type' do
+ it 'returns 422' do
+ post :create, params: create_params.merge(key: 'fabric'), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when field_type is not a registered type' do
+ it 'returns 422' do
+ post :create, params: create_params.merge(field_type: 'Spree::Metafields::FakeKind'), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when resource_type is not registered' do
+ it 'returns 422' do
+ post :create, params: create_params.merge(resource_type: 'Spree::Sasquatch'), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when label is omitted' do
+ it 'derives the name from the titleized key' do
+ post :create, params: create_params.except(:label), as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['label']).to eq('Origin')
+ end
+ end
+
+ it 'silently drops `metafield_type` (no longer a permitted API param)' do
+ # 5.4 leaks no `metafield_type` API key; sending one is ignored. The
+ # `field_type` API param is the only way to set the column.
+ post :create,
+ params: create_params.merge(metafield_type: 'Spree::Metafields::Number'),
+ as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['field_type']).to eq('short_text')
+ end
+
+ it 'accepts the legacy class-name form on `field_type` writes' do
+ # Back-compat: external integrations that wrote `Spree::Metafields::*`
+ # under the old API contract keep working. Writes are translated; reads
+ # always emit the token form.
+ post :create,
+ params: create_params.merge(field_type: 'Spree::Metafields::Number', key: 'priority'),
+ as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['field_type']).to eq('number')
+ end
+ end
+
+ describe 'PATCH #update' do
+ it "updates the definition's label and visibility" do
+ patch :update,
+ params: {
+ id: product_definition.prefixed_id,
+ label: 'Fabric Composition',
+ storefront_visible: false
+ },
+ as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['label']).to eq('Fabric Composition')
+ expect(json_response['storefront_visible']).to eq(false)
+ expect(product_definition.reload.display_on).to eq('back_end')
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'destroys the definition and cascades to its custom fields' do
+ product = create(:product)
+ create(:metafield, resource: product, metafield_definition: product_definition, value: 'wool')
+
+ delete :destroy, params: { id: product_definition.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::CustomFieldDefinition.where(id: product_definition.id)).to be_empty
+ expect(Spree::CustomField.where(custom_field_definition_id: product_definition.id)).to be_empty
+ end
+ end
+
+ describe 'API key scope enforcement' do
+ let(:api_key) { create(:api_key, :secret, store: store, scopes: [granted_scope]) }
+ let(:api_key_headers) { { 'x-spree-api-key' => api_key.plaintext_token } }
+ let(:headers) { api_key_headers }
+
+ context 'with read_custom_field_definitions' do
+ let(:granted_scope) { 'read_custom_field_definitions' }
+
+ it 'allows index' do
+ get :index, as: :json
+ expect(response).to have_http_status(:ok)
+ end
+
+ it 'rejects writes' do
+ post :create, params: { namespace: 'x', key: 'y', field_type: 'short_text', resource_type: 'Spree::Product' }, as: :json
+ expect(response).to have_http_status(:forbidden)
+ end
+ end
+
+ context 'with no relevant scope' do
+ let(:granted_scope) { 'read_orders' }
+
+ it 'rejects index with 403' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb
new file mode 100644
index 0000000000..775d08d5f6
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb
@@ -0,0 +1,230 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::CustomFieldsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let(:product) { create(:product) }
+ let(:short_text_definition) { create(:metafield_definition, :short_text_field) }
+ let(:long_text_definition) { create(:metafield_definition, :long_text_field) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ let!(:custom_field) do
+ create(:metafield, resource: product, metafield_definition: short_text_definition, value: 'wool')
+ end
+
+ it 'returns the parent custom fields' do
+ get :index, params: { product_id: product.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+ expect(json_response['data'].first['custom_field_definition_id']).to eq(short_text_definition.prefixed_id)
+ expect(json_response['data'].first['value']).to eq('wool')
+ end
+
+ it 'returns 404 when the parent product does not exist' do
+ get :index, params: { product_id: 'prod_NotARealId' }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+
+ it 'scopes the collection to the parent — sibling products are not returned' do
+ other_product = create(:product)
+ create(:metafield, resource: other_product, metafield_definition: long_text_definition,
+ type: 'Spree::Metafields::LongText', value: 'unrelated')
+
+ get :index, params: { product_id: product.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ values = json_response['data'].map { |cf| cf['value'] }
+ expect(values).to contain_exactly('wool')
+ end
+ end
+
+ describe 'POST #create' do
+ let(:create_params) do
+ {
+ product_id: product.prefixed_id,
+ custom_field_definition_id: short_text_definition.prefixed_id,
+ value: 'wool'
+ }
+ end
+
+ it 'creates a custom field on the parent' do
+ expect { post :create, params: create_params, as: :json }.
+ to change { product.metafields.count }.by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['value']).to eq('wool')
+ expect(json_response['custom_field_definition_id']).to eq(short_text_definition.prefixed_id)
+ end
+
+ context 'when custom_field_definition_id is missing' do
+ it 'returns 422' do
+ post :create, params: create_params.except(:custom_field_definition_id), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when value is missing' do
+ it 'returns 422' do
+ post :create, params: create_params.merge(value: ''), as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when a custom field for the same definition already exists' do
+ before do
+ create(:metafield, resource: product, metafield_definition: short_text_definition, value: 'cotton')
+ end
+
+ it 'returns 422 (uniqueness on definition + resource)' do
+ post :create, params: create_params, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'when the parent does not exist' do
+ it 'returns 404' do
+ post :create, params: create_params.merge(product_id: 'prod_NotARealId'), as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+ end
+
+ describe 'PATCH #update' do
+ let!(:custom_field) do
+ create(:metafield, resource: product, metafield_definition: short_text_definition, value: 'wool')
+ end
+
+ it "updates the custom field's value" do
+ patch :update,
+ params: { product_id: product.prefixed_id, id: custom_field.prefixed_id, value: 'cotton' },
+ as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['value']).to eq('cotton')
+ expect(custom_field.reload.value).to eq('cotton')
+ end
+
+ it 'ignores attempts to swap the linked definition' do
+ patch :update,
+ params: {
+ product_id: product.prefixed_id,
+ id: custom_field.prefixed_id,
+ value: 'cotton',
+ custom_field_definition_id: long_text_definition.prefixed_id
+ },
+ as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(custom_field.reload.metafield_definition_id).to eq(short_text_definition.id)
+ end
+
+ it 'returns 404 when the custom field does not belong to the parent' do
+ sibling = create(:product)
+ foreign = create(:metafield, resource: sibling, metafield_definition: long_text_definition,
+ type: 'Spree::Metafields::LongText', value: 'foreign')
+
+ patch :update,
+ params: { product_id: product.prefixed_id, id: foreign.prefixed_id, value: 'x' },
+ as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ let!(:custom_field) do
+ create(:metafield, resource: product, metafield_definition: short_text_definition, value: 'wool')
+ end
+
+ it 'destroys the custom field' do
+ delete :destroy, params: { product_id: product.prefixed_id, id: custom_field.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::CustomField.where(id: custom_field.id)).to be_empty
+ end
+
+ it 'does not destroy a custom field that belongs to a sibling parent' do
+ sibling = create(:product)
+ foreign = create(:metafield, resource: sibling, metafield_definition: long_text_definition,
+ type: 'Spree::Metafields::LongText', value: 'foreign')
+
+ delete :destroy, params: { product_id: product.prefixed_id, id: foreign.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ expect(Spree::CustomField.where(id: foreign.id)).to exist
+ end
+ end
+
+ describe 'API key scope enforcement' do
+ let(:api_key) { create(:api_key, :secret, store: store, scopes: [granted_scope]) }
+ let(:api_key_headers) { { 'x-spree-api-key' => api_key.plaintext_token } }
+ let(:headers) { api_key_headers }
+
+ context 'with a key that grants write_products' do
+ let(:granted_scope) { 'write_products' }
+
+ it 'allows creating a product custom field' do
+ post :create,
+ params: {
+ product_id: product.prefixed_id,
+ custom_field_definition_id: short_text_definition.prefixed_id,
+ value: 'wool'
+ },
+ as: :json
+
+ expect(response).to have_http_status(:created)
+ end
+ end
+
+ context 'with a key that only grants read_products' do
+ let(:granted_scope) { 'read_products' }
+
+ it 'allows reading' do
+ create(:metafield, resource: product, metafield_definition: short_text_definition, value: 'wool')
+
+ get :index, params: { product_id: product.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it 'rejects writing with 403' do
+ post :create,
+ params: {
+ product_id: product.prefixed_id,
+ custom_field_definition_id: short_text_definition.prefixed_id,
+ value: 'wool'
+ },
+ as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ expect(json_response['error']['details']['required_scope']).to eq('write_products')
+ end
+ end
+
+ context 'with a key that grants write_orders but not write_products' do
+ let(:granted_scope) { 'write_orders' }
+
+ it 'rejects with 403' do
+ post :create,
+ params: {
+ product_id: product.prefixed_id,
+ custom_field_definition_id: short_text_definition.prefixed_id,
+ value: 'wool'
+ },
+ as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_polymorphic_parent_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_polymorphic_parent_spec.rb
new file mode 100644
index 0000000000..b639c4bb1a
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_polymorphic_parent_spec.rb
@@ -0,0 +1,51 @@
+# Confirms the parent-from-route inference works for every first-class parent
+# the route concern is applied to. One smoke test per parent is enough — the
+# CRUD logic is covered by the products-scoped controller spec.
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::CustomFieldsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ before { request.headers.merge!(headers) }
+
+ shared_examples 'parent-from-route inference' do |parent_factory:, definition_trait:, param_key:|
+ let!(:parent) { create(parent_factory) }
+ let!(:definition) { create(:metafield_definition, definition_trait) }
+ let!(:custom_field) do
+ create(:metafield, resource: parent, metafield_definition: definition,
+ type: definition.metafield_type,
+ value: 'value-for-parent')
+ end
+
+ it 'returns the parent\'s custom fields' do
+ get :index, params: { param_key => parent.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ values = json_response['data'].map { |cf| cf['value'] }
+ expect(values).to include('value-for-parent')
+ end
+ end
+
+ describe 'orders' do
+ include_examples 'parent-from-route inference',
+ parent_factory: :order,
+ definition_trait: :for_order,
+ param_key: :order_id
+ end
+
+ describe 'customers' do
+ include_examples 'parent-from-route inference',
+ parent_factory: :user,
+ definition_trait: :for_user,
+ param_key: :customer_id
+ end
+
+ describe 'variants' do
+ include_examples 'parent-from-route inference',
+ parent_factory: :variant,
+ definition_trait: :for_variant,
+ param_key: :variant_id
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
new file mode 100644
index 0000000000..d7cf885176
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:product_definition) do
+ create(:metafield_definition, :short_text_field, namespace: 'specs', key: 'fabric')
+ end
+ let!(:order_definition) do
+ create(:metafield_definition, :for_order)
+ end
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/custom_field_definitions' do
+ get 'List custom field definitions' do
+ tags 'Custom Fields'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.'
+ admin_scope :read, :custom_field_definitions
+
+ admin_sdk_example <<~JS
+ const { data: definitions } = await client.customFieldDefinitions.list({
+ q: { resource_type_eq: 'Spree::Product' },
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'definitions returned' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].length).to be >= 2
+ item = data['data'].find { |d| d['key'] == 'fabric' }
+ expect(item['namespace']).to eq('specs')
+ expect(item['field_type']).to eq('short_text')
+ expect(item['storefront_visible']).to eq(true)
+ expect(item['resource_type']).to eq('Spree::Product')
+ end
+ end
+ end
+
+ post 'Create a custom field definition' do
+ tags 'Custom Fields'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :custom_field_definitions
+
+ admin_sdk_example <<~JS
+ const definition = await client.customFieldDefinitions.create({
+ namespace: 'specs',
+ key: 'origin',
+ label: 'Country of Origin',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true,
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[key field_type resource_type],
+ properties: {
+ namespace: { type: :string, description: 'Defaults to `custom`' },
+ key: { type: :string },
+ label: { type: :string, description: 'Human-readable name; defaults to titleized `key`' },
+ field_type: {
+ type: :string,
+ description: 'Custom field type identifier (one of the registered field-type class names).'
+ },
+ resource_type: {
+ type: :string,
+ description: 'Owner class, e.g. `Spree::Product`'
+ },
+ storefront_visible: {
+ type: :boolean,
+ description: 'When false, definition is admin-only (was `display_on: back_end`)'
+ }
+ }
+ }
+
+ response '201', 'definition created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) do
+ {
+ namespace: 'specs',
+ key: 'origin',
+ label: 'Country of Origin',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true
+ }
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['key']).to eq('origin')
+ expect(data['label']).to eq('Country of Origin')
+ expect(data['field_type']).to eq('short_text')
+ expect(data['storefront_visible']).to eq(true)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/custom_field_definitions/{id}' do
+ let(:id) { product_definition.prefixed_id }
+
+ get 'Show a custom field definition' do
+ tags 'Custom Fields'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :custom_field_definitions
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'definition found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(product_definition.prefixed_id)
+ expect(data['key']).to eq('fabric')
+ end
+ end
+ end
+
+ patch 'Update a custom field definition' do
+ tags 'Custom Fields'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :custom_field_definitions
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ label: { type: :string },
+ storefront_visible: { type: :boolean }
+ }
+ }
+
+ response '200', 'definition updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { label: 'Fabric Composition', storefront_visible: false } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['label']).to eq('Fabric Composition')
+ expect(data['storefront_visible']).to eq(false)
+ end
+ end
+ end
+
+ delete 'Delete a custom field definition' do
+ tags 'Custom Fields'
+ security [api_key: [], bearer_auth: []]
+ description 'Deletes the definition and cascades to all custom field values referencing it.'
+ admin_scope :write, :custom_field_definitions
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'definition deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do
+ expect(Spree::CustomFieldDefinition.where(id: product_definition.id)).to be_empty
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/products/custom_fields_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products/custom_fields_spec.rb
new file mode 100644
index 0000000000..9946d300f7
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/products/custom_fields_spec.rb
@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Product Custom Fields API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:product) { create(:product) }
+ let!(:definition) { create(:metafield_definition, :short_text_field) }
+ let!(:custom_field) do
+ create(:metafield, resource: product, metafield_definition: definition, value: 'wool')
+ end
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/products/{product_id}/custom_fields' do
+ let(:product_id) { product.prefixed_id }
+
+ get 'List product custom fields' do
+ tags 'Products'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the product's custom field values."
+ admin_scope :read, :products
+
+ admin_sdk_example <<~JS
+ const { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+
+ response '200', 'custom fields found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].length).to eq(1)
+ expect(data['data'].first['value']).to eq('wool')
+ expect(data['data'].first['custom_field_definition_id']).to eq(definition.prefixed_id)
+ end
+ end
+ end
+
+ post 'Create a product custom field' do
+ tags 'Products'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id."
+ admin_scope :write, :products
+
+ admin_sdk_example <<~JS
+ const customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
+ custom_field_definition_id: 'cfdef_AbC123XyZ',
+ value: 'wool',
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[custom_field_definition_id value],
+ properties: {
+ custom_field_definition_id: { type: :string, description: 'Prefixed `cfdef_…` id' },
+ value: { description: 'Value matching the definition\'s `field_type`' }
+ }
+ }
+
+ response '201', 'custom field created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:other_definition) { create(:metafield_definition, :long_text_field) }
+ let(:body) do
+ {
+ custom_field_definition_id: other_definition.prefixed_id,
+ value: 'A longer description'
+ }
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['value']).to eq('A longer description')
+ expect(data['custom_field_definition_id']).to eq(other_definition.prefixed_id)
+ end
+ end
+
+ response '422', 'duplicate definition for the same product' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) do
+ { custom_field_definition_id: definition.prefixed_id, value: 'cotton' }
+ end
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/products/{product_id}/custom_fields/{id}' do
+ let(:product_id) { product.prefixed_id }
+ let(:id) { custom_field.prefixed_id }
+
+ get 'Show a product custom field' do
+ tags 'Products'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :products
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'custom field found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(custom_field.prefixed_id)
+ expect(data['value']).to eq('wool')
+ end
+ end
+ end
+
+ patch 'Update a product custom field' do
+ tags 'Products'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates the custom field\'s `value`. The linked definition cannot be changed — delete and recreate to switch.'
+ admin_scope :write, :products
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[value],
+ properties: { value: { description: 'New value' } }
+ }
+
+ response '200', 'custom field updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { value: 'cotton' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['value']).to eq('cotton')
+ end
+ end
+ end
+
+ delete 'Delete a product custom field' do
+ tags 'Products'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :products
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'custom field deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do
+ expect(Spree::CustomField.where(id: custom_field.id)).to be_empty
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/api_key.rb b/spree/core/app/models/spree/api_key.rb
index 0bb74834f6..a47dcf1d1d 100644
--- a/spree/core/app/models/spree/api_key.rb
+++ b/spree/core/app/models/spree/api_key.rb
@@ -19,6 +19,7 @@ module Spree
read_gift_cards write_gift_cards
read_store_credits write_store_credits
read_categories write_categories
+ read_custom_field_definitions write_custom_field_definitions
read_settings write_settings
read_webhooks write_webhooks
read_dashboard
diff --git a/spree/core/app/models/spree/custom_field.rb b/spree/core/app/models/spree/custom_field.rb
new file mode 100644
index 0000000000..bef54706ee
--- /dev/null
+++ b/spree/core/app/models/spree/custom_field.rb
@@ -0,0 +1,9 @@
+module Spree
+ # Constant alias for the legacy Spree::Metafield class. Lets controllers,
+ # serializers, and 5.5+ extensions reference the model by its 6.0-bound name
+ # without the actual class rename (which lands with the table rename in 6.0).
+ #
+ # This is a true constant alias — the underlying class, table, STI subclasses,
+ # and `model_name` are all `Spree::Metafield`. Only the constant name differs.
+ CustomField = Metafield
+end
diff --git a/spree/core/app/models/spree/custom_field_definition.rb b/spree/core/app/models/spree/custom_field_definition.rb
new file mode 100644
index 0000000000..a9bd22ac02
--- /dev/null
+++ b/spree/core/app/models/spree/custom_field_definition.rb
@@ -0,0 +1,7 @@
+module Spree
+ # Constant alias for the legacy Spree::MetafieldDefinition class. Lets
+ # controllers, serializers, and 5.5+ extensions reference the model by its
+ # 6.0-bound name without the actual class rename (which lands with the table
+ # rename in 6.0).
+ CustomFieldDefinition = MetafieldDefinition
+end
diff --git a/spree/core/app/models/spree/metafield.rb b/spree/core/app/models/spree/metafield.rb
index c950d68368..fb07425c1e 100644
--- a/spree/core/app/models/spree/metafield.rb
+++ b/spree/core/app/models/spree/metafield.rb
@@ -1,5 +1,26 @@
module Spree
class Metafield < Spree.base_class
+ # Map of API-facing tokens to Ruby STI class names. The wire format is the
+ # token (`short_text`); the database column stores the class name. Reads
+ # translate to the token via `field_type`; writes accept either form.
+ # Plugin-defined types fall through to the raw class name until 6.0 when a
+ # registration API lands.
+ TYPE_TOKENS = {
+ 'short_text' => 'Spree::Metafields::ShortText',
+ 'long_text' => 'Spree::Metafields::LongText',
+ 'rich_text' => 'Spree::Metafields::RichText',
+ 'number' => 'Spree::Metafields::Number',
+ 'boolean' => 'Spree::Metafields::Boolean',
+ 'json' => 'Spree::Metafields::Json'
+ }.freeze
+ TYPE_CLASS_TO_TOKEN = TYPE_TOKENS.invert.freeze
+
+ # Array form consumed by serializers via
+ # `typelize field_type: Spree::Metafield::FIELD_TYPE_TOKENS`. Typelizer
+ # emits a string-literal union in TypeScript and `{type: string, enum: […]}`
+ # in OpenAPI (string-array form was added in typelizer 0.10.0).
+ FIELD_TYPE_TOKENS = TYPE_TOKENS.keys.freeze
+
has_prefix_id :cf
#
@@ -8,6 +29,21 @@ module Spree
belongs_to :resource, polymorphic: true, touch: true
belongs_to :metafield_definition, class_name: 'Spree::MetafieldDefinition'
+ #
+ # API naming bridge — internal column rename lands in 6.0
+ #
+ alias_attribute :custom_field_definition_id, :metafield_definition_id
+
+ # API-facing form of the STI `type` column. Returns the token
+ # (`short_text`) when the row's type is a registered built-in; falls
+ # through to the raw class name for plugin types.
+ #
+ # `self[:type]` reads the raw column to bypass AR's STI reader (which
+ # returns the resolved class constant, not a string).
+ def field_type
+ TYPE_CLASS_TO_TOKEN[self[:type]] || self[:type]
+ end
+
#
# Delegations
#
@@ -43,6 +79,8 @@ module Spree
private
def set_type_from_metafield_definition
+ return if metafield_definition.blank?
+
self.type ||= metafield_definition.metafield_type
end
diff --git a/spree/core/app/models/spree/metafield_definition.rb b/spree/core/app/models/spree/metafield_definition.rb
index 4c00cfa10b..d774cc40c6 100644
--- a/spree/core/app/models/spree/metafield_definition.rb
+++ b/spree/core/app/models/spree/metafield_definition.rb
@@ -18,6 +18,7 @@ module Spree
validates :metafield_type, presence: true, inclusion: { in: :valid_available_types }
validates :resource_type, presence: true, inclusion: { in: :valid_available_resources }
validates :key, uniqueness: { scope: spree_base_uniqueness_scope + [:resource_type, :namespace] }
+ validate :field_type_input_must_be_recognized
#
# Scopes
@@ -51,14 +52,37 @@ module Spree
self.whitelisted_ransackable_attributes = %w[key namespace name resource_type display_on]
self.whitelisted_ransackable_scopes = %w[search multi_search]
- # 5.5 API naming bridge (DB column rename in 6.0)
- # Aligns with OptionType/OptionValue which also expose `label` for the display name.
- def label
- name
+ # API naming bridge — internal columns rename in 6.0.
+ # `label` matches OptionType/OptionValue conventions.
+ # `storefront_visible` maps the boolean API field to the
+ # `display_on: 'both'/'back_end'` string enum.
+ alias_attribute :label, :name
+
+ # API-facing token for the STI subclass name stored in `metafield_type`.
+ # Reader returns the registered token (`short_text`); writer accepts either
+ # the token or the legacy class-name form for back-compat.
+ def field_type
+ Spree::Metafield::TYPE_CLASS_TO_TOKEN[metafield_type] || metafield_type
end
- def label=(value)
- self.name = value
+ def field_type=(value)
+ v = value.to_s
+ mapped = Spree::Metafield::TYPE_TOKENS[v]
+ # An input is "recognized" when it's either a known token (mapped to a
+ # class) or already a known class name. Anything else gets surfaced as
+ # an error on `field_type` so API clients get a token-vocabulary
+ # message instead of the raw class-name inclusion error on
+ # `metafield_type`.
+ @field_type_input_recognized = !mapped.nil? || Spree::Metafield::TYPE_CLASS_TO_TOKEN.key?(v)
+ self.metafield_type = mapped || value
+ end
+
+ def storefront_visible
+ available_on_front_end?
+ end
+
+ def storefront_visible=(value)
+ self.display_on = ActiveModel::Type::Boolean.new.cast(value) ? 'both' : 'back_end'
end
# Returns the full key with namespace
@@ -91,6 +115,13 @@ module Spree
self.class.available_types.map(&:to_s)
end
+ def field_type_input_must_be_recognized
+ return if @field_type_input_recognized.nil? || @field_type_input_recognized
+
+ tokens = Spree::Metafield::TYPE_TOKENS.keys.join(', ')
+ errors.add(:field_type, "is not a known custom field type (expected one of: #{tokens})")
+ end
+
def valid_available_resources
self.class.available_resources.map(&:to_s)
end
diff --git a/spree/core/spec/models/spree/custom_field_definition_spec.rb b/spree/core/spec/models/spree/custom_field_definition_spec.rb
new file mode 100644
index 0000000000..2b68ffe1a2
--- /dev/null
+++ b/spree/core/spec/models/spree/custom_field_definition_spec.rb
@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+RSpec.describe 'Spree::CustomFieldDefinition constant alias' do
+ it 'aliases Spree::MetafieldDefinition' do
+ expect(Spree::CustomFieldDefinition).to equal(Spree::MetafieldDefinition)
+ end
+
+ it 'lets the alias serve as a model entry point' do
+ defn = Spree::CustomFieldDefinition.new(
+ namespace: 'specs',
+ key: 'fabric',
+ label: 'Fabric',
+ field_type: 'Spree::Metafields::ShortText',
+ resource_type: 'Spree::Product'
+ )
+ expect(defn).to be_valid
+ end
+
+ describe 'field_type input validation' do
+ let(:base_attrs) do
+ { namespace: 'specs', key: 'fabric', label: 'Fabric', resource_type: 'Spree::Product' }
+ end
+
+ it 'accepts the token form' do
+ defn = Spree::CustomFieldDefinition.new(base_attrs.merge(field_type: 'short_text'))
+ expect(defn).to be_valid
+ expect(defn.field_type).to eq('short_text')
+ end
+
+ it 'accepts the legacy class-name form' do
+ defn = Spree::CustomFieldDefinition.new(base_attrs.merge(field_type: 'Spree::Metafields::ShortText'))
+ expect(defn).to be_valid
+ expect(defn.field_type).to eq('short_text')
+ end
+
+ it 'reports an error on `field_type` with the token vocabulary for typo input' do
+ defn = Spree::CustomFieldDefinition.new(base_attrs.merge(field_type: 'shrt_text'))
+ expect(defn).not_to be_valid
+ expect(defn.errors[:field_type]).to include(a_string_matching(/short_text.*long_text/))
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/custom_field_spec.rb b/spree/core/spec/models/spree/custom_field_spec.rb
new file mode 100644
index 0000000000..10a7961e4a
--- /dev/null
+++ b/spree/core/spec/models/spree/custom_field_spec.rb
@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+RSpec.describe 'Spree::CustomField constant alias' do
+ it 'aliases Spree::Metafield' do
+ expect(Spree::CustomField).to equal(Spree::Metafield)
+ end
+
+ it 'lets the alias serve as a model entry point' do
+ product = create(:product)
+ definition = create(:metafield_definition, :short_text_field)
+
+ cf = Spree::CustomField.new(
+ resource: product,
+ custom_field_definition_id: definition.id,
+ value: 'wool'
+ )
+ expect(cf.save).to be(true)
+ expect(Spree::CustomField.find(cf.id).value).to eq('wool')
+ end
+end