Skip to content

armgit / spree

Public Imported from GitHub
0

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

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.yaml
index 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_gUllizQIwryS4
user:
id: cus_UkLWZg9DAJ
- first_name: Emilia
- last_name: Wehner
+ first_name: Na
+ last_name: Bailey
phone:
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_utZw
user:
id: cus_UkLWZg9DAJ
- first_name: Tracey
- last_name: Koss
+ first_name: Shiloh
+ last_name: Kutch
phone:
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
+ number: R592928780
+ token: GEAm9PwN7XmzKQ7JNmxx2n12ihh1gTJBgbG
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -851,8 +851,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 21424
- slug: product-21424
+ name: Product 23018
+ slug: product-23018
options_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: H54022746010
state: pending
tracking: U10000
tracking_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_gbHJdmfrXB
name: UPS Ground
@@ -895,7 +895,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_37
- name: Caryl Feeney
+ name: Raye Franecki
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -950,9 +950,9 @@ paths:
state_name: STATE_NAME_42
payment_methods: []
- id: cart_UkLWZg9DAJ
- number: R741612804
- token: 1Wnd3pNEjwU19G8iipANmeJ1ihP7n3j5pe3
+ number: R472289234
+ token: xwmD8eiHXxkGKntwxDEuERyn7Y1zn2eewCm
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -987,8 +987,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 15258
- slug: product-15258
+ name: Product 14966
+ slug: product-14966
options_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: H63711482146
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -1031,7 +1031,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_37
- name: Caryl Feeney
+ name: Raye Franecki
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1159,8 +1159,8 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R820921292
- token: 9YbrGXVaCKW3nXiUVZyzLCkzSGYyJomFZap
+ number: R295996236
+ token: NzSJZ3FryrE1GrCtYiQhpqkKGzr2xq8RBsd
email:
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: address
completed_steps: []
requirements:
@@ -1290,9 +1290,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R274060221
- token: UfvdA4eYrAv2zSSFpookDap37GdR3pk51xh
+ number: R734543831
+ token: FdfRrq4gBGXE6Q9XjzmuMNLfkMaJH3QoHmu
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -1327,8 +1327,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 52481
- slug: product-52481
+ name: Product 59838
+ slug: product-59838
options_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: H54892494980
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -1371,7 +1371,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_47
- name: Florentino Kuhn
+ name: Janetta Willms
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1506,9 +1506,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R321260229
- token: 7xXrFbBGu8uGBWPEWtmfyctkZmBmG7VWsym
+ number: R504503846
+ token: SQMBuPzUDarhEmJW5eDLNVWGPietZKKGryM
special_instructions: Leave at door
currency: USD
locale: 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: payment
completed_steps:
- address
@@ -1545,8 +1545,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 65837
- slug: product-65837
+ name: Product 69382
+ slug: product-69382
options_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: H11758386245
state: pending
tracking:
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_UkLWZg9DAJ
name: UPS Ground
@@ -1589,7 +1589,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_49
- name: Luana Schuppe
+ name: Sherrell Wintheiser
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1811,9 +1811,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R055833456
- token: KQNMFNmjDq1ksBnKMPLyyN2fERN9FkT4EMX
+ number: R645646809
+ token: NR2WHSSdvEdvT32QiHz6cmDxJM7nPZeTWRt
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -1848,8 +1848,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 84030
- slug: product-84030
+ name: Product 84356
+ slug: product-84356
options_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: H79543816122
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -1892,7 +1892,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_57
- name: Emilee Osinski
+ name: Karena Keebler
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2011,8 +2011,8 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R792302214
+ number: R423170020
special_instructions:
currency: USD
locale: 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_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 106099
- slug: product-106099
+ name: Product 108826
+ slug: product-108826
options_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: H38566815614
state: pending
tracking:
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_UkLWZg9DAJ
name: UPS Ground
@@ -2088,7 +2088,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_63
- name: Darnell Weissnat
+ name: Alejandro Hermann
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2111,11 +2111,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: completed
response_code: '12345'
- number: PKB74RGB
+ number: PNDK0HIN
amount: '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_card
source_id: card_UkLWZg9DAJ
source:
@@ -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_UkLWZg9DAJ
description: ''
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_gbHJdmfrXB
description: ''
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_UkLWZg9DAJ
description: ''
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-199134
meta_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: true
in_stock: false
backorderable: true
@@ -2794,9 +2795,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R239512747
- token: DG7zZrtiYGCSVPJ265jT1Tiv5nsrR5etsk7
+ number: R979204925
+ token: KQSk4bW8gYhDWB97YXPPXQ64DHh2wzmPcVN
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements: []
@@ -2828,8 +2829,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 23971
- slug: product-23971
+ name: Product 234469
+ slug: product-234469
options_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: H07824285599
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -2872,7 +2873,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_85
- name: Aliza Bednar
+ name: Tracy Trantow
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2894,12 +2895,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260315095641975501
- number: P7HJEX3A
+ response_code: 1-SC-20260316114212663794
+ number: PUZIDS8M
amount: '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_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -3042,9 +3043,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R737368305
- token: hxLpj3PmQJveF8goUcH6yJ5g9fpNf3vwBwa
+ number: R380290666
+ token: JJqUnbpdK4uJfdGf4uQvsWxJ2VCDRZj3sXw
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -3079,8 +3080,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 254999
- slug: product-254999
+ name: Product 251943
+ slug: product-251943
options_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: H93851004237
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -3123,7 +3124,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_93
- name: Kimberly Rolfson
+ name: Maya Huels
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3589,16 +3590,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJiMzViNzEzLThkMmEtNGU5Ni04MzI0LThlZmJjMDNhOGFjYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMjA4fQ.lvT_KdvwjKK9epprdnp52TsqSGzg1LG1J4Q9Tn8Bjsk
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImY2ZTZlYmFkLTQwZDgtNDViZi1hOGVlLThiM2IyYWU0NjcxZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTM5fQ.Cw26SBmNlH613s9ji0WNPUOmmTtgezQooaIWsWF84Kk
user:
id: cus_UkLWZg9DAJ
- first_name: Evelina
- last_name: Herman
+ first_name: Antonietta
+ last_name: Deckow
phone:
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
+ number: R294365647
special_instructions:
currency: USD
locale: 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_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 276901
- slug: product-276901
+ name: Product 278791
+ slug: product-278791
options_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: H73483267054
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -3763,7 +3764,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_113
- name: Carli Roob
+ name: Shizuko Strosin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3883,8 +3884,8 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R913804901
+ number: R079052985
special_instructions:
currency: USD
locale: 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_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 293199
- slug: product-293199
+ name: Product 298764
+ slug: product-298764
options_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: H31898065583
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -3960,7 +3961,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_119
- name: Halina Larson
+ name: Lyman Doyle
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4066,7 +4067,7 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjEyMjRiMWQ0LWM5ODEtNDBhZC1iOWI5LTQxNTU2NmQ5NjY2MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNTcyMjExfQ.p1jhTIxt8zTeAy51FvCRmLJ9QNkr8A135crtZ-BTvxw
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImI2YTQ1YjIzLTFmNTAtNGNlZC04MGYzLTkyYzJhNTAzNzhhOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczNjY0OTQxfQ.Hbdwqg6sS8oS9UGKeCp-zGsD98oUKq859M23kq0mI2A
user:
id: cus_UkLWZg9DAJ
@@ -4074,8 +4075,8 @@ paths:
last_name: Doe
phone: "+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
- first_name: Millie
- last_name: Jerde
+ first_name: Jeramy
+ last_name: Fritsch
phone: 555-555-0199
accepts_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_gbHJdmfrXB
firstname: John
@@ -4309,13 +4310,13 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
accepts_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_gbHJdmfrXB
firstname: John
@@ -4539,7 +4540,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: B608F79E2170A577
+ code: 28CABF0C75127A6A
state: active
currency: USD
amount: '10.0'
@@ -4553,8 +4554,8 @@ paths:
redeemed_at:
expired: false
active: 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: 1
limit: 25
@@ -4637,7 +4638,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 531FE0239DCE4448
+ code: A8F57643BDF60F5F
state: active
currency: USD
amount: '10.0'
@@ -4651,8 +4652,8 @@ paths:
redeemed_at:
expired: false
active: 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
+ number: R452121802
+ token: grWFKTAFcGQo6oZmZnr6tKM414FiJxQSACU
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -4772,8 +4773,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 398150
- slug: product-398150
+ name: Product 399968
+ slug: product-399968
options_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_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 402535
- slug: product-402535
+ name: Product 404361
+ slug: product-404361
options_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
+ number: R198416438
+ token: NnLWSHFmPCYkAzer8M5CJKZ8mfu4JPTYHUv
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -4983,8 +4984,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 434622
- slug: product-434622
+ name: Product 436993
+ slug: product-436993
options_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
+ number: R559013003
+ token: 3EjQ6SbAtYkmZXxS6py5axLK3STcURbj7QP
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -5680,7 +5681,7 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R431379959
+ number: R659779239
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_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 471096
- slug: product-471096
+ name: Product 472278
+ slug: product-472278
options_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: H36992806743
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -5757,7 +5758,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_178
- name: Eliseo Anderson
+ name: Garry Stokes
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5962,13 +5963,13 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_a0977e1348c050bfa16b4ec0
+ external_id: bogus_daabaa50d1c57f13c5014881
external_data:
- client_secret: bogus_secret_5361e4eb9f61beb5
+ client_secret: bogus_secret_e7e604a73544eb4e
customer_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_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6063,13 +6064,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_cf57445d529c06574c445f2b
+ external_id: bogus_77fbd02f6677cef6ebe14fe3
external_data:
client_secret: secret_123
customer_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_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6126,13 +6127,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_2558128ec996a5f552ea55e3
+ external_id: bogus_30506623e48d658c98419dc3
external_data:
client_secret: secret_123
customer_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_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6229,13 +6230,13 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_f6e3add7f8155fd60a723dac
+ external_id: bogus_424ada87b0da602b935acd08
external_data:
client_secret: secret_123
customer_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_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -6315,11 +6316,11 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_35831340b9be1dda0dc879b7
- external_client_secret: bogus_seti_secret_645160465b56014d
+ external_id: bogus_seti_5c545f3dc7c5849d72ffc674
+ external_client_secret: bogus_seti_secret_467a3b3ef01f86d7
external_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_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6416,12 +6417,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_2e9ef45b42d7fb1b4e5fac91
- external_client_secret: seti_secret_4165488a7c42172d41e2e0fb
+ external_id: seti_test_1a2c9705d0abdecef67304e3
+ external_client_secret: seti_secret_d3c3962baa443c69e575a041
external_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_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6494,12 +6495,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_e65035e9af9ec10297b861e1
- external_client_secret: seti_secret_4abb4347ff85b4dac427a0de
+ external_id: seti_test_ef6d5d09f94b0b678cc84d3c
+ external_client_secret: seti_secret_f94fdb8a44d560744d38eb25
external_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_UkLWZg9DAJ
payment_source_id: card_UkLWZg9DAJ
payment_source_type: Spree::CreditCard
@@ -6587,11 +6588,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PE69K01S
+ number: PYNZVFY8
amount: '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_card
source_id: card_UkLWZg9DAJ
source:
@@ -6678,11 +6679,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code:
- number: P95WC0IE
+ number: PCY45KRA
amount: '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: expand
in: query
required: 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-597011
meta_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: true
in_stock: false
backorderable: 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-60113
meta_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: true
in_stock: false
backorderable: 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-71220
meta_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: true
in_stock: false
backorderable: true
@@ -7217,15 +7216,15 @@ paths:
example:
data:
- id: ship_UkLWZg9DAJ
- number: H69528152229
+ number: H32619135381
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -7233,7 +7232,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_250
- name: Ludie Grant
+ name: Heidy Breitenberg
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7315,9 +7314,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R905508813
- token: 9NzoeWMT2z8be7kife1xnWDAbiZTWnACkNG
+ number: R706175501
+ token: uS2yq6s6KK5KbJPuRRN8JDNmLLNzKcfyxk9
special_instructions:
currency: USD
locale: 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: payment
completed_steps:
- address
@@ -7354,8 +7353,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1003603
- slug: product-1003603
+ name: Product 1007033
+ slug: product-1007033
options_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: H01859618016
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -7398,7 +7397,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_254
- name: Benjamin Beier
+ name: Elyse Anderson
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7534,9 +7533,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R002787829
- token: 642ULnFDFXNEANAEZoa4Hx8NFhF5JmmxJ39
+ number: R685095009
+ token: t3PTz46C1e8c5zfHcuUbDvKMTGYVmFQFroG
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements: []
@@ -7568,8 +7567,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1026200
- slug: product-1026200
+ name: Product 1023689
+ slug: product-1023689
options_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: H41244189674
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -7612,7 +7611,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_262
- name: Henriette Larkin
+ name: Forrest Legros
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7634,12 +7633,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260315095720181607
- number: PGSET0HH
+ response_code: 1-SC-20260316114249277866
+ number: PD9CO5Q5
amount: '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_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -7770,9 +7769,9 @@ paths:
application/json:
example:
id: cart_UkLWZg9DAJ
- number: R153268950
- token: RE7XHmBaKZBWVbEsynYnqQ56xZPNk3Uyepm
+ number: R556097630
+ token: DNEdTx4FU6gYcifjJ2aH8MUPEMmays28g5g
special_instructions:
currency: USD
locale: 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: address
completed_steps: []
requirements:
@@ -7807,8 +7806,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1044733
- slug: product-1044733
+ name: Product 1046044
+ slug: product-1046044
options_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: H07440904442
state: pending
tracking: U10000
tracking_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_UkLWZg9DAJ
name: UPS Ground
@@ -7851,7 +7850,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_270
- name: Damion Crist
+ name: Cherish Green
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7967,9 +7966,9 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: 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: false
is_private: true
meta:
@@ -8045,9 +8044,9 @@ paths:
example:
id: wl_gbHJdmfrXB
name: 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: false
is_private: true
schema:
@@ -8143,9 +8142,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: 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: false
is_private: true
schema:
@@ -8207,9 +8206,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: 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: false
is_private: true
schema:
@@ -8321,8 +8320,8 @@ paths:
variant_id: variant_gbHJdmfrXB
wishlist_id: wl_UkLWZg9DAJ
quantity: 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_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
@@ -8330,10 +8329,10 @@ paths:
is_master: true
options_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: true
in_stock: false
backorderable: true
@@ -9267,66 +9266,6 @@ components:
- created_at
- updated_at
x-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: true
ImportRow:
type: object
properties:
@@ -9602,6 +9541,79 @@ components:
- default
- supported_locales
x-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: true
Metafield:
type: object
properties:
@@ -10118,10 +10130,12 @@ components:
allOf:
- "$ref": "#/components/schemas/Price"
nullable: true
- images:
+ primary_media:
+ "$ref": "#/components/schemas/Media"
+ media:
type: array
items:
- "$ref": "#/components/schemas/Image"
+ "$ref": "#/components/schemas/Media"
variants:
type: array
items:
@@ -10723,13 +10737,13 @@ components:
type: string
track_inventory:
type: boolean
- image_count:
+ media_count:
type: number
created_at:
type: string
updated_at:
type: string
- thumbnail:
+ thumbnail_url:
type: string
nullable: true
purchasable:
@@ -10756,10 +10770,12 @@ components:
allOf:
- "$ref": "#/components/schemas/Price"
nullable: true
- images:
+ primary_media:
+ "$ref": "#/components/schemas/Media"
+ media:
type: array
items:
- "$ref": "#/components/schemas/Image"
+ "$ref": "#/components/schemas/Media"
option_values:
type: array
items:
@@ -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
- backorderable
diff --git a/docs/developer/admin/components.mdx b/docs/developer/admin/components.mdx
index 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>
## Tooltip
diff --git a/docs/developer/core-concepts/images-assets.mdx b/docs/developer/core-concepts/media.mdx
similarity index 52%
rename from docs/developer/core-concepts/images-assets.mdx
rename to docs/developer/core-concepts/media.mdx
index 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 SDK
const 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_count
product.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 configuration
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 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 relations
const 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_type
Option 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 SDK
const 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_count
product.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 pagination
diff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdx
index 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 product
diff --git a/docs/developer/sdk/store/products.mdx b/docs/developer/sdk/store/products.mdx
index 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 SDK
const 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 request
const product = await client.products.get('spree-tote', {
- expand: ['variants.images', 'option_types'],
+ expand: ['variants.media', 'option_types'],
});
// Access nested data
product.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:
```typescript
const 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.mdx
index 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 images
diff --git a/docs/developer/storefront/helper-methods.mdx b/docs/developer/storefront/helper-methods.mdx
index 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 methods
diff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdx
index 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 cac
import { 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.json
index 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.mdx
index 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.md
new file mode 100644
index 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 API
diff --git a/packages/admin-sdk/src/types/generated/AllowedOrigin.ts b/packages/admin-sdk/src/types/generated/AllowedOrigin.ts
new file mode 100644
index 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.ts
similarity index 58%
rename from packages/admin-sdk/src/types/generated/Image.ts
rename to packages/admin-sdk/src/types/generated/Media.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 Changes
diff --git a/packages/next/README.md b/packages/next/README.md
index 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
```typescript
import { 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 Changes
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 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 slug
const 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.json
index 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.ts
similarity index 55%
rename from packages/sdk/src/types/generated/Image.ts
rename to packages/sdk/src/types/generated/Media.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 56%
rename from packages/sdk/src/zod/generated/Image.ts
rename to packages/sdk/src/zod/generated/Media.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.lock
index a7d65a7a5f..8a65ba01ff 100644
--- a/server/Gemfile.lock
+++ b/server/Gemfile.lock
@@ -11,7 +11,7 @@ GIT
PATH
remote: ../spree/admin
specs:
- spree_admin (5.4.0.beta6)
+ spree_admin (5.4.0.beta7)
active_link_to
breadcrumbs_on_rails (~> 4.1)
chartkick (~> 5.0)
@@ -23,7 +23,7 @@ PATH
mapkick-rb (~> 0.1)
pagy (~> 43.0)
ruby-oembed (~> 0.18)
- spree (>= 5.4.0.beta6)
+ spree (>= 5.4.0.beta7)
stimulus-rails
tailwindcss-rails (>= 4.0)
tailwindcss-ruby (>= 4.0)
@@ -33,22 +33,22 @@ PATH
PATH
remote: ../spree/emails
specs:
- spree_emails (5.4.0.beta6)
- spree (>= 5.4.0.beta6)
+ spree_emails (5.4.0.beta7)
+ spree (>= 5.4.0.beta7)
PATH
remote: ../spree
specs:
- 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-on
acts_as_list (>= 0.8)
@@ -1125,12 +1125,12 @@ CHECKSUMS
simplecov-cobertura (3.1.0) sha256=6d7f38aa32c965ca2174b2e5bd88cb17138eaf629518854976ac50e628925dc5
simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
simplecov_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=71725dafe45319a2be1bd2b564a416afe8029af8e18ac703bdb835e09553e1df
spree_i18n (5.3.2) sha256=03b805235ca156644951f6bc3d07cbe43d0aa01134c4a27e3f3304011956f79b
spree_stripe (1.6.0.beta)
diff --git a/server/db/schema.rb b/server/db/schema.rb
index 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 database
enable_extension "pg_catalog.plpgsql"
enable_extension "pg_trgm"
@@ -195,6 +195,10 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) do
t.datetime "attachment_updated_at", precision: nil
t.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) do
t.datetime "updated_at", precision: nil
t.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) do
t.text "description"
t.datetime "discontinue_on", precision: nil
t.datetime "make_active_at", precision: nil
+ t.integer "media_count", default: 0, null: false
t.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: true
t.jsonb "public_metadata"
@@ -1027,8 +1034,6 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) do
t.string "slug"
t.string "status", default: "draft", null: false
t.bigint "tax_category_id"
- t.bigint "thumbnail_id"
- t.integer "total_image_count", default: 0, null: false
t.datetime "updated_at", null: false
t.integer "variant_count", default: 0, null: false
t.index ["available_on"], name: "index_spree_products_on_available_on"
@@ -1036,15 +1041,15 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) do
t.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: true
t.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) do
t.string "dimensions_unit"
t.datetime "discontinue_on", precision: nil
t.decimal "height", precision: 8, scale: 2
- t.integer "image_count", default: 0, null: false
t.boolean "is_master", default: false
+ t.integer "media_count", default: 0, null: false
t.integer "position"
+ t.bigint "primary_media_id"
t.jsonb "private_metadata"
t.bigint "product_id"
t.jsonb "public_metadata"
t.string "sku", default: "", null: false
t.bigint "tax_category_id"
- t.bigint "thumbnail_id"
t.boolean "track_inventory", default: true
t.datetime "updated_at", precision: nil, null: false
t.decimal "weight", precision: 8, scale: 2, default: "0.0"
@@ -1916,13 +1921,13 @@ ActiveRecord::Schema[8.1].define(version: 2026_03_15_144027) do
t.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"
end
diff --git a/spree/admin/app/controllers/spree/admin/classifications_controller.rb b/spree/admin/app/controllers/spree/admin/classifications_controller.rb
index 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 Spree
includes(
: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.rb
index 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 Spree
scope = 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 Spree
def 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.erb
index 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.rb
index 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 do
expect(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)
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/products_controller.rb
index 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 them
def 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.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
index 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 Spree
resource: 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.rb
index 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 Spree
end
# 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_serializer
diff --git a/spree/api/app/serializers/spree/api/v3/base_serializer.rb b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
index 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 Spree
end
# 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_s
expands.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.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/api/app/serializers/spree/api/v3/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/media_serializer.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/product_serializer.rb
index 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 Spree
product.default_variant&.prefixed_id
end
- # 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)
end
attribute :tags do |product|
@@ -68,10 +68,14 @@ module Spree
end
# 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.rb
index 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 fields
class VariantSerializer < BaseSerializer
typelize 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 Spree
variant.product&.prefixed_id
end
- 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)
end
attribute :purchasable do |variant|
@@ -70,9 +70,14 @@ module Spree
end
# 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_serializer
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index 71f37693d9..ef18a29c9f 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -96,7 +96,7 @@ module Spree
price_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 Spree
admin_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.rb
index 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 do
end
describe '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')
end
end
- it 'expands variants without images when only variants requested' do
+ it 'expands variants without media when only variants requested' do
get :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')
end
end
it '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')
end
end
it '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')
end
end
end
describe 'collection endpoint' do
it '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')
end
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
index 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/store
price_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/store
parameter 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/store
sdk_example <<~JS
const product = await client.products.get('spree-tote', {
- expand: ['variants', 'images'],
+ expand: ['variants', 'media'],
})
JS
diff --git a/spree/core/app/helpers/spree/base_helper.rb b/spree/core/app/helpers/spree/base_helper.rb
index 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 PDP
def 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_media
end
def 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_media
end
def base_cache_key
diff --git a/spree/core/app/models/spree/asset.rb b/spree/core/app/models/spree/asset.rb
index 3bf97179dc..053c4b2faa 100644
--- a/spree/core/app/models/spree/asset.rb
+++ b/spree/core/app/models/spree/asset.rb
@@ -1,20 +1,42 @@
module Spree
class Asset < Spree.base_class
- has_prefix_id :asset # Stripe: file_
+ has_prefix_id :media
include Support::ActiveStorage
+ include Rails.application.routes.url_helpers
+ include Spree::ImageMethods # legacy, will be removed in Spree 6
include Spree::Metafields
include 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_events
EXTERNAL_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: true
acts_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 Spree
default_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_uuid
scope :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]
+ end
end
def external_url
@@ -66,7 +120,71 @@ module Spree
end
def 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)
+ end
end
+
+ 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_thumbnail
end
end
diff --git a/spree/core/app/models/spree/image.rb b/spree/core/app/models/spree/image.rb
index 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 Spree
class 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
- end
end
end
diff --git a/spree/core/app/models/spree/image/configuration/active_storage.rb b/spree/core/app/models/spree/image/configuration/active_storage.rb
index 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 Spree
class Image < Asset
module Configuration
module ActiveStorage
extend 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
- end
end
end
end
diff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rb
index 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 Spree
delegate :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_media
end
delegate :tax_zone, to: :order
delegate :digital?, :can_supply?, to: :variant
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 73c94c32d5..8b4b648962 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -114,10 +114,12 @@ module Spree
has_many :orders, through: :line_items
has_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_master
has_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_id
has_many :option_value_variants, class_name: 'Spree::OptionValueVariant', through: :variants
has_many :option_values, class_name: 'Spree::OptionValue', through: :variants
@@ -335,17 +337,26 @@ module Spree
@default_variant_id ||= default_variant.id
end
- # 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_images
end
- # 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_media
end
- # 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_media
end
- # 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_image
variant_for_images&.secondary_image
end
- # 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 instead
def image_count
- variant_for_images&.image_count || 0
+ media_count
end
- # 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).first
end
@@ -630,12 +641,12 @@ module Spree
private
- # 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 media
def 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?
nil
end
diff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rb
index 9c213e209b..9dae271f3f 100644
--- a/spree/core/app/models/spree/variant.rb
+++ b/spree/core/app/models/spree/variant.rb
@@ -48,8 +48,8 @@ module Spree
has_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_id
has_many :prices,
class_name: 'Spree::Price',
@@ -279,26 +279,35 @@ module Spree
is_master? ? name + ' - Master' : name + ' - ' + options_text
end
- # 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_media
end
- # 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/lib/spree/permitted_attributes.rb b/spree/core/lib/spree/permitted_attributes.rb
index 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.rb
index 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 do
factory :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
+ end
end
end
diff --git a/spree/core/lib/spree/testing_support/factories/image_factory.rb b/spree/core/lib/spree/testing_support/factories/image_factory.rb
index 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.rake
index 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_media
end
- 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_media
end
puts 'Done!'
diff --git a/spree/core/lib/tasks/products.rake b/spree/core/lib/tasks/products.rake
index 7b1272a14e..be71883dda 100644
--- a/spree/core/lib/tasks/products.rake
+++ b/spree/core/lib/tasks/products.rake
@@ -1,14 +1,16 @@
namespace :spree do
namespace :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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/asset_spec.rb b/spree/core/spec/models/spree/asset_spec.rb
index 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 do
it_behaves_like 'metadata'
- it_behaves_like 'lifecycle events'
+ it_behaves_like 'lifecycle events', event_prefix: 'media'
describe 'named variants' do
let(: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.rb
index 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 do
end
end
- describe 'image_count counter cache' do
+ describe 'media_count counter cache' do
let(: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' do
image = 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)
end
it '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)
end
end
- describe 'total_image_count counter cache on product' do
+ describe 'product media_count counter cache' do
let(: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' do
image = 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)
end
end
- describe 'thumbnail_id updates' do
+ describe 'primary_media_id updates' do
let(: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_nil
image = 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_nil
image = 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' do
image1 = 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' do
image = 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_nil
end
- it 'updates thumbnail_id when image position changes' do
+ it 'updates primary_media_id when image position changes' do
image1 = 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)
end
end
end
diff --git a/spree/core/spec/models/spree/product_spec.rb b/spree/core/spec/models/spree/product_spec.rb
index 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 do
end
end
- describe '#default_image' do
+ describe '#primary_media' do
let(:product) { create(:product, stores: [store]) }
context 'when master has images' do
let!(: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)
end
context 'with variants that also have images' do
@@ -806,7 +806,7 @@ describe Spree::Product, type: :model do
let!(: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)
end
end
end
@@ -816,13 +816,13 @@ describe Spree::Product, type: :model do
let!(: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)
end
end
context 'when no variants have images' do
it 'returns nil' do
- expect(product.default_image).to be_nil
+ expect(product.primary_media).to be_nil
end
end
end
@@ -904,42 +904,38 @@ describe Spree::Product, type: :model do
end
end
- describe '#image_count' do
+ describe '#media_count' do
let(:product) { create(:product, stores: [store]) }
- context 'when no variants have images' do
+ context 'when no variants have media' do
it 'returns 0' do
- expect(product.image_count).to eq(0)
+ expect(product.media_count).to eq(0)
end
end
- context 'when master has images' do
+ context 'when master has media' do
let!(: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' do
let!(: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)
end
end
end
- context 'when only variant has images' do
+ context 'when only variant has media' do
let!(: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)
end
end
end
@@ -1037,7 +1033,7 @@ describe Spree::Product, type: :model do
it 'returns correct images with storefront includes' do
loaded_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 true
end
@@ -1055,7 +1051,7 @@ describe Spree::Product, type: :model do
expect(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)
end
end
end
diff --git a/spree/core/spec/models/spree/variant_spec.rb b/spree/core/spec/models/spree/variant_spec.rb
index 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 do
end
end
- describe '#default_image' do
+ describe '#primary_media' do
let(:variant) { create(:variant) }
context 'when variant has images' do
let!(: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)
end
end
context 'when variant has no images' do
it 'returns nil' do
- expect(variant.default_image).to be_nil
+ expect(variant.primary_media).to be_nil
end
end
end
diff --git a/spree/emails/app/helpers/spree/mail_helper.rb b/spree/emails/app/helpers/spree/mail_helper.rb
index 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 Spree
include Spree::ImagesHelper
def variant_image_url(variant)
- image = variant.default_image
+ image = variant.primary_media
image.present? && image.attached? ? spree_image_url(image, variant: :mini) : image_url('noimage/small.png')
end