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
Product media system: core data model + Store API (images → media) (#13778)
Damian Legawiecc3713dd59762
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex f90e17202d..fac9919efe 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -661,16 +661,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjNhMTQzMTZlLTQxN2MtNDRkNS05MWIzLTQ3YWRjZGY1YWFlMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMTkyfQ.-nJLamwDUlgW3KPN_OY0S9-3u9muXVzpYSPnBJKjpBE+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjI5MzJlYmY3LWNiNmUtNDdkNC1iYzc5LTI3YTU3YTJmYzYzNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTIzfQ.t5s-bHZ_RPSxJW3g-6Q-oryr8wKsy_gUllizQIwryS4user:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Emilia- last_name: Wehner+ first_name: Na+ last_name: Baileyphone:accepts_email_marketing: false- created_at: '2026-03-15T09:56:32.161Z'- updated_at: '2026-03-15T09:56:32.161Z'+ created_at: '2026-03-16T11:42:03.325Z'+ updated_at: '2026-03-16T11:42:03.325Z'addresses: []default_billing_address:default_shipping_address:@@ -747,16 +747,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImMxNjEwNDNjLWI1NjItNDU3YS05YjIwLTkwNTNhODJjNjZkMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMTkzfQ.0D4-S9NJHJF-W2YtiqshpVkEY4kiM7loXp-79cy-9pc+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY4ZjdkMmMwLWU1ZjEtNDBmZi1hMDg0LTBiMjA0Y2I2ZDAwMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTI0fQ.XQ0KorF8kID65mTA4wnxHtrQtoKU5P0SgKZfXx_utZwuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Tracey- last_name: Koss+ first_name: Shiloh+ last_name: Kutchphone:accepts_email_marketing: false- created_at: '2026-03-15T09:56:33.527Z'- updated_at: '2026-03-15T09:56:33.527Z'+ created_at: '2026-03-16T11:42:04.747Z'+ updated_at: '2026-03-16T11:42:04.747Z'addresses: []default_billing_address:default_shipping_address:@@ -814,9 +814,9 @@ paths:example:data:- id: cart_gbHJdmfrXB- number: R272337197- token: U9HRYmYTNAj3n1kngD1MupUfU1LT1GiKrrG- email: [email protected]+ number: R592928780+ token: GEAm9PwN7XmzKQ7JNmxx2n12ihh1gTJBgbG+ email: [email protected]special_instructions:currency: USDlocale: en@@ -837,8 +837,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:34.274Z'- updated_at: '2026-03-15T09:56:34.328Z'+ created_at: '2026-03-16T11:42:05.467Z'+ updated_at: '2026-03-16T11:42:05.516Z'current_step: addresscompleted_steps: []requirements:@@ -851,8 +851,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 21424- slug: product-21424+ name: Product 23018+ slug: product-23018options_text: ''price: '10.0'display_price: "$10.00"@@ -871,23 +871,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:34.306Z'- updated_at: '2026-03-15T09:56:34.306Z'+ created_at: '2026-03-16T11:42:05.497Z'+ updated_at: '2026-03-16T11:42:05.497Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_gbHJdmfrXB- number: H07549026034+ number: H54022746010state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:34.314Z'- updated_at: '2026-03-15T09:56:34.326Z'+ created_at: '2026-03-16T11:42:05.505Z'+ updated_at: '2026-03-16T11:42:05.514Z'shipping_method:id: shpm_gbHJdmfrXBname: UPS Ground@@ -895,7 +895,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_37- name: Caryl Feeney+ name: Raye Franeckiaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -950,9 +950,9 @@ paths:state_name: STATE_NAME_42payment_methods: []- id: cart_UkLWZg9DAJ- number: R741612804- token: 1Wnd3pNEjwU19G8iipANmeJ1ihP7n3j5pe3- email: [email protected]+ number: R472289234+ token: xwmD8eiHXxkGKntwxDEuERyn7Y1zn2eewCm+ email: [email protected]special_instructions:currency: USDlocale: en@@ -973,8 +973,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:34.100Z'- updated_at: '2026-03-15T09:56:34.268Z'+ created_at: '2026-03-16T11:42:05.317Z'+ updated_at: '2026-03-16T11:42:05.460Z'current_step: addresscompleted_steps: []requirements:@@ -987,8 +987,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 15258- slug: product-15258+ name: Product 14966+ slug: product-14966options_text: ''price: '10.0'display_price: "$10.00"@@ -1007,23 +1007,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:34.204Z'- updated_at: '2026-03-15T09:56:34.204Z'+ created_at: '2026-03-16T11:42:05.387Z'+ updated_at: '2026-03-16T11:42:05.387Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H33942229319+ number: H63711482146state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:34.220Z'- updated_at: '2026-03-15T09:56:34.263Z'+ created_at: '2026-03-16T11:42:05.400Z'+ updated_at: '2026-03-16T11:42:05.456Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1031,7 +1031,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_37- name: Caryl Feeney+ name: Raye Franeckiaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1159,8 +1159,8 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R820921292- token: 9YbrGXVaCKW3nXiUVZyzLCkzSGYyJomFZap+ number: R295996236+ token: NzSJZ3FryrE1GrCtYiQhpqkKGzr2xq8RBsdemail:special_instructions:currency: USD@@ -1182,8 +1182,8 @@ paths:display_additional_tax_total: "$0.00"total: '0.0'display_total: "$0.00"- created_at: '2026-03-15T09:56:34.825Z'- updated_at: '2026-03-15T09:56:34.825Z'+ created_at: '2026-03-16T11:42:05.981Z'+ updated_at: '2026-03-16T11:42:05.981Z'current_step: addresscompleted_steps: []requirements:@@ -1290,9 +1290,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R274060221- token: UfvdA4eYrAv2zSSFpookDap37GdR3pk51xh- email: [email protected]+ number: R734543831+ token: FdfRrq4gBGXE6Q9XjzmuMNLfkMaJH3QoHmu+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1313,8 +1313,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:35.105Z'- updated_at: '2026-03-15T09:56:35.160Z'+ created_at: '2026-03-16T11:42:06.262Z'+ updated_at: '2026-03-16T11:42:06.314Z'current_step: addresscompleted_steps: []requirements:@@ -1327,8 +1327,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 52481- slug: product-52481+ name: Product 59838+ slug: product-59838options_text: ''price: '10.0'display_price: "$10.00"@@ -1347,23 +1347,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:35.136Z'- updated_at: '2026-03-15T09:56:35.136Z'+ created_at: '2026-03-16T11:42:06.294Z'+ updated_at: '2026-03-16T11:42:06.294Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H88293867577+ number: H54892494980state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:35.141Z'- updated_at: '2026-03-15T09:56:35.158Z'+ created_at: '2026-03-16T11:42:06.298Z'+ updated_at: '2026-03-16T11:42:06.312Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1371,7 +1371,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_47- name: Florentino Kuhn+ name: Janetta Willmsaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1506,9 +1506,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R321260229- token: 7xXrFbBGu8uGBWPEWtmfyctkZmBmG7VWsym- email: [email protected]+ number: R504503846+ token: SQMBuPzUDarhEmJW5eDLNVWGPietZKKGryM+ email: [email protected]special_instructions: Leave at doorcurrency: USDlocale: en@@ -1529,8 +1529,8 @@ paths:display_additional_tax_total: "$0.00"total: '29.99'display_total: "$29.99"- created_at: '2026-03-15T09:56:35.810Z'- updated_at: '2026-03-15T09:56:36.017Z'+ created_at: '2026-03-16T11:42:06.890Z'+ updated_at: '2026-03-16T11:42:07.042Z'current_step: paymentcompleted_steps:- address@@ -1545,8 +1545,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 65837- slug: product-65837+ name: Product 69382+ slug: product-69382options_text: ''price: '19.99'display_price: "$19.99"@@ -1565,23 +1565,23 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:35.853Z'- updated_at: '2026-03-15T09:56:35.964Z'+ created_at: '2026-03-16T11:42:06.921Z'+ updated_at: '2026-03-16T11:42:06.997Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_gbHJdmfrXB- number: H35789928369+ number: H11758386245state: pendingtracking:tracking_url:cost: '10.0'display_cost: "$10.00"shipped_at:- created_at: '2026-03-15T09:56:35.983Z'- updated_at: '2026-03-15T09:56:35.999Z'+ created_at: '2026-03-16T11:42:07.015Z'+ updated_at: '2026-03-16T11:42:07.028Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1589,7 +1589,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_49- name: Luana Schuppe+ name: Sherrell Wintheiseraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1811,9 +1811,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R055833456- token: KQNMFNmjDq1ksBnKMPLyyN2fERN9FkT4EMX- email: [email protected]+ number: R645646809+ token: NR2WHSSdvEdvT32QiHz6cmDxJM7nPZeTWRt+ email: [email protected]special_instructions:currency: USDlocale: en@@ -1834,8 +1834,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:36.714Z'- updated_at: '2026-03-15T09:56:36.780Z'+ created_at: '2026-03-16T11:42:07.729Z'+ updated_at: '2026-03-16T11:42:07.797Z'current_step: addresscompleted_steps: []requirements:@@ -1848,8 +1848,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 84030- slug: product-84030+ name: Product 84356+ slug: product-84356options_text: ''price: '10.0'display_price: "$10.00"@@ -1868,23 +1868,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:36.755Z'- updated_at: '2026-03-15T09:56:36.755Z'+ created_at: '2026-03-16T11:42:07.772Z'+ updated_at: '2026-03-16T11:42:07.772Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H87986565781+ number: H79543816122state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:36.761Z'- updated_at: '2026-03-15T09:56:36.778Z'+ created_at: '2026-03-16T11:42:07.778Z'+ updated_at: '2026-03-16T11:42:07.795Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -1892,7 +1892,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_57- name: Emilee Osinski+ name: Karena Keebleraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2011,8 +2011,8 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R792302214- email: [email protected]+ number: R423170020+ email: [email protected]special_instructions:currency: USDlocale: en@@ -2035,17 +2035,17 @@ paths:display_additional_tax_total: "$0.00"total: '29.99'display_total: "$29.99"- completed_at: '2026-03-15T09:56:38.225Z'- created_at: '2026-03-15T09:56:37.947Z'- updated_at: '2026-03-15T09:56:38.225Z'+ completed_at: '2026-03-16T11:42:09.278Z'+ created_at: '2026-03-16T11:42:09.067Z'+ updated_at: '2026-03-16T11:42:09.278Z'promotions: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 106099- slug: product-106099+ name: Product 108826+ slug: product-108826options_text: ''price: '19.99'display_price: "$19.99"@@ -2064,23 +2064,23 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:37.981Z'- updated_at: '2026-03-15T09:56:38.230Z'+ created_at: '2026-03-16T11:42:09.098Z'+ updated_at: '2026-03-16T11:42:09.282Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_gbHJdmfrXB- number: H94144915344+ number: H38566815614state: pendingtracking:tracking_url:cost: '10.0'display_cost: "$10.00"shipped_at:- created_at: '2026-03-15T09:56:38.071Z'- updated_at: '2026-03-15T09:56:38.219Z'+ created_at: '2026-03-16T11:42:09.174Z'+ updated_at: '2026-03-16T11:42:09.273Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -2088,7 +2088,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_63- name: Darnell Weissnat+ name: Alejandro Hermannaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2111,11 +2111,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: completedresponse_code: '12345'- number: PKB74RGB+ number: PNDK0HINamount: '29.99'display_amount: "$29.99"- created_at: '2026-03-15T09:56:38.171Z'- updated_at: '2026-03-15T09:56:38.197Z'+ created_at: '2026-03-16T11:42:09.237Z'+ updated_at: '2026-03-16T11:42:09.258Z'source_type: credit_cardsource_id: card_UkLWZg9DAJsource:@@ -2247,8 +2247,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-15T09:56:38.892Z'- updated_at: '2026-03-15T09:56:38.957Z'+ created_at: '2026-03-16T11:42:09.914Z'+ updated_at: '2026-03-16T11:42:09.960Z'parent_id:description: ''description_html: ''@@ -2266,8 +2266,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-15T09:56:38.902Z'- updated_at: '2026-03-15T09:56:38.957Z'+ created_at: '2026-03-16T11:42:09.922Z'+ updated_at: '2026-03-16T11:42:09.960Z'parent_id: ctg_UkLWZg9DAJdescription: ''description_html: ''@@ -2285,8 +2285,8 @@ paths:meta_description:meta_keywords:children_count: 0- created_at: '2026-03-15T09:56:38.916Z'- updated_at: '2026-03-15T09:56:38.924Z'+ created_at: '2026-03-16T11:42:09.931Z'+ updated_at: '2026-03-16T11:42:09.936Z'parent_id: ctg_gbHJdmfrXBdescription: ''description_html: ''@@ -2387,8 +2387,8 @@ paths:meta_description:meta_keywords:children_count: 1- created_at: '2026-03-15T09:56:39.323Z'- updated_at: '2026-03-15T09:56:39.369Z'+ created_at: '2026-03-16T11:42:10.323Z'+ updated_at: '2026-03-16T11:42:10.356Z'parent_id: ctg_UkLWZg9DAJdescription: ''description_html: ''@@ -2515,16 +2515,17 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 19398- description: Minus similique repellat atque nobis. Fugiat placeat- repudiandae hic quam. Omnis error aperiam officiis repellat.- slug: product-19398+ name: Product 199134+ description: |-+ Distinctio ipsum totam optio impedit nobis. Voluptatum sapiente ab quidem ullam neque amet. Natus qui provident sunt occaecati suscipit eveniet. Sint voluptas aperiam inventore alias voluptatum voluptates.+ Ab a voluptas similique ratione eius omnis asperiores dicta. Alias atque corporis nobis doloremque facilis. Praesentium similique vero cupiditate voluptas inventore veritatis atque. Explicabo inventore illum fugit totam.+ slug: product-199134meta_description:meta_keywords:variant_count: 0- available_on: '2025-03-15T09:56:39.966Z'- created_at: '2026-03-15T09:56:39.981Z'- updated_at: '2026-03-15T09:56:39.998Z'+ available_on: '2025-03-16T11:42:10.781Z'+ created_at: '2026-03-16T11:42:10.794Z'+ updated_at: '2026-03-16T11:42:10.807Z'purchasable: truein_stock: falsebackorderable: true@@ -2794,9 +2795,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R239512747- token: DG7zZrtiYGCSVPJ265jT1Tiv5nsrR5etsk7- email: [email protected]+ number: R979204925+ token: KQSk4bW8gYhDWB97YXPPXQ64DHh2wzmPcVN+ email: [email protected]special_instructions:currency: USDlocale: en@@ -2817,8 +2818,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:41.865Z'- updated_at: '2026-03-15T09:56:41.983Z'+ created_at: '2026-03-16T11:42:12.519Z'+ updated_at: '2026-03-16T11:42:12.670Z'current_step: addresscompleted_steps: []requirements: []@@ -2828,8 +2829,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 23971- slug: product-23971+ name: Product 234469+ slug: product-234469options_text: ''price: '10.0'display_price: "$10.00"@@ -2848,23 +2849,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:41.903Z'- updated_at: '2026-03-15T09:56:41.903Z'+ created_at: '2026-03-16T11:42:12.568Z'+ updated_at: '2026-03-16T11:42:12.568Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H11031309423+ number: H07824285599state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:41.909Z'- updated_at: '2026-03-15T09:56:41.924Z'+ created_at: '2026-03-16T11:42:12.579Z'+ updated_at: '2026-03-16T11:42:12.603Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -2872,7 +2873,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_85- name: Aliza Bednar+ name: Tracy Trantowaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2894,12 +2895,12 @@ paths:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJstate: checkout- response_code: 1-SC-20260315095641975501- number: P7HJEX3A+ response_code: 1-SC-20260316114212663794+ number: PUZIDS8Mamount: '50.0'display_amount: "$50.00"- created_at: '2026-03-15T09:56:41.977Z'- updated_at: '2026-03-15T09:56:41.977Z'+ created_at: '2026-03-16T11:42:12.665Z'+ updated_at: '2026-03-16T11:42:12.665Z'source_type: store_creditsource_id: credit_UkLWZg9DAJsource:@@ -3042,9 +3043,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R737368305- token: hxLpj3PmQJveF8goUcH6yJ5g9fpNf3vwBwa- email: [email protected]+ number: R380290666+ token: JJqUnbpdK4uJfdGf4uQvsWxJ2VCDRZj3sXw+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3065,8 +3066,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:56:43.255Z'- updated_at: '2026-03-15T09:56:43.376Z'+ created_at: '2026-03-16T11:42:13.837Z'+ updated_at: '2026-03-16T11:42:13.934Z'current_step: addresscompleted_steps: []requirements:@@ -3079,8 +3080,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 254999- slug: product-254999+ name: Product 251943+ slug: product-251943options_text: ''price: '10.0'display_price: "$10.00"@@ -3099,23 +3100,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:43.290Z'- updated_at: '2026-03-15T09:56:43.369Z'+ created_at: '2026-03-16T11:42:13.864Z'+ updated_at: '2026-03-16T11:42:13.930Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H55998223093+ number: H93851004237state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:43.296Z'- updated_at: '2026-03-15T09:56:43.311Z'+ created_at: '2026-03-16T11:42:13.868Z'+ updated_at: '2026-03-16T11:42:13.881Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -3123,7 +3124,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_93- name: Kimberly Rolfson+ name: Maya Huelsaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3589,16 +3590,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJiMzViNzEzLThkMmEtNGU5Ni04MzI0LThlZmJjMDNhOGFjYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMjA4fQ.lvT_KdvwjKK9epprdnp52TsqSGzg1LG1J4Q9Tn8Bjsk+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImY2ZTZlYmFkLTQwZDgtNDViZi1hOGVlLThiM2IyYWU0NjcxZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTM5fQ.Cw26SBmNlH613s9ji0WNPUOmmTtgezQooaIWsWF84Kkuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Evelina- last_name: Herman+ first_name: Antonietta+ last_name: Deckowphone:accepts_email_marketing: false- created_at: '2026-03-15T09:56:48.256Z'- updated_at: '2026-03-15T09:56:48.531Z'+ created_at: '2026-03-16T11:42:18.809Z'+ updated_at: '2026-03-16T11:42:19.086Z'addresses: []default_billing_address:default_shipping_address:@@ -3686,8 +3687,8 @@ paths:example:data:- id: or_UkLWZg9DAJ- number: R351447625- email: [email protected]+ number: R294365647+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3710,17 +3711,17 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- completed_at: '2026-03-15T09:56:49.440Z'- created_at: '2026-03-15T09:56:49.382Z'- updated_at: '2026-03-15T09:56:49.440Z'+ completed_at: '2026-03-16T11:42:19.985Z'+ created_at: '2026-03-16T11:42:19.922Z'+ updated_at: '2026-03-16T11:42:19.985Z'promotions: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 276901- slug: product-276901+ name: Product 278791+ slug: product-278791options_text: ''price: '10.0'display_price: "$10.00"@@ -3739,23 +3740,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:49.416Z'- updated_at: '2026-03-15T09:56:49.416Z'+ created_at: '2026-03-16T11:42:19.960Z'+ updated_at: '2026-03-16T11:42:19.960Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H42845699184+ number: H73483267054state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:49.421Z'- updated_at: '2026-03-15T09:56:49.437Z'+ created_at: '2026-03-16T11:42:19.967Z'+ updated_at: '2026-03-16T11:42:19.983Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -3763,7 +3764,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_113- name: Carli Roob+ name: Shizuko Strosinaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3883,8 +3884,8 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R913804901- email: [email protected]+ number: R079052985+ email: [email protected]special_instructions:currency: USDlocale: en@@ -3907,17 +3908,17 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- completed_at: '2026-03-15T09:56:50.133Z'- created_at: '2026-03-15T09:56:50.077Z'- updated_at: '2026-03-15T09:56:50.132Z'+ completed_at: '2026-03-16T11:42:20.665Z'+ created_at: '2026-03-16T11:42:20.616Z'+ updated_at: '2026-03-16T11:42:20.665Z'promotions: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 293199- slug: product-293199+ name: Product 298764+ slug: product-298764options_text: ''price: '10.0'display_price: "$10.00"@@ -3936,23 +3937,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:50.109Z'- updated_at: '2026-03-15T09:56:50.109Z'+ created_at: '2026-03-16T11:42:20.646Z'+ updated_at: '2026-03-16T11:42:20.646Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H53393663228+ number: H31898065583state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:56:50.115Z'- updated_at: '2026-03-15T09:56:50.130Z'+ created_at: '2026-03-16T11:42:20.650Z'+ updated_at: '2026-03-16T11:42:20.663Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -3960,7 +3961,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_119- name: Halina Larson+ name: Lyman Doyleaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4066,7 +4067,7 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjEyMjRiMWQ0LWM5ODEtNDBhZC1iOWI5LTQxNTU2NmQ5NjY2MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMjExfQ.p1jhTIxt8zTeAy51FvCRmLJ9QNkr8A135crtZ-BTvxw+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImI2YTQ1YjIzLTFmNTAtNGNlZC04MGYzLTkyYzJhNTAzNzhhOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTQxfQ.Hbdwqg6sS8oS9UGKeCp-zGsD98oUKq859M23kq0mI2Auser:id: cus_UkLWZg9DAJemail: [email protected]@@ -4074,8 +4075,8 @@ paths:last_name: Doephone: "+1234567890"accepts_email_marketing: true- created_at: '2026-03-15T09:56:51.359Z'- updated_at: '2026-03-15T09:56:51.359Z'+ created_at: '2026-03-16T11:42:21.838Z'+ updated_at: '2026-03-16T11:42:21.838Z'addresses: []default_billing_address:default_shipping_address:@@ -4179,13 +4180,13 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Millie- last_name: Jerde+ email: [email protected]+ first_name: Jeramy+ last_name: Fritschphone: 555-555-0199accepts_email_marketing: false- created_at: '2026-03-15T09:56:51.908Z'- updated_at: '2026-03-15T09:56:52.178Z'+ created_at: '2026-03-16T11:42:22.380Z'+ updated_at: '2026-03-16T11:42:22.649Z'addresses:- id: addr_gbHJdmfrXBfirstname: John@@ -4309,13 +4310,13 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199accepts_email_marketing: false- created_at: '2026-03-15T09:56:52.468Z'- updated_at: '2026-03-15T09:56:52.749Z'+ created_at: '2026-03-16T11:42:22.943Z'+ updated_at: '2026-03-16T11:42:23.223Z'addresses:- id: addr_gbHJdmfrXBfirstname: John@@ -4539,7 +4540,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: B608F79E2170A577+ code: 28CABF0C75127A6Astate: activecurrency: USDamount: '10.0'@@ -4553,8 +4554,8 @@ paths:redeemed_at:expired: falseactive: true- created_at: '2026-03-15T09:56:55.879Z'- updated_at: '2026-03-15T09:56:55.879Z'+ created_at: '2026-03-16T11:42:26.268Z'+ updated_at: '2026-03-16T11:42:26.268Z'meta:page: 1limit: 25@@ -4637,7 +4638,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: 531FE0239DCE4448+ code: A8F57643BDF60F5Fstate: activecurrency: USDamount: '10.0'@@ -4651,8 +4652,8 @@ paths:redeemed_at:expired: falseactive: true- created_at: '2026-03-15T09:56:56.987Z'- updated_at: '2026-03-15T09:56:56.987Z'+ created_at: '2026-03-16T11:42:27.349Z'+ updated_at: '2026-03-16T11:42:27.349Z'schema:"$ref": "#/components/schemas/GiftCard"'404':@@ -4729,9 +4730,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R503264262- token: dt5Bn5EmpZZwYARF7WnTrRu92yV5nrkpvDX- email: [email protected]+ number: R452121802+ token: grWFKTAFcGQo6oZmZnr6tKM414FiJxQSACU+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4752,8 +4753,8 @@ paths:display_additional_tax_total: "$0.00"total: '29.99'display_total: "$29.99"- created_at: '2026-03-15T09:56:58.847Z'- updated_at: '2026-03-15T09:56:58.972Z'+ created_at: '2026-03-16T11:42:29.094Z'+ updated_at: '2026-03-16T11:42:29.196Z'current_step: addresscompleted_steps: []requirements:@@ -4772,8 +4773,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 398150- slug: product-398150+ name: Product 399968+ slug: product-399968options_text: ''price: '10.0'display_price: "$10.00"@@ -4792,8 +4793,8 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:58.883Z'- updated_at: '2026-03-15T09:56:58.883Z'+ created_at: '2026-03-16T11:42:29.118Z'+ updated_at: '2026-03-16T11:42:29.118Z'compare_at_amount:thumbnail_url:option_values: []@@ -4802,8 +4803,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 402535- slug: product-402535+ name: Product 404361+ slug: product-404361options_text: ''price: '19.99'display_price: "$19.99"@@ -4822,8 +4823,8 @@ paths:discounted_amount: '19.99'display_discounted_amount: "$19.99"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:56:58.928Z'- updated_at: '2026-03-15T09:56:58.928Z'+ created_at: '2026-03-16T11:42:29.158Z'+ updated_at: '2026-03-16T11:42:29.158Z'compare_at_amount:thumbnail_url:option_values: []@@ -4943,9 +4944,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R774166219- token: JMrytsemQpzmg8h11vACQazS7fyvTta8pBJ- email: [email protected]+ number: R198416438+ token: NnLWSHFmPCYkAzer8M5CJKZ8mfu4JPTYHUv+ email: [email protected]special_instructions:currency: USDlocale: en@@ -4966,8 +4967,8 @@ paths:display_additional_tax_total: "$0.00"total: '0.0'display_total: "$0.00"- created_at: '2026-03-15T09:57:00.741Z'- updated_at: '2026-03-15T09:57:00.791Z'+ created_at: '2026-03-16T11:42:30.955Z'+ updated_at: '2026-03-16T11:42:30.981Z'current_step: addresscompleted_steps: []requirements:@@ -4983,8 +4984,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 434622- slug: product-434622+ name: Product 436993+ slug: product-436993options_text: ''price: '10.0'display_price: "$10.00"@@ -5003,8 +5004,8 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:57:00.791Z'- updated_at: '2026-03-15T09:57:00.820Z'+ created_at: '2026-03-16T11:42:30.981Z'+ updated_at: '2026-03-16T11:42:30.997Z'compare_at_amount:thumbnail_url:option_values: []@@ -5104,9 +5105,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R315470094- token: 1Q4v5MBRVvdkfVV2CVDKkEji6cMcgZ7UCjK- email: [email protected]+ number: R559013003+ token: 3EjQ6SbAtYkmZXxS6py5axLK3STcURbj7QP+ email: [email protected]special_instructions:currency: USDlocale: en@@ -5127,8 +5128,8 @@ paths:display_additional_tax_total: "$0.00"total: '0.0'display_total: "$0.00"- created_at: '2026-03-15T09:57:01.391Z'- updated_at: '2026-03-15T09:57:01.475Z'+ created_at: '2026-03-16T11:42:31.562Z'+ updated_at: '2026-03-16T11:42:31.646Z'current_step: addresscompleted_steps: []requirements:@@ -5680,7 +5681,7 @@ paths:application/json:example:id: or_UkLWZg9DAJ- number: R431379959+ number: R659779239email: [email protected]special_instructions:currency: USD@@ -5704,17 +5705,17 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- completed_at: '2026-03-15T09:57:03.285Z'- created_at: '2026-03-15T09:57:03.226Z'- updated_at: '2026-03-15T09:57:03.285Z'+ completed_at: '2026-03-16T11:42:33.415Z'+ created_at: '2026-03-16T11:42:33.368Z'+ updated_at: '2026-03-16T11:42:33.414Z'promotions: []items:- id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 471096- slug: product-471096+ name: Product 472278+ slug: product-472278options_text: ''price: '10.0'display_price: "$10.00"@@ -5733,23 +5734,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:57:03.259Z'- updated_at: '2026-03-15T09:57:03.259Z'+ created_at: '2026-03-16T11:42:33.395Z'+ updated_at: '2026-03-16T11:42:33.395Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H99381335009+ number: H36992806743state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:57:03.265Z'- updated_at: '2026-03-15T09:57:03.282Z'+ created_at: '2026-03-16T11:42:33.400Z'+ updated_at: '2026-03-16T11:42:33.413Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -5757,7 +5758,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_178- name: Eliseo Anderson+ name: Garry Stokesaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5962,13 +5963,13 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_a0977e1348c050bfa16b4ec0+ external_id: bogus_daabaa50d1c57f13c5014881external_data:- client_secret: bogus_secret_5361e4eb9f61beb5+ client_secret: bogus_secret_e7e604a73544eb4ecustomer_external_id:expires_at:- created_at: '2026-03-15T09:57:05.798Z'- updated_at: '2026-03-15T09:57:05.798Z'+ created_at: '2026-03-16T11:42:35.818Z'+ updated_at: '2026-03-16T11:42:35.818Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6063,13 +6064,13 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_cf57445d529c06574c445f2b+ external_id: bogus_77fbd02f6677cef6ebe14fe3external_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-15T09:57:06.471Z'- updated_at: '2026-03-15T09:57:06.471Z'+ created_at: '2026-03-16T11:42:36.405Z'+ updated_at: '2026-03-16T11:42:36.405Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6126,13 +6127,13 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_2558128ec996a5f552ea55e3+ external_id: bogus_30506623e48d658c98419dc3external_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-15T09:57:07.733Z'- updated_at: '2026-03-15T09:57:07.747Z'+ created_at: '2026-03-16T11:42:37.617Z'+ updated_at: '2026-03-16T11:42:37.631Z'amount: '50.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6229,13 +6230,13 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_f6e3add7f8155fd60a723dac+ external_id: bogus_424ada87b0da602b935acd08external_data:client_secret: secret_123customer_external_id:expires_at:- created_at: '2026-03-15T09:57:08.350Z'- updated_at: '2026-03-15T09:57:08.363Z'+ created_at: '2026-03-16T11:42:38.221Z'+ updated_at: '2026-03-16T11:42:38.232Z'amount: '110.0'payment_method_id: pm_UkLWZg9DAJorder_id: or_UkLWZg9DAJ@@ -6315,11 +6316,11 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_35831340b9be1dda0dc879b7- external_client_secret: bogus_seti_secret_645160465b56014d+ external_id: bogus_seti_5c545f3dc7c5849d72ffc674+ external_client_secret: bogus_seti_secret_467a3b3ef01f86d7external_data: {}- created_at: '2026-03-15T09:57:09.547Z'- updated_at: '2026-03-15T09:57:09.547Z'+ created_at: '2026-03-16T11:42:39.440Z'+ updated_at: '2026-03-16T11:42:39.440Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -6416,12 +6417,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_2e9ef45b42d7fb1b4e5fac91- external_client_secret: seti_secret_4165488a7c42172d41e2e0fb+ external_id: seti_test_1a2c9705d0abdecef67304e3+ external_client_secret: seti_secret_d3c3962baa443c69e575a041external_data:client_secret: secret_123- created_at: '2026-03-15T09:57:11.198Z'- updated_at: '2026-03-15T09:57:11.198Z'+ created_at: '2026-03-16T11:42:41.069Z'+ updated_at: '2026-03-16T11:42:41.069Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id:payment_source_type:@@ -6494,12 +6495,12 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_e65035e9af9ec10297b861e1- external_client_secret: seti_secret_4abb4347ff85b4dac427a0de+ external_id: seti_test_ef6d5d09f94b0b678cc84d3c+ external_client_secret: seti_secret_f94fdb8a44d560744d38eb25external_data:client_secret: secret_123- created_at: '2026-03-15T09:57:12.306Z'- updated_at: '2026-03-15T09:57:12.323Z'+ created_at: '2026-03-16T11:42:42.156Z'+ updated_at: '2026-03-16T11:42:42.168Z'payment_method_id: pm_UkLWZg9DAJpayment_source_id: card_UkLWZg9DAJpayment_source_type: Spree::CreditCard@@ -6587,11 +6588,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code: '12345'- number: PE69K01S+ number: PYNZVFY8amount: '110.0'display_amount: "$110.00"- created_at: '2026-03-15T09:57:13.516Z'- updated_at: '2026-03-15T09:57:13.516Z'+ created_at: '2026-03-16T11:42:43.304Z'+ updated_at: '2026-03-16T11:42:43.304Z'source_type: credit_cardsource_id: card_UkLWZg9DAJsource:@@ -6678,11 +6679,11 @@ paths:payment_method_id: pm_UkLWZg9DAJstate: checkoutresponse_code:- number: P95WC0IE+ number: PCY45KRAamount: '110.0'display_amount: "$110.00"- created_at: '2026-03-15T09:57:14.154Z'- updated_at: '2026-03-15T09:57:14.154Z'+ created_at: '2026-03-16T11:42:43.912Z'+ updated_at: '2026-03-16T11:42:43.912Z'source_type:source_id:source:@@ -6752,7 +6753,7 @@ paths:price_gte: 20,price_lte: 100,with_option_value_ids: ['optval_abc', 'optval_def'],- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})parameters:- name: x-spree-api-key@@ -6820,7 +6821,7 @@ paths:- name: expandin: queryrequired: false- description: Comma-separated associations to expand (variants, images, categories,+ description: Comma-separated associations to expand (variants, media, categories,option_types)schema:type: string@@ -6839,19 +6840,19 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 594464- description: Pariatur quae consequatur quo rerum modi magnam. Facilis- sint nam temporibus quas officia vero nobis. Reprehenderit nam- possimus numquam consectetur rerum. Temporibus quo inventore culpa- expedita fugiat. Repudiandae voluptatum vero natus incidunt cupiditate- nemo.- slug: product-594464+ name: Product 597011+ description: |-+ Corrupti omnis nulla deserunt voluptatum reprehenderit. Quam ipsam autem deleniti recusandae cum. Corrupti quod molestias illo asperiores quas. Quibusdam provident nemo consectetur eius. Eius consectetur suscipit reprehenderit natus.+ Nobis expedita ex laudantium harum soluta itaque veniam. Cupiditate sed vero impedit incidunt sapiente deleniti. Nobis ullam nam distinctio odio pariatur hic. Impedit corporis nobis provident laboriosam.+ Dolorem et mollitia blanditiis dicta reprehenderit nostrum quidem quos. Illum aspernatur officia consectetur labore ipsum fugiat. Quia modi totam ad perferendis facere.+ Ut repudiandae voluptatibus natus maiores. Nesciunt dicta ut magni temporibus non. Assumenda tempore nesciunt modi consequuntur officiis. Perspiciatis fuga libero sed ipsa consequatur qui sequi praesentium. Molestiae tempora voluptatem iusto omnis inventore officia error.+ slug: product-597011meta_description:meta_keywords:variant_count: 1- available_on: '2025-03-15T09:57:14.832Z'- created_at: '2026-03-15T09:57:14.852Z'- updated_at: '2026-03-15T09:57:14.903Z'+ available_on: '2025-03-16T11:42:44.563Z'+ created_at: '2026-03-16T11:42:44.576Z'+ updated_at: '2026-03-16T11:42:44.615Z'purchasable: truein_stock: falsebackorderable: true@@ -6871,18 +6872,17 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 607834- description: Autem reiciendis minima aspernatur quaerat qui repudiandae.- Inventore libero vero adipisci recusandae iste expedita veniam- deserunt. Cum dicta distinctio harum ea nesciunt sequi eveniet- modi.- slug: product-607834+ name: Product 60113+ description: |-+ Facere ullam exercitationem possimus voluptatem. Occaecati odio vero facilis velit quod laudantium fuga eligendi. Minus nesciunt sed corrupti placeat. Ipsum dolorem illum assumenda dolorum quia. Qui iure recusandae minima velit nemo quam libero.+ Accusamus facilis voluptate delectus doloremque ratione corrupti ex. Eum tempore officiis nam optio. Quam alias nostrum fugit facilis excepturi labore. Magnam maiores voluptatem iure aperiam in molestiae eum.+ slug: product-60113meta_description:meta_keywords:variant_count: 0- available_on: '2025-03-15T09:57:14.911Z'- created_at: '2026-03-15T09:57:14.922Z'- updated_at: '2026-03-15T09:57:14.936Z'+ available_on: '2025-03-16T11:42:44.621Z'+ created_at: '2026-03-16T11:42:44.631Z'+ updated_at: '2026-03-16T11:42:44.644Z'purchasable: truein_stock: falsebackorderable: true@@ -6953,7 +6953,7 @@ paths:})const product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})parameters:- name: x-spree-api-key@@ -6988,18 +6988,17 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 719274- description: |-- Doloremque cupiditate cumque porro dolor. Veritatis perferendis dolor expedita ipsum tempore nulla iusto nemo. Eveniet voluptate impedit voluptatem voluptates.- Accusamus facilis at soluta vero quibusdam natus cum vitae. Ex sequi pariatur laboriosam nisi molestias labore. Rem odio pariatur earum labore saepe consectetur ullam. Ad eius dolorem minus nulla. Aperiam illum veritatis sed eaque itaque.- Quibusdam commodi at distinctio deleniti incidunt. Minus soluta esse fugiat saepe unde molestias. Ullam asperiores rem laboriosam a.- slug: product-719274+ name: Product 71220+ description: Blanditiis fuga nostrum expedita exercitationem labore.+ Incidunt qui neque quam dolores dignissimos cum nihil debitis. Eum+ deserunt cumque maxime exercitationem ipsa provident voluptatum.+ slug: product-71220meta_description:meta_keywords:variant_count: 1- available_on: '2025-03-15T09:57:15.553Z'- created_at: '2026-03-15T09:57:15.580Z'- updated_at: '2026-03-15T09:57:15.645Z'+ available_on: '2025-03-16T11:42:45.169Z'+ created_at: '2026-03-16T11:42:45.185Z'+ updated_at: '2026-03-16T11:42:45.221Z'purchasable: truein_stock: falsebackorderable: true@@ -7217,15 +7216,15 @@ paths:example:data:- id: ship_UkLWZg9DAJ- number: H69528152229+ number: H32619135381state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:57:17.857Z'- updated_at: '2026-03-15T09:57:17.873Z'+ created_at: '2026-03-16T11:42:47.061Z'+ updated_at: '2026-03-16T11:42:47.073Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -7233,7 +7232,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_250- name: Ludie Grant+ name: Heidy Breitenbergaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7315,9 +7314,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R905508813- token: 9NzoeWMT2z8be7kife1xnWDAbiZTWnACkNG- email: [email protected]+ number: R706175501+ token: uS2yq6s6KK5KbJPuRRN8JDNmLLNzKcfyxk9+ email: [email protected]special_instructions:currency: USDlocale: en@@ -7338,8 +7337,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:57:18.433Z'- updated_at: '2026-03-15T09:57:18.531Z'+ created_at: '2026-03-16T11:42:47.633Z'+ updated_at: '2026-03-16T11:42:47.717Z'current_step: paymentcompleted_steps:- address@@ -7354,8 +7353,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1003603- slug: product-1003603+ name: Product 1007033+ slug: product-1007033options_text: ''price: '10.0'display_price: "$10.00"@@ -7374,23 +7373,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:57:18.467Z'- updated_at: '2026-03-15T09:57:18.467Z'+ created_at: '2026-03-16T11:42:47.662Z'+ updated_at: '2026-03-16T11:42:47.662Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H28170725534+ number: H01859618016state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:57:18.473Z'- updated_at: '2026-03-15T09:57:18.514Z'+ created_at: '2026-03-16T11:42:47.667Z'+ updated_at: '2026-03-16T11:42:47.700Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -7398,7 +7397,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_254- name: Benjamin Beier+ name: Elyse Andersonaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7534,9 +7533,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R002787829- token: 642ULnFDFXNEANAEZoa4Hx8NFhF5JmmxJ39- email: [email protected]+ number: R685095009+ token: t3PTz46C1e8c5zfHcuUbDvKMTGYVmFQFroG+ email: [email protected]special_instructions:currency: USDlocale: en@@ -7557,8 +7556,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:57:19.784Z'- updated_at: '2026-03-15T09:57:19.869Z'+ created_at: '2026-03-16T11:42:48.865Z'+ updated_at: '2026-03-16T11:42:48.947Z'current_step: addresscompleted_steps: []requirements: []@@ -7568,8 +7567,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1026200- slug: product-1026200+ name: Product 1023689+ slug: product-1023689options_text: ''price: '10.0'display_price: "$10.00"@@ -7588,23 +7587,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:57:19.839Z'- updated_at: '2026-03-15T09:57:19.839Z'+ created_at: '2026-03-16T11:42:48.915Z'+ updated_at: '2026-03-16T11:42:48.915Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H72079528401+ number: H41244189674state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:57:19.847Z'- updated_at: '2026-03-15T09:57:19.866Z'+ created_at: '2026-03-16T11:42:48.924Z'+ updated_at: '2026-03-16T11:42:48.943Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -7612,7 +7611,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_262- name: Henriette Larkin+ name: Forrest Legrosaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7634,12 +7633,12 @@ paths:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJstate: checkout- response_code: 1-SC-20260315095720181607- number: PGSET0HH+ response_code: 1-SC-20260316114249277866+ number: PD9CO5Q5amount: '10.0'display_amount: "$10.00"- created_at: '2026-03-15T09:57:20.185Z'- updated_at: '2026-03-15T09:57:20.185Z'+ created_at: '2026-03-16T11:42:49.282Z'+ updated_at: '2026-03-16T11:42:49.282Z'source_type: store_creditsource_id: credit_UkLWZg9DAJsource:@@ -7770,9 +7769,9 @@ paths:application/json:example:id: cart_UkLWZg9DAJ- number: R153268950- token: RE7XHmBaKZBWVbEsynYnqQ56xZPNk3Uyepm- email: [email protected]+ number: R556097630+ token: DNEdTx4FU6gYcifjJ2aH8MUPEMmays28g5g+ email: [email protected]special_instructions:currency: USDlocale: en@@ -7793,8 +7792,8 @@ paths:display_additional_tax_total: "$0.00"total: '110.0'display_total: "$110.00"- created_at: '2026-03-15T09:57:21.371Z'- updated_at: '2026-03-15T09:57:21.432Z'+ created_at: '2026-03-16T11:42:50.441Z'+ updated_at: '2026-03-16T11:42:50.488Z'current_step: addresscompleted_steps: []requirements:@@ -7807,8 +7806,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1044733- slug: product-1044733+ name: Product 1046044+ slug: product-1046044options_text: ''price: '10.0'display_price: "$10.00"@@ -7827,23 +7826,23 @@ paths:discounted_amount: '10.0'display_discounted_amount: "$10.00"display_compare_at_amount: "$0.00"- created_at: '2026-03-15T09:57:21.406Z'- updated_at: '2026-03-15T09:57:21.406Z'+ created_at: '2026-03-16T11:42:50.468Z'+ updated_at: '2026-03-16T11:42:50.468Z'compare_at_amount:thumbnail_url:option_values: []digital_links: []shipments:- id: ship_UkLWZg9DAJ- number: H94443388943+ number: H07440904442state: pendingtracking: U10000tracking_url:cost: '100.0'display_cost: "$100.00"shipped_at:- created_at: '2026-03-15T09:57:21.412Z'- updated_at: '2026-03-15T09:57:21.429Z'+ created_at: '2026-03-16T11:42:50.472Z'+ updated_at: '2026-03-16T11:42:50.485Z'shipping_method:id: shpm_UkLWZg9DAJname: UPS Ground@@ -7851,7 +7850,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: STATE_ABBR_270- name: Damion Crist+ name: Cherish Greenaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7967,9 +7966,9 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: Q7WVpKPerdP728LP2cTyre52- created_at: '2026-03-15T09:57:22.003Z'- updated_at: '2026-03-15T09:57:22.003Z'+ token: dkuvh484hiXe6uVHeTy74DgD+ created_at: '2026-03-16T11:42:51.049Z'+ updated_at: '2026-03-16T11:42:51.049Z'is_default: falseis_private: truemeta:@@ -8045,9 +8044,9 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: v9F5QMgvHgcV1s7jkH7YKV6W- created_at: '2026-03-15T09:57:23.219Z'- updated_at: '2026-03-15T09:57:23.219Z'+ token: rezrFsX8j96FoJPxxN76T4fN+ created_at: '2026-03-16T11:42:52.221Z'+ updated_at: '2026-03-16T11:42:52.221Z'is_default: falseis_private: trueschema:@@ -8143,9 +8142,9 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: ksKtAtTwXqPMvcoNpX3sSBi9- created_at: '2026-03-15T09:57:24.339Z'- updated_at: '2026-03-15T09:57:24.339Z'+ token: T3nvejJBwkEfb5gR57Lsc3Aw+ created_at: '2026-03-16T11:42:53.331Z'+ updated_at: '2026-03-16T11:42:53.331Z'is_default: falseis_private: trueschema:@@ -8207,9 +8206,9 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: Y9zmnLuTSR9iY1HLtHeDYW9o- created_at: '2026-03-15T09:57:25.494Z'- updated_at: '2026-03-15T09:57:25.542Z'+ token: SLMiCNtkg26pgV693X6bQV7M+ created_at: '2026-03-16T11:42:54.465Z'+ updated_at: '2026-03-16T11:42:54.505Z'is_default: falseis_private: trueschema:@@ -8321,8 +8320,8 @@ paths:variant_id: variant_gbHJdmfrXBwishlist_id: wl_UkLWZg9DAJquantity: 1- created_at: '2026-03-15T09:57:26.730Z'- updated_at: '2026-03-15T09:57:26.730Z'+ created_at: '2026-03-16T11:42:55.669Z'+ updated_at: '2026-03-16T11:42:55.669Z'variant:id: variant_gbHJdmfrXBproduct_id: prod_gbHJdmfrXB@@ -8330,10 +8329,10 @@ paths:is_master: trueoptions_text: ''track_inventory: true- image_count: 0- created_at: '2026-03-15T09:57:26.705Z'- updated_at: '2026-03-15T09:57:26.716Z'- thumbnail:+ media_count: 0+ created_at: '2026-03-16T11:42:55.641Z'+ updated_at: '2026-03-16T11:42:55.652Z'+ thumbnail_url:purchasable: truein_stock: falsebackorderable: true@@ -9267,66 +9266,6 @@ components:- created_at- updated_atx-typelizer: true- Image:- type: object- properties:- id:- type: string- viewable_id:- type: string- type:- type: string- nullable: true- viewable_type:- type: string- position:- type: number- nullable: true- alt:- type: string- nullable: true- created_at:- type: string- updated_at:- type: string- original_url:- type: string- nullable: true- mini_url:- type: string- nullable: true- small_url:- type: string- nullable: true- medium_url:- type: string- nullable: true- large_url:- type: string- nullable: true- xlarge_url:- type: string- nullable: true- og_image_url:- type: string- nullable: true- required:- - id- - viewable_id- - type- - viewable_type- - position- - alt- - created_at- - updated_at- - original_url- - mini_url- - small_url- - medium_url- - large_url- - xlarge_url- - og_image_url- x-typelizer: trueImportRow:type: objectproperties:@@ -9602,6 +9541,79 @@ components:- default- supported_localesx-typelizer: true+ Media:+ type: object+ properties:+ id:+ type: string+ product_id:+ type: string+ nullable: true+ variant_ids:+ type: array+ items:+ type: string+ position:+ type: number+ alt:+ type: string+ nullable: true+ media_type:+ type: string+ focal_point_x:+ type: number+ nullable: true+ focal_point_y:+ type: number+ nullable: true+ external_video_url:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ original_url:+ type: string+ nullable: true+ mini_url:+ type: string+ nullable: true+ small_url:+ type: string+ nullable: true+ medium_url:+ type: string+ nullable: true+ large_url:+ type: string+ nullable: true+ xlarge_url:+ type: string+ nullable: true+ og_image_url:+ type: string+ nullable: true+ required:+ - id+ - product_id+ - variant_ids+ - position+ - alt+ - media_type+ - focal_point_x+ - focal_point_y+ - external_video_url+ - created_at+ - updated_at+ - original_url+ - mini_url+ - small_url+ - medium_url+ - large_url+ - xlarge_url+ - og_image_url+ x-typelizer: trueMetafield:type: objectproperties:@@ -10118,10 +10130,12 @@ components:allOf:- "$ref": "#/components/schemas/Price"nullable: true- images:+ primary_media:+ "$ref": "#/components/schemas/Media"+ media:type: arrayitems:- "$ref": "#/components/schemas/Image"+ "$ref": "#/components/schemas/Media"variants:type: arrayitems:@@ -10723,13 +10737,13 @@ components:type: stringtrack_inventory:type: boolean- image_count:+ media_count:type: numbercreated_at:type: stringupdated_at:type: string- thumbnail:+ thumbnail_url:type: stringnullable: truepurchasable:@@ -10756,10 +10770,12 @@ components:allOf:- "$ref": "#/components/schemas/Price"nullable: true- images:+ primary_media:+ "$ref": "#/components/schemas/Media"+ media:type: arrayitems:- "$ref": "#/components/schemas/Image"+ "$ref": "#/components/schemas/Media"option_values:type: arrayitems:@@ -10775,10 +10791,10 @@ components:- is_master- options_text- track_inventory- - image_count+ - media_count- created_at- updated_at- - thumbnail+ - thumbnail_url- purchasable- in_stock- backorderablediff --git a/docs/developer/admin/components.mdx b/docs/developer/admin/components.mdxindex e6d6d4b044..d5f634c67b 100644--- a/docs/developer/admin/components.mdx+++ b/docs/developer/admin/components.mdx@@ -401,7 +401,7 @@ Displays optimized images with automatic WebP conversion and retina support.```<Info>- For comprehensive documentation on image handling, storage configuration, and best practices, see the [Images & Assets](/developer/core-concepts/images-assets) guide.+ For comprehensive documentation on image handling, storage configuration, and best practices, see the [Media](/developer/core-concepts/media) guide.</Info>## Tooltipdiff --git a/docs/developer/core-concepts/images-assets.mdx b/docs/developer/core-concepts/media.mdxsimilarity index 52%rename from docs/developer/core-concepts/images-assets.mdxrename to docs/developer/core-concepts/media.mdxindex 9124fa9163..dfffe0807c 100644--- a/docs/developer/core-concepts/images-assets.mdx+++ b/docs/developer/core-concepts/media.mdx@@ -1,23 +1,28 @@----title: Images & Assets-sidebarTitle: "Images & Assets"-description: Product images, named variants, and how images are served via the Store API+title: Media+sidebarTitle: "Media"+description: Product media (images, videos), named variants, focal points, and how media is served via the Store API---## Overview-Spree handles image uploads, processing, and delivery for product images and other assets. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.+Spree handles uploads, processing, and delivery for product media. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.-## Product Images+## Product Media-Product images use the `Spree::Image` model, which provides:+Product media uses the `Spree::Asset` model, which provides:-- **Multiple images per variant** with ordering+- **Multiple media per product** with ordering+- **Media types** — `image`, `video`, `external_video`- **Alt text** for accessibility and SEO-- **Position management** for image galleries+- **Focal point** coordinates for smart cropping- **Preprocessed named variants** for fast delivery-Images belong to variants, not products directly. Product-level images are attached to the master variant.+Each media item has a `media_type` field that defaults to `image`. The `variant_ids` field indicates which product variants the media is associated with — an empty array means the media belongs to the product as a whole.++<Note>+`Spree::Image` is a backward-compatible subclass of `Spree::Asset` that sets `media_type` to `image`. New code should use `Spree::Asset` directly.+</Note>### Named Variant Sizes@@ -37,7 +42,7 @@ All variants are cropped to fill the exact dimensions and converted to WebP form### Thumbnails (Always Available)-Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and an `image_count` counter.+Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and a `media_count` counter.<CodeGroup>@@ -59,45 +64,51 @@ curl 'https://api.mystore.com/api/v3/store/products?limit=12' \</CodeGroup><Warning>-Avoid using `?expand=images` on listing pages. This loads **all** images for every product in the response. Use `thumbnail_url` instead and only expand full images on product detail pages.+Avoid using `?expand=media` on listing pages. This loads **all** media for every product in the response. Use `thumbnail_url` instead and only expand full media on product detail pages.</Warning>-### Full Images (On Demand)+### Full Media (On Demand)-On the product detail page, expand `images` and `variants` to get the full set of images with all named variant URLs:+On the product detail page, expand `media` and `variants` to get the full set of media with all named variant URLs:<CodeGroup>```typescript SDKconst product = await client.products.get('spree-tote', {- expand: ['images', 'variants'],+ expand: ['media', 'variants'],})-// Product-level images (from master variant)-product.images // [{ url, mini_url, small_url, medium_url, large_url, xlarge_url, alt, position }, ...]+// Product media gallery+product.media // [{ id, media_type, product_id, variant_ids, original_url, mini_url, ..., alt, position }, ...]-// Each variant has its own thumbnail and image_count+// Each variant has its own thumbnail and media_countproduct.variants?.forEach(variant => {variant.thumbnail // "https://cdn.../tote-red.webp" — always available- variant.image_count // 3 — quick check without loading images- variant.images // full image array (only with ?expand=images)+ variant.media_count // 3 — quick check without loading media+ variant.media // full media array (only with ?expand=media)})``````bash cURL-curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,variants' \+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \-H 'Authorization: Bearer spree_pk_xxx'```</CodeGroup>-**Response (image object):**+**Response (media object):**```json{- "id": "img_k5nR8xLq",+ "id": "media_k5nR8xLq",+ "media_type": "image",+ "product_id": "prod_86Rf07xd4z",+ "variant_ids": ["variant_m3Rp9wXz"],"position": 1,"alt": "Front view",+ "focal_point_x": null,+ "focal_point_y": null,+ "external_video_url": null,"original_url": "https://cdn.example.com/images/original.jpg","mini_url": "https://cdn.example.com/images/mini.webp","small_url": "https://cdn.example.com/images/small.webp",@@ -107,14 +118,30 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,var}```-### Image Fields Summary+### Media Fields Summary| Field | Available on | Always Returned | Description ||-------|-------------|:---:|-------------|-| `thumbnail_url` | Product | Yes | URL to the product's first image |-| `thumbnail` | Variant | Yes | URL to the variant's first image |-| `image_count` | Variant | Yes | Number of images (no extra query) |-| `images` | Product, Variant | No | Full image array (requires `?expand=images`) |+| `thumbnail_url` | Product | Yes | URL to the product's first media |+| `thumbnail` | Variant | Yes | URL to the variant's first media |+| `media_count` | Variant | Yes | Number of media items (counter cache) |+| `media` | Product, Variant | No | Full media array (requires `?expand=media`) |++### Media Object Fields++| Field | Type | Description |+|-------|------|-------------|+| `id` | string | Prefixed ID (`media_xxx`) |+| `media_type` | string | `image`, `video`, or `external_video` |+| `product_id` | string \| null | Owning product prefixed ID |+| `variant_ids` | string[] | Associated variant prefixed IDs (empty = product-level) |+| `position` | number | Sort order |+| `alt` | string \| null | Alt text |+| `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |+| `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |+| `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |+| `original_url` | string \| null | Full-size image URL |+| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |## Image Processing@@ -139,12 +166,12 @@ For production deployments, use cloud storage (S3, GCS, Azure) instead of local## Best Practices-- **Use `thumbnail_url`** on listing pages — avoid loading full images via expand+- **Use `thumbnail_url`** on listing pages — avoid loading full media via expand- **Always provide alt text** for accessibility and SEO- **Use named variant sizes** (`mini`, `small`, `medium`, `large`, `xlarge`) for optimal performance- **Use a CDN** in production for faster delivery## Related Documentation-- [Products](/developer/core-concepts/products) — Product catalog and images+- [Products](/developer/core-concepts/products) — Product catalog and media- [Deployment — Assets](/developer/deployment/assets) — Storage and CDN configurationdiff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdxindex 87dc2adabd..a84cf11499 100644--- a/docs/developer/core-concepts/products.mdx+++ b/docs/developer/core-concepts/products.mdx@@ -133,15 +133,15 @@ const product = await client.products.get('spree-tote')// Get with included relationsconst detailed = await client.products.get('spree-tote', {- expand: ['variants', 'images', 'option_types', 'categories'],+ expand: ['variants', 'media', 'option_types', 'categories'],})// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]-// detailed.images => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]+// detailed.media => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]// detailed.option_types => [{ name: "size", presentation: "Size", option_values: [...] }]``````bash cURL-curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,images,option_types,categories' \+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \-H 'Authorization: Bearer spree_pk_xxx'```@@ -244,13 +244,13 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_typeOption type `name` and `presentation` fields are translatable.</Info>-## Images+## Media-Images can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.+Media can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.### Thumbnails-Every product response includes a `thumbnail_url` field — the URL to the first image, ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and an `image_count` counter.+Every product response includes a `thumbnail_url` field — the URL to the first image, ready to use without any expands. Similarly, each variant includes a `thumbnail_url` URL and an `media_count` counter.Use these fields for product listing pages to avoid loading all images:@@ -274,33 +274,33 @@ curl 'https://api.mystore.com/api/v3/store/products?limit=12' \</CodeGroup><Warning>-Avoid using `?expand=images` on listing pages. This loads **all** images for every product in the response, which is unnecessary when you only need a thumbnail. Use `thumbnail_url` instead and only expand full images on the product detail page.+Avoid using `?expand=media` on listing pages. This loads **all** images for every product in the response, which is unnecessary when you only need a thumbnail. Use `thumbnail_url` instead and only expand full media on the product detail page.</Warning>### All Images-On the product detail page, expand `images` and `variants` to get the full set of images. Images are ordered by `position`:+On the product detail page, expand `media` and `variants` to get the full set of images. Images are ordered by `position`:<CodeGroup>```typescript SDKconst product = await client.products.get('spree-tote', {- expand: ['images', 'variants'],+ expand: ['media', 'variants'],})// Product-level images (from master variant)-product.images // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]+product.media // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]-// Each variant has its own thumbnail and image_count+// Each variant has its own thumbnail and media_countproduct.variants?.forEach(variant => {variant.thumbnail // "https://cdn.../tote-red.jpg" — always available- variant.image_count // 3 — quick check without loading images- variant.images // full image array (only when ?expand=images)+ variant.media_count // 3 — quick check without loading media+ variant.media // full image array (only when ?expand=media)})``````bash cURL-curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,variants' \+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \-H 'Authorization: Bearer spree_pk_xxx'```@@ -308,10 +308,10 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=images,var| Field | Available on | Always returned | Description ||-------|-------------|:---:|-------------|-| `thumbnail_url` | Product | Yes | URL to the product's first image |-| `thumbnail` | Variant | Yes | URL to the variant's first image |-| `image_count` | Variant | Yes | Number of images (counter cache — no DB query) |-| `images` | Product, Variant | No | Full image array (requires `?expand=images`) |+| `thumbnail_url` | Product | Yes | URL to the product's first media |+| `thumbnail_url` | Variant | Yes | URL to the variant's first media |+| `media_count` | Variant | Yes | Number of media |+| `media` | Product, Variant | No | Full image array (requires `?expand=media`) |## Prices@@ -376,7 +376,7 @@ Category `name` and `description` fields are translatable.- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and market-specific pricing- [Inventory](/developer/core-concepts/inventory) — Stock management and backorders-- [Images & Assets](/developer/core-concepts/images-assets) — Image management+- [Media](/developer/core-concepts/media) — Image management- [Translations](/developer/core-concepts/translations) — Translating product content- [Search & Filtering](/developer/core-concepts/search-filtering) — Full-text search and Ransack filtering- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and paginationdiff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdxindex cd34aaeb50..586995f7c9 100644--- a/docs/developer/sdk/quickstart.mdx+++ b/docs/developer/sdk/quickstart.mdx@@ -27,7 +27,7 @@ const client = createClient({// Browse products (Store API)const products = await client.products.list({limit: 10,- expand: ['variants', 'images'],+ expand: ['variants', 'media'],});// Get a single productdiff --git a/docs/developer/sdk/store/products.mdx b/docs/developer/sdk/store/products.mdxindex 3a400f070b..9c692740e7 100644--- a/docs/developer/sdk/store/products.mdx+++ b/docs/developer/sdk/store/products.mdx@@ -11,7 +11,7 @@ description: Browse products and categories with the Spree SDKconst products = await client.products.list({page: 1,limit: 25,- expand: ['variants', 'images', 'categories'],+ expand: ['variants', 'media', 'categories'],});```@@ -52,7 +52,7 @@ const products = await client.products.list({const product = await client.products.get('spree-tote', {fields: ['name', 'slug', 'price'],- expand: ['images'], // expanded associations are always included+ expand: ['media'], // expanded associations are always included});```@@ -65,12 +65,12 @@ Use dot notation to expand nested associations (up to 4 levels):```typescript// Expand variants with their images in one requestconst product = await client.products.get('spree-tote', {- expand: ['variants.images', 'option_types'],+ expand: ['variants.media', 'option_types'],});// Access nested dataproduct.variants.forEach(variant => {- console.log(variant.images); // Images are included+ console.log(variant.media); // Media are included});```@@ -80,7 +80,7 @@ Fetch a single product by slug or prefix ID:```typescriptconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],});```@@ -133,7 +133,7 @@ const category = await client.categories.get('clothing/shirts', {const categoryProducts = await client.categories.products.list('clothing/shirts', {page: 1,limit: 12,- expand: ['images', 'default_variant'],+ expand: ['media', 'default_variant'],});```diff --git a/docs/developer/storefront/blocks.mdx b/docs/developer/storefront/blocks.mdxindex a11048c781..8a7b17de0c 100644--- a/docs/developer/storefront/blocks.mdx+++ b/docs/developer/storefront/blocks.mdx@@ -282,4 +282,4 @@ block.asset.attached?- [Sections](/developer/storefront/sections) - Parent containers for blocks- [Links](/developer/storefront/links) - Adding links to blocks-- [Images & Assets](/developer/core-concepts/images-assets) - Working with images+- [Media](/developer/core-concepts/media) - Working with imagesdiff --git a/docs/developer/storefront/helper-methods.mdx b/docs/developer/storefront/helper-methods.mdxindex da7e988739..9cc6180993 100644--- a/docs/developer/storefront/helper-methods.mdx+++ b/docs/developer/storefront/helper-methods.mdx@@ -270,7 +270,7 @@ Generates a URL for an image with specified dimensions.```<Info>- See [Images & Assets](/developer/core-concepts/images-assets) for more details on image helpers.+ See [Media](/developer/core-concepts/media) for more details on image helpers.</Info>## Product Helpers@@ -332,4 +332,4 @@ These helpers are used for Page Builder preview functionality:- [Sections](/developer/storefront/sections) - Section rendering and customization- [Blocks](/developer/storefront/blocks) - Block rendering-- [Images & Assets](/developer/core-concepts/images-assets) - Image helper methods+- [Media](/developer/core-concepts/media) - Image helper methodsdiff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdxindex 986768fb90..b9c6384c20 100644--- a/docs/developer/storefront/nextjs/spree-next-package.mdx+++ b/docs/developer/storefront/nextjs/spree-next-package.mdx@@ -49,7 +49,7 @@ Plain async functions for reading data in Server Components. Wrap with `"use cacimport { listProducts, getProduct, getProductFilters } from '@spree/next';const products = await listProducts({ limit: 25 });-const product = await getProduct('spree-tote', { expand: ['variants', 'images'] });+const product = await getProduct('spree-tote', { expand: ['variants', 'media'] });const filters = await getProductFilters({ category_id: 'ctg_123' });```diff --git a/docs/docs.json b/docs/docs.jsonindex a69481f993..bb661824df 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -35,7 +35,11 @@"redirects": [{"source": "/developer/storefront/images",- "destination": "/developer/core-concepts/images-assets"+ "destination": "/developer/core-concepts/media"+ },+ {+ "source": "/developer/core-concepts/images-assets",+ "destination": "/developer/core-concepts/media"},{"source": "/developer/admin/permissions",@@ -103,7 +107,7 @@"developer/core-concepts/products","developer/core-concepts/pricing","developer/core-concepts/inventory",- "developer/core-concepts/images-assets",+ "developer/core-concepts/media","developer/core-concepts/search-filtering"]},diff --git a/docs/index.mdx b/docs/index.mdxindex 5e3ba4d77d..3f450559ed 100644--- a/docs/index.mdx+++ b/docs/index.mdx@@ -202,9 +202,9 @@ export const CopyCommand = ({ command }) => {<ConceptItem href="/developer/core-concepts/inventory"icon={<SmallIcon><path d="M16 16h6" /><path d="M19 13v6" /><path d="M21 10V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l2-1.14" /><path d="m7.5 4.27 9 5.15" /><path d="M3.3 7 12 12l8.7-5" /><path d="M12 22V12" /></SmallIcon>}title="Inventory" />- <ConceptItem href="/developer/core-concepts/images-assets"+ <ConceptItem href="/developer/core-concepts/media"icon={<SmallIcon><rect width="18" height="18" x="3" y="3" rx="2" ry="2" /><circle cx="9" cy="9" r="2" /><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" /></SmallIcon>}- title="Images & Assets" />+ title="Media" /></div></div>diff --git a/docs/plans/5.4-6.0-product-media-system.md b/docs/plans/5.4-6.0-product-media-system.mdnew file mode 100644index 0000000000..3f6351e5a5--- /dev/null+++ b/docs/plans/5.4-6.0-product-media-system.md@@ -0,0 +1,153 @@+# Product Media System++**Status:** In Progress+**Target:** Spree 5.4 (foundation) + Spree 6.0 (full flip)+**Depends on:** None+**Author:** Damian + Claude+**Last updated:** 2026-03-16++## Summary++Spree's image system ties each `Spree::Image` 1:1 to a `Spree::Variant`. Sharing an image across variants requires re-uploading it, duplicating Active Storage blobs. There is no product-level media gallery, no video support, and no focal point for smart cropping.++This plan moves to a **product-level media gallery** (the industry standard) where variants reference product media via a join table. Blobs are never duplicated. The Store API renames `images` → `media` with a `media_type` discriminator.++## Key Decisions (do not deviate without discussion)++1. **Rename `images` → `media`** throughout the Store API. Clean break — no deprecated alias.+2. **Drop `viewable_id`/`viewable_type`** from Store API. Admin API keeps them.+3. **Add `product_id`** to the media serializer.+4. **Single `Spree::Asset` class** — `Spree::Image` logic merged into `Spree::Asset`. `Spree::Image` kept as thin subclass (sets `media_type: 'image'`). No STI.+5. **`media_type` defaults to `'image'`** — always present, never null.+6. **No dedicated Store media endpoint** — media is served via `expand=media` on products/variants (industry standard).+7. **VariantMedia join table deferred to 6.0** — not needed until data migration moves images from variants to products.+8. **Rename `Spree::Asset` → `Spree::Media` in 6.0** — aligns model/table/prefix with API naming.++## Design Details++### Data Model++```+Spree::Asset (single class, replaces Spree::Image)+ viewable_type: 'Spree::Product' (new) or 'Spree::Variant' (legacy)+ media_type: 'image' | 'video' | 'external_video' (default: 'image')+ focal_point_x, focal_point_y (decimal, nullable)+ external_video_url (string, nullable)++Spree::Image < Spree::Asset (thin backward-compat subclass)++Spree::Product+ has_many :media, as: :viewable ← product-level gallery+ has_many :variant_images, through: ... ← kept for backward compat+ #gallery_media → media.any? ? media : variant_images++Spree::Variant+ has_many :images, as: :viewable ← kept (legacy)+ #gallery_media → images ← 6.0: will use join table++Spree::VariantMedia (6.0)+ belongs_to :variant+ belongs_to :asset+ position (per-variant ordering)+ unique index on [variant_id, asset_id]+```++### Store API (5.4)++| Field | Type | Notes |+|-------|------|-------|+| `id` | string | Prefixed ID (`media_xxx`) |+| `product_id` | string \| null | Product prefixed ID |+| `media_type` | string | `'image'`, `'video'`, `'external_video'` |+| `position` | number | Sort order |+| `alt` | string \| null | Alt text |+| `focal_point_x` | number \| null | 0.0–1.0 |+| `focal_point_y` | number \| null | 0.0–1.0 |+| `external_video_url` | string \| null | YouTube/Vimeo URL |+| `original_url` | string \| null | Full-size image URL |+| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |++**Removed** from Store API: `viewable_id`, `viewable_type`+**Admin API** extends Store with: `viewable_id`, `viewable_type`++### Breaking Changes (5.4)++| Change | Before | After |+|--------|--------|-------|+| Expansion param | `expand=images` | `expand=media` |+| Response key | `"images": [...]` | `"media": [...]` |+| `viewable_id` | Present | Removed (Store API) |+| `viewable_type` | Present | Removed (Store API) |+| TS type | `Image` / `StoreImage` | `Media` / `StoreMedia` |+| Serializer | `ImageSerializer` | `MediaSerializer` (deleted, no alias) |++## Migration Path++### 5.4 (PR #13778) — DONE ✓++- New columns on `spree_assets`: `media_type`, `focal_point_x/y`, `external_video_url`+- Backfill existing records: `media_type = 'image'`+- Merge `Spree::Image` into `Spree::Asset`+- Store API: `MediaSerializer` replaces `ImageSerializer`, `expand=media`+- Admin API: `Admin::MediaSerializer` extends Store (adds `viewable_id/type`)+- SDK bumped to 0.11.0, Next bumped to 0.11.0+- TypeScript types, Zod schemas, OpenAPI spec regenerated+- Docs updated throughout++### 6.0 — TODO++**Phase 1: VariantMedia join table**+- Create `spree_variant_media` table + `Spree::VariantMedia` model+- `Variant#variant_media`, `Variant#associated_media` associations+- Update `Variant#gallery_media` to prefer associated_media over direct images+- Admin API: media CRUD endpoints for products and variant media association++**Phase 2: Admin UI**+- Product form uploads to `Product` (not master `Variant`)+- Variant edit shows media picker (select from product gallery, drag-to-reorder)+- Focal point UI on asset edit dialog++**Phase 3: Data migration**+- Rake task `spree:migrate_images_to_product_media`+- Move master variant images to product level+- Move non-master variant images to product + create VariantMedia records+- Deduplicate shared blobs+- Recalculate counter caches and thumbnails++**Phase 4: Video support (can be deferred)**+- `Spree::Video` or media_type='external_video' with URL validation+- Admin UI: "Add video" button for YouTube/Vimeo URLs++**Phase 5: Rename Asset → Media**+- Rename table `spree_assets` → `spree_media`+- Rename model `Spree::Asset` → `Spree::Media`+- Prefix ID already `media_xxx` since 5.4 — no change needed+- Remove `Spree::Image` subclass++**Phase 6: Cleanup**+- Remove `Product#variant_images` (use `Product#media`)+- Remove `viewable_id/type` from Admin API+- Update Duplicator and CSV presenter++## Constraints on Current Work++- **Always use `expand=media`** (not `expand=images`) in new Store API code and SDK examples+- **Always use `Spree::Asset`** for new code; `Spree::Image` is for backward compat only+- **Use `gallery_media`** as the unified accessor on Product and Variant+- **Do not create `VariantMedia` records** — the join table doesn't exist yet in 5.4+- **`media_type` is never null** — defaults to `'image'`, always validate inclusion++## Open Questions++- Should we support hosted video uploads (not just external URLs)?+- Should focal point have a visual picker UI or just numeric fields?+- Should 3D model support (GLB/USDZ) be a `media_type` value or a separate system?++## References++- PR #13778: [Product media system: core data model + Store API](https://github.com/spree/spree/pull/13778)+- Key files:+ - `core/app/models/spree/asset.rb` — single Asset class with all media logic+ - `core/app/models/spree/image.rb` — thin backward-compat subclass+ - `api/app/serializers/spree/api/v3/media_serializer.rb` — Store API+ - `api/app/serializers/spree/api/v3/admin/media_serializer.rb` — Admin APIdiff --git a/packages/admin-sdk/src/types/generated/AllowedOrigin.ts b/packages/admin-sdk/src/types/generated/AllowedOrigin.tsnew file mode 100644index 0000000000..37ed576cd0--- /dev/null+++ b/packages/admin-sdk/src/types/generated/AllowedOrigin.ts@@ -0,0 +1,13 @@+// Typelizer digest 2340eabe63e24f397f46d39fcf103bde+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type AllowedOrigin = {+ id: string;+ origin: unknown;+ store_id: string;+ created_at: string;+ updated_at: string;+}++export default AllowedOrigin;diff --git a/packages/admin-sdk/src/types/generated/Image.ts b/packages/admin-sdk/src/types/generated/Media.tssimilarity index 58%rename from packages/admin-sdk/src/types/generated/Image.tsrename to packages/admin-sdk/src/types/generated/Media.tsindex 02426675f1..f8d23652a2 100644--- a/packages/admin-sdk/src/types/generated/Image.ts+++ b/packages/admin-sdk/src/types/generated/Media.ts@@ -1,14 +1,17 @@-// Typelizer digest 5ec63f1c6a56885532a0e14043f48fce+// Typelizer digest 87865bd0f729b8e029e9d1480f85e35b//// DO NOT MODIFY: This file was automatically generated by Typelizer.-type Image = {+type Media = {id: string;- viewable_id: string;- type: string | null;- viewable_type: string;- position: number | null;+ product_id: string | null;+ variant_ids: Array<string>;+ position: number;alt: string | null;+ media_type: string;+ focal_point_x: number | null;+ focal_point_y: number | null;+ external_video_url: string | null;created_at: string;updated_at: string;original_url: string | null;@@ -18,6 +21,8 @@ type Image = {large_url: string | null;xlarge_url: string | null;og_image_url: string | null;+ viewable_id: string;+ viewable_type: string;}-export default Image;+export default Media;diff --git a/packages/admin-sdk/src/types/generated/Product.ts b/packages/admin-sdk/src/types/generated/Product.tsindex db9d12dae1..2ca581e387 100644--- a/packages/admin-sdk/src/types/generated/Product.ts+++ b/packages/admin-sdk/src/types/generated/Product.ts@@ -1,7 +1,7 @@-// Typelizer digest 3f80b68185ecc8b201bb41c384acaa05+// Typelizer digest 6b59ae5c6e1c93b3e2889235dda4b17c//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'+import type {Price, Media, Variant, OptionType, Category, Metafield} from '@/types'type Product = {id: string;@@ -23,7 +23,8 @@ type Product = {tags: Array<string>;price: Price;original_price: Price | null;- images?: Array<Image>;+ primary_media?: Media;+ media?: Array<Media>;variants?: Array<Variant>;default_variant?: Variant;master_variant?: Variant;diff --git a/packages/admin-sdk/src/types/generated/Variant.ts b/packages/admin-sdk/src/types/generated/Variant.tsindex 1523362d72..8f64e4d0fd 100644--- a/packages/admin-sdk/src/types/generated/Variant.ts+++ b/packages/admin-sdk/src/types/generated/Variant.ts@@ -1,7 +1,7 @@-// Typelizer digest a1336509c01c26dd007063c050d72f43+// Typelizer digest 0eb33fd101b5908c3453d5f8f75e04a5//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {Price, Image, OptionValue, Metafield} from '@/types'+import type {Price, Media, OptionValue, Metafield} from '@/types'type Variant = {id: string;@@ -10,10 +10,10 @@ type Variant = {is_master: boolean;options_text: string;track_inventory: boolean;- image_count: number;+ media_count: number;created_at: string;updated_at: string;- thumbnail: string | null;+ thumbnail_url: string | null;purchasable: boolean;in_stock: boolean;backorderable: boolean;@@ -23,7 +23,8 @@ type Variant = {depth: number | null;price: Price;original_price: Price | null;- images?: Array<Image>;+ primary_media?: Media;+ media?: Array<Media>;option_values: Array<OptionValue>;metafields?: Array<Metafield>;position: number;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex aca0c57f17..0aebf70182 100644--- a/packages/admin-sdk/src/types/generated/index.ts+++ b/packages/admin-sdk/src/types/generated/index.ts@@ -1,16 +1,17 @@-// Typelizer digest 07c3216434ae36f2d5204abb7ac05832+// Typelizer digest 5303466aa5441036b50030ebe2bef1c5//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { default as Address } from './Address'export type { default as Adjustment } from './Adjustment'export type { default as AdminUser } from './AdminUser'+export type { default as AllowedOrigin } from './AllowedOrigin'export type { default as Asset } from './Asset'export type { default as Category } from './Category'export type { default as CreditCard } from './CreditCard'export type { default as Customer } from './Customer'export type { default as DigitalLink } from './DigitalLink'-export type { default as Image } from './Image'export type { default as LineItem } from './LineItem'+export type { default as Media } from './Media'export type { default as Metafield } from './Metafield'export type { default as OptionType } from './OptionType'export type { default as OptionValue } from './OptionValue'diff --git a/packages/next/CHANGELOG.md b/packages/next/CHANGELOG.mdindex c9d888f5b7..d7fe14f600 100644--- a/packages/next/CHANGELOG.md+++ b/packages/next/CHANGELOG.md@@ -1,5 +1,13 @@# @spree/next+## 0.11.0++### Minor Changes++- **Breaking:** Rename `images` to `media` — aligns with Spree 5.4 Store API media system+ - `expand: ['images']` → `expand: ['media']`+ - `Image` type re-export replaced by `Media`+## 0.10.5### Patch Changesdiff --git a/packages/next/README.md b/packages/next/README.mdindex 01c41748f0..8cc5371d08 100644--- a/packages/next/README.md+++ b/packages/next/README.md@@ -93,7 +93,7 @@ Plain async functions for reading data in Server Components. Wrap with `"use cac```typescriptimport { listProducts, getProduct, getProductFilters } from '@spree/next';-const products = await listProducts({ limit: 25, expand: ['variants', 'images'] });+const products = await listProducts({ limit: 25, expand: ['variants', 'media'] });const product = await getProduct('spree-tote');const filters = await getProductFilters({ category_id: 'ctg_123' });```diff --git a/packages/next/package.json b/packages/next/package.jsonindex f85c1de5c2..e2f9b246f2 100644--- a/packages/next/package.json+++ b/packages/next/package.json@@ -1,6 +1,6 @@{"name": "@spree/next",- "version": "0.10.5",+ "version": "0.11.0","description": "Next.js integration for Spree Commerce — server actions, caching, and cookie-based auth","type": "module","main": "./dist/index.js",diff --git a/packages/next/src/index.ts b/packages/next/src/index.tsindex 5a984aa1aa..7b475ce521 100644--- a/packages/next/src/index.ts+++ b/packages/next/src/index.ts@@ -88,7 +88,7 @@ export type {PaymentMethod,PaymentSession,PaymentSetupSession,- Image,+ Media,OptionType,OptionValue,Price,diff --git a/packages/sdk-core/src/params.ts b/packages/sdk-core/src/params.tsindex a9f81f2e43..78697e800c 100644--- a/packages/sdk-core/src/params.ts+++ b/packages/sdk-core/src/params.ts@@ -21,7 +21,7 @@ export function transformListParams(if (value === undefined) continue;if (PASSTHROUGH_KEYS.has(key)) {- // Join arrays for passthrough keys (e.g., expand: ['variants', 'images'] → 'variants,images')+ // Join arrays for passthrough keys (e.g., expand: ['variants', 'media'] → 'variants,media')result[key] = Array.isArray(value) ? (value as (string | number)[]).join(',') : value as ParamValue;continue;}diff --git a/packages/sdk-core/src/types.ts b/packages/sdk-core/src/types.tsindex 5c5690d54f..f8948d8ed2 100644--- a/packages/sdk-core/src/types.ts+++ b/packages/sdk-core/src/types.ts@@ -40,7 +40,7 @@ export interface ListParams {limit?: number;/** Sort order. Prefix with - for descending, e.g. '-created_at', 'name'. Comma-separated for multiple fields. */sort?: string;- /** Associations to expand. Supports dot notation for nested expand (max 4 levels), e.g. ['variants', 'variants.images'] */+ /** Associations to expand. Supports dot notation for nested expand (max 4 levels), e.g. ['variants', 'variants.media'] */expand?: string[];/** Fields to include in response, e.g. ['name', 'slug', 'price']. Omit to return all fields. 'id' is always included. */fields?: string[];diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.mdindex f407e791a7..1e69e1bebc 100644--- a/packages/sdk/CHANGELOG.md+++ b/packages/sdk/CHANGELOG.md@@ -1,5 +1,17 @@# @spree/sdk+## 0.11.0++### Minor Changes++- **Breaking:** Rename `images` to `media` across the Store API+ - `expand: ['images']` → `expand: ['media']` on products and variants+ - Response key `images` → `media`+ - `Image` type replaced by `Media` type (with `media_type`, `product_id`, `focal_point_x/y`, `external_video_url`)+ - `StoreImage` type replaced by `StoreMedia`+ - Removed `viewable_id` and `viewable_type` from media responses+ - Added `product_id` field to media responses+## 0.10.1### Patch Changesdiff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex 4fbe053d4e..8fd2c1afb7 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -26,7 +26,7 @@ const client = createClient({// Browse products (Store API)const products = await client.products.list({limit: 10,- expand: ['variants', 'images'],+ expand: ['variants', 'media'],});// Get a single product@@ -156,12 +156,12 @@ const products = await client.products.list({limit: 25,name_cont: 'shirt',sort: 'price asc',- expand: ['variants', 'images', 'categories'],+ expand: ['variants', 'media', 'categories'],});// Get single product by ID or slugconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],});// Get available filters (price range, availability, options, categories)@@ -187,7 +187,7 @@ const category = await client.categories.get('clothing/shirts', {const categoryProducts = await client.categories.products.list('clothing/shirts', {page: 1,limit: 12,- expand: ['images', 'default_variant'],+ expand: ['media', 'default_variant'],});```@@ -700,7 +700,7 @@ The SDK exports all Store API types:- `StoreOrderPromotion` - Promotion applied to an order (uses `oprom_` prefixed IDs)### Product Types-- `StoreImage` - Product image+- `StoreMedia` - Product media (images, videos)- `StorePrice` - Price data- `StoreOptionType` - Option type (e.g., Size, Color)- `StoreOptionValue` - Option value (e.g., Small, Red)diff --git a/packages/sdk/package.json b/packages/sdk/package.jsonindex f67db2b460..ffd2c893fb 100644--- a/packages/sdk/package.json+++ b/packages/sdk/package.json@@ -1,6 +1,6 @@{"name": "@spree/sdk",- "version": "0.10.1",+ "version": "0.11.0","description": "Official TypeScript SDK for Spree Commerce Store API","type": "module","main": "./dist/index.cjs",diff --git a/packages/sdk/src/types/generated/Image.ts b/packages/sdk/src/types/generated/Media.tssimilarity index 55%rename from packages/sdk/src/types/generated/Image.tsrename to packages/sdk/src/types/generated/Media.tsindex 02426675f1..375c0c7afd 100644--- a/packages/sdk/src/types/generated/Image.ts+++ b/packages/sdk/src/types/generated/Media.ts@@ -1,14 +1,17 @@-// Typelizer digest 5ec63f1c6a56885532a0e14043f48fce+// Typelizer digest 625de791cc6aa03d537978d99bf32bd8//// DO NOT MODIFY: This file was automatically generated by Typelizer.-type Image = {+type Media = {id: string;- viewable_id: string;- type: string | null;- viewable_type: string;- position: number | null;+ product_id: string | null;+ variant_ids: Array<string>;+ position: number;alt: string | null;+ media_type: string;+ focal_point_x: number | null;+ focal_point_y: number | null;+ external_video_url: string | null;created_at: string;updated_at: string;original_url: string | null;@@ -20,4 +23,4 @@ type Image = {og_image_url: string | null;}-export default Image;+export default Media;diff --git a/packages/sdk/src/types/generated/Product.ts b/packages/sdk/src/types/generated/Product.tsindex b3a4348df3..32d344047b 100644--- a/packages/sdk/src/types/generated/Product.ts+++ b/packages/sdk/src/types/generated/Product.ts@@ -1,7 +1,7 @@-// Typelizer digest 91825afbdee8d60521a89338e3d8b720+// Typelizer digest 81d9c7e30819ca27528939932201fa4f//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'+import type {Price, Media, Variant, OptionType, Category, Metafield} from '@/types'type Product = {id: string;@@ -23,7 +23,8 @@ type Product = {tags: Array<string>;price: Price;original_price: Price | null;- images?: Array<Image>;+ primary_media?: Media;+ media?: Array<Media>;variants?: Array<Variant>;default_variant?: Variant;master_variant?: Variant;diff --git a/packages/sdk/src/types/generated/Variant.ts b/packages/sdk/src/types/generated/Variant.tsindex c15a89a8f7..5e01787624 100644--- a/packages/sdk/src/types/generated/Variant.ts+++ b/packages/sdk/src/types/generated/Variant.ts@@ -1,7 +1,7 @@-// Typelizer digest 226f43de17cf9a25ec44ae428175dce4+// Typelizer digest f6ba1f2e259f0c8a6027c706aedac647//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {Price, Image, OptionValue, Metafield} from '@/types'+import type {Price, Media, OptionValue, Metafield} from '@/types'type Variant = {id: string;@@ -10,10 +10,10 @@ type Variant = {is_master: boolean;options_text: string;track_inventory: boolean;- image_count: number;+ media_count: number;created_at: string;updated_at: string;- thumbnail: string | null;+ thumbnail_url: string | null;purchasable: boolean;in_stock: boolean;backorderable: boolean;@@ -23,7 +23,8 @@ type Variant = {depth: number | null;price: Price;original_price: Price | null;- images?: Array<Image>;+ primary_media?: Media;+ media?: Array<Media>;option_values: Array<OptionValue>;metafields?: Array<Metafield>;}diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.tsindex f0f356051b..4e56b500c1 100644--- a/packages/sdk/src/types/generated/index.ts+++ b/packages/sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest 5925290903d07bde49afb5187341cc20+// Typelizer digest 06b4c1b4ec7e795574441c291ca84959//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { default as Address } from './Address'@@ -17,13 +17,13 @@ export type { default as Digital } from './Digital'export type { default as Export } from './Export'export type { default as GiftCardBatch } from './GiftCardBatch'export type { default as GiftCard } from './GiftCard'-export type { default as Image } from './Image'export type { default as ImportRow } from './ImportRow'export type { default as Import } from './Import'export type { default as Invitation } from './Invitation'export type { default as LineItem } from './LineItem'export type { default as Locale } from './Locale'export type { default as Market } from './Market'+export type { default as Media } from './Media'export type { default as Metafield } from './Metafield'export type { default as NewsletterSubscriber } from './NewsletterSubscriber'export type { default as OptionType } from './OptionType'diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.tsindex 950396b82d..3aa8a09d59 100644--- a/packages/sdk/src/types/index.ts+++ b/packages/sdk/src/types/index.ts@@ -18,7 +18,7 @@ export type {Export,GiftCardBatch,GiftCard,- Image,+ Media,ImportRow,Import,Invitation,@@ -74,7 +74,7 @@ export type { DigitalLink as StoreDigitalLink } from './generated';export type { Digital as StoreDigital } from './generated';export type { GiftCardBatch as StoreGiftCardBatch } from './generated';export type { GiftCard as StoreGiftCard } from './generated';-export type { Image as StoreImage } from './generated';+export type { Media as StoreMedia } from './generated';export type { LineItem as StoreLineItem } from './generated';export type { Locale as StoreLocale } from './generated';export type { Market as StoreMarket } from './generated';diff --git a/packages/sdk/src/zod/generated/Image.ts b/packages/sdk/src/zod/generated/Media.tssimilarity index 56%rename from packages/sdk/src/zod/generated/Image.tsrename to packages/sdk/src/zod/generated/Media.tsindex 58c98f6773..66965ec27a 100644--- a/packages/sdk/src/zod/generated/Image.ts+++ b/packages/sdk/src/zod/generated/Media.ts@@ -1,13 +1,16 @@// This file is auto-generated. Do not edit directly.import { z } from 'zod';-export const ImageSchema = z.object({+export const MediaSchema = z.object({id: z.string(),- viewable_id: z.string(),- type: z.string().nullable(),- viewable_type: z.string(),- position: z.number().nullable(),+ product_id: z.string().nullable(),+ variant_ids: z.array(z.string()),+ position: z.number(),alt: z.string().nullable(),+ media_type: z.string(),+ focal_point_x: z.number().nullable(),+ focal_point_y: z.number().nullable(),+ external_video_url: z.string().nullable(),created_at: z.string(),updated_at: z.string(),original_url: z.string().nullable(),@@ -19,4 +22,4 @@ export const ImageSchema = z.object({og_image_url: z.string().nullable(),});-export type Image = z.infer<typeof ImageSchema>;+export type Media = z.infer<typeof MediaSchema>;diff --git a/packages/sdk/src/zod/generated/Product.ts b/packages/sdk/src/zod/generated/Product.tsindex a2b3018472..393652f8be 100644--- a/packages/sdk/src/zod/generated/Product.ts+++ b/packages/sdk/src/zod/generated/Product.ts@@ -1,7 +1,7 @@// This file is auto-generated. Do not edit directly.import { z } from 'zod';import { CategorySchema } from './Category';-import { ImageSchema } from './Image';+import { MediaSchema } from './Media';import { MetafieldSchema } from './Metafield';import { OptionTypeSchema } from './OptionType';import { PriceSchema } from './Price';@@ -27,7 +27,8 @@ export const ProductSchema = z.object({tags: z.array(z.string()),price: PriceSchema,original_price: PriceSchema.nullable(),- images: z.array(ImageSchema).optional(),+ primary_media: MediaSchema.optional(),+ media: z.array(MediaSchema).optional(),variants: z.array(VariantSchema).optional(),default_variant: VariantSchema.optional(),master_variant: VariantSchema.optional(),diff --git a/packages/sdk/src/zod/generated/Variant.ts b/packages/sdk/src/zod/generated/Variant.tsindex 304651dd3b..67be7b540f 100644--- a/packages/sdk/src/zod/generated/Variant.ts+++ b/packages/sdk/src/zod/generated/Variant.ts@@ -1,6 +1,6 @@// This file is auto-generated. Do not edit directly.import { z } from 'zod';-import { ImageSchema } from './Image';+import { MediaSchema } from './Media';import { MetafieldSchema } from './Metafield';import { OptionValueSchema } from './OptionValue';import { PriceSchema } from './Price';@@ -12,10 +12,10 @@ export const VariantSchema = z.object({is_master: z.boolean(),options_text: z.string(),track_inventory: z.boolean(),- image_count: z.number(),+ media_count: z.number(),created_at: z.string(),updated_at: z.string(),- thumbnail: z.string().nullable(),+ thumbnail_url: z.string().nullable(),purchasable: z.boolean(),in_stock: z.boolean(),backorderable: z.boolean(),@@ -25,7 +25,8 @@ export const VariantSchema = z.object({depth: z.number().nullable(),price: PriceSchema,original_price: PriceSchema.nullable(),- images: z.array(ImageSchema).optional(),+ primary_media: MediaSchema.optional(),+ media: z.array(MediaSchema).optional(),option_values: z.array(OptionValueSchema),metafields: z.array(MetafieldSchema).optional(),});diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.tsindex e6aa2509e2..6411339754 100644--- a/packages/sdk/src/zod/generated/index.ts+++ b/packages/sdk/src/zod/generated/index.ts@@ -15,13 +15,13 @@ export { DigitalLinkSchema, type DigitalLink } from './DigitalLink';export { ExportSchema, type Export } from './Export';export { GiftCardSchema, type GiftCard } from './GiftCard';export { GiftCardBatchSchema, type GiftCardBatch } from './GiftCardBatch';-export { ImageSchema, type Image } from './Image';export { ImportSchema, type Import } from './Import';export { ImportRowSchema, type ImportRow } from './ImportRow';export { InvitationSchema, type Invitation } from './Invitation';export { LineItemSchema, type LineItem } from './LineItem';export { LocaleSchema, type Locale } from './Locale';export { MarketSchema, type Market } from './Market';+export { MediaSchema, type Media } from './Media';export { MetafieldSchema, type Metafield } from './Metafield';export { NewsletterSubscriberSchema, type NewsletterSubscriber } from './NewsletterSubscriber';export { OptionTypeSchema, type OptionType } from './OptionType';diff --git a/packages/sdk/tests/params.test.ts b/packages/sdk/tests/params.test.tsindex 15cd0eab15..fe9f3b644d 100644--- a/packages/sdk/tests/params.test.ts+++ b/packages/sdk/tests/params.test.ts@@ -8,8 +8,8 @@ describe('transformListParams', () => {});it('joins expand array into comma-separated string', () => {- const result = transformListParams({ expand: ['variants', 'images'] });- expect(result).toEqual({ expand: 'variants,images' });+ const result = transformListParams({ expand: ['variants', 'media'] });+ expect(result).toEqual({ expand: 'variants,media' });});it('joins single-element expand array', () => {@@ -95,7 +95,7 @@ describe('transformListParams', () => {const result = transformListParams({page: 1,limit: 12,- expand: ['images', 'default_variant'],+ expand: ['media', 'default_variant'],sort: '-created_at',name_cont: 'shirt',price_gte: 20,@@ -104,7 +104,7 @@ describe('transformListParams', () => {expect(result).toEqual({page: 1,limit: 12,- expand: 'images,default_variant',+ expand: 'media,default_variant',sort: '-created_at','q[name_cont]': 'shirt','q[price_gte]': 20,diff --git a/packages/sdk/tests/products.test.ts b/packages/sdk/tests/products.test.tsindex fd189a6d66..144a287243 100644--- a/packages/sdk/tests/products.test.ts+++ b/packages/sdk/tests/products.test.ts@@ -56,10 +56,10 @@ describe('products', () => {});await customClient.products.get('test-product', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],});- expect(capturedUrl).toContain('expand=variants%2Cimages');+ expect(capturedUrl).toContain('expand=variants%2Cmedia');});it('omits expand param when array is empty', async () => {diff --git a/server/Gemfile.lock b/server/Gemfile.lockindex a7d65a7a5f..8a65ba01ff 100644--- a/server/Gemfile.lock+++ b/server/Gemfile.lock@@ -11,7 +11,7 @@ GITPATHremote: ../spree/adminspecs:- spree_admin (5.4.0.beta6)+ spree_admin (5.4.0.beta7)active_link_tobreadcrumbs_on_rails (~> 4.1)chartkick (~> 5.0)@@ -23,7 +23,7 @@ PATHmapkick-rb (~> 0.1)pagy (~> 43.0)ruby-oembed (~> 0.18)- spree (>= 5.4.0.beta6)+ spree (>= 5.4.0.beta7)stimulus-railstailwindcss-rails (>= 4.0)tailwindcss-ruby (>= 4.0)@@ -33,22 +33,22 @@ PATHPATHremote: ../spree/emailsspecs:- spree_emails (5.4.0.beta6)- spree (>= 5.4.0.beta6)+ spree_emails (5.4.0.beta7)+ spree (>= 5.4.0.beta7)PATHremote: ../spreespecs:- spree (5.4.0.beta6)- spree_api (= 5.4.0.beta6)- spree_core (= 5.4.0.beta6)- spree_api (5.4.0.beta6)+ spree (5.4.0.beta7)+ spree_api (= 5.4.0.beta7)+ spree_core (= 5.4.0.beta7)+ spree_api (5.4.0.beta7)alba (~> 3.0)oj (~> 3.16)pagy (~> 43.0)- spree_core (= 5.4.0.beta6)+ spree_core (= 5.4.0.beta7)typelizer (~> 0.10.0)- spree_core (5.4.0.beta6)+ spree_core (5.4.0.beta7)active_storage_validations (= 1.3.0)acts-as-taggable-onacts_as_list (>= 0.8)@@ -1125,12 +1125,12 @@ CHECKSUMSsimplecov-cobertura (3.1.0) sha256=6d7f38aa32c965ca2174b2e5bd88cb17138eaf629518854976ac50e628925dc5simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428- spree (5.4.0.beta6)- spree_admin (5.4.0.beta6)- spree_api (5.4.0.beta6)- spree_core (5.4.0.beta6)+ spree (5.4.0.beta7)+ spree_admin (5.4.0.beta7)+ spree_api (5.4.0.beta7)+ spree_core (5.4.0.beta7)spree_dev_tools (0.5.3) sha256=64ae7b215ac5d5c5f5890f6fc0dbcb12882b9af305a860f36f95f564ec240a75- spree_emails (5.4.0.beta6)+ spree_emails (5.4.0.beta7)spree_extension (1.0.2) sha256=71725dafe45319a2be1bd2b564a416afe8029af8e18ac703bdb835e09553e1dfspree_i18n (5.3.2) sha256=03b805235ca156644951f6bc3d07cbe43d0aa01134c4a27e3f3304011956f79bspree_stripe (1.6.0.beta)diff --git a/server/db/schema.rb b/server/db/schema.rbindex f752cc5d0f..4276db020b 100644--- a/server/db/schema.rb+++ b/server/db/schema.rb@@ -10,7 +10,7 @@## It's strongly recommended that you check this file into your version control system.-ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) do+ActiveRecord::Schema[8.1].define(version: 2026_03_16_114857) do# These are extensions that must be enabled in order to support this databaseenable_extension "pg_catalog.plpgsql"enable_extension "pg_trgm"@@ -195,6 +195,10 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.datetime "attachment_updated_at", precision: nilt.integer "attachment_width"t.datetime "created_at", precision: nil+ t.string "external_video_url"+ t.decimal "focal_point_x", precision: 5, scale: 4+ t.decimal "focal_point_y", precision: 5, scale: 4+ t.string "media_type"t.integer "position"t.jsonb "private_metadata"t.jsonb "public_metadata"@@ -203,6 +207,7 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.datetime "updated_at", precision: nilt.bigint "viewable_id"t.string "viewable_type"+ t.index ["media_type"], name: "index_spree_assets_on_media_type"t.index ["position"], name: "index_spree_assets_on_position"t.index ["viewable_id"], name: "index_assets_on_viewable_id"t.index ["viewable_type", "type"], name: "index_assets_on_viewable_type_and_type"@@ -1016,10 +1021,12 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.text "description"t.datetime "discontinue_on", precision: nilt.datetime "make_active_at", precision: nil+ t.integer "media_count", default: 0, null: falset.text "meta_description"t.string "meta_keywords"t.string "meta_title"t.string "name", default: "", null: false+ t.bigint "primary_media_id"t.jsonb "private_metadata"t.boolean "promotionable", default: truet.jsonb "public_metadata"@@ -1027,8 +1034,6 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.string "slug"t.string "status", default: "draft", null: falset.bigint "tax_category_id"- t.bigint "thumbnail_id"- t.integer "total_image_count", default: 0, null: falset.datetime "updated_at", null: falset.integer "variant_count", default: 0, null: falset.index ["available_on"], name: "index_spree_products_on_available_on"@@ -1036,15 +1041,15 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.index ["deleted_at"], name: "index_spree_products_on_deleted_at"t.index ["discontinue_on"], name: "index_spree_products_on_discontinue_on"t.index ["make_active_at"], name: "index_spree_products_on_make_active_at"+ t.index ["media_count"], name: "index_spree_products_on_media_count"t.index ["name"], name: "index_spree_products_on_name"+ t.index ["primary_media_id"], name: "index_spree_products_on_primary_media_id"t.index ["promotionable"], name: "index_spree_products_on_promotionable"t.index ["shipping_category_id"], name: "index_spree_products_on_shipping_category_id"t.index ["slug"], name: "index_spree_products_on_slug", unique: truet.index ["status", "deleted_at"], name: "index_spree_products_on_status_and_deleted_at"t.index ["status"], name: "index_spree_products_on_status"t.index ["tax_category_id"], name: "index_spree_products_on_tax_category_id"- t.index ["thumbnail_id"], name: "index_spree_products_on_thumbnail_id"- t.index ["total_image_count"], name: "index_spree_products_on_total_image_count"t.index ["variant_count"], name: "index_spree_products_on_variant_count"end@@ -1899,15 +1904,15 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.string "dimensions_unit"t.datetime "discontinue_on", precision: nilt.decimal "height", precision: 8, scale: 2- t.integer "image_count", default: 0, null: falset.boolean "is_master", default: false+ t.integer "media_count", default: 0, null: falset.integer "position"+ t.bigint "primary_media_id"t.jsonb "private_metadata"t.bigint "product_id"t.jsonb "public_metadata"t.string "sku", default: "", null: falset.bigint "tax_category_id"- t.bigint "thumbnail_id"t.boolean "track_inventory", default: truet.datetime "updated_at", precision: nil, null: falset.decimal "weight", precision: 8, scale: 2, default: "0.0"@@ -1916,13 +1921,13 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) dot.index ["barcode"], name: "index_spree_variants_on_barcode"t.index ["deleted_at"], name: "index_spree_variants_on_deleted_at"t.index ["discontinue_on"], name: "index_spree_variants_on_discontinue_on"- t.index ["image_count"], name: "index_spree_variants_on_image_count"t.index ["is_master"], name: "index_spree_variants_on_is_master"+ t.index ["media_count"], name: "index_spree_variants_on_media_count"t.index ["position"], name: "index_spree_variants_on_position"+ t.index ["primary_media_id"], name: "index_spree_variants_on_primary_media_id"t.index ["product_id"], name: "index_spree_variants_on_product_id"t.index ["sku"], name: "index_spree_variants_on_sku"t.index ["tax_category_id"], name: "index_spree_variants_on_tax_category_id"- t.index ["thumbnail_id"], name: "index_spree_variants_on_thumbnail_id"t.index ["track_inventory"], name: "index_spree_variants_on_track_inventory"enddiff --git a/spree/admin/app/controllers/spree/admin/classifications_controller.rb b/spree/admin/app/controllers/spree/admin/classifications_controller.rbindex c88546a997..7dbd4c82a5 100644--- a/spree/admin/app/controllers/spree/admin/classifications_controller.rb+++ b/spree/admin/app/controllers/spree/admin/classifications_controller.rb@@ -38,7 +38,7 @@ module Spreeincludes(:taxon,product: {- thumbnail: [attachment_attachment: :blob],+ primary_media: [attachment_attachment: :blob],master: [:stock_items, :stock_locations],variants: [:stock_items, :stock_locations]}diff --git a/spree/admin/app/controllers/spree/admin/products_controller.rb b/spree/admin/app/controllers/spree/admin/products_controller.rbindex 263dbe0643..127b36a0f9 100644--- a/spree/admin/app/controllers/spree/admin/products_controller.rb+++ b/spree/admin/app/controllers/spree/admin/products_controller.rb@@ -35,7 +35,7 @@ module Spreescope = current_store.products.not_archived.accessible_by(current_ability, :index)scope = scope.where.not(id: params[:omit_ids].split(',')) if params[:omit_ids].present?- @products = scope.includes(:thumbnail).multi_search(query).limit(params[:limit] || 10)+ @products = scope.includes(:primary_media).multi_search(query).limit(params[:limit] || 10)respond_to do |format|format.turbo_stream do@@ -223,7 +223,7 @@ module Spreedef collection_includes{- thumbnail: [attachment_attachment: :blob],+ primary_media: [attachment_attachment: :blob],stock_items: [],master: [:prices, :stock_items],variants: [:prices, :stock_items]diff --git a/spree/admin/app/views/spree/admin/shared/_product_image.html.erb b/spree/admin/app/views/spree/admin/shared/_product_image.html.erbindex 91d4e150ed..c81daf5e1e 100644--- a/spree/admin/app/views/spree/admin/shared/_product_image.html.erb+++ b/spree/admin/app/views/spree/admin/shared/_product_image.html.erb@@ -1,7 +1,7 @@<% width ||= 50 %><% height ||= 50 %><% variant ||= :mini %>-<% image ||= object.default_image %>+<% image ||= object.primary_media %><% if image.present? && image.attached? && image.variable? %><% alt ||= image.alt || object.name %>diff --git a/spree/admin/spec/controllers/spree/admin/assets_controller_spec.rb b/spree/admin/spec/controllers/spree/admin/assets_controller_spec.rbindex e359b3940e..ccede6604e 100644--- a/spree/admin/spec/controllers/spree/admin/assets_controller_spec.rb+++ b/spree/admin/spec/controllers/spree/admin/assets_controller_spec.rb@@ -60,12 +60,12 @@ describe Spree::Admin::AssetsController, type: :controller doexpect(Spree::Image.last.viewable).to eq(product.master)end- it 'increments variant image_count counter cache' do- expect { subject }.to change { product.master.reload.image_count }.by(1)+ it 'increments variant media_count counter cache' do+ expect { subject }.to change { product.master.reload.media_count }.by(1)end- it 'increments product total_image_count counter cache' do- expect { subject }.to change { product.reload.total_image_count }.by(1)+ it 'increments product media_count counter cache' do+ expect { subject }.to change { product.reload.media_count }.by(1)endendenddiff --git a/spree/api/app/controllers/spree/api/v3/store/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/products_controller.rbindex 62adafe7e1..1bf1d83ac4 100644--- a/spree/api/app/controllers/spree/api/v3/store/products_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/products_controller.rb@@ -41,7 +41,7 @@ module Spree# these scopes are not automatically picked by ar_lazy_preload gem and we need to explicitly include themdef scope_includes[- thumbnail: [attachment_attachment: :blob],+ primary_media: [attachment_attachment: :blob],master: [:prices, stock_items: :stock_location],variants: [:prices, stock_items: :stock_location]]diff --git a/spree/api/app/serializers/spree/api/v3/admin/image_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/image_serializer.rbdeleted file mode 100644index d046b1a965..0000000000--- a/spree/api/app/serializers/spree/api/v3/admin/image_serializer.rb+++ /dev/null@@ -1,10 +0,0 @@-module Spree- module Api- module V3- module Admin- class ImageSerializer < V3::ImageSerializer- end- end- end- end-enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rbnew file mode 100644index 0000000000..82fec18faf--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb@@ -0,0 +1,17 @@+module Spree+ module Api+ module V3+ module Admin+ class MediaSerializer < V3::MediaSerializer+ typelize viewable_type: :string, viewable_id: :string++ attribute :viewable_id do |asset|+ asset.viewable&.prefixed_id+ end++ attributes :viewable_type+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rbindex 70d86edd39..f158c57ae9 100644--- a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb@@ -37,10 +37,14 @@ module Spreeresource: Spree.api.admin_variant_serializer,if: proc { expand?('master_variant') }- many :variant_images,- key: :images,- resource: Spree.api.admin_image_serializer,- if: proc { expand?('images') }+ one :primary_media,+ resource: Spree.api.admin_media_serializer,+ if: proc { expand?('primary_media') }++ many :gallery_media,+ key: :media,+ resource: Spree.api.admin_media_serializer,+ if: proc { expand?('media') }many :option_types,resource: Spree.api.admin_option_type_serializer,diff --git a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rbindex ad728b6368..c022b776d0 100644--- a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb@@ -20,9 +20,14 @@ module Spreeend# Override inherited associations to use admin serializers- many :images,- resource: Spree.api.admin_image_serializer,- if: proc { expand?('images') }+ one :primary_media,+ resource: Spree.api.admin_media_serializer,+ if: proc { expand?('primary_media') }++ many :gallery_media,+ key: :media,+ resource: Spree.api.admin_media_serializer,+ if: proc { expand?('media') }many :option_values, resource: Spree.api.admin_option_value_serializerdiff --git a/spree/api/app/serializers/spree/api/v3/base_serializer.rb b/spree/api/app/serializers/spree/api/v3/base_serializer.rbindex 1294375af8..c64a49c141 100644--- a/spree/api/app/serializers/spree/api/v3/base_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/base_serializer.rb@@ -38,7 +38,7 @@ module Spreeend# Check if an association should be expanded- # Supports dot notation: expand?('variants') matches both 'variants' and 'variants.images'+ # Supports dot notation: expand?('variants') matches both 'variants' and 'variants.media'def expand?(name)name = name.to_sexpands.any? { |e| e == name || e.start_with?("#{name}.") }diff --git a/spree/api/app/serializers/spree/api/v3/image_serializer.rb b/spree/api/app/serializers/spree/api/v3/image_serializer.rbdeleted file mode 100644index 2b98a30ad1..0000000000--- a/spree/api/app/serializers/spree/api/v3/image_serializer.rb+++ /dev/null@@ -1,43 +0,0 @@-module Spree- module Api- module V3- class ImageSerializer < AssetSerializer- typelize position: :number, alt: [:string, nullable: true], viewable_type: :string, viewable_id: :string,- original_url: [:string, nullable: true], mini_url: [:string, nullable: true],- small_url: [:string, nullable: true], medium_url: [:string, nullable: true],- large_url: [:string, nullable: true], xlarge_url: [:string, nullable: true],- og_image_url: [:string, nullable: true]-- attribute :viewable_id do |image|- image.viewable&.prefixed_id- end-- attributes :position, :alt, :viewable_type,- created_at: :iso8601, updated_at: :iso8601-- attribute :original_url do |image|- image_url_for(image)- end-- # Dynamically define attributes for each configured image variant- # Uses named variants from Spree::Config.product_image_variant_sizes- # (e.g., mini, small, medium, large, xlarge)- Spree::Config.product_image_variant_sizes.each_key do |variant_name|- attribute :"#{variant_name}_url" do |image|- variant_url(image, variant_name)- end- end-- private-- def variant_url(image, variant_name)- return nil unless image&.attachment&.attached?-- Rails.application.routes.url_helpers.cdn_image_url(- image.attachment.variant(variant_name)- )- end- end- end- end-enddiff --git a/spree/api/app/serializers/spree/api/v3/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/media_serializer.rbnew file mode 100644index 0000000000..73d83331c2--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/media_serializer.rb@@ -0,0 +1,60 @@+module Spree+ module Api+ module V3+ class MediaSerializer < BaseSerializer+ typelize position: :number, alt: [:string, nullable: true],+ product_id: [:string, nullable: true],+ variant_ids: [:string, multi: true],+ media_type: :string,+ focal_point_x: [:number, nullable: true],+ focal_point_y: [:number, nullable: true],+ external_video_url: [:string, nullable: true],+ original_url: [:string, nullable: true], mini_url: [:string, nullable: true],+ small_url: [:string, nullable: true], medium_url: [:string, nullable: true],+ large_url: [:string, nullable: true], xlarge_url: [:string, nullable: true],+ og_image_url: [:string, nullable: true]++ attribute :product_id do |asset|+ asset.product&.prefixed_id+ end++ # Returns prefixed IDs of variants this media is associated with.+ # Currently: single variant via viewable (legacy). In 6.0: multiple via VariantMedia join table.+ attribute :variant_ids do |asset|+ if asset.viewable_type == 'Spree::Variant'+ [asset.viewable&.prefixed_id].compact+ else+ []+ end+ end++ attributes :position, :alt, :media_type,+ :focal_point_x, :focal_point_y, :external_video_url,+ created_at: :iso8601, updated_at: :iso8601++ attribute :original_url do |asset|+ image_url_for(asset)+ end++ # Dynamically define attributes for each configured image variant+ # Uses named variants from Spree::Config.product_image_variant_sizes+ # (e.g., mini, small, medium, large, xlarge)+ Spree::Config.product_image_variant_sizes.each_key do |variant_name|+ attribute :"#{variant_name}_url" do |asset|+ variant_url(asset, variant_name)+ end+ end++ private++ def variant_url(asset, variant_name)+ return nil unless asset&.attachment&.attached?++ Rails.application.routes.url_helpers.cdn_image_url(+ asset.attachment.variant(variant_name)+ )+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/product_serializer.rbindex 84753f0909..65cdf9cace 100644--- a/spree/api/app/serializers/spree/api/v3/product_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/product_serializer.rb@@ -40,9 +40,9 @@ module Spreeproduct.default_variant&.prefixed_idend- # Main product image URL for listings (cached thumbnail)+ # Main product image URL for listings (cached primary_media)attribute :thumbnail_url do |product|- image_url_for(product.thumbnail)+ image_url_for(product.primary_media)endattribute :tags do |product|@@ -68,10 +68,14 @@ module Spreeend# Conditional associations- many :variant_images,- key: :images,- resource: Spree.api.image_serializer,- if: proc { expand?('images') }+ one :primary_media,+ resource: Spree.api.media_serializer,+ if: proc { expand?('primary_media') }++ many :gallery_media,+ key: :media,+ resource: Spree.api.media_serializer,+ if: proc { expand?('media') }many :variants,resource: Spree.api.variant_serializer,diff --git a/spree/api/app/serializers/spree/api/v3/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/variant_serializer.rbindex a6a81cc4de..24c492f6e3 100644--- a/spree/api/app/serializers/spree/api/v3/variant_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/variant_serializer.rb@@ -5,8 +5,8 @@ module Spree# Customer-facing variant data with limited fieldsclass VariantSerializer < BaseSerializertypelize product_id: :string, sku: [:string, nullable: true],- is_master: :boolean, options_text: :string, track_inventory: :boolean, image_count: :number,- thumbnail: [:string, nullable: true],+ is_master: :boolean, options_text: :string, track_inventory: :boolean, media_count: :number,+ thumbnail_url: [:string, nullable: true],purchasable: :boolean, in_stock: :boolean, backorderable: :boolean,weight: [:number, nullable: true], height: [:number, nullable: true], width: [:number, nullable: true], depth: [:number, nullable: true],price: 'Price',@@ -16,12 +16,12 @@ module Spreevariant.product&.prefixed_idend- attributes :sku, :is_master, :options_text, :track_inventory, :image_count,+ attributes :sku, :is_master, :options_text, :track_inventory, :media_count,created_at: :iso8601, updated_at: :iso8601- # Main variant image URL for listings (cached thumbnail)- attribute :thumbnail do |variant|- image_url_for(variant.thumbnail)+ # Main variant image URL for listings (cached primary_media)+ attribute :thumbnail_url do |variant|+ image_url_for(variant.primary_media)endattribute :purchasable do |variant|@@ -70,9 +70,14 @@ module Spreeend# Conditional associations- many :images,- resource: Spree.api.image_serializer,- if: proc { expand?('images') }+ one :primary_media,+ resource: Spree.api.media_serializer,+ if: proc { expand?('primary_media') }++ many :gallery_media,+ key: :media,+ resource: Spree.api.media_serializer,+ if: proc { expand?('media') }many :option_values, resource: Spree.api.option_value_serializerdiff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 71f37693d9..ef18a29c9f 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -96,7 +96,7 @@ module Spreeprice_serializer: 'Spree::Api::V3::PriceSerializer',product_serializer: 'Spree::Api::V3::ProductSerializer',variant_serializer: 'Spree::Api::V3::VariantSerializer',- image_serializer: 'Spree::Api::V3::ImageSerializer',+ media_serializer: 'Spree::Api::V3::MediaSerializer',option_type_serializer: 'Spree::Api::V3::OptionTypeSerializer',option_value_serializer: 'Spree::Api::V3::OptionValueSerializer',cart_serializer: 'Spree::Api::V3::CartSerializer',@@ -161,7 +161,7 @@ module Spreeadmin_line_item_serializer: 'Spree::Api::V3::Admin::LineItemSerializer',admin_option_type_serializer: 'Spree::Api::V3::Admin::OptionTypeSerializer',admin_option_value_serializer: 'Spree::Api::V3::Admin::OptionValueSerializer',- admin_image_serializer: 'Spree::Api::V3::Admin::ImageSerializer',+ admin_media_serializer: 'Spree::Api::V3::Admin::MediaSerializer',admin_asset_serializer: 'Spree::Api::V3::Admin::AssetSerializer',admin_stock_item_serializer: 'Spree::Api::V3::Admin::StockItemSerializer',admin_shipment_serializer: 'Spree::Api::V3::Admin::ShipmentSerializer',diff --git a/spree/api/spec/controllers/concerns/spree/api/v3/nested_expand_spec.rb b/spree/api/spec/controllers/concerns/spree/api/v3/nested_expand_spec.rbindex 2e16e081b1..cd9dd854bb 100644--- a/spree/api/spec/controllers/concerns/spree/api/v3/nested_expand_spec.rb+++ b/spree/api/spec/controllers/concerns/spree/api/v3/nested_expand_spec.rb@@ -30,58 +30,58 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller doenddescribe 'nested expand with dot notation' do- it 'expands variants with nested images' do- get :show, params: { id: product.prefixed_id, expand: 'variants.images' }+ it 'expands variants with nested media' do+ get :show, params: { id: product.prefixed_id, expand: 'variants.media' }data = JSON.parse(response.body)expect(data).to have_key('variants')data['variants'].each do |variant|- expect(variant).to have_key('images')+ expect(variant).to have_key('media')endend- it 'expands variants without images when only variants requested' do+ it 'expands variants without media when only variants requested' doget :show, params: { id: product.prefixed_id, expand: 'variants' }data = JSON.parse(response.body)expect(data).to have_key('variants')data['variants'].each do |variant|- expect(variant).not_to have_key('images')+ expect(variant).not_to have_key('media')endendit 'supports multiple nested expands' do- get :show, params: { id: product.prefixed_id, expand: 'variants.images,variants.metafields' }+ get :show, params: { id: product.prefixed_id, expand: 'variants.media,variants.metafields' }data = JSON.parse(response.body)expect(data).to have_key('variants')data['variants'].each do |variant|- expect(variant).to have_key('images')+ expect(variant).to have_key('media')expect(variant).to have_key('metafields')endendit 'supports mixed top-level and nested expands' do- get :show, params: { id: product.prefixed_id, expand: 'variants.images,option_types' }+ get :show, params: { id: product.prefixed_id, expand: 'variants.media,option_types' }data = JSON.parse(response.body)expect(data).to have_key('variants')expect(data).to have_key('option_types')data['variants'].each do |variant|- expect(variant).to have_key('images')+ expect(variant).to have_key('media')endendenddescribe 'collection endpoint' doit 'supports nested expand on index' do- get :index, params: { expand: 'variants.images' }+ get :index, params: { expand: 'variants.media' }data = JSON.parse(response.body)['data']data.each do |product|expect(product).to have_key('variants')product['variants'].each do |variant|- expect(variant).to have_key('images')+ expect(variant).to have_key('media')endendenddiff --git a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb b/spree/api/spec/integration/spree/api/v3/store/products_spec.rbindex bad487cb79..5580843179 100644--- a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb@@ -39,7 +39,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/storeprice_gte: 20,price_lte: 100,with_option_value_ids: ['optval_abc', 'optval_def'],- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})JS@@ -64,7 +64,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/storeparameter name: 'q[in_stock]', in: :query, type: :boolean, required: false,description: 'Filter to only in-stock products'parameter name: :expand, in: :query, type: :string, required: false,- description: 'Comma-separated associations to expand (variants, images, categories, option_types)'+ description: 'Comma-separated associations to expand (variants, media, categories, option_types)'parameter name: :fields, in: :query, type: :string, required: false,description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'@@ -107,7 +107,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/storesdk_example <<~JSconst product = await client.products.get('spree-tote', {- expand: ['variants', 'images'],+ expand: ['variants', 'media'],})JSdiff --git a/spree/core/app/helpers/spree/base_helper.rb b/spree/core/app/helpers/spree/base_helper.rbindex 8f9a383bc2..f75b39dc20 100644--- a/spree/core/app/helpers/spree/base_helper.rb+++ b/spree/core/app/helpers/spree/base_helper.rb@@ -149,15 +149,15 @@ module Spree# we should always try to render image of the default variant# same as it's done on PDPdef default_image_for_product(product)- Spree::Deprecation.warn('BaseHelper#default_image_for_product is deprecated and will be removed in Spree 5.5. Please use product.default_image instead')+ Spree::Deprecation.warn('BaseHelper#default_image_for_product is deprecated and will be removed in Spree 6.0. Please use product.primary_media instead')- product.default_image+ product.primary_mediaenddef default_image_for_product_or_variant(product_or_variant)- Spree::Deprecation.warn('BaseHelper#default_image_for_product_or_variant is deprecated and will be removed in Spree 5.5. Please use product_or_variant.default_image instead')+ Spree::Deprecation.warn('BaseHelper#default_image_for_product_or_variant is deprecated and will be removed in Spree 6.0. Please use product_or_variant.primary_media instead')- product_or_variant.default_image+ product_or_variant.primary_mediaenddef base_cache_keydiff --git a/spree/core/app/models/spree/asset.rb b/spree/core/app/models/spree/asset.rbindex 3bf97179dc..053c4b2faa 100644--- a/spree/core/app/models/spree/asset.rb+++ b/spree/core/app/models/spree/asset.rb@@ -1,20 +1,42 @@module Spreeclass Asset < Spree.base_class- has_prefix_id :asset # Stripe: file_+ has_prefix_id :mediainclude Support::ActiveStorage+ include Rails.application.routes.url_helpers+ include Spree::ImageMethods # legacy, will be removed in Spree 6include Spree::Metafieldsinclude Spree::Metadata+ # Legacy styles support (was in Spree::Image::Configuration::ActiveStorage)+ # @deprecated Will be removed in Spree 6+ def self.styles+ @styles ||= Spree::Config.product_image_variant_sizes.transform_values do |dimensions|+ "#{dimensions[0]}x#{dimensions[1]}>"+ end+ end++ def default_style+ :small+ end+publishes_lifecycle_eventsEXTERNAL_URL_METAFIELD_KEY = 'external.url'+ MEDIA_TYPES = %w[image video external_video].freeze++ after_initialize { self.media_type ||= 'image' }belongs_to :viewable, polymorphic: true, touch: trueacts_as_list scope: [:viewable_id, :viewable_type]delegate :key, :attached?, :variant, :variable?, :blob, :filename, :variation, to: :attachment+ validates :media_type, inclusion: { in: MEDIA_TYPES }+ validates :attachment, attached: true, content_type: Rails.application.config.active_storage.web_image_content_types,+ if: -> { media_type == 'image' }+ validates :external_video_url, presence: true, if: -> { media_type.in?(%w[video external_video]) }+WEBP_SAVER_OPTIONS = {strip: true,quality: 75,@@ -43,14 +65,46 @@ module Spreedefault_scope { includes(attachment_attachment: :blob) }+ # STI was disabled in Spree::Image, keep it disabled here+ self.inheritance_column = nil+store_accessor :private_metadata, :session_uploaded_assets_uuidscope :with_session_uploaded_assets_uuid, lambda { |uuid|where(session_id: uuid)}scope :with_external_url, ->(url) { url.present? ? with_metafield_key_value(EXTERNAL_URL_METAFIELD_KEY, url.strip) : none }+ # Callbacks merged from Spree::Image+ after_commit :touch_product_variants, if: :should_touch_product_variants?, on: :update+ after_commit :update_viewable_thumbnail_on_create, on: :create+ after_commit :update_viewable_thumbnail_on_destroy, on: :destroy+ after_commit :update_viewable_thumbnail_on_reorder, on: :update, if: :saved_change_to_position?+ after_commit :update_viewable_thumbnail_on_viewable_change, on: :update, if: :saved_change_to_viewable_id?++ after_create :increment_viewable_media_count+ after_destroy :decrement_viewable_media_count+def product- @product ||= viewable_type == 'Spree::Variant' ? viewable&.product : nil+ @product ||= case viewable_type+ when 'Spree::Variant' then viewable&.product+ when 'Spree::Product' then viewable+ end+ end++ def focal_point+ return nil if focal_point_x.nil? || focal_point_y.nil?++ { x: focal_point_x, y: focal_point_y }+ end++ def focal_point=(point)+ if point.nil?+ self.focal_point_x = nil+ self.focal_point_y = nil+ else+ self.focal_point_x = point[:x]+ self.focal_point_y = point[:y]+ endenddef external_url@@ -66,7 +120,71 @@ module Spreeenddef event_prefix- 'asset'+ 'media'+ end++ # @deprecated+ def styles+ Spree::Deprecation.warn("Asset#styles is deprecated and will be removed in Spree 6.0. Please use active storage variants with cdn_image_url")++ self.class.styles.map do |_, size|+ width, height = size.chop.split('x').map(&:to_i)++ {+ url: generate_url(size: size),+ size: size,+ width: width,+ height: height+ }+ end+ end++ private++ def touch_product_variants+ viewable.product.variants.touch_all+ end++ def should_touch_product_variants?+ viewable.is_a?(Spree::Variant) &&+ viewable.is_master? &&+ viewable.product.has_variants? &&+ saved_change_to_position?+ end++ def increment_viewable_media_count+ case viewable_type+ when 'Spree::Variant'+ Spree::Variant.increment_counter(:media_count, viewable_id)+ Spree::Product.increment_counter(:media_count, viewable.product_id)+ when 'Spree::Product'+ Spree::Product.increment_counter(:media_count, viewable_id)+ end+ end++ def decrement_viewable_media_count+ case viewable_type+ when 'Spree::Variant'+ Spree::Variant.decrement_counter(:media_count, viewable_id)+ Spree::Product.decrement_counter(:media_count, viewable.product_id)+ when 'Spree::Product'+ Spree::Product.decrement_counter(:media_count, viewable_id)+ endend++ def update_viewable_thumbnail+ case viewable_type+ when 'Spree::Variant'+ viewable.update_thumbnail!+ viewable.product.update_thumbnail!+ when 'Spree::Product'+ viewable.update_thumbnail!+ end+ end++ alias update_viewable_thumbnail_on_create update_viewable_thumbnail+ alias update_viewable_thumbnail_on_destroy update_viewable_thumbnail+ alias update_viewable_thumbnail_on_reorder update_viewable_thumbnail+ alias update_viewable_thumbnail_on_viewable_change update_viewable_thumbnailendenddiff --git a/spree/core/app/models/spree/image.rb b/spree/core/app/models/spree/image.rbindex 13295b33a3..9b5b29cda1 100644--- a/spree/core/app/models/spree/image.rb+++ b/spree/core/app/models/spree/image.rb@@ -1,82 +1,6 @@+# Backward compatibility — all logic now lives in Spree::Asset.+# This class will be removed in Spree 6.0.module Spreeclass Image < Asset- include Spree::Image::Configuration::ActiveStorage # legacy to be removed in Spree 6- include Rails.application.routes.url_helpers- include Spree::ImageMethods # legacy, will be removed in Spree 6-- validates :attachment, attached: true, content_type: Rails.application.config.active_storage.web_image_content_types-- after_commit :touch_product_variants, if: :should_touch_product_variants?, on: :update- after_commit :update_variant_thumbnail, on: [:create, :destroy]- after_commit :update_variant_thumbnail_on_reorder, on: :update, if: :saved_change_to_position?- after_commit :update_variant_thumbnail_on_viewable_change, on: :update, if: :saved_change_to_viewable_id?-- after_create :increment_viewable_image_count- after_destroy :decrement_viewable_image_count-- # In Rails 5.x class constants are being undefined/redefined during the code reloading process- # in a rails development environment, after which the actual ruby objects stored in those class constants- # are no longer equal (subclass == self) what causes error ActiveRecord::SubclassNotFound- # Invalid single-table inheritance type: Spree::Image is not a subclass of Spree::Image.- # The line below prevents the error.- self.inheritance_column = nil-- # @deprecated- def styles- Spree::Deprecation.warn("Image#styles is deprecated and will be removed in Spree 6.0. Please use active storage variants with cdn_image_url")-- self.class.styles.map do |_, size|- width, height = size.chop.split('x').map(&:to_i)-- {- url: generate_url(size: size),- size: size,- width: width,- height: height- }- end- end-- private-- def touch_product_variants- viewable.product.variants.touch_all- end-- def should_touch_product_variants?- viewable.is_a?(Spree::Variant) &&- viewable.is_master? &&- viewable.product.has_variants? &&- saved_change_to_position?- end-- def increment_viewable_image_count- return unless viewable.is_a?(Spree::Variant)-- Spree::Variant.increment_counter(:image_count, viewable_id)- Spree::Product.increment_counter(:total_image_count, viewable.product_id)- end-- def decrement_viewable_image_count- return unless viewable.is_a?(Spree::Variant)-- Spree::Variant.decrement_counter(:image_count, viewable_id)- Spree::Product.decrement_counter(:total_image_count, viewable.product_id)- end-- def update_variant_thumbnail- return unless viewable.is_a?(Spree::Variant)-- viewable.update_thumbnail!- viewable.product.update_thumbnail!- end-- def update_variant_thumbnail_on_reorder- update_variant_thumbnail- end-- def update_variant_thumbnail_on_viewable_change- update_variant_thumbnail- endendenddiff --git a/spree/core/app/models/spree/image/configuration/active_storage.rb b/spree/core/app/models/spree/image/configuration/active_storage.rbindex e8a5583ef1..d044c98a22 100644--- a/spree/core/app/models/spree/image/configuration/active_storage.rb+++ b/spree/core/app/models/spree/image/configuration/active_storage.rb@@ -1,22 +1,10 @@+# @deprecated This module is now a no-op. All logic has been moved to Spree::Asset.+# Will be removed in Spree 6.0.module Spreeclass Image < Assetmodule Configurationmodule ActiveStorageextend ActiveSupport::Concern-- included do- # Returns image styles derived from Spree::Config.product_image_variant_sizes- # Format: { variant_name: 'WxH>' } for API compatibility- def self.styles- @styles ||= Spree::Config.product_image_variant_sizes.transform_values do |dimensions|- "#{dimensions[0]}x#{dimensions[1]}>"- end- end-- def default_style- :small- end- endendendenddiff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rbindex bd581c1951..b8e27d5bda 100644--- a/spree/core/app/models/spree/line_item.rb+++ b/spree/core/app/models/spree/line_item.rb@@ -55,10 +55,10 @@ module Spreedelegate :name, :description, :brand, :category, to: :product# Returns the thumbnail image for this line item- # Prefers variant thumbnail, falls back to product thumbnail- # @return [Spree::Image, nil]+ # Prefers variant primary media, falls back to product primary media+ # @return [Spree::Asset, nil]def thumbnail- variant.thumbnail || product.thumbnail+ variant.primary_media || product.primary_mediaenddelegate :tax_zone, to: :orderdelegate :digital?, :can_supply?, to: :variantdiff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rbindex 73c94c32d5..8b4b648962 100644--- a/spree/core/app/models/spree/product.rb+++ b/spree/core/app/models/spree/product.rb@@ -114,10 +114,12 @@ module Spreehas_many :orders, through: :line_itemshas_many :completed_orders, -> { reorder(nil).distinct.complete }, through: :line_items, source: :order+ has_many :media, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'+has_many :variant_images, -> { order(:position) }, source: :images, through: :variants_including_masterhas_many :variant_images_without_master, -> { order(:position) }, source: :images, through: :variants- belongs_to :thumbnail, class_name: 'Spree::Image', optional: true+ belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_idhas_many :option_value_variants, class_name: 'Spree::OptionValueVariant', through: :variantshas_many :option_values, class_name: 'Spree::OptionValue', through: :variants@@ -335,17 +337,26 @@ module Spree@default_variant_id ||= default_variant.idend- # Returns true if any variant (including master) has images.- # Uses loaded association when available, otherwise falls back to counter cache.+ # Returns the product's media gallery.+ # Uses product-level media if present, otherwise falls back to variant images.+ # @return [ActiveRecord::Relation]+ def gallery_media+ return media if association(:media).loaded? ? media.any? : media.exists?++ variant_images+ end++ # Returns true if the product has any media (product-level or variant-level).+ # Uses counter cache for performance.# @return [Boolean]- def has_variant_images?+ def has_media?return variant_images.any? if association(:variant_images).loaded?- total_image_count.positive?+ media_count.positive?end- # Alias for has_variant_images? for consistency with Variant#has_images?- alias has_images? has_variant_images?+ alias has_images? has_media?+ alias has_variant_images? has_media?# Returns the variant that should be used for displaying images.# Priority: master > default_variant > first variant with images@@ -354,47 +365,47 @@ module Spree@variant_for_images ||= find_variant_for_imagesend- # Returns default Image for Product.- # Uses cached thumbnail_id which is updated when images are added/removed/reordered.- # @return [Spree::Image, nil]+ # @deprecated Use #primary_media instead.def default_image- thumbnail+ Spree::Deprecation.warn('Spree::Product#default_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')+ primary_mediaend- # Backward compatibility for Spree 5.2 and earlier.- # @deprecated Use Spree::Product#default_image instead.+ # @deprecated Use #primary_media instead.def featured_image- Spree::Deprecation.warn('Spree::Product#featured_image is deprecated and will be removed in Spree 5.5. Please use Spree::Product#default_image instead.')+ Spree::Deprecation.warn('Spree::Product#featured_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')+ primary_media+ end- default_image+ # @deprecated Use #primary_media instead.+ def primary_image+ Spree::Deprecation.warn('Spree::Product#primary_image is deprecated and will be removed in Spree 6.0. Please use Spree::Product#primary_media instead.')+ primary_mediaend- # Returns secondary Image for Product (for hover effects).- # @return [Spree::Image, nil]+ # Returns secondary media for Product (for hover effects).+ # @return [Spree::Asset, nil]def secondary_imagevariant_for_images&.secondary_imageend- # Alias for default_image for consistency.- alias primary_image default_image-- # Returns the image count from the variant used for displaying images.- # @return [Integer]+ # @deprecated Use media_count insteaddef image_count- variant_for_images&.image_count || 0+ media_countend- # Updates the thumbnail_id to the first image from variant_images.- # Called when images are added, removed, or reordered on any variant.+ # Updates primary_media_id to the first media item.+ # Checks product-level media first, then falls back to variant images.+ # Called when media is added, removed, or reordered.def update_thumbnail!- first_image = variant_images.order(:position).first- update_column(:thumbnail_id, first_image&.id)+ first_media = media.order(:position).first || variant_images.order(:position).first+ update_column(:primary_media_id, first_media&.id)end- # Finds first variant with images using preloaded data when available.+ # Finds first variant with media using preloaded data when available.# @return [Spree::Variant, nil]def find_variant_with_images- return variants.find(&:has_images?) if variants.loaded?+ return variants.find(&:has_media?) if variants.loaded?variants.joins(:images).firstend@@ -630,12 +641,12 @@ module Spreeprivate- # Determines which variant should be used for displaying images.- # Priority: master > default_variant > first variant with images+ # Determines which variant should be used for displaying media.+ # Priority: master > default_variant > first variant with mediadef find_variant_for_images- return master if master.has_images?- return default_variant if has_variants? && default_variant.has_images?- return find_variant_with_images if has_variant_images?+ return master if master.has_media?+ return default_variant if has_variants? && default_variant.has_media?+ return find_variant_with_images if has_media?nilenddiff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rbindex 9c213e209b..9dae271f3f 100644--- a/spree/core/app/models/spree/variant.rb+++ b/spree/core/app/models/spree/variant.rb@@ -48,8 +48,8 @@ module Spreehas_many :option_value_variants, class_name: 'Spree::OptionValueVariant'has_many :option_values, through: :option_value_variants, dependent: :destroy, class_name: 'Spree::OptionValue'- has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Image'- belongs_to :thumbnail, class_name: 'Spree::Image', optional: true+ has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'+ belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_idhas_many :prices,class_name: 'Spree::Price',@@ -279,26 +279,35 @@ module Spreeis_master? ? name + ' - Master' : name + ' - ' + options_textend- # Returns true if the variant has images.+ # Returns the variant's media gallery.+ # Currently returns direct images. In 6.0 will use variant_media join table.+ # @return [ActiveRecord::Relation]+ def gallery_media+ images+ end++ # Returns true if the variant has media.# Uses loaded association when available, otherwise falls back to counter cache.# @return [Boolean]- def has_images?+ def has_media?return images.any? if images.loaded?- image_count.positive?+ media_count.positive?end- # Returns default Image for Variant.- # @return [Spree::Image, nil]+ alias has_images? has_media?++ # @deprecated Use #primary_media instead.def default_image- thumbnail+ Spree::Deprecation.warn('Spree::Variant#default_image is deprecated and will be removed in Spree 6.0. Please use Spree::Variant#primary_media instead.')+ primary_mediaend- # Updates the thumbnail_id to the first image by position.- # Called when images are added, removed, or reordered.+ # Updates primary_media_id to the first media item by position.+ # Called when media is added, removed, or reordered.def update_thumbnail!- first_image = images.order(:position).first- update_column(:thumbnail_id, first_image&.id)+ first_media = images.order(:position).first+ update_column(:primary_media_id, first_media&.id)end# Returns first Image for Variant.diff --git a/spree/core/db/migrate/20260315100000_add_product_media_support.rb b/spree/core/db/migrate/20260315100000_add_product_media_support.rbnew file mode 100644index 0000000000..a2d428bb67--- /dev/null+++ b/spree/core/db/migrate/20260315100000_add_product_media_support.rb@@ -0,0 +1,21 @@+class AddProductMediaSupport < ActiveRecord::Migration[7.2]+ def change+ add_column :spree_assets, :media_type, :string+ add_column :spree_assets, :focal_point_x, :decimal, precision: 5, scale: 4+ add_column :spree_assets, :focal_point_y, :decimal, precision: 5, scale: 4+ add_column :spree_assets, :external_video_url, :string++ add_index :spree_assets, :media_type++ rename_column :spree_variants, :image_count, :media_count+ rename_column :spree_products, :total_image_count, :media_count+ rename_column :spree_variants, :thumbnail_id, :primary_media_id+ rename_column :spree_products, :thumbnail_id, :primary_media_id++ reversible do |dir|+ dir.up do+ Spree::Asset.unscoped.where(media_type: nil).update_all(media_type: 'image')+ end+ end+ end+enddiff --git a/spree/core/lib/spree/permitted_attributes.rb b/spree/core/lib/spree/permitted_attributes.rbindex 9489da2d99..7edce87cba 100644--- a/spree/core/lib/spree/permitted_attributes.rb+++ b/spree/core/lib/spree/permitted_attributes.rb@@ -92,7 +92,8 @@ module Spree@@api_key_attributes = [:name, :key_type]- @@asset_attributes = [:type, :viewable_id, :viewable_type, :attachment, :alt, :position]+ @@asset_attributes = [:type, :viewable_id, :viewable_type, :attachment, :alt, :position,+ :media_type, :focal_point_x, :focal_point_y, :external_video_url]@@checkout_attributes = [:coupon_code, :email, :shipping_method_id, :special_instructions, :use_billing, :use_shipping,diff --git a/spree/core/lib/spree/testing_support/factories/asset_factory.rb b/spree/core/lib/spree/testing_support/factories/asset_factory.rbindex e08b6142db..c6b55f11d9 100644--- a/spree/core/lib/spree/testing_support/factories/asset_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/asset_factory.rb@@ -1,15 +1,12 @@FactoryBot.define dofactory :asset, class: Spree::Asset do- viewable_type {}- viewable_id {}- attachment_width { 340 }- attachment_height { 280 }- attachment_file_size { 128 }position { 1 }- attachment_content_type { '.jpg' }- attachment_file_name { 'attachment.jpg' }- type {}- attachment_updated_at {}alt {}++ after(:build) do |asset|+ if asset.media_type == 'image' && !asset.attachment.attached?+ asset.attachment.attach(io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'), filename: 'thinking-cat.jpg')+ end+ endendenddiff --git a/spree/core/lib/spree/testing_support/factories/image_factory.rb b/spree/core/lib/spree/testing_support/factories/image_factory.rbindex 9ceef6f222..320ddcd0d8 100644--- a/spree/core/lib/spree/testing_support/factories/image_factory.rb+++ b/spree/core/lib/spree/testing_support/factories/image_factory.rb@@ -1,5 +1,7 @@FactoryBot.define do- factory :image, class: Spree::Image do+ factory :image, class: Spree::Asset do+ media_type { 'image' }+before(:create) do |image|if image.class.method_defined?(:attachment)image.attachment.attach(io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'), filename: 'thinking-cat.jpg')diff --git a/spree/core/lib/tasks/images.rake b/spree/core/lib/tasks/images.rakeindex db37112d44..073900dd2a 100644--- a/spree/core/lib/tasks/images.rake+++ b/spree/core/lib/tasks/images.rake@@ -1,17 +1,17 @@namespace :spree do- namespace :images do- desc 'Backfill thumbnail_id for all variants and products'- task backfill_thumbnails: :environment do- puts 'Backfilling variant thumbnails...'- Spree::Variant.where(thumbnail_id: nil).where.not(image_count: 0).find_each do |variant|- first_image = variant.images.order(:position).first- variant.update_column(:thumbnail_id, first_image.id) if first_image+ namespace :media do+ desc 'Backfill primary_media_id for all variants and products'+ task backfill_primary_media: :environment do+ puts 'Backfilling variant primary_media...'+ Spree::Variant.where(primary_media_id: nil).where.not(media_count: 0).find_each do |variant|+ first_media = variant.gallery_media.first+ variant.update_column(:primary_media_id, first_media.id) if first_mediaend- puts 'Backfilling product thumbnails...'- Spree::Product.where(thumbnail_id: nil).where.not(total_image_count: 0).find_each do |product|- first_image = product.variant_images.order(:position).first- product.update_column(:thumbnail_id, first_image.id) if first_image+ puts 'Backfilling product primary_media...'+ Spree::Product.where(primary_media_id: nil).where.not(media_count: 0).find_each do |product|+ first_media = product.gallery_media.first+ product.update_column(:primary_media_id, first_media.id) if first_mediaendputs 'Done!'diff --git a/spree/core/lib/tasks/products.rake b/spree/core/lib/tasks/products.rakeindex 7b1272a14e..be71883dda 100644--- a/spree/core/lib/tasks/products.rake+++ b/spree/core/lib/tasks/products.rake@@ -1,14 +1,16 @@namespace :spree donamespace :products do- desc 'Reset counter caches (variant_count, classification_count, total_image_count) on products'+ desc 'Reset counter caches (variant_count, classification_count, media_count) on products'task reset_counter_caches: :environment do |_t, _args|puts 'Resetting product counter caches...'Spree::Product.find_each do |product|+ total_media = product.media.count + product.variant_images.where.not(id: product.media.select(:id)).count+product.update_columns(variant_count: product.variants.count,classification_count: product.classifications.count,- total_image_count: product.variant_images.count,+ media_count: total_media,updated_at: Time.current)print '.'diff --git a/spree/core/spec/models/spree/asset_media_spec.rb b/spree/core/spec/models/spree/asset_media_spec.rbnew file mode 100644index 0000000000..a7b8a25ad2--- /dev/null+++ b/spree/core/spec/models/spree/asset_media_spec.rb@@ -0,0 +1,161 @@+require 'spec_helper'++RSpec.describe 'Product media system', type: :model do+ describe 'Spree::Asset' do+ describe '#focal_point' do+ let(:asset) { build(:asset, focal_point_x: 0.5, focal_point_y: 0.3) }++ it 'returns hash with x and y' do+ expect(asset.focal_point).to eq({ x: 0.5, y: 0.3 })+ end++ it 'returns nil when coordinates are not set' do+ asset.focal_point_x = nil+ expect(asset.focal_point).to be_nil+ end+ end++ describe '#focal_point=' do+ let(:asset) { build(:asset) }++ it 'sets x and y from hash' do+ asset.focal_point = { x: 0.25, y: 0.75 }+ expect(asset.focal_point_x).to eq(0.25)+ expect(asset.focal_point_y).to eq(0.75)+ end++ it 'clears focal point when set to nil' do+ asset.focal_point = { x: 0.5, y: 0.5 }+ asset.focal_point = nil+ expect(asset.focal_point_x).to be_nil+ expect(asset.focal_point_y).to be_nil+ end+ end++ describe '#product' do+ it 'returns product when viewable is a Product' do+ product = create(:product)+ asset = create(:image, viewable: product)+ expect(asset.product).to eq(product)+ end+ end++ describe 'media_type validation' do+ it 'accepts valid media types' do+ %w[image video external_video].each do |type|+ asset = build(:asset, media_type: type)+ asset.valid?+ expect(asset.errors[:media_type]).to be_empty+ end+ end++ it 'rejects invalid media types' do+ asset = build(:asset, media_type: 'audio')+ expect(asset).not_to be_valid+ expect(asset.errors[:media_type]).to be_present+ end++ it 'defaults to image' do+ asset = Spree::Asset.new+ expect(asset.media_type).to eq('image')+ end++ it 'defaults to image for Spree::Image subclass' do+ image = Spree::Image.new+ expect(image.media_type).to eq('image')+ end+ end++ describe 'counter caches with product viewable' do+ let(:product) { create(:product) }++ it 'increments media_count on product when image is created' do+ expect {+ create(:image, viewable: product)+ }.to change { product.reload.media_count }.by(1)+ end++ it 'decrements media_count on product when image is destroyed' do+ image = create(:image, viewable: product)+ expect {+ image.destroy+ }.to change { product.reload.media_count }.by(-1)+ end+ end++ describe 'thumbnail updates with product viewable' do+ let(:product) { create(:product) }++ it 'sets product primary_media_id when image is created' do+ image = create(:image, viewable: product)+ expect(product.reload.primary_media_id).to eq(image.id)+ end++ it 'clears product primary_media_id when last image is destroyed' do+ image = create(:image, viewable: product)+ image.destroy+ expect(product.reload.primary_media_id).to be_nil+ end+ end+ end++ describe 'Spree::Product' do+ let(:product) { create(:product) }++ describe '#media' do+ it 'returns product-level assets' do+ image = create(:image, viewable: product)+ expect(product.media).to include(image)+ end++ it 'does not include variant images' do+ variant_image = create(:image, viewable: product.master)+ expect(product.media).not_to include(variant_image)+ end++ it 'is ordered by position' do+ img2 = create(:image, viewable: product, position: 2)+ img1 = create(:image, viewable: product, position: 1)+ expect(product.media.to_a).to eq([img1, img2])+ end+ end++ describe '#gallery_media' do+ it 'returns product media when present' do+ product_image = create(:image, viewable: product)+ create(:image, viewable: product.master) # variant image+ expect(product.reload.gallery_media).to include(product_image)+ end++ it 'falls back to variant_images when no product media' do+ variant_image = create(:image, viewable: product.master)+ expect(product.reload.gallery_media).to include(variant_image)+ end+ end++ describe '#update_thumbnail!' do+ it 'uses product media first' do+ product_image = create(:image, viewable: product)+ expect(product.reload.primary_media_id).to eq(product_image.id)+ end++ it 'falls back to variant images when no product media' do+ variant_image = create(:image, viewable: product.master)+ product.update_thumbnail!+ expect(product.reload.primary_media_id).to eq(variant_image.id)+ end+ end+ end++ describe 'Spree::Variant' do+ let(:product) { create(:product) }+ let(:variant) { create(:variant, product: product) }++ describe '#gallery_media' do+ it 'returns direct images' do+ direct_image = create(:image, viewable: variant)+ expect(variant.gallery_media).to include(direct_image)+ end+ end+ end+enddiff --git a/spree/core/spec/models/spree/asset_spec.rb b/spree/core/spec/models/spree/asset_spec.rbindex 2ff717ba77..928e09fcad 100644--- a/spree/core/spec/models/spree/asset_spec.rb+++ b/spree/core/spec/models/spree/asset_spec.rb@@ -2,7 +2,7 @@ require 'spec_helper'describe Spree::Asset, type: :model doit_behaves_like 'metadata'- it_behaves_like 'lifecycle events'+ it_behaves_like 'lifecycle events', event_prefix: 'media'describe 'named variants' dolet(:reflection) { described_class.attachment_reflections['attachment'] }diff --git a/spree/core/spec/models/spree/image_spec.rb b/spree/core/spec/models/spree/image_spec.rbindex 719a891b6b..897fd5bc41 100644--- a/spree/core/spec/models/spree/image_spec.rb+++ b/spree/core/spec/models/spree/image_spec.rb@@ -64,92 +64,92 @@ describe Spree::Image, type: :model doendend- describe 'image_count counter cache' do+ describe 'media_count counter cache' dolet(:variant) { create(:variant) }- it 'increments image_count when image is created' do- expect { create(:image, viewable: variant) }.to change { variant.reload.image_count }.by(1)+ it 'increments media_count when image is created' do+ expect { create(:image, viewable: variant) }.to change { variant.reload.media_count }.by(1)end- it 'decrements image_count when image is destroyed' do+ it 'decrements media_count when image is destroyed' doimage = create(:image, viewable: variant)- expect { image.destroy }.to change { variant.reload.image_count }.by(-1)+ expect { image.destroy }.to change { variant.reload.media_count }.by(-1)endit 'tracks multiple images correctly' do- expect(variant.image_count).to eq(0)+ expect(variant.media_count).to eq(0)create(:image, viewable: variant)create(:image, viewable: variant)- expect(variant.reload.image_count).to eq(2)+ expect(variant.reload.media_count).to eq(2)endend- describe 'total_image_count counter cache on product' do+ describe 'product media_count counter cache' dolet(:product) { create(:product) }let(:variant) { create(:variant, product: product) }- it 'increments total_image_count when image is created on master' do- expect { create(:image, viewable: product.master) }.to change { product.reload.total_image_count }.by(1)+ it 'increments media_count when image is created on master' do+ expect { create(:image, viewable: product.master) }.to change { product.reload.media_count }.by(1)end- it 'increments total_image_count when image is created on variant' do- expect { create(:image, viewable: variant) }.to change { product.reload.total_image_count }.by(1)+ it 'increments media_count when image is created on variant' do+ expect { create(:image, viewable: variant) }.to change { product.reload.media_count }.by(1)end- it 'decrements total_image_count when image is destroyed' do+ it 'decrements media_count when image is destroyed' doimage = create(:image, viewable: variant)- expect { image.destroy }.to change { product.reload.total_image_count }.by(-1)+ expect { image.destroy }.to change { product.reload.media_count }.by(-1)end- it 'tracks images across all variants correctly' do- expect(product.total_image_count).to eq(0)+ it 'tracks media across all variants correctly' do+ expect(product.media_count).to eq(0)create(:image, viewable: product.master)create(:image, viewable: variant)create(:image, viewable: variant)- expect(product.reload.total_image_count).to eq(3)+ expect(product.reload.media_count).to eq(3)endend- describe 'thumbnail_id updates' do+ describe 'primary_media_id updates' dolet(:product) { create(:product) }let(:variant) { product.master }- it 'sets variant thumbnail_id when first image is created' do- expect(variant.thumbnail_id).to be_nil+ it 'sets variant primary_media_id when first image is created' do+ expect(variant.primary_media_id).to be_nilimage = create(:image, viewable: variant)- expect(variant.reload.thumbnail_id).to eq(image.id)+ expect(variant.reload.primary_media_id).to eq(image.id)end- it 'sets product thumbnail_id when first image is created' do- expect(product.thumbnail_id).to be_nil+ it 'sets product primary_media_id when first image is created' do+ expect(product.primary_media_id).to be_nilimage = create(:image, viewable: variant)- expect(product.reload.thumbnail_id).to eq(image.id)+ expect(product.reload.primary_media_id).to eq(image.id)end- it 'updates thumbnail_id when first image is destroyed' do+ it 'updates primary_media_id when first image is destroyed' doimage1 = create(:image, viewable: variant, position: 1)image2 = create(:image, viewable: variant, position: 2)- expect(variant.reload.thumbnail_id).to eq(image1.id)+ expect(variant.reload.primary_media_id).to eq(image1.id)image1.destroy- expect(variant.reload.thumbnail_id).to eq(image2.id)+ expect(variant.reload.primary_media_id).to eq(image2.id)end- it 'sets thumbnail_id to nil when last image is destroyed' do+ it 'sets primary_media_id to nil when last image is destroyed' doimage = create(:image, viewable: variant)- expect(variant.reload.thumbnail_id).to eq(image.id)+ expect(variant.reload.primary_media_id).to eq(image.id)image.destroy- expect(variant.reload.thumbnail_id).to be_nil+ expect(variant.reload.primary_media_id).to be_nilend- it 'updates thumbnail_id when image position changes' do+ it 'updates primary_media_id when image position changes' doimage1 = create(:image, viewable: variant, position: 1)image2 = create(:image, viewable: variant, position: 2)- expect(variant.reload.thumbnail_id).to eq(image1.id)+ expect(variant.reload.primary_media_id).to eq(image1.id)image2.update!(position: 0)- expect(variant.reload.thumbnail_id).to eq(image2.id)+ expect(variant.reload.primary_media_id).to eq(image2.id)endendenddiff --git a/spree/core/spec/models/spree/product_spec.rb b/spree/core/spec/models/spree/product_spec.rbindex 5b234a1e79..b107c9a01d 100644--- a/spree/core/spec/models/spree/product_spec.rb+++ b/spree/core/spec/models/spree/product_spec.rb@@ -791,14 +791,14 @@ describe Spree::Product, type: :model doendend- describe '#default_image' do+ describe '#primary_media' dolet(:product) { create(:product, stores: [store]) }context 'when master has images' dolet!(:image) { create(:image, viewable: product.master) }it 'returns the master image' do- expect(product.reload.default_image).to eq(image)+ expect(product.reload.primary_media).to eq(image)endcontext 'with variants that also have images' do@@ -806,7 +806,7 @@ describe Spree::Product, type: :model dolet!(:variant_image) { create(:image, viewable: variant) }it 'returns the master image (master takes priority)' do- expect(product.reload.default_image).to eq(image)+ expect(product.reload.primary_media).to eq(image)endendend@@ -816,13 +816,13 @@ describe Spree::Product, type: :model dolet!(:variant_image) { create(:image, viewable: variant) }it 'returns the variant image' do- expect(product.reload.default_image).to eq(variant_image)+ expect(product.reload.primary_media).to eq(variant_image)endendcontext 'when no variants have images' doit 'returns nil' do- expect(product.default_image).to be_nil+ expect(product.primary_media).to be_nilendendend@@ -904,42 +904,38 @@ describe Spree::Product, type: :model doendend- describe '#image_count' do+ describe '#media_count' dolet(:product) { create(:product, stores: [store]) }- context 'when no variants have images' do+ context 'when no variants have media' doit 'returns 0' do- expect(product.image_count).to eq(0)+ expect(product.media_count).to eq(0)endend- context 'when master has images' do+ context 'when master has media' dolet!(:images) { create_list(:image, 2, viewable: product.master) }- it 'returns the master image count' do- expect(product.reload.image_count).to eq(2)+ it 'returns total media count' do+ expect(product.reload.media_count).to eq(2)end- context 'when variant also has images' do+ context 'when variant also has media' dolet!(:variant) { create(:variant, product: product) }let!(:variant_images) { create_list(:image, 3, viewable: variant) }- it 'returns master image count (master takes priority)' do- product.reload- expect(product.variant_for_images).to eq(product.master)- expect(product.image_count).to eq(2)+ it 'returns total across all variants' do+ expect(product.reload.media_count).to eq(5)endendend- context 'when only variant has images' do+ context 'when only variant has media' dolet!(:variant) { create(:variant, product: product) }let!(:variant_images) { create_list(:image, 3, viewable: variant) }- it 'returns the variant image count' do- product.reload- expect(product.variant_for_images).to eq(variant)- expect(product.image_count).to eq(3)+ it 'returns the variant media count' do+ expect(product.reload.media_count).to eq(3)endendend@@ -1037,7 +1033,7 @@ describe Spree::Product, type: :model doit 'returns correct images with storefront includes' doloaded_product = Spree::Product.includes(*storefront_includes).find(product.id)- expect(loaded_product.default_image).to eq(image)+ expect(loaded_product.primary_media).to eq(image)expect(loaded_product.variant_for_images).to eq(variant)expect(loaded_product.has_images?).to be trueend@@ -1055,7 +1051,7 @@ describe Spree::Product, type: :model doexpect(loaded_product.default_variant).to eq(variant2)expect(loaded_product.variant_for_images).to eq(variant)- expect(loaded_product.default_image).to eq(image)+ expect(loaded_product.primary_media).to eq(image)endendenddiff --git a/spree/core/spec/models/spree/variant_spec.rb b/spree/core/spec/models/spree/variant_spec.rbindex 23865b38eb..1abbf2317d 100644--- a/spree/core/spec/models/spree/variant_spec.rb+++ b/spree/core/spec/models/spree/variant_spec.rb@@ -1388,20 +1388,20 @@ describe Spree::Variant, type: :model doendend- describe '#default_image' do+ describe '#primary_media' dolet(:variant) { create(:variant) }context 'when variant has images' dolet!(:image) { create(:image, position: 1, viewable: variant) }it 'returns the first image' do- expect(variant.reload.default_image).to eq(image)+ expect(variant.reload.primary_media).to eq(image)endendcontext 'when variant has no images' doit 'returns nil' do- expect(variant.default_image).to be_nil+ expect(variant.primary_media).to be_nilendendenddiff --git a/spree/emails/app/helpers/spree/mail_helper.rb b/spree/emails/app/helpers/spree/mail_helper.rbindex 524ac311c4..5839f21630 100644--- a/spree/emails/app/helpers/spree/mail_helper.rb+++ b/spree/emails/app/helpers/spree/mail_helper.rb@@ -4,7 +4,7 @@ module Spreeinclude Spree::ImagesHelperdef variant_image_url(variant)- image = variant.default_image+ image = variant.primary_mediaimage.present? && image.attached? ? spree_image_url(image, variant: :mini) : image_url('noimage/small.png')end