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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Custom Fields support for Admin API / SDK
Damian Legawiecd8792db56c40
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex 5eb0a31d4c..12ec62d974 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -39,6 +39,282 @@ info:```version: v3paths:+ "/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: falsestate_name: New Yorklabel:- 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_UkLWZg9DAJmetadata:meta:@@ -194,8 +470,8 @@ paths:is_default_shipping: falsestate_name: New Yorklabel: 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_UkLWZg9DAJmetadata:requestBody:@@ -306,8 +582,8 @@ paths:is_default_shipping: falsestate_name: New Yorklabel:- 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_UkLWZg9DAJmetadata:requestBody:@@ -426,8 +702,8 @@ paths:gateway_payment_profile_id:customer_id: cus_UkLWZg9DAJpayment_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: 1limit: 25@@ -499,8 +775,8 @@ paths:gateway_payment_profile_id:customer_id: cus_UkLWZg9DAJpayment_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 cardtags:@@ -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_UkLWZg9DAJcreated_by_id: admin_UkLWZg9DAJmetadata:@@ -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_UkLWZg9DAJcreated_by_id: admin_gbHJdmfrXBmetadata:@@ -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_UkLWZg9DAJcreated_by_id: admin_UkLWZg9DAJmetadata:@@ -904,8 +1180,8 @@ paths:login: [email protected]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: 0failed_attempts: 0last_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: 0failed_attempts: 0last_sign_in_ip:@@ -1098,8 +1374,8 @@ paths:login: [email protected]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: 0failed_attempts: 0last_sign_in_ip:@@ -1173,8 +1449,8 @@ paths:login: [email protected]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: 0failed_attempts: 0last_sign_in_ip:@@ -1299,11 +1575,11 @@ paths:example:user:id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Eugena- last_name: Schinner- created_at: '2026-04-30T17:39:16.150Z'- updated_at: '2026-04-30T17:39:16.150Z'+ email: [email protected]+ first_name: Brice+ last_name: Wunsch+ created_at: '2026-05-04T08:18:13.278Z'+ updated_at: '2026-05-04T08:18:13.278Z'permissions:- allow: trueactions:@@ -1434,8 +1710,8 @@ paths:label: Sizeposition: 1kind: 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: Materialposition: 2kind: 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: Sizeposition: 1kind: 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 Presentationposition: 1kind: 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: H91580344267tracking: U10000tracking_url:cost: '10.0'@@ -1874,8 +2150,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -1944,7 +2220,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H66722024407+ number: H45072272093tracking: U10000tracking_url:cost: '10.0'@@ -1968,8 +2244,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2029,7 +2305,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H26951071944+ number: H05567524152tracking: 1Z999AA10123456784tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784cost: '10.0'@@ -2053,8 +2329,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2124,7 +2400,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H59010085771+ number: H32361035715tracking: U10000tracking_url:cost: '10.0'@@ -2141,15 +2417,15 @@ paths:display_tax_total: "$0.00"status: shippedfulfillment_type: shipping- fulfilled_at: '2026-04-30T17:39:21Z'+ fulfilled_at: '2026-05-04T08:18:18Z'items:- item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2208,7 +2484,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H11062995371+ number: H50596003602tracking: U10000tracking_url:cost: '10.0'@@ -2232,8 +2508,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2292,7 +2568,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H73917570309+ number: H37273886452tracking: U10000tracking_url:cost: '10.0'@@ -2316,8 +2592,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2379,7 +2655,7 @@ paths:example:data:- id: ful_gbHJdmfrXB- number: H45144705822+ number: H23393483302tracking:tracking_url:cost: '10.0'@@ -2403,8 +2679,8 @@ paths:quantity: 1adjustment_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_UkLWZg9DAJstock_location_id: sloc_gbHJdmfrXB@@ -2477,7 +2753,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: A606124B200C4A08+ code: 7DBCEEFC73F9FF66status: activecurrency: USDamount: '10.0'@@ -2491,8 +2767,8 @@ paths:redeemed_at:expired: falseactive: 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_gbHJdmfrXBquantity: 2currency: USD- name: Product 105238- slug: product-105238+ name: Product 102336+ slug: product-102336options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -2641,11 +2917,11 @@ paths:option_type_name: foo-size-10option_type_label: Sizeimage_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_VqXmZF31wYquantity: 3currency: USD- name: Product 123429- slug: product-123429+ name: Product 123967+ slug: product-123967options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -2745,11 +3021,11 @@ paths:option_type_name: foo-size-12option_type_label: Sizeimage_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_gbHJdmfrXBquantity: 2currency: USD- name: Product 132800- slug: product-132800+ name: Product 138668+ slug: product-138668options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -2857,11 +3133,11 @@ paths:option_type_name: foo-size-13option_type_label: Sizeimage_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_gbHJdmfrXBquantity: 5currency: USD- name: Product 146018- slug: product-146018+ name: Product 144376+ slug: product-144376options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -2956,11 +3232,11 @@ paths:option_type_name: foo-size-14option_type_label: Sizeimage_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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-a12cd90aafd6- number: PMY93VR3+ response_code: BGS-4ca27ab05995+ number: PKEYJ1FFamount: '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_gbHJdmfrXBpayment_method_id: pm_EfhxLZ9ck8response_code:- number: P3FUVY7V+ number: PDCYMWJUamount: '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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-b1cb046b71ce- number: PQJOW62R+ response_code: BGS-488350fca4f5+ number: PTHXUWEQamount: '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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-1a8085888edb- number: P3PJS3ID+ response_code: BGS-d953f655065f+ number: PJR0AOH3amount: '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_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: void-BGS-078ef0f90fcc- number: PY30IHFO+ response_code: void-BGS-f1e2ddbf894b+ number: PHWYXVBUamount: '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-82fec6976642amount: '5.0'payment_id: py_UkLWZg9DAJrefund_reason_id: rr_UkLWZg9DAJreimbursement_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_UkLWZg9DAJmarket_id:- number: R934946092- email: [email protected]+ number: R427865406+ email: [email protected]customer_note:currency: USDlocale: 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_UkLWZg9DAJmarket_id:- number: R073320480- email: [email protected]+ number: R572553723+ email: [email protected]customer_note:currency: USDlocale: 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_gbHJdmfrXBmarket_id:- number: R246782549+ number: R234115124email: [email protected]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_UkLWZg9DAJmarket_id:- number: R910724152- email: [email protected]+ number: R209363898+ email: [email protected]customer_note:currency: USDlocale: 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_UkLWZg9DAJmarket_id:- number: R310689257+ number: R829346308email: [email protected]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_UkLWZg9DAJmarket_id:- number: R273023523- email: [email protected]+ number: R135201417+ email: [email protected]customer_note:currency: USDlocale: en@@ -4586,7 +4862,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status: readypayment_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_UkLWZg9DAJmarket_id:- number: R833529851- email: [email protected]+ number: R080643573+ email: [email protected]customer_note:currency: USDlocale: en@@ -4710,7 +4986,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: canceledpayment_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_UkLWZg9DAJmarket_id:- number: R829205283- email: [email protected]+ number: R019437152+ email: [email protected]customer_note:currency: USDlocale: 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_UkLWZg9DAJmarket_id:- number: R399512921- email: [email protected]+ number: R431218252+ email: [email protected]customer_note:currency: USDlocale: en@@ -4914,7 +5190,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: canceledpayment_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_UkLWZg9DAJmarket_id:- number: R549593036- email: [email protected]+ number: R238735286+ email: [email protected]customer_note:currency: USDlocale: 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: falseactive: trueauto_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: 1limit: 25@@ -5156,8 +5432,294 @@ paths:source_required: falseactive: trueauto_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-391435meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-30T17:39:43.506Z'+ available_on: '2025-05-04T08:18:43.678Z'purchasable: truein_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: USDmeta:@@ -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: draftmake_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: USDschema:@@ -5618,27 +6171,36 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 379711- slug: product-379711+ name: Product 433377+ slug: product-433377meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-30T17:39:44.540Z'+ available_on: '2025-05-04T08:18:44.721Z'purchasable: truein_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: USDschema:@@ -5729,21 +6291,37 @@ paths:example:id: prod_UkLWZg9DAJname: Updated Name- slug: product-399957+ slug: product-458439meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-30T17:39:45.168Z'+ available_on: '2025-05-04T08:18:45.378Z'purchasable: truein_stock: falsebackorderable: trueavailable: 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_UkLWZg9DAJthumbnail_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: USDschema:@@ -6067,7 +6645,7 @@ paths:data:- id: variant_UkLWZg9DAJproduct_id: prod_UkLWZg9DAJ- sku: SKU-48+ sku: SKU-54options_text: ''track_inventory: truemedia_count: 0@@ -6097,13 +6675,13 @@ paths:cost_price: '17.0'cost_currency: USDdeleted_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 487682display_price: "$0.00"- id: variant_gbHJdmfrXBproduct_id: prod_UkLWZg9DAJ- sku: SKU-49+ sku: SKU-55options_text: 'Size: S'track_inventory: truemedia_count: 0@@ -6111,10 +6689,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 70.1- height: 190.68- width: 110.11- depth: 158.34+ weight: 121.22+ height: 104.22+ width: 183.8+ depth: 112.31price:id: price_gbHJdmfrXBamount: '19.99'@@ -6136,17 +6714,17 @@ paths:option_type_name: foo-size-16option_type_label: Sizeimage_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: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_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 487682display_price: "$19.99"meta:page: 1@@ -6257,17 +6835,17 @@ paths:option_type_name: sizeoption_type_label: Sizeimage_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: 3total_on_hand: 0tax_category_id: 1cost_price:cost_currency: USDdeleted_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 499403display_price: "$24.99"'422':description: validation error@@ -6440,7 +7018,7 @@ paths:example:id: variant_gbHJdmfrXBproduct_id: prod_UkLWZg9DAJ- sku: SKU-55+ sku: SKU-61options_text: 'Size: S'track_inventory: truemedia_count: 0@@ -6448,10 +7026,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 24.34- height: 38.8- width: 37.45- depth: 130.76+ weight: 51.48+ height: 25.56+ width: 36.76+ depth: 55.9price:id: price_gbHJdmfrXBamount: '19.99'@@ -6473,17 +7051,17 @@ paths:option_type_name: foo-size-19option_type_label: Sizeimage_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: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_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 518260display_price: "$19.99"'404':description: variant not found@@ -6563,10 +7141,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 149.67- height: 190.8- width: 68.1- depth: 71.17+ weight: 57.69+ height: 194.68+ width: 92.41+ depth: 68.65price:id: price_gbHJdmfrXBamount: '19.99'@@ -6588,17 +7166,17 @@ paths:option_type_name: foo-size-21option_type_label: Sizeimage_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: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_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 531666display_price: "$19.99"requestBody:content:@@ -7347,6 +7925,45 @@ components:- created_at- updated_atx-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: trueCustomField:type: objectproperties:@@ -7356,6 +7973,16 @@ components:type: stringtype:type: string+ deprecated: true+ field_type:+ type: string+ enum:+ - short_text+ - long_text+ - rich_text+ - number+ - boolean+ - jsonkey:type: stringvalue:@@ -7366,15 +7993,19 @@ components:type: stringstorefront_visible:type: boolean+ custom_field_definition_id:+ type: stringrequired:- id- label- type+ - field_type- key- value- created_at- updated_at- storefront_visible+ - custom_field_definition_idx-typelizer: trueCustomer:type: objectdiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex fe5bad1acb..cbe98219ad 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -102,7 +102,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 65 Lovely Street+ address1: 71 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -120,7 +120,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 64 Lovely Street+ address1: 70 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -138,7 +138,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 63 Lovely Street+ address1: 69 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -387,7 +387,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 77 Lovely Street+ address1: 83 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -462,7 +462,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 83 Lovely Street+ address1: 89 Lovely Streetaddress2: Northwestpostal_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: 8rovZTJMREzNzgUStfy9pgKuuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Mathew- last_name: Bayer+ first_name: Malisa+ last_name: Leuschkephone:accepts_email_marketing: false- full_name: Mathew Bayer+ full_name: Malisa Leuschkeavailable_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: FHiHaeJnXuFSAvh9LRvQL3bBuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Ahmad- last_name: Grady+ first_name: Anneliese+ last_name: Balistreriphone:accepts_email_marketing: false- full_name: Ahmad Grady+ full_name: Anneliese Balistreriavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -845,9 +845,9 @@ paths:data:- id: cart_gbHJdmfrXBmarket_id:- number: R182881602- token: 7xmFzBupB64Eqt1AJrjxAZshQ6hpfxqeukX- email: [email protected]+ number: R618887686+ token: SdM2BkjKUA6XPWqzhwZoZvmBGHFfGaXRpfK+ email: [email protected]customer_note:currency: USDlocale: en@@ -889,8 +889,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 477312- slug: product-477312+ name: Product 565163+ slug: product-565163options_text: ''price: '10.0'display_price: "$10.00"@@ -915,7 +915,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H50238594154+ number: H29558440573tracking: U10000tracking_url:cost: '100.0'@@ -944,7 +944,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rashida Ward+ name: Evelyne Stiedemannaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -976,7 +976,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 98 Lovely Street+ address1: 104 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -995,7 +995,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 99 Lovely Street+ address1: 105 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1014,9 +1014,9 @@ paths:market:- id: cart_UkLWZg9DAJmarket_id:- number: R180174120- token: M8LpDgv8esPyaFgerorVBCzTNxbbRBiBcH6- email: [email protected]+ number: R580209874+ token: 258t3vNeWcMi9BBqqiFH1xsnLaWrH2kZSzt+ email: [email protected]customer_note:currency: USDlocale: en@@ -1058,8 +1058,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 466677- slug: product-466677+ name: Product 557480+ slug: product-557480options_text: ''price: '10.0'display_price: "$10.00"@@ -1084,7 +1084,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H72269460516+ number: H03632429641tracking: U10000tracking_url:cost: '100.0'@@ -1113,7 +1113,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rashida Ward+ name: Evelyne Stiedemannaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1145,7 +1145,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 96 Lovely Street+ address1: 102 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1164,7 +1164,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 97 Lovely Street+ address1: 103 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1256,8 +1256,8 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R019335701- token: gt4CxjNxUGXa3c8guMYCXPvRMWBbpKPSDCy+ number: R512988572+ token: Jzia2KJwSNKSxQVpnDvKMfaxuHvVkmmHrhTemail:customer_note:currency: USD@@ -1412,9 +1412,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R136520724- token: RDTgrgyzKwVcNA6uExX2tPfK9FiT5RiXg5X- email: [email protected]+ number: R832102444+ token: ouoSYizfBMrzkSPKEgu8QUVvWQ9HDHYa7FA+ email: [email protected]customer_note:currency: USDlocale: 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 outline_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJstore_credit_total: '0.0'@@ -1466,7 +1466,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 106 Lovely Street+ address1: 112 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1485,7 +1485,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 107 Lovely Street+ address1: 113 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1583,9 +1583,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R589446831- token: 5jpsbFd46zdFZnxX83WMCjoaVuRUz5NjNCv- email: [email protected]+ number: R906855847+ token: YXZMcqYT6ywxEpj9S5GPjFRnUPpJrqVLaCn+ email: [email protected]customer_note: Leave at doorcurrency: USDlocale: en@@ -1629,8 +1629,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 52369- slug: product-52369+ name: Product 613243+ slug: product-613243options_text: ''price: '19.99'display_price: "$19.99"@@ -1655,7 +1655,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H91438962756+ number: H78556410272tracking:tracking_url:cost: '10.0'@@ -1684,7 +1684,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Ike Schumm+ name: Angla Cassinaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1716,7 +1716,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 110 Lovely Street+ address1: 116 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1735,7 +1735,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 111 Lovely Street+ address1: 117 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1921,9 +1921,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R265003786- token: aFhxuJ1gwfZ9RxSPHFyEdgDesj1URBDnDwg- email: [email protected]+ number: R931173712+ token: 7uLnCxRpQs3Sa1DMRyojktddwi1E4dueJZU+ email: [email protected]customer_note:currency: USDlocale: en@@ -1965,8 +1965,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 545852- slug: product-545852+ name: Product 631338+ slug: product-631338options_text: ''price: '10.0'display_price: "$10.00"@@ -1991,7 +1991,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H27932063184+ number: H42747051940tracking: U10000tracking_url:cost: '100.0'@@ -2020,7 +2020,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Hiram Schmidt+ name: Tana Runolfsdottiraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2052,7 +2052,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 116 Lovely Street+ address1: 122 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2071,7 +2071,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 117 Lovely Street+ address1: 123 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2154,8 +2154,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R600375601- email: [email protected]+ number: R719386816+ email: [email protected]customer_note:currency: USDlocale: en@@ -2182,7 +2182,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: backorderpayment_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_UkLWZg9DAJquantity: 1currency: USD- name: Product 566923- slug: product-566923+ name: Product 654923+ slug: product-654923options_text: ''price: '19.99'display_price: "$19.99"@@ -2218,7 +2218,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H21719438891+ number: H79182010537tracking:tracking_url:cost: '10.0'@@ -2247,7 +2247,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Zella Flatley+ name: Sunday Nicolasaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2276,8 +2276,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-3cd8d54d3a63- number: P5SEJH2N+ response_code: BGS-a3e2563c9b7a+ number: P8OVW6DMamount: '29.99'display_amount: "$29.99"status: completed@@ -2304,7 +2304,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 124 Lovely Street+ address1: 130 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2323,7 +2323,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 125 Lovely Street+ address1: 131 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2625,7 +2625,7 @@ paths:example:data:- iso: DE- iso3: IS32+ iso3: IS35name: Germanystates_required: falsezipcode_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: Rij6tnvCbRznq1sSJzoSGiUKuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Katlyn- last_name: Kuhn+ first_name: Stasia+ last_name: Danielphone:accepts_email_marketing: false- full_name: Katlyn Kuhn+ full_name: Stasia Danielavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -3312,8 +3312,8 @@ paths:data:- id: or_UkLWZg9DAJmarket_id:- number: R270430768- email: [email protected]+ number: R035435259+ email: [email protected]customer_note:currency: USDlocale: 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_UkLWZg9DAJquantity: 1currency: USD- name: Product 653038- slug: product-653038+ name: Product 746357+ slug: product-746357options_text: ''price: '10.0'display_price: "$10.00"@@ -3376,7 +3376,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H02369830101+ number: H28466111211tracking: U10000tracking_url:cost: '100.0'@@ -3405,7 +3405,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Shayla Gerlach+ name: Deandrea Wilkinsonaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3437,7 +3437,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 144 Lovely Street+ address1: 150 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3456,7 +3456,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 145 Lovely Street+ address1: 151 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3567,8 +3567,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R634795563- email: [email protected]+ number: R460046994+ email: [email protected]customer_note:currency: USDlocale: 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_UkLWZg9DAJquantity: 1currency: USD- name: Product 673736- slug: product-673736+ name: Product 762732+ slug: product-762732options_text: ''price: '10.0'display_price: "$10.00"@@ -3631,7 +3631,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H68508572865+ number: H17519938428tracking: U10000tracking_url:cost: '100.0'@@ -3660,7 +3660,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rivka Harvey+ name: Erlinda Ferryaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3692,7 +3692,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 150 Lovely Street+ address1: 156 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3711,7 +3711,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 151 Lovely Street+ address1: 157 Lovely Streetaddress2: Northwestpostal_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: amBVTCe49MBLT5yVXcTP7rJDuser:id: cus_UkLWZg9DAJemail: [email protected]@@ -3895,12 +3895,12 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Manuela- last_name: O'Kon+ email: [email protected]+ first_name: Lynell+ last_name: Westphone: 555-555-0199accepts_email_marketing: false- full_name: Manuela O'Kon+ full_name: Lynell Westavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses:@@ -3908,7 +3908,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 157 Lovely Street+ address1: 163 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3926,7 +3926,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 156 Lovely Street+ address1: 162 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3945,7 +3945,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 157 Lovely Street+ address1: 163 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3964,7 +3964,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 156 Lovely Street+ address1: 162 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4034,7 +4034,7 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199@@ -4047,7 +4047,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 159 Lovely Street+ address1: 165 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4065,7 +4065,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 158 Lovely Street+ address1: 164 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4084,7 +4084,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 159 Lovely Street+ address1: 165 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4103,7 +4103,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 158 Lovely Street+ address1: 164 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4274,9 +4274,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R686751507- token: PfLkSHCKhzw3ZFoT3Evj6bX72KEAePEERfW- email: [email protected]+ number: R215796217+ token: BBdNFUTVzy83u24enuPFKhbgh5dk51wWWEB+ email: [email protected]customer_note:currency: USDlocale: en@@ -4325,8 +4325,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 755782- slug: product-755782+ name: Product 848009+ slug: product-848009options_text: ''price: '10.0'display_price: "$10.00"@@ -4351,7 +4351,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H81703772553+ number: H98606593694tracking: U10000tracking_url:cost: '100.0'@@ -4380,7 +4380,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Larita Lakin+ name: Mana Hirtheaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4412,7 +4412,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 176 Lovely Street+ address1: 182 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4431,7 +4431,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 177 Lovely Street+ address1: 183 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4534,9 +4534,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R666419309- token: nc7Dy8DuA7PFHd5sn1zM2b8gpHDPfgEp1tt- email: [email protected]+ number: R769106477+ token: 4o4VZZGUXJmyKLQSe9KN1cJm9pcrfd9gqQ7+ email: [email protected]customer_note:currency: USDlocale: en@@ -4578,8 +4578,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 772017- slug: product-772017+ name: Product 862500+ slug: product-862500options_text: ''price: '10.0'display_price: "$10.00"@@ -4604,7 +4604,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H42154252733+ number: H13342204637tracking: U10000tracking_url:cost: '100.0'@@ -4633,7 +4633,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Margarett Hoeger+ name: Dolly Koeppaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4665,7 +4665,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 184 Lovely Street+ address1: 190 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4684,7 +4684,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 185 Lovely Street+ address1: 191 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4776,9 +4776,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R679060655- token: gePNeiWirzf2J7y37iBdarBX4qVLfs3eEgi- email: [email protected]+ number: R557817101+ token: 9xquwSgjHp1uzfydK6j3c8w1VSA9E9VKQxZ+ email: [email protected]customer_note:currency: USDlocale: en@@ -4822,8 +4822,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 796254- slug: product-796254+ name: Product 886097+ slug: product-886097options_text: ''price: '10.0'display_price: "$10.00"@@ -4848,7 +4848,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H02184977229+ number: H98772230904tracking: U10000tracking_url:cost: '100.0'@@ -4877,7 +4877,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Bridget Heller+ name: Cedrick Smithamaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4909,7 +4909,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 192 Lovely Street+ address1: 198 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4928,7 +4928,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 193 Lovely Street+ address1: 199 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5034,9 +5034,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R134922089- token: v2NsykGGYJxbRhYHnN1wb62cK4Q7KNoBxYx- email: [email protected]+ number: R726947393+ token: Khad7phz9S8A5xjfqQw38waD9HfpEyNKnHV+ email: [email protected]customer_note:currency: USDlocale: en@@ -5075,8 +5075,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 813626- slug: product-813626+ name: Product 903701+ slug: product-903701options_text: ''price: '10.0'display_price: "$10.00"@@ -5101,7 +5101,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H20006652345+ number: H17628770254tracking: U10000tracking_url:cost: '100.0'@@ -5130,7 +5130,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Taisha Koch+ name: Abbie Nitzscheaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5159,8 +5159,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429203120465620- number: PYZM56EO+ response_code: 1-SC-20260504081919984006+ number: P0XK3WL3amount: '50.0'display_amount: "$50.00"status: checkout@@ -5187,7 +5187,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 200 Lovely Street+ address1: 206 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5206,7 +5206,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 201 Lovely Street+ address1: 207 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5339,9 +5339,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R739841957- token: Zsmwu1S5EBR4ua9KCtREh1LboGrdYxeCjXh- email: [email protected]+ number: R773580298+ token: SCQJkkKqTF1VQmLY8oHgueJuWw6TZnxiv73+ email: [email protected]customer_note:currency: USDlocale: en@@ -5383,8 +5383,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 856826- slug: product-856826+ name: Product 945451+ slug: product-945451options_text: ''price: '10.0'display_price: "$10.00"@@ -5409,7 +5409,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H08780625784+ number: H38060487694tracking: U10000tracking_url:cost: '100.0'@@ -5438,7 +5438,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Lynsey Bode+ name: Aide O'Connelladdress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5467,8 +5467,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429203123363868- number: P605ZYX4+ response_code: 1-SC-20260504081922520413+ number: P1T1EVFAamount: '50.0'display_amount: "$50.00"status: invalid@@ -5495,7 +5495,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 216 Lovely Street+ address1: 222 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5514,7 +5514,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 217 Lovely Street+ address1: 223 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5592,7 +5592,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: 49492AAAF001FBB7+ code: 2EEC2C0A144AA41Estatus: activecurrency: USDamount: '10.0'@@ -5688,7 +5688,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: 7C8C28BE6FE5ECDE+ code: B032500DFD566D52status: activecurrency: USDamount: '10.0'@@ -5779,9 +5779,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R160774453- token: VshV5k2uUhjKTJj8apmDPv31xd5qkh3sh5Y- email: [email protected]+ number: R215627740+ token: ukn3dovsVnSmp7ZzUQAXcU9Uy5L6KPcUgJ4+ email: [email protected]customer_note:currency: USDlocale: en@@ -5829,8 +5829,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 888823- slug: product-888823+ name: Product 972562+ slug: product-972562options_text: ''price: '10.0'display_price: "$10.00"@@ -5857,8 +5857,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 895490- slug: product-895490+ name: Product 98775+ slug: product-98775options_text: ''price: '19.99'display_price: "$19.99"@@ -5888,7 +5888,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 231 Lovely Street+ address1: 237 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6001,9 +6001,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R417441624- token: 6fGMJoT6FeteiGKiWb7Awm5ZSeEZGUYFXPT- email: [email protected]+ number: R770436707+ token: oZ4bd4hojS9S32t8AhgeYNmdy2RWDt3q8z4+ email: [email protected]customer_note:currency: USDlocale: en@@ -6048,8 +6048,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 925658- slug: product-925658+ name: Product 101922+ slug: product-101922options_text: ''price: '10.0'display_price: "$10.00"@@ -6079,7 +6079,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 240 Lovely Street+ address1: 246 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6172,9 +6172,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R327511489- token: vz6NujDsYszBfSh8snFmiUjv4XN8jV22n8D- email: [email protected]+ number: R959911711+ token: fGLqoT7RVigFuCMbZQ64wR7nZdt6mV8bLj6+ email: [email protected]customer_note:currency: USDlocale: en@@ -6225,7 +6225,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 243 Lovely Street+ address1: 249 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6386,12 +6386,12 @@ paths:- frcountries:- iso: DE- iso3: IS59+ iso3: IS62name: Germanystates_required: falsezipcode_required: true- iso: FR- iso3: IS60+ iso3: IS63name: Francestates_required: falsezipcode_required: true@@ -6470,12 +6470,12 @@ paths:- frcountries:- iso: DE- iso3: IS63+ iso3: IS66name: Germanystates_required: falsezipcode_required: true- iso: FR- iso3: IS64+ iso3: IS67name: Francestates_required: falsezipcode_required: true@@ -6550,12 +6550,12 @@ paths:- frcountries:- iso: DE- iso3: IS67+ iso3: IS70name: Germanystates_required: falsezipcode_required: true- iso: FR- iso3: IS68+ iso3: IS71name: Francestates_required: falsezipcode_required: true@@ -6619,12 +6619,12 @@ paths:example:data:- iso: FR- iso3: IS72+ iso3: IS75name: Francestates_required: falsezipcode_required: true- iso: DE- iso3: IS71+ iso3: IS74name: Germanystates_required: falsezipcode_required: true@@ -6775,7 +6775,7 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R773500111+ number: R099312823email: [email protected]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_UkLWZg9DAJquantity: 1currency: USD- name: Product 966442- slug: product-966442+ name: Product 1051611+ slug: product-1051611options_text: ''price: '10.0'display_price: "$10.00"@@ -6839,7 +6839,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H86313255182+ number: H29105448841tracking: U10000tracking_url:cost: '100.0'@@ -6868,7 +6868,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Tandra Weber+ name: Lupe Welchaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6900,7 +6900,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 251 Lovely Street+ address1: 257 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6919,7 +6919,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 252 Lovely Street+ address1: 258 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -7013,9 +7013,9 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_5be4f6882cb65c798b36044b+ external_id: bogus_1cd883ef85a581926b812bf5external_data:- client_secret: bogus_secret_83acefba58c748fa+ client_secret: bogus_secret_c7d9d655c9959cd8customer_external_id:expires_at:amount: '110.0'@@ -7113,7 +7113,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_eea6b836764131d01d8930c3+ external_id: bogus_d12a4c4449ea25cafcca4b0bexternal_data:client_secret: secret_123customer_external_id:@@ -7175,7 +7175,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_c42d7bb8c46ce77865501174+ external_id: bogus_3906af62cca5c291d50963e3external_data:client_secret: secret_123customer_external_id:@@ -7277,7 +7277,7 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_da9af71a978676085b99ce61+ external_id: bogus_d18c75a6fd035f585624d7faexternal_data:client_secret: secret_123customer_external_id:@@ -7362,8 +7362,8 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_69d0c0fba541cf751511c029- external_client_secret: bogus_seti_secret_e91402dff84ebb58+ external_id: bogus_seti_f561720992e188ca83fe6437+ external_client_secret: bogus_seti_secret_99f60ae80c94b07bexternal_data: {}payment_method_id: pm_UkLWZg9DAJpayment_source_id:@@ -7462,8 +7462,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_c9f7f791cdf7b9c36dea5ae9- external_client_secret: seti_secret_e7cca325c5d0792f378adc51+ external_id: seti_test_ac2adbf49a51de7bbd63247f+ external_client_secret: seti_secret_4632ebeed41691d82c291f4cexternal_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -7539,8 +7539,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_73a3566842a3d01db9a800e0- external_client_secret: seti_secret_2f94274fab6af1dfb46b5b39+ external_id: seti_test_336c94146c6a51ba0194f2e3+ external_client_secret: seti_secret_90f14bb01966cba00ff4b199external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -7634,7 +7634,7 @@ paths:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJresponse_code:- number: PHAY8LI4+ number: PIIEW65Xamount: '110.0'display_amount: "$110.00"status: checkout@@ -7730,7 +7730,7 @@ paths:body_html: ''- id: pol_OIJLhNcSbfname: Privacy Policy- slug: privacy-policy-24a44547-bd29-493a-9028-25e30b0c6417+ slug: privacy-policy-96e1ecce-0357-480b-909e-d684265f3ec5body: 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-1158874meta_description:meta_keywords:variant_count: 1- available_on: '2025-04-29T20:31:41.571Z'+ available_on: '2025-05-04T08:19:40.720Z'purchasable: truein_stock: falsebackorderable: 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-1162830meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-29T20:31:41.632Z'+ available_on: '2025-05-04T08:19:40.780Z'purchasable: truein_stock: falsebackorderable: trueavailable: 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_EfhxLZ9ck8thumbnail_url:tags: []@@ -8136,12 +8118,12 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 1341741- slug: product-1341741+ name: Product 1434230+ slug: product-1434230meta_description:meta_keywords:variant_count: 1- available_on: '2025-04-29T20:31:43.333Z'+ available_on: '2025-05-04T08:19:42.365Z'purchasable: truein_stock: falsebackorderable: true@@ -8168,7 +8150,7 @@ paths:amount_in_cents: 999currency: USDdisplay_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_UkLWZg9DAJmarket_id:- number: R702444710- token: KKKKz15uUX3wLs3WeMci3aiDUn8NLgjRMRd- email: [email protected]+ number: R945566384+ token: pd95wgtA8uoLj2dVyav9nBsjUbopiEtiouS+ email: [email protected]customer_note:currency: USDlocale: en@@ -8584,8 +8566,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1546874- slug: product-1546874+ name: Product 1631788+ slug: product-1631788options_text: ''price: '10.0'display_price: "$10.00"@@ -8610,7 +8592,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H03249355163+ number: H72649836525tracking: U10000tracking_url:cost: '100.0'@@ -8639,7 +8621,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Nada Hettinger+ name: Natividad Hamilladdress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -8668,8 +8650,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429203148434892- number: POQWOLDS+ response_code: 1-SC-20260504081947644571+ number: PH7LEI1Pamount: '10.0'display_amount: "$10.00"status: checkout@@ -8696,7 +8678,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 315 Lovely Street+ address1: 321 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8715,7 +8697,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 316 Lovely Street+ address1: 322 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8812,9 +8794,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R968281647- token: vyW18bBrgGcr9BHW4DWLGKxUtYnnhyyRGVG- email: [email protected]+ number: R971986124+ token: EBUj579M5ZLmTAozTeeFz1UkKUo1PqYU51o+ email: [email protected]customer_note:currency: USDlocale: en@@ -8856,8 +8838,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1567335- slug: product-1567335+ name: Product 1658215+ slug: product-1658215options_text: ''price: '10.0'display_price: "$10.00"@@ -8882,7 +8864,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H34150382243+ number: H95990973054tracking: U10000tracking_url:cost: '100.0'@@ -8911,7 +8893,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Kylee Jones+ name: Linh Casperaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -8943,7 +8925,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 323 Lovely Street+ address1: 329 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8962,7 +8944,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 324 Lovely Street+ address1: 330 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9041,7 +9023,7 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: NtdmeixQzCBf9oTPYdxpf9Sv+ token: XVznyCqcTCE652qaPsdvEiUBis_default: falseis_private: truemeta:@@ -9117,7 +9099,7 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: 8cXeJyppojDAcyKGtrqEhahv+ token: QovG4j4AcaMhZU8SaUvXcLajis_default: falseis_private: trueschema:@@ -9213,7 +9195,7 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: 7kZxgV92WcKPHpXSc1Cn695L+ token: P35Ve31uYuQ4ciNbAx4u3yLwis_default: falseis_private: trueschema:@@ -9275,7 +9257,7 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: zTmZe61pQGipm76nbGax6Wii+ token: rWAv6WURLxPYHfpCnTFLKUKiis_default: falseis_private: trueschema:@@ -9390,7 +9372,7 @@ paths:variant:id: variant_gbHJdmfrXBproduct_id: prod_gbHJdmfrXB- sku: SKU-191+ sku: SKU-200options_text: ''track_inventory: truemedia_count: 0@@ -10159,6 +10141,16 @@ components:type: stringtype:type: string+ deprecated: true+ field_type:+ type: string+ enum:+ - short_text+ - long_text+ - rich_text+ - number+ - boolean+ - jsonkey:type: stringvalue:@@ -10167,6 +10159,7 @@ components:- id- label- type+ - field_type- key- valuex-typelizer: truediff --git a/docs/plans/5.4-6.0-custom-fields-rename.md b/docs/plans/5.5-6.0-custom-fields-rename.mdsimilarity index 51%rename from docs/plans/5.4-6.0-custom-fields-rename.mdrename to docs/plans/5.5-6.0-custom-fields-rename.mdindex 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_custThe 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 SimplificationFull 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.mdindex 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 codediff --git a/packages/admin-sdk/.changeset/admin-custom-fields-crud.md b/packages/admin-sdk/.changeset/admin-custom-fields-crud.mdnew file mode 100644index 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.yamlindex eb330d0fd9..5b19740977 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -151,6 +151,9 @@ importers:'@vitest/coverage-v8':specifier: ^4.1.5version: 4.1.5([email protected])+ msw:+ specifier: ^2.14.2+ version: 2.14.2(@types/[email protected])([email protected])tsup:specifier: ^8.0.0version: 8.5.1([email protected])([email protected])([email protected])([email protected])([email protected])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.rbindex 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 Spreereturn unless current_api_keyreturn 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_kinddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbindex 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 fieldsclass CustomFieldSerializer < V3::CustomFieldSerializer- typelize storefront_visible: :boolean+ typelize storefront_visible: :boolean,+ custom_field_definition_id: :stringattributes 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_idendendenddiff --git a/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rb b/spree/api/app/serializers/spree/api/v3/custom_field_serializer.rbindex 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 Spreemodule Apimodule 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_valueendendenddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 3f2712da3f..d462f2c154 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -91,6 +91,15 @@ Spree::Core::Engine.add_routes doendnamespace :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+# Authenticationpost 'auth/login', to: 'auth#create'post 'auth/refresh', to: 'auth#refresh'@@ -110,7 +119,7 @@ Spree::Core::Engine.add_routes doresources :direct_uploads, only: [:create]# Products- resources :products do+ resources :products, concerns: :custom_fieldable domember dopost :cloneend@@ -121,10 +130,10 @@ Spree::Core::Engine.add_routes doend# 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 Categoriesresources :tax_categories, only: [:index, :show]@@ -136,20 +145,20 @@ Spree::Core::Engine.add_routes doresources :tags, only: [:index]# Customers- resources :customers do+ resources :customers, concerns: :custom_fieldable doresources :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 domember dopatch :completepatch :canceldiff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 85b24a7fa5..15ddf5ce3c 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -166,6 +166,7 @@ module Spreeadmin_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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/api_key.rb b/spree/core/app/models/spree/api_key.rbindex 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 Spreeread_gift_cards write_gift_cardsread_store_credits write_store_creditsread_categories write_categories+ read_custom_field_definitions write_custom_field_definitionsread_settings write_settingsread_webhooks write_webhooksread_dashboarddiff --git a/spree/core/app/models/spree/custom_field.rb b/spree/core/app/models/spree/custom_field.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/custom_field_definition.rb b/spree/core/app/models/spree/custom_field_definition.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/metafield.rb b/spree/core/app/models/spree/metafield.rbindex c950d68368..fb07425c1e 100644--- a/spree/core/app/models/spree/metafield.rb+++ b/spree/core/app/models/spree/metafield.rb@@ -1,5 +1,26 @@module Spreeclass 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 Spreebelongs_to :resource, polymorphic: true, touch: truebelongs_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 Spreeprivatedef set_type_from_metafield_definition+ return if metafield_definition.blank?+self.type ||= metafield_definition.metafield_typeenddiff --git a/spree/core/app/models/spree/metafield_definition.rb b/spree/core/app/models/spree/metafield_definition.rbindex 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 Spreevalidates :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 Spreeself.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_typeend- 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 Spreeself.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_resourcesself.class.available_resources.map(&:to_s)enddiff --git a/spree/core/spec/models/spree/custom_field_definition_spec.rb b/spree/core/spec/models/spree/custom_field_definition_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/custom_field_spec.rb b/spree/core/spec/models/spree/custom_field_spec.rbnew file mode 100644index 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