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.

Let integrations declare a hosted logo and localized description

Damian Legawiec86476834a2e8
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 1f8d409469..9b78435d20 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -87,16 +87,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdkZjA0MzYzLTZhYmUtNDFiMC1iNDI2LTc1NjU1NTM4ZDhhYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDQ4NTA5fQ.DK2U12X83qkwU0sDESLS3WDVPeaHbZLYXepnI77eA_o
- refresh_token: YFe8tXg639PEcQZeoCLMfHcj
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBkZTg2OGNmLWNlMDEtNDcwOC1hNDQ3LTljY2NmN2Y2YWQ0ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDUwMDI4fQ.VSB4GdlZ4DdHpTv1BLClvkDVrERRK6Lrhnt_D9JlQpU
+ refresh_token: 6d3hptkexdAW6X5unJnXcmqq
user:
id: cust_UkLWZg9DAJ
- first_name: Apryl
- last_name: Wiegand
+ first_name: Arnette
+ last_name: Kshlerin
phone:
accepts_email_marketing: false
- full_name: Apryl Wiegand
+ full_name: Arnette Kshlerin
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -194,16 +194,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImZiNTJmOGM0LTAwYTItNGVhYS04NDNhLWMxNDdlOWZkZDhlNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDQ4NTA5fQ.7OugEQdfAA_5xH9rZOHKwuRdPX19qCykaGAZjAhIoO8
- refresh_token: pPTjFCBqzzQDdz8HQY7mJ1kN
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFjNjRiMzEzLTlhMTktNGQ2NS05ZTkyLWMzYzY5MjAyNGZkNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDUwMDI4fQ.5D-Hww_cj0Cv7ZMh-ZORhZk-aSwbgrpwsJnpxDjHqVc
+ refresh_token: gQGXtEnLD7ouERpuwZFLJwms
user:
id: cust_UkLWZg9DAJ
- first_name: Darnell
- last_name: Kiehn
+ first_name: Risa
+ last_name: Kuhlman
phone:
accepts_email_marketing: false
- full_name: Darnell Kiehn
+ full_name: Risa Kuhlman
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -393,16 +393,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImJhMzViZTlhLTVkN2YtNDBiYS1hYTc5LThmNmI3YzNjZWU5ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDQ4NTE1fQ.C3KslBW4tr3TnquwcV_ZacHpDeqcxD5qxWmG5Z8oQgg
- refresh_token: bwJDGrzApB7s2oBvgttNjQNt
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImU5NzRkYjQ2LWMzMzYtNGFhMS1hNWViLTljYzAyMTY1ZjQ0OCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDUwMDMxfQ.l4wNhDZUCgt3SKQqYrmqHuaqa-K45Ent3xlcEqqjWaM
+ refresh_token: MQ55xStoAAKK9BhLjzKLn8S3
user:
id: cust_UkLWZg9DAJ
- first_name: Sharonda
- last_name: Larkin
+ first_name: Alejandra
+ last_name: Goodwin
phone:
accepts_email_marketing: false
- full_name: Sharonda Larkin
+ full_name: Alejandra Goodwin
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -879,8 +879,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1291956
- slug: product-1291956
+ name: Product 1293745
+ slug: product-1293745
meta_title:
meta_description:
meta_keywords:
@@ -892,12 +892,27 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Optio inventore rerum sapiente voluptate ad quia. Iure
- repudiandae occaecati dicta animi alias expedita inventore. Quas
- deleniti quia vitae illo.
- description_html: Optio inventore rerum sapiente voluptate ad quia.
- Iure repudiandae occaecati dicta animi alias expedita inventore.
- Quas deleniti quia vitae illo.
+ description: Cupiditate autem eaque dolorum maxime. Id rerum minima
+ quas iste ullam voluptatem. Quas praesentium inventore sed non
+ tenetur eaque laboriosam quae. Nesciunt asperiores explicabo nobis
+ similique fugit aperiam consectetur omnis. Officiis inventore
+ cumque sed dolorum quaerat accusantium. Nulla ipsam cumque accusantium
+ libero ut error. Maiores laboriosam excepturi optio illo perspiciatis
+ placeat. Nulla maxime ipsa esse sunt assumenda necessitatibus.
+ Dolor quod aliquam reprehenderit consequuntur nemo doloremque
+ quae voluptatem. Quis exercitationem vero dolorem voluptatem.
+ Possimus vero quibusdam magnam nemo. Sapiente alias modi totam
+ reiciendis impedit tempora quae. Numquam quod explicabo qui id
+ commodi repellendus. Dolorum nulla earum quos esse aspernatur
+ quaerat exercitationem optio. Nulla provident illum illo debitis
+ in. Minima magni eum corporis tempora. Excepturi itaque nihil
+ doloremque facere. Odit praesentium nemo cumque magnam. Autem
+ quo vero saepe in animi sequi id voluptas.
+ description_html: |-
+ Cupiditate autem eaque dolorum maxime. Id rerum minima quas iste ullam voluptatem. Quas praesentium inventore sed non tenetur eaque laboriosam quae. Nesciunt asperiores explicabo nobis similique fugit aperiam consectetur omnis. Officiis inventore cumque sed dolorum quaerat accusantium.
+ Nulla ipsam cumque accusantium libero ut error. Maiores laboriosam excepturi optio illo perspiciatis placeat. Nulla maxime ipsa esse sunt assumenda necessitatibus. Dolor quod aliquam reprehenderit consequuntur nemo doloremque quae voluptatem. Quis exercitationem vero dolorem voluptatem.
+ Possimus vero quibusdam magnam nemo. Sapiente alias modi totam reiciendis impedit tempora quae. Numquam quod explicabo qui id commodi repellendus. Dolorum nulla earum quos esse aspernatur quaerat exercitationem optio.
+ Nulla provident illum illo debitis in. Minima magni eum corporis tempora. Excepturi itaque nihil doloremque facere. Odit praesentium nemo cumque magnam. Autem quo vero saepe in animi sequi id voluptas.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -1052,8 +1067,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1719413
- slug: product-1719413
+ name: Product 1717279
+ slug: product-1717279
meta_title:
meta_description:
meta_keywords:
@@ -1082,8 +1097,8 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 1723010
- slug: product-1723010
+ name: Product 1721476
+ slug: product-1721476
meta_title:
meta_description:
meta_keywords:
@@ -1095,29 +1110,28 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Ut eum eveniet voluptatem saepe. Voluptates minima
- eos consequuntur a. Voluptas aliquid rerum libero blanditiis.
- Voluptatem modi mollitia accusantium tempore ratione quasi. Culpa
- incidunt magnam similique tempora quia perferendis assumenda doloribus.
- Explicabo ex provident consequatur dicta. Voluptas rerum est odio
- ea nihil dolores illo doloremque. Inventore distinctio eaque nam
- tempore expedita provident ut. Quasi autem dolore facilis reiciendis
- animi nostrum molestias. Quos quasi animi corrupti iusto natus
- cum quas. Natus excepturi repellat placeat esse dolorem ab dolorum
- minus. Optio impedit qui cum consequatur quaerat eligendi rem.
- Accusantium cumque id sed molestias excepturi ab facere. Ratione
- rerum vero at ipsum officiis porro exercitationem. Voluptates
- ipsa tempore nulla repellat eaque aperiam natus dolor. Facilis
- molestiae labore deserunt repellat ipsum dolores. Suscipit nesciunt
- aut fugiat a ipsam autem accusantium. Placeat quibusdam illum
- eaque reiciendis accusamus quos. Dolorum veniam error voluptatem
- nam officiis sapiente.
+ description: Maiores expedita eaque omnis quibusdam totam saepe
+ velit. Sequi cum rem nesciunt maxime tenetur occaecati voluptatum.
+ Laborum maxime illum fugit mollitia voluptas hic. Dolorem occaecati
+ deleniti nostrum doloribus eius dolorum. Voluptate delectus ratione
+ sapiente ex porro qui amet. Praesentium placeat quibusdam aperiam
+ perferendis. Eaque nisi beatae dicta natus. Molestiae vel iusto
+ ducimus exercitationem fugiat reiciendis fugit laudantium. Unde
+ optio corrupti officia pariatur asperiores. Modi accusantium incidunt
+ natus repellendus. Neque quaerat animi sequi dolores. Nesciunt
+ sint delectus consequatur minima quia ipsum. Aspernatur voluptatum
+ expedita perferendis incidunt nisi aperiam enim culpa. Id amet
+ magni magnam nostrum culpa. Deleniti praesentium omnis perferendis
+ velit sapiente voluptates harum qui. Accusantium ducimus repellendus
+ quis voluptates. Molestiae similique laboriosam nostrum deleniti
+ quas. Doloribus saepe minus cumque repellendus quis nulla. Eveniet
+ vero debitis excepturi suscipit ex.
description_html: |-
- Ut eum eveniet voluptatem saepe. Voluptates minima eos consequuntur a. Voluptas aliquid rerum libero blanditiis. Voluptatem modi mollitia accusantium tempore ratione quasi. Culpa incidunt magnam similique tempora quia perferendis assumenda doloribus.
- Explicabo ex provident consequatur dicta. Voluptas rerum est odio ea nihil dolores illo doloremque. Inventore distinctio eaque nam tempore expedita provident ut. Quasi autem dolore facilis reiciendis animi nostrum molestias.
- Quos quasi animi corrupti iusto natus cum quas. Natus excepturi repellat placeat esse dolorem ab dolorum minus. Optio impedit qui cum consequatur quaerat eligendi rem. Accusantium cumque id sed molestias excepturi ab facere.
- Ratione rerum vero at ipsum officiis porro exercitationem. Voluptates ipsa tempore nulla repellat eaque aperiam natus dolor. Facilis molestiae labore deserunt repellat ipsum dolores.
- Suscipit nesciunt aut fugiat a ipsam autem accusantium. Placeat quibusdam illum eaque reiciendis accusamus quos. Dolorum veniam error voluptatem nam officiis sapiente.
+ Maiores expedita eaque omnis quibusdam totam saepe velit. Sequi cum rem nesciunt maxime tenetur occaecati voluptatum. Laborum maxime illum fugit mollitia voluptas hic.
+ Dolorem occaecati deleniti nostrum doloribus eius dolorum. Voluptate delectus ratione sapiente ex porro qui amet. Praesentium placeat quibusdam aperiam perferendis. Eaque nisi beatae dicta natus. Molestiae vel iusto ducimus exercitationem fugiat reiciendis fugit laudantium.
+ Unde optio corrupti officia pariatur asperiores. Modi accusantium incidunt natus repellendus. Neque quaerat animi sequi dolores. Nesciunt sint delectus consequatur minima quia ipsum.
+ Aspernatur voluptatum expedita perferendis incidunt nisi aperiam enim culpa. Id amet magni magnam nostrum culpa. Deleniti praesentium omnis perferendis velit sapiente voluptates harum qui.
+ Accusantium ducimus repellendus quis voluptates. Molestiae similique laboriosam nostrum deleniti quas. Doloribus saepe minus cumque repellendus quis nulla. Eveniet vero debitis excepturi suscipit ex.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -1219,8 +1233,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1991180
- slug: product-1991180
+ name: Product 1992650
+ slug: product-1992650
meta_title:
meta_description:
meta_keywords:
@@ -1254,7 +1268,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-07-22T19:35:26Z'
+ recorded_at: '2026-07-22T20:00:38Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -1504,7 +1518,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_gbHJdmfrXB
- token: 16nLQDuPfp7Cxw4qWrGkiz8t
+ token: 6GA9htpQSwBLyRQqQtFiHwqu
email:
customer_note:
currency: USD
@@ -1563,8 +1577,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1046279
- slug: product-1046279
+ name: Product 1044222
+ slug: product-1044222
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1609,7 +1623,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: 2rNE1eUBBMZ9P3V1dYkA7KXx
+ token: pfApFbFnA4kmgpW1N7FvKvya
email:
customer_note:
currency: USD
@@ -1668,8 +1682,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1039421
- slug: product-1039421
+ name: Product 1032723
+ slug: product-1032723
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1787,7 +1801,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: wLN1fuhf3LC4AhatNGc3Sc1b
+ token: PCzs3UFMyGPxfwdMvWAJfJn5
email:
customer_note:
currency: USD
@@ -1952,7 +1966,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: dyHuaWjtLM3AFycwCXXnvaTc
+ token: DQKqbtCs4PhL3PreGoyvhdHh
email:
customer_note:
currency: USD
@@ -1960,7 +1974,7 @@ paths:
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 1086484 was removed because it was sold out
+ message: Product 1086243 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
@@ -2102,7 +2116,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: xV3G3QHJiYoZFN6wqWsuFf7G
+ token: 7p9c963q5GNJ13LuXkmfWu4j
email:
customer_note: Leave at door
currency: USD
@@ -2157,8 +2171,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 109348
- slug: product-109348
+ name: Product 1093949
+ slug: product-1093949
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2377,8 +2391,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: shBYK89r7yrz8VviJ1JAxE9U
+ token: 2gD1iT5aqvfD2BPke1CDz1w7
customer_note:
currency: USD
locale: en
@@ -2429,8 +2443,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1112162
- slug: product-1112162
+ name: Product 1114288
+ slug: product-1114288
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2584,8 +2598,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id: cart_UkLWZg9DAJ
channel_id: ch_UkLWZg9DAJ
- number: R221352155
+ number: R191958576
customer_note:
currency: USD
locale: en
@@ -2593,7 +2607,7 @@ paths:
coupon_code:
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-08-06T19:35:11.545Z'
+ completed_at: '2026-08-06T20:00:29.491Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -2625,8 +2639,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1148911
- slug: product-1148911
+ name: Product 1141222
+ slug: product-1141222
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2651,7 +2665,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: F01798836736
+ number: F38651412087
tracking:
tracking_url:
pickup_point_data:
@@ -2685,7 +2699,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Ingeborg Volkman
+ name: Breann Adams
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2720,8 +2734,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-5e8e6fa7fda2
- number: PA7NRM7D
+ response_code: BGS-7d2a61b1b4ea
+ number: PE1VU5GQ
amount: '20.0'
display_amount: "$20.00"
status: completed
@@ -2877,7 +2891,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: SV866WN2Gp16BNyeaS959dyM
+ token: Spfca52dVJxNC81KgRt98L8B
email:
customer_note:
currency: USD
@@ -2935,8 +2949,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1403829
- slug: product-1403829
+ name: Product 1407127
+ slug: product-1407127
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3065,7 +3079,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: ATZgwGp4hbKcwFkHB7VhfKSV
+ token: HeJSt7e8jy1aS5TSAxvi8NW1
email:
customer_note:
currency: USD
@@ -3120,8 +3134,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 142165
- slug: product-142165
+ name: Product 1429879
+ slug: product-1429879
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3239,8 +3253,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: 56Qp5GhwMgeQRKxZ7Gyw9xcW
+ token: kPHkdphQo6EVkdFhGfvLwDri
customer_note:
currency: USD
locale: en
@@ -3288,8 +3302,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 14473
- slug: product-14473
+ name: Product 1448093
+ slug: product-1448093
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3314,7 +3328,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: F92763895526
+ number: F66418645657
tracking:
tracking_url:
pickup_point_data:
@@ -3348,7 +3362,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Lesley Bernhard
+ name: Aleisha Lueilwitz
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3506,7 +3520,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: Ep4xuLTQ3vg8D76jFTsKd1Ff
+ token: bubZvz5855SDyA8pq7GYnhBP
email:
customer_note:
currency: USD
@@ -3557,8 +3571,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1469406
- slug: product-1469406
+ name: Product 1467016
+ slug: product-1467016
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3585,8 +3599,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260806193518606088
- number: PV9Q7MMU
+ response_code: 1-SC-20260806200033816233
+ number: PVDN5XQU
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -3742,7 +3756,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: DDh7856pV8pfKoE2S6d974zS
+ token: tMi9SYDpd8kr4cC8wKNbJahB
email:
customer_note:
currency: USD
@@ -3797,8 +3811,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1506673
- slug: product-1506673
+ name: Product 1503448
+ slug: product-1503448
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3825,8 +3839,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260806193519097499
- number: P278EXBS
+ response_code: 1-SC-20260806200034112725
+ number: PX4N6TC6
amount: '10.0'
display_amount: "$10.00"
status: invalid
@@ -3933,7 +3947,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: R6hdKenoJ4gkNWLtZSd1dhjq
+ token: 5bbcSKGPt33LMt6F4CYFFd8x
email:
customer_note:
currency: USD
@@ -3941,10 +3955,10 @@ paths:
total_quantity: 2
warnings:
- code: delivery_unavailable
- message: Product 1531928 cannot be delivered to the selected address
+ message: Product 1535677 cannot be delivered to the selected address
line_item_id: li_UkLWZg9DAJ
- code: delivery_unavailable
- message: Product 154548 cannot be delivered to the selected address
+ message: Product 1543365 cannot be delivered to the selected address
line_item_id: li_gbHJdmfrXB
coupon_code:
item_total: '29.99'
@@ -3994,8 +4008,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1531928
- slug: product-1531928
+ name: Product 1535677
+ slug: product-1535677
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4024,8 +4038,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 154548
- slug: product-154548
+ name: Product 1543365
+ slug: product-1543365
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4163,7 +4177,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: oQDn3igJyS97LqT9gDtFXTxo
+ token: Ni8unDeRnMKZ5eUJUyMogLcg
email:
customer_note:
currency: USD
@@ -4214,8 +4228,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1572940
- slug: product-1572940
+ name: Product 1572993
+ slug: product-1572993
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4333,7 +4347,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: EYQAxqqk7xZpw5c8xdZFqBJU
+ token: iC4uNgdEnbzKByoziaenx8KN
email:
customer_note:
currency: USD
@@ -4473,9 +4487,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_4a3a25825dcec624b11ec9f0
+ external_id: bogus_d3dfdfcfab797783cbecda80
external_data:
- client_secret: bogus_secret_8fbafaf05f8920ac
+ client_secret: bogus_secret_82e1e635f4bfe00d
customer_external_id:
expires_at:
amount: '10.0'
@@ -4574,7 +4588,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_9768785dc1a3fbbc497a54bb
+ external_id: bogus_7ad6829a2d8226ba4df091a5
external_data:
client_secret: secret_123
customer_external_id:
@@ -4637,7 +4651,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_bdcf20347668987e76ba2b2c
+ external_id: bogus_e8c3573e9cb8269caf5319f8
external_data:
client_secret: secret_123
customer_external_id:
@@ -4740,7 +4754,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_ddc3dddc904885575c142edb
+ external_id: bogus_cd1d22009b4961215403e778
external_data:
client_secret: secret_123
customer_external_id:
@@ -4839,7 +4853,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: PY6KBJY3
+ number: P7XCQ5CM
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -4948,7 +4962,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: 4aThVc7Mn1ecknadc8wvosQV
+ token: PjdYqMVFwXpq9TJTd5wVHQp9
email:
customer_note:
currency: USD
@@ -4999,8 +5013,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2199950
- slug: product-2199950
+ name: Product 2197781
+ slug: product-2197781
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5027,8 +5041,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260806193529173491
- number: PHY7ZRF4
+ response_code: 1-SC-20260806200040057449
+ number: P30ZVFZS
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -5148,7 +5162,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: tSu8yFEALcpjshM1aSwEixTH
+ token: FGnDGsn5tNrKKrEwbWGGmNu3
email:
customer_note:
currency: USD
@@ -5203,8 +5217,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 221529
- slug: product-221529
+ name: Product 221807
+ slug: product-221807
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5319,7 +5333,7 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R563210785
+ number: R950634159
customer_note:
currency: USD
@@ -5328,7 +5342,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-06T19:35:22.220Z'
+ completed_at: '2026-08-06T20:00:36.065Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -5360,8 +5374,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1612163
- slug: product-1612163
+ name: Product 1615450
+ slug: product-1615450
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5386,7 +5400,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: F72312627371
+ number: F43767956970
tracking: U10000
tracking_url:
pickup_point_data:
@@ -5420,7 +5434,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Olivia Heaney
+ name: Rebeca Barton
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6375,8 +6389,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R856998164
+ number: R847194696
customer_note:
currency: USD
locale: en
@@ -6384,7 +6398,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-06T19:35:16.001Z'
+ completed_at: '2026-08-06T20:00:32.052Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6416,8 +6430,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1304015
- slug: product-1304015
+ name: Product 1307456
+ slug: product-1307456
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6442,7 +6456,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: F84078870375
+ number: F70412700069
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6476,7 +6490,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Pattie Conn
+ name: Debbie Bahringer
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6656,8 +6670,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R200778197
+ number: R398149125
customer_note:
currency: USD
locale: en
@@ -6665,7 +6679,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-06T19:35:16.232Z'
+ completed_at: '2026-08-06T20:00:32.258Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6697,8 +6711,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1326869
- slug: product-1326869
+ name: Product 1328611
+ slug: product-1328611
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6723,7 +6737,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: F86829812152
+ number: F53926315863
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6757,7 +6771,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Connie Nader
+ name: Julee Rippin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6893,8 +6907,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjJkN2Y2ODk3LTczNTMtNDVhYy1iZjU5LTc2ZWQxNzdiNzMzMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDQ4NTE2fQ.Aw0zzgk8sKIi3HOiG-l1h3RvyeacT5vRt_KFDG2r5kk
- refresh_token: n2JGsWNy7BwvMczZht369KJv
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBmNWI3ZjAzLTdiZGEtNGFjYS1hMmIyLTE5MWJkYTZkMDAwZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2MDUwMDMyfQ.qxCJCnfMIEdCj2BxjkPlkwpiGo7AQvARrKZPEJTALiw
+ refresh_token: LPw6unEZGdjbWqiJgMztV8ei
user:
id: cust_UkLWZg9DAJ
@@ -6911,10 +6925,10 @@ paths:
newsletter_subscriber:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-06T19:35:16.500Z'
- updated_at: '2026-08-06T19:35:16.503Z'
+ created_at: '2026-08-06T20:00:32.421Z'
+ updated_at: '2026-08-06T20:00:32.423Z'
verified: true
- verified_at: '2026-08-06T19:35:16Z'
+ verified_at: '2026-08-06T20:00:32Z'
customer_id: cust_UkLWZg9DAJ
customer_groups: []
schema:
@@ -7017,12 +7031,12 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
- first_name: Michaela
- last_name: Ullrich
+ first_name: Lovie
+ last_name: Lynch
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Michaela Ullrich
+ full_name: Lovie Lynch
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -7158,7 +7172,7 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -7349,7 +7363,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: C1B4195CBA8C9DFC
+ code: BE19973852173D8D
status: active
currency: USD
amount: '10.0'
@@ -7445,7 +7459,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: E4835489C866A427
+ code: 134DAB09459EE746
status: active
currency: USD
amount: '10.0'
@@ -7517,8 +7531,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_49bf960a0bc1b3f35a5ea8b2
- external_client_secret: bogus_seti_secret_928561da89187ffd
+ external_id: bogus_seti_de311527bbd0ed89a4a88eba
+ external_client_secret: bogus_seti_secret_e78a0af5cf82efbf
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7617,8 +7631,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_2ca8059e20ea1c3ef7598e64
- external_client_secret: seti_secret_76e56d138d8ce35a74b0e03f
+ external_id: seti_test_bac1a9ec609eef34ebfc3a58
+ external_client_secret: seti_secret_19e3b04c197d70196cc5c459
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7694,8 +7708,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_c7e9c020a499323913c87558
- external_client_secret: seti_secret_6318315d208d2168ae67a402
+ external_id: seti_test_10cc6a1375277d7bc7d9bc6b
+ external_client_secret: seti_secret_747ea4a0b355507f59c85fa1
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8639,7 +8653,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: ZT7GTpYvdH4kThcF4NKF4K48
+ token: JAhvQvbWCCUj6Yon3ctm5dBy
is_default: false
is_private: true
meta:
@@ -8715,7 +8729,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: KJymRqAuDD3dvP5kM2neE82k
+ token: vqH5fZ5kVkFAHSseEFRynfrx
is_default: false
is_private: true
schema:
@@ -8816,7 +8830,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: Ub7dErqk9cNeLCyEXsytqDdM
+ token: 5z4BPg3GB1MjSoCXrL1fa5DP
is_default: false
is_private: true
schema:
@@ -8878,7 +8892,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: wrQ4A9YUQZv5v5eCzzvoctsp
+ token: ynZjcf2hrkntSomZq7pwrjvk
is_default: false
is_private: true
schema:
@@ -9160,11 +9174,11 @@ paths:
application/json:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-06T19:35:21.212Z'
- updated_at: '2026-08-06T19:35:21.213Z'
+ created_at: '2026-08-06T20:00:35.440Z'
+ updated_at: '2026-08-06T20:00:35.441Z'
verified: true
- verified_at: '2026-08-06T19:35:21Z'
+ verified_at: '2026-08-06T20:00:35Z'
customer_id: cust_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9243,10 +9257,10 @@ paths:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-06T19:35:21.243Z'
- updated_at: '2026-08-06T19:35:21.256Z'
+ created_at: '2026-08-06T20:00:35.461Z'
+ updated_at: '2026-08-06T20:00:35.467Z'
verified: true
- verified_at: '2026-08-06T19:35:21Z'
+ verified_at: '2026-08-06T20:00:35Z'
customer_id:
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9416,7 +9430,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-75062192-0431-4cfb-b071-0b2e5e4f06c5
+ slug: privacy-policy-3d42b2b0-4cb8-4cd2-8d7b-6959016621c8
body: We respect your privacy.
body_html: |
<div class="trix-content">
diff --git a/docs/plans/6.0-integrations-admin.md b/docs/plans/6.0-integrations-admin.md
index e9356d902c..681cd1213b 100644
--- a/docs/plans/6.0-integrations-admin.md
+++ b/docs/plans/6.0-integrations-admin.md
@@ -24,6 +24,7 @@ Make `Spree::Integration` the single credential surface for every provider seam
- **One integration per (store, type)** stays (model validation shipped; this plan adds the backing unique DB index per house rule). Multi-account support is explicitly out of scope — same deferral as `5.7-payment-method-rules.md`'s per-channel credentials grooming note.
- **Admin-only surface.** No store serializer, no storefront exposure, ever. Secret-key access is gated by new `read_integrations` / `write_integrations` scopes; JWT access by CanCanCan on `Spree::Integration`.
- **Verify before activate** (resolved 2026-08-06). Saving credentials never runs a network call — partial setups save fine, inactive. Flipping `active: true` runs `can_connect?` and rejects with 422 (`connection_error_message` in the error) on failure. Accepted trade-off: a vendor outage temporarily blocks *going live* (not editing); the explicit `POST /:id/test` endpoint remains for diagnostics at any time.
+- **Gallery branding is `logo_url` + server-localized `description`** (resolved 2026-08-06). Integration gems declare a class-level `logo_url` — an absolute URL to hosted brand assets, or a `data:` URI for self-contained gems — and a `description` (with `spree.integrations.<api_type>.description` Rails translations winning, so gems localize server-side; dashboard locale files are not extendable by Ruby gems). **Deliberately not asset-pipeline paths**: in the 6.0 split the Rails side is a data API — integration gems shipping browser images would force Propshaft onto headless hosts plus precompile hints and host-URL resolution. Accepted trade-off: hosted logos are a courtesy, not a guarantee (vendor CDNs rot, air-gapped admins) — the dashboard always falls back to a letter avatar, and self-contained gems use data URIs.
- **Connection status is ephemeral** (resolved 2026-08-06). No `last_checked_at`/`last_error` columns — the test endpoint returns live results, the gallery shows stored state (`active`) plus on-demand test results. Accepted trade-off: no "last verified 2h ago" display without clicking test.
## Design Details
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index c98f14f996..109134d370 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -1409,7 +1409,10 @@ export interface IntegrationTypeDefinition {
name: string
/** Display grouping, e.g. `shipping`, `tax`; null for ungrouped. */
group: string | null
- icon: string | null
+ /** One-line description, localized server-side from the gem's translations. */
+ description: string | null
+ /** Gallery logo: an absolute URL to hosted brand assets, or a `data:` URI for self-contained gems. Render with a fallback — hosted logos are a courtesy, not a guarantee. */
+ logo_url: string | null
preference_schema: { key: string; type: string; default: unknown }[]
/** Whether the current store already holds credentials for this type. */
connected: boolean
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
index dfde94efbe..f45c76a09a 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/integrations.tsx
@@ -153,33 +153,63 @@ function IntegrationCard({
return (
<Card>
- <CardContent className="flex items-center justify-between gap-3 p-4">
- <div className="flex min-w-0 flex-col gap-1">
- <span className="truncate font-medium text-sm">{type.name}</span>
- {integration ? (
- <Badge variant={integration.active ? 'default' : 'secondary'} className="w-fit">
- {integration.active
- ? t('admin.integrations.status.active')
- : t('admin.integrations.status.connected_inactive')}
- </Badge>
- ) : (
- <span className="text-muted-foreground text-xs">
- {t('admin.integrations.status.not_connected')}
- </span>
- )}
+ <CardContent className="flex flex-col gap-3 p-4">
+ <div className="flex items-center gap-3">
+ <IntegrationLogo name={type.name} logoUrl={type.logo_url} />
+ <div className="flex min-w-0 flex-1 flex-col gap-1">
+ <span className="truncate font-medium text-sm">{type.name}</span>
+ {integration ? (
+ <Badge variant={integration.active ? 'default' : 'secondary'} className="w-fit">
+ {integration.active
+ ? t('admin.integrations.status.active')
+ : t('admin.integrations.status.connected_inactive')}
+ </Badge>
+ ) : (
+ <span className="text-muted-foreground text-xs">
+ {t('admin.integrations.status.not_connected')}
+ </span>
+ )}
+ </div>
+ <Button size="sm" variant={integration ? 'outline' : 'default'} onClick={onConfigure}>
+ {integration
+ ? t('admin.integrations.configure_cta')
+ : canWrite
+ ? t('admin.integrations.connect_cta')
+ : t('admin.integrations.view_cta')}
+ </Button>
</div>
- <Button size="sm" variant={integration ? 'outline' : 'default'} onClick={onConfigure}>
- {integration
- ? t('admin.integrations.configure_cta')
- : canWrite
- ? t('admin.integrations.connect_cta')
- : t('admin.integrations.view_cta')}
- </Button>
+ {type.description && (
+ <p className="line-clamp-2 text-muted-foreground text-xs">{type.description}</p>
+ )}
</CardContent>
</Card>
)
}
+// Gem-declared logo (hosted URL or data URI), falling back to an
+// initial-letter avatar when none is declared — or when the URL fails to
+// load (offline, vendor moved the file) — so cards never show a broken image.
+function IntegrationLogo({ name, logoUrl }: { name: string; logoUrl: string | null }) {
+ const [failed, setFailed] = useState(false)
+
+ if (logoUrl && !failed) {
+ return (
+ <img
+ src={logoUrl}
+ alt=""
+ onError={() => setFailed(true)}
+ className="size-9 shrink-0 rounded-md object-contain"
+ />
+ )
+ }
+
+ return (
+ <div className="flex size-9 shrink-0 items-center justify-center rounded-md bg-muted font-medium text-muted-foreground text-sm">
+ {name.charAt(0).toUpperCase()}
+ </div>
+ )
+}
+
function ConfigureIntegrationSheet({
type,
integration,
diff --git a/spree/api/app/controllers/spree/api/v3/admin/integrations_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/integrations_controller.rb
index 12f8b6fe9c..d9e714ce9f 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/integrations_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/integrations_controller.rb
@@ -27,7 +27,8 @@ module Spree
type: klass.api_type,
name: klass.integration_name,
group: klass.integration_group,
- icon: klass.icon_path,
+ description: klass.localized_description,
+ logo_url: klass.logo_url,
preference_schema: klass.serialized_preference_schema,
connected: connected_types.include?(klass.to_s)
}
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/integrations_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/integrations_controller_spec.rb
index 08215bbc68..d638570ff8 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/integrations_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/integrations_controller_spec.rb
@@ -53,6 +53,27 @@ RSpec.describe Spree::Api::V3::Admin::IntegrationsController, type: :controller
entry = json_response['data'].find { |row| row['type'] == 'carrier' }
expect(entry['connected']).to be true
end
+
+ describe 'gallery metadata' do
+ it 'serves the class description and no logo by default' do
+ allow(TestIntegrations::Carrier).to receive(:description).and_return('Ships things')
+
+ get :types, as: :json
+
+ entry = json_response['data'].find { |row| row['type'] == 'carrier' }
+ expect(entry['description']).to eq('Ships things')
+ expect(entry['logo_url']).to be_nil
+ end
+
+ it 'serves the declared logo url untouched' do
+ allow(TestIntegrations::Carrier).to receive(:logo_url).and_return('https://cdn.example.com/logo.svg')
+
+ get :types, as: :json
+
+ entry = json_response['data'].find { |row| row['type'] == 'carrier' }
+ expect(entry['logo_url']).to eq('https://cdn.example.com/logo.svg')
+ end
+ end
end
describe 'POST #create' do
diff --git a/spree/core/app/models/spree/integration.rb b/spree/core/app/models/spree/integration.rb
index 8b20e86928..cbd6859fda 100644
--- a/spree/core/app/models/spree/integration.rb
+++ b/spree/core/app/models/spree/integration.rb
@@ -57,6 +57,36 @@ module Spree
nil
end
+ # Logo shown on the gallery card: an absolute URL to publicly hosted
+ # brand assets, or a `data:` URI for gems that want to be self-contained
+ # (works air-gapped, no CSP domain to allowlist). Anything an `<img src>`
+ # accepts. Deliberately not an asset-pipeline path — integration gems
+ # must not force an asset pipeline onto headless API hosts. Hosted logos
+ # are a courtesy, not a guarantee: the dashboard falls back to a letter
+ # avatar when unset or unreachable.
+ #
+ # @return [String, nil]
+ def self.logo_url
+ nil
+ end
+
+ # One-line marketing description shown on the integration's gallery card.
+ # Localize by shipping a Rails translation instead (or additionally):
+ # `spree.integrations.<api_type>.description` wins over this fallback.
+ #
+ # @return [String, nil]
+ def self.description
+ nil
+ end
+
+ # Description for the current locale: the gem's Rails translation when
+ # present, otherwise the {.description} fallback.
+ #
+ # @return [String, nil]
+ def self.localized_description
+ Spree.t("integrations.#{api_type}.description", default: description)
+ end
+
def self.integration_name
name.demodulize.titleize.strip
end
diff --git a/spree/core/spec/models/spree/integration_spec.rb b/spree/core/spec/models/spree/integration_spec.rb
index 66044ab75f..3e9fa708a7 100644
--- a/spree/core/spec/models/spree/integration_spec.rb
+++ b/spree/core/spec/models/spree/integration_spec.rb
@@ -38,6 +38,35 @@ RSpec.describe Spree::Integration, type: :model do
end
end
+ describe 'gallery metadata' do
+ let(:described_klass) do
+ Class.new(described_class) do
+ def self.name = 'SpreeCarrier::Integration'
+ def self.description = 'Fallback description'
+ end
+ end
+
+ before { stub_const('SpreeCarrier::Integration', described_klass) }
+
+ it 'declares no logo or description by default' do
+ expect(described_class.logo_url).to be_nil
+ expect(described_class.description).to be_nil
+ end
+
+ it 'falls back to the class description without a translation' do
+ expect(SpreeCarrier::Integration.localized_description).to eq('Fallback description')
+ end
+
+ it 'prefers the Rails translation for the current locale' do
+ translations = { spree: { integrations: { carrier: { description: 'Translated' } } } }
+ I18n.backend.store_translations(:en, translations)
+
+ expect(SpreeCarrier::Integration.localized_description).to eq('Translated')
+ ensure
+ I18n.backend.reload!
+ end
+ end
+
describe 'verify before activate' do
let(:failing_class) do
Class.new(described_class) do
diff --git a/spree/easypost/README.md b/spree/easypost/README.md
index 5675a5f241..9ccc333daf 100644
--- a/spree/easypost/README.md
+++ b/spree/easypost/README.md
@@ -19,6 +19,7 @@ Methods without the EasyPost provider keep pricing through their calculator —
- Weights are converted to ounces from the store's unit system (imperial → pounds, metric → grams).
- Label purchase and tracking (a `FulfillmentProvider`) are not part of this gem yet — fulfillment stays manual.
+- The gallery card's logo is the official hosted EasyPost asset (`logo_url` — no asset pipeline involved; the dashboard falls back to a letter avatar if unreachable) and its description lives in `config/locales/`, resolved per the store's locale.
## Testing
diff --git a/spree/easypost/app/models/spree_easypost/integration.rb b/spree/easypost/app/models/spree_easypost/integration.rb
index af5d0c50ec..b93cdee972 100644
--- a/spree/easypost/app/models/spree_easypost/integration.rb
+++ b/spree/easypost/app/models/spree_easypost/integration.rb
@@ -12,6 +12,16 @@ module SpreeEasyPost
'EasyPost'
end
+ def self.logo_url
+ 'https://www.easypost.com/wp-content/uploads/2026/03/EasyPost-Logo.svg'
+ end
+
+ # Fallback for hosts without the gem's translations; the localized
+ # description in config/locales wins.
+ def self.description
+ 'Live multi-carrier delivery rates at checkout through your EasyPost account.'
+ end
+
# A cheap authenticated read: fails with 401 on a bad key without
# creating anything on the account.
def can_connect?
diff --git a/spree/easypost/config/locales/en.yml b/spree/easypost/config/locales/en.yml
new file mode 100644
index 0000000000..207ea4891a
--- /dev/null
+++ b/spree/easypost/config/locales/en.yml
@@ -0,0 +1,6 @@
+---
+en:
+ spree:
+ integrations:
+ easy_post:
+ description: Live multi-carrier delivery rates at checkout through your EasyPost account, including your own negotiated carrier contracts.
diff --git a/spree/easypost/spec/models/spree_easypost/integration_spec.rb b/spree/easypost/spec/models/spree_easypost/integration_spec.rb
index f9ba32f535..5e0d195bfe 100644
--- a/spree/easypost/spec/models/spree_easypost/integration_spec.rb
+++ b/spree/easypost/spec/models/spree_easypost/integration_spec.rb
@@ -13,6 +13,12 @@ RSpec.describe SpreeEasyPost::Integration do
expect(described_class.api_type).to eq('easy_post')
end
+ it 'declares gallery metadata' do
+ expect(described_class.logo_url).to start_with('https://')
+ # The gem's locale file wins over the class fallback.
+ expect(described_class.localized_description).to include('negotiated carrier contracts')
+ end
+
it 'masks the api key as a password preference' do
expect(described_class.password_preference_keys).to include(:api_key)
end