Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add Store API support for Newsletter Subscribers
Damian Legawiece767f1a9c5c8
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 1f9cae2531..97784f57b2 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -590,16 +590,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjllNWE1NWJlLTJkYzktNDE4MC1iNzVhLTJkMDZiZTA5OWU3MyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc4NzE0Nzk0fQ.WFswarYhOtFQrLBlhP-Eb7SA6CAGdJCjTLsUfw9u-Cg- refresh_token: 51fTpJHejSdmreCpH6oBm82L+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjQxNmNkZmZkLTFjNjMtNDVlZS1hZmZmLWZhMDIyNjg4ZTRmYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5Mzc1NjU4fQ.di9q1SWMr4u6iu85LphhF1wm14rfo7TSMV_mL-w2x_c+ refresh_token: BzLiMBEy42daj8QzPgfdN7VRuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Carrie- last_name: Metz+ first_name: Muriel+ last_name: Rolfsonphone:accepts_email_marketing: false- full_name: Carrie Metz+ full_name: Muriel Rolfsonavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -672,16 +672,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijk5MTM5YTQxLTk1ODQtNDNmYy05Y2M5LWExNWFiNzQ0Y2Q4ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc4NzE0Nzk1fQ.Ms3kK7ALwfl8AEFgqOTtQuY4OXYdpyHN6ifI-4MWStg- refresh_token: mLMEGNP4zaY5Za3k5N4puKhF+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImY1ZTI0OWZjLTU2OWItNGMxOS05NmY0LTczMGQ0MTkyNDllYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5Mzc1NjU5fQ.Mj5GatT53qoIVQWM5C6SGLMjC_8W-tbfBAYiwuqxssw+ refresh_token: ATUxJ8cznsCRdeM94bt6MpFbuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Abram- last_name: Trantow+ first_name: Yoshiko+ last_name: Gerlachphone:accepts_email_marketing: false- full_name: Abram Trantow+ full_name: Yoshiko Gerlachavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -845,9 +845,9 @@ paths:data:- id: cart_gbHJdmfrXBmarket_id:- number: R139181277- token: HcVHbgtZJ4WxxcynuTKt6p79iQNAxukuSNX- email: [email protected]+ number: R664489317+ token: DNbsRBmEum7pEjvQP1kQfL82Sa9dpamPvNH+ email: [email protected]customer_note:currency: USDlocale: en@@ -889,8 +889,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 583630- slug: product-583630+ name: Product 583769+ slug: product-583769options_text: ''price: '10.0'display_price: "$10.00"@@ -915,7 +915,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H38066716360+ number: H67163565781tracking: U10000tracking_url:cost: '100.0'@@ -944,7 +944,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Winfred Dietrich+ name: Ilona Raynoraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1014,9 +1014,9 @@ paths:market:- id: cart_UkLWZg9DAJmarket_id:- number: R653240222- token: Lta26Lyfq4EtwsMwD1kt4az1XZLr14fQKqn- email: [email protected]+ number: R608295263+ token: hPKQmwQsRPWzchLyF6W66k6tmz7FDgywVra+ email: [email protected]customer_note:currency: USDlocale: en@@ -1058,8 +1058,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 574608- slug: product-574608+ name: Product 571600+ slug: product-571600options_text: ''price: '10.0'display_price: "$10.00"@@ -1084,7 +1084,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H27683996067+ number: H06444123777tracking: U10000tracking_url:cost: '100.0'@@ -1113,7 +1113,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Winfred Dietrich+ name: Ilona Raynoraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1256,8 +1256,8 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R175749722- token: rrsVnbxwLVc2KkMntz2RqPaKhfxtDk4AaQx+ number: R614354862+ token: GFVVFvrWYoqA1u1YH7pVUxznA9FVYYYN16iemail:customer_note:currency: USD@@ -1412,9 +1412,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R662034436- token: utvMuyjqh2mMd74g3NcvfyCvJVMPqYSZ9At- email: [email protected]+ number: R391007411+ token: TJQaoQquys2FEa6bQAQG6UNsTbugSQWxvu9+ email: [email protected]customer_note:currency: USDlocale: en@@ -1441,7 +1441,7 @@ paths:display_delivery_total: "$0.00"warnings:- code: line_item_removed- message: Product 628846 was removed because it was sold out+ message: Product 623222 was removed because it was sold outline_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJstore_credit_total: '0.0'@@ -1583,9 +1583,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R973162333- token: QPDkdD3JJT4D25jB8dadWYfyrSxvWpPXnp1- email: [email protected]+ number: R819048584+ token: 2fF1kfwXemRtwo39BV6ZNNQHG29ThFThfx7+ email: [email protected]customer_note: Leave at doorcurrency: USDlocale: en@@ -1629,8 +1629,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 631959- slug: product-631959+ name: Product 639240+ slug: product-639240options_text: ''price: '19.99'display_price: "$19.99"@@ -1655,7 +1655,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H29882311098+ number: H40312398138tracking:tracking_url:cost: '10.0'@@ -1684,7 +1684,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Casimira Emmerich+ name: Adella Krisaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1921,9 +1921,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R252978915- token: 4Lii2eNk6MZSo8FLKpBmUXXTHLTNdTLfAC8- email: [email protected]+ number: R632083010+ token: Hud7FDknGoibTteuPcBENinKizai8DriaWj+ email: [email protected]customer_note:currency: USDlocale: en@@ -1965,8 +1965,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 659809- slug: product-659809+ name: Product 659069+ slug: product-659069options_text: ''price: '10.0'display_price: "$10.00"@@ -1991,7 +1991,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H28360472279+ number: H50751149271tracking: U10000tracking_url:cost: '100.0'@@ -2020,7 +2020,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Meryl Kohler+ name: Aurelia McGlynnaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2155,8 +2155,8 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R923625339- email: [email protected]+ number: R775225129+ email: [email protected]customer_note:currency: USDlocale: en@@ -2183,7 +2183,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: backorderpayment_status: paid- completed_at: '2026-05-13T22:26:41.547Z'+ completed_at: '2026-05-21T14:01:05.267Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -2193,8 +2193,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 676533- slug: product-676533+ name: Product 677597+ slug: product-677597options_text: ''price: '19.99'display_price: "$19.99"@@ -2219,7 +2219,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H91422323884+ number: H07213205217tracking:tracking_url:cost: '10.0'@@ -2248,7 +2248,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Catharine Cronin+ name: Phylis Kozeyaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2277,8 +2277,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-9ccf88928ac4- number: PRCUU49P+ response_code: BGS-d9218ca0c082+ number: P6TGTMWLamount: '29.99'display_amount: "$29.99"status: completed@@ -3134,16 +3134,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNkNzQ5N2QzLTM5YjctNGYzMi04OGNiLWQzNWI1ODM2MWQxZCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc4NzE0ODA4fQ.tOwJzz71w-YuOe_DK0dHrNS4f1ZccZxLVRe5kSATM3M- refresh_token: 5G4xXN5Vx6ThMLPdqLHAoyAp+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijk2ZTc1YzViLTY4NjMtNDkzMy1iYWFhLTZmNDZhNzFiY2VhZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5Mzc1NjcxfQ.TGikt0JLnGCtiRl8AWD75GYMbSA_VFk8R8tkkcVmo4M+ refresh_token: rUy5d5FkkFKRKVTjSNLMmGXCuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Jamal- last_name: Berge+ first_name: Iris+ last_name: Hirthephone:accepts_email_marketing: false- full_name: Jamal Berge+ full_name: Iris Hirtheavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -3316,8 +3316,8 @@ paths:- id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R531767804- email: [email protected]+ number: R453573119+ email: [email protected]customer_note:currency: USDlocale: en@@ -3344,7 +3344,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-05-13T22:26:49.047Z'+ completed_at: '2026-05-21T14:01:12.513Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -3354,8 +3354,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 764134- slug: product-764134+ name: Product 763572+ slug: product-763572options_text: ''price: '10.0'display_price: "$10.00"@@ -3380,7 +3380,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H30074853996+ number: H92480409501tracking: U10000tracking_url:cost: '100.0'@@ -3409,7 +3409,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Sebrina Hermann+ name: Aleen Powlowskiaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3572,8 +3572,8 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R928393368- email: [email protected]+ number: R788321337+ email: [email protected]customer_note:currency: USDlocale: en@@ -3600,7 +3600,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-05-13T22:26:49.756Z'+ completed_at: '2026-05-21T14:01:13.194Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -3610,8 +3610,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 783776- slug: product-783776+ name: Product 78558+ slug: product-78558options_text: ''price: '10.0'display_price: "$10.00"@@ -3636,7 +3636,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H92068676734+ number: H85969598405tracking: U10000tracking_url:cost: '100.0'@@ -3665,7 +3665,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Shiela Romaguera+ name: Ruthe Davisaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3785,8 +3785,8 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImVlMjZiNjE5LTg3MjktNDhkNi05NmEzLThlZmJhYmNhNzRkNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc4NzE0ODEwfQ.mrOcLTuL5ZJ1Wg8_6Fgl8zKtVCcMFqrmceormTlOOUM- refresh_token: pMnXxoXdrUE1b8DanCp2HaFs+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijg4ZWUyNGZiLTI2YjgtNDQxZi1hM2IwLTQ0ZDE1NWMxZDljNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5Mzc1Njc0fQ.H0u-Q3oSCKP2k0LaX7rQVF_U8c1IUvaRnwvBrzw8kGk+ refresh_token: Zm5W1wfivD9a8J1WsaKiBAycuser:id: cus_UkLWZg9DAJemail: [email protected]@@ -3900,12 +3900,12 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Rebekah- last_name: Dickinson+ email: [email protected]+ first_name: Jacinta+ last_name: Langphone: 555-555-0199accepts_email_marketing: false- full_name: Rebekah Dickinson+ full_name: Jacinta Langavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses:@@ -4039,7 +4039,7 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199@@ -4279,9 +4279,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R944275414- token: msg6sEmFpE3ouDVpMU1EdLZ3yeuJieR5aTS- email: [email protected]+ number: R877670295+ token: jgYbDf4iuvRHVAFiJSJPC67pctiy9JX6pm3+ email: [email protected]customer_note:currency: USDlocale: en@@ -4330,8 +4330,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 864988- slug: product-864988+ name: Product 866689+ slug: product-866689options_text: ''price: '10.0'display_price: "$10.00"@@ -4356,7 +4356,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H39326999271+ number: H97941431341tracking: U10000tracking_url:cost: '100.0'@@ -4385,7 +4385,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Darin Nolan+ name: Delora Kerlukeaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4539,9 +4539,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R847897368- token: o5ZBcbm28ynKSmisZKNn4S6uSzQQ29V4LzP- email: [email protected]+ number: R645855426+ token: xKbwRLgMS3z13qkQ8U9pN6NYL6ofcQ9GHZ7+ email: [email protected]customer_note:currency: USDlocale: en@@ -4583,8 +4583,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 884521- slug: product-884521+ name: Product 885251+ slug: product-885251options_text: ''price: '10.0'display_price: "$10.00"@@ -4609,7 +4609,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H45597673137+ number: H21042794370tracking: U10000tracking_url:cost: '100.0'@@ -4638,7 +4638,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Angelita Hirthe+ name: Meri O'Haraaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4781,9 +4781,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R776312936- token: PZxhxWxQUUeUfBPNAWtA84T3wj4VSjgDAuX- email: [email protected]+ number: R735538070+ token: pJmy9PSsevBtccAFgssJj5xxWh7Zx2avpvg+ email: [email protected]customer_note:currency: USDlocale: en@@ -4827,8 +4827,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 902074- slug: product-902074+ name: Product 90269+ slug: product-90269options_text: ''price: '10.0'display_price: "$10.00"@@ -4853,7 +4853,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H84960578003+ number: H61990909745tracking: U10000tracking_url:cost: '100.0'@@ -4882,7 +4882,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Marcella Gleason+ name: Gianna Prosaccoaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5039,9 +5039,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R477575561- token: XmsrQSMW1GjTQXoR84zjmPkRKDBu9wPohGR- email: [email protected]+ number: R786565483+ token: rPCVCzH2MAhdyzFpsLwftnwAWtyVzCAuH5j+ email: [email protected]customer_note:currency: USDlocale: en@@ -5080,8 +5080,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 928799- slug: product-928799+ name: Product 924064+ slug: product-924064options_text: ''price: '10.0'display_price: "$10.00"@@ -5106,7 +5106,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H17569959219+ number: H72899618600tracking: U10000tracking_url:cost: '100.0'@@ -5135,7 +5135,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Cherilyn Rohan+ name: Hoa Abshireaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5164,8 +5164,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260513222659480328- number: PJICQI95+ response_code: 1-SC-20260521140122745447+ number: PKDTTE1Camount: '50.0'display_amount: "$50.00"status: checkout@@ -5344,9 +5344,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R763170613- token: jazQ6BN13e6FaHWeFZZtsY3SWiJbYmT32Vs- email: [email protected]+ number: R305341957+ token: cYad5ZEwRxucQSrUZeYvDNJJeNzFMkpais6+ email: [email protected]customer_note:currency: USDlocale: en@@ -5388,8 +5388,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 969841- slug: product-969841+ name: Product 967644+ slug: product-967644options_text: ''price: '10.0'display_price: "$10.00"@@ -5414,7 +5414,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H66513225741+ number: H87527277081tracking: U10000tracking_url:cost: '100.0'@@ -5443,7 +5443,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Alona Lebsack+ name: Marget Carteraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5472,8 +5472,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260513222702020297- number: PRSNCO99+ response_code: 1-SC-20260521140125170061+ number: P247ASB1amount: '50.0'display_amount: "$50.00"status: invalid@@ -5597,7 +5597,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: 35825F9FC9C04D3E+ code: 5F5907332CD24C13status: activecurrency: USDamount: '10.0'@@ -5693,7 +5693,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: 3B095595FD9C8DF0+ code: E7D8EEDBD8B38629status: activecurrency: USDamount: '10.0'@@ -5784,9 +5784,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R218798477- token: FDVh29CghDceRzZhTTRHQcH6RzwtaYu7ZoM- email: [email protected]+ number: R898038455+ token: kwoDUG5ytVevnyteMSLq11LFUoUeQvgvj3C+ email: [email protected]customer_note:currency: USDlocale: en@@ -5834,8 +5834,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 994255- slug: product-994255+ name: Product 998774+ slug: product-998774options_text: ''price: '10.0'display_price: "$10.00"@@ -5862,8 +5862,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 1004709- slug: product-1004709+ name: Product 1007565+ slug: product-1007565options_text: ''price: '19.99'display_price: "$19.99"@@ -6006,9 +6006,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R208536174- token: sPa7oQxwwRHBBMxMdgeELoGPVNup8VFHhKf- email: [email protected]+ number: R361093646+ token: ANzLKaHuynyv78jwmNXN17TGQvYaPbpDZpf+ email: [email protected]customer_note:currency: USDlocale: en@@ -6053,8 +6053,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1035511- slug: product-1035511+ name: Product 1032574+ slug: product-1032574options_text: ''price: '10.0'display_price: "$10.00"@@ -6177,9 +6177,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R450595189- token: egYzsmtmVmA8p8CnZuYJY5xCqPqCXyjvcP2- email: [email protected]+ number: R782177832+ token: 3qTD9CqYFu8if2zPw9fjYJT6bcLLBXgqdkB+ email: [email protected]customer_note:currency: USDlocale: en@@ -6709,6 +6709,182 @@ paths:message: Country not foundschema:"$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/newsletter_subscribers":+ post:+ summary: Subscribe to the newsletter+ tags:+ - Newsletter Subscribers+ security:+ - api_key: []+ description: |+ Subscribes an email address to the newsletter for the current store.++ Behavior:++ - If the email is already verified for this store, the existing subscription is returned unchanged.+ - If the request is unauthenticated (guest), the subscription is created in an unverified state+ and a `newsletter_subscriber.subscription_requested` event is published containing the+ `verification_token` and the validated `redirect_url`. Storefronts subscribe to this event+ via a webhook to send the confirmation email; the link should point at+ `redirect_url?token=<verification_token>` and call `POST /newsletter_subscribers/verify`+ when the user clicks it.+ - If the request is authenticated via JWT and the customer's email matches the subscribed email,+ the subscription is auto-verified — no event is fired.++ The optional `redirect_url` is where the verification token should land on the storefront. It is+ validated against the store's [Allowed Origins](/developer/core-concepts/allowed-origins) and+ silently dropped from the webhook payload if it does not match (secure-by-default).++ Newsletter consent is preserved across registration: if a guest subscribes and later registers+ with the same email, the existing subscriber record is reused.+ x-codeSamples:+ - lang: javascript+ label: Spree SDK+ source: |-+ import { createClient } from '@spree/sdk'++ const client = createClient({+ baseUrl: 'https://your-store.com',+ publishableKey: '<api-key>',+ })++ const subscriber = await client.newsletterSubscribers.create({+ email: '[email protected]',+ // Where the verification token should land. Must be in the store's+ // allowed origins. The storefront's webhook handler will send the+ // confirmation email with a link to `<redirect_url>?token=<token>`.+ redirect_url: 'https://your-store.com/newsletter/confirm',+ })+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: false+ description: Optional Bearer JWT — when present, links the subscription to+ that customer+ schema:+ type: string+ responses:+ '201':+ description: auto-verified when JWT matches subscribed email+ content:+ application/json:+ example:+ id: sub_UkLWZg9DAJ+ email: [email protected]+ created_at: '2026-05-21T14:01:32.605Z'+ updated_at: '2026-05-21T14:01:32.605Z'+ verified: true+ verified_at: '2026-05-21T14:01:32Z'+ customer_id: cus_UkLWZg9DAJ+ schema:+ "$ref": "#/components/schemas/NewsletterSubscriber"+ '422':+ description: invalid email format+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Email is invalid+ details:+ email:+ - is invalid+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ email:+ type: string+ format: email+ example: [email protected]+ redirect_url:+ type: string+ format: uri+ example: https://your-store.com/newsletter/confirm+ description: Storefront URL the verification token should be appended+ to. Must be in the store's allowed origins.+ required:+ "/api/v3/store/newsletter_subscribers/verify":+ post:+ summary: Verify a newsletter subscription+ tags:+ - Newsletter Subscribers+ security:+ - api_key: []+ description: |+ Confirms a pending newsletter subscription using the verification token sent by email.++ After successful verification:+ - The subscriber record is marked verified.+ - If the subscription is associated with a customer, that customer's `accepts_email_marketing`+ flag is set to `true`.+ x-codeSamples:+ - lang: javascript+ label: Spree SDK+ source: |-+ import { createClient } from '@spree/sdk'++ const client = createClient({+ baseUrl: 'https://your-store.com',+ publishableKey: '<api-key>',+ })++ const subscriber = await client.newsletterSubscribers.verify({+ token: 'abc123def456',+ })+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: subscription verified+ content:+ application/json:+ example:+ id: sub_UkLWZg9DAJ+ email: [email protected]+ created_at: '2026-05-21T14:01:32.629Z'+ updated_at: '2026-05-21T14:01:32.640Z'+ verified: true+ verified_at: '2026-05-21T14:01:32Z'+ customer_id:+ schema:+ "$ref": "#/components/schemas/NewsletterSubscriber"+ '422':+ description: missing token+ content:+ application/json:+ example:+ error:+ code: parameter_missing+ message: token is required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ token:+ type: string+ example: abc123def456+ description: Verification token from the confirmation email+ required:+ - token"/api/v3/store/orders/{id}":get:summary: Get an order@@ -6781,7 +6957,7 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R197640310+ number: R219546930email: [email protected]customer_note:currency: USD@@ -6809,7 +6985,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-05-13T22:27:10.111Z'+ completed_at: '2026-05-21T14:01:33.348Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -6819,8 +6995,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1079923- slug: product-1079923+ name: Product 1078893+ slug: product-1078893options_text: ''price: '10.0'display_price: "$10.00"@@ -6845,7 +7021,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H69918660946+ number: H66784286474tracking: U10000tracking_url:cost: '100.0'@@ -6874,7 +7050,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Lasandra Parker+ name: Naida Boyeraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6906,7 +7082,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 258 Lovely Street+ address1: 260 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6925,7 +7101,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 259 Lovely Street+ address1: 261 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -7019,9 +7195,9 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_9a4fd867e33eda3a85f7af87+ external_id: bogus_a17b47e0398d13f0b001d373external_data:- client_secret: bogus_secret_15971e84c2d8ac80+ client_secret: bogus_secret_5dec9b38272306ebcustomer_external_id:expires_at:amount: '110.0'@@ -7119,7 +7295,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_3683ac1ff6e691f3adbfb2ec+ external_id: bogus_9d936b37603e2d2e9f882ba5external_data:client_secret: secret_123customer_external_id:@@ -7181,7 +7357,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_9107f7f0c69399f6d227c22c+ external_id: bogus_62a32b13abfdf70ffe97ebfeexternal_data:client_secret: secret_123customer_external_id:@@ -7283,7 +7459,7 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_16f2990e33899eaa9093a63f+ external_id: bogus_690fbde1d19bee42865caa8fexternal_data:client_secret: secret_123customer_external_id:@@ -7368,8 +7544,8 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_b86e791bebf1f51c2f249647- external_client_secret: bogus_seti_secret_21e471b276d8a28b+ external_id: bogus_seti_c30c9b5f22811f96e01ae78e+ external_client_secret: bogus_seti_secret_4c73525f5d30ff33external_data: {}payment_method_id: pm_UkLWZg9DAJpayment_source_id:@@ -7468,8 +7644,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_bd7e3c37db41dadfdd3ded55- external_client_secret: seti_secret_668be0e627f0b82a32113dd8+ external_id: seti_test_d7fa0cbdbc9e070360f09d67+ external_client_secret: seti_secret_890b28449262f42d588f7226external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -7545,8 +7721,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_88c1489315b6c12dd3f35176- external_client_secret: seti_secret_a4e461ece2ef965cf95ab200+ external_id: seti_test_0deba6c34d39f196388036e2+ external_client_secret: seti_secret_c8e8baf1be390bcebea53f33external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -7640,7 +7816,7 @@ paths:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJresponse_code:- number: PREKGE98+ number: P8EAYC6Lamount: '110.0'display_amount: "$110.00"status: checkout@@ -7736,7 +7912,7 @@ paths:body_html: ''- id: pol_OIJLhNcSbfname: Privacy Policy- slug: privacy-policy-05ad8a43-341b-4283-b2b3-42a1597d4c3f+ slug: privacy-policy-e33e52be-144d-4d70-99a2-978929d3c22abody: We respect your privacy.body_html: |<div class="trix-content">@@ -7980,13 +8156,13 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 1171648- slug: product-1171648+ name: Product 1173606+ slug: product-1173606meta_title:meta_description:meta_keywords:variant_count: 1- available_on: '2025-05-13T22:27:20.479Z'+ available_on: '2025-05-21T14:01:43.412Z'purchasable: truein_stock: falsebackorderable: true@@ -8008,28 +8184,29 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 1189078- slug: product-1189078+ name: Product 1189963+ slug: product-1189963meta_title:meta_description:meta_keywords:variant_count: 0- available_on: '2025-05-13T22:27:20.542Z'+ available_on: '2025-05-21T14:01:43.466Z'purchasable: truein_stock: falsebackorderable: trueavailable: true- description: Nisi nostrum blanditiis sit reiciendis id dolorum.- Rerum consequatur laudantium fugiat corrupti eum atque perspiciatis- repellendus. Repellendus eum laborum praesentium totam consequuntur.- Dignissimos facere aut eaque suscipit. Sit itaque officiis recusandae- tempore libero sapiente laboriosam. Quod quisquam natus deleniti- provident et error velit. Veritatis facere temporibus qui maiores- quaerat iure aliquid. Iusto repudiandae tenetur assumenda officia- occaecati.+ description: Nobis autem cum dolorum nesciunt harum sequi voluptates.+ Sunt qui hic libero exercitationem ratione iusto. Vero odit quia+ assumenda minus similique corrupti a. Iste aliquam temporibus+ et aliquid beatae. Placeat odit voluptates molestias quam accusantium+ natus sed. Ut vero cumque delectus consectetur rem. Quae nam repudiandae+ corporis voluptate. Debitis rerum a recusandae sit dolorum earum+ fugiat ea. Praesentium alias veritatis molestias neque incidunt+ laudantium doloribus. Quo non eum placeat dolorem.description_html: |-- Nisi nostrum blanditiis sit reiciendis id dolorum. Rerum consequatur laudantium fugiat corrupti eum atque perspiciatis repellendus. Repellendus eum laborum praesentium totam consequuntur.- Dignissimos facere aut eaque suscipit. Sit itaque officiis recusandae tempore libero sapiente laboriosam. Quod quisquam natus deleniti provident et error velit. Veritatis facere temporibus qui maiores quaerat iure aliquid. Iusto repudiandae tenetur assumenda officia occaecati.+ Nobis autem cum dolorum nesciunt harum sequi voluptates. Sunt qui hic libero exercitationem ratione iusto. Vero odit quia assumenda minus similique corrupti a.+ Iste aliquam temporibus et aliquid beatae. Placeat odit voluptates molestias quam accusantium natus sed. Ut vero cumque delectus consectetur rem. Quae nam repudiandae corporis voluptate.+ Debitis rerum a recusandae sit dolorum earum fugiat ea. Praesentium alias veritatis molestias neque incidunt laudantium doloribus. Quo non eum placeat dolorem.default_variant_id: variant_EfhxLZ9ck8thumbnail_url:tags: []@@ -8131,13 +8308,13 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 1453907- slug: product-1453907+ name: Product 1451391+ slug: product-1451391meta_title:meta_description:meta_keywords:variant_count: 1- available_on: '2025-05-13T22:27:22.136Z'+ available_on: '2025-05-21T14:01:44.847Z'purchasable: truein_stock: falsebackorderable: true@@ -8164,7 +8341,7 @@ paths:amount_in_cents: 999currency: USDdisplay_amount: "$9.99"- recorded_at: '2026-04-28T22:27:22Z'+ recorded_at: '2026-05-06T14:01:44Z'schema:"$ref": "#/components/schemas/Product"'404':@@ -8539,9 +8716,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R001729941- token: W5ynafzKqDZLvj1bsDGYkxVU9XfM54fj2TU- email: [email protected]+ number: R744140023+ token: pTFm3XRZudeeoLXmviqWz6uNkVtaBp4uLrV+ email: [email protected]customer_note:currency: USDlocale: en@@ -8580,8 +8757,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1655543- slug: product-1655543+ name: Product 1658176+ slug: product-1658176options_text: ''price: '10.0'display_price: "$10.00"@@ -8606,7 +8783,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H55534597898+ number: H59588366435tracking: U10000tracking_url:cost: '100.0'@@ -8635,7 +8812,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Natalie Lind+ name: Veta Mitchelladdress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -8664,8 +8841,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260513222727628021- number: PZL9IN69+ response_code: 1-SC-20260521140150066371+ number: PEHXTQG6amount: '10.0'display_amount: "$10.00"status: checkout@@ -8692,7 +8869,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 322 Lovely Street+ address1: 324 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8711,7 +8888,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 323 Lovely Street+ address1: 325 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8808,9 +8985,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R023022648- token: k1F6SZ5iqCV1Vu88Ywos6XpvwkPwy1ARPt6- email: [email protected]+ number: R244936382+ token: Ycdv7VgR4x426YxWUz7eoyGEFZ1sRY4SpaC+ email: [email protected]customer_note:currency: USDlocale: en@@ -8852,8 +9029,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1672629- slug: product-1672629+ name: Product 1673068+ slug: product-1673068options_text: ''price: '10.0'display_price: "$10.00"@@ -8878,7 +9055,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H15373018353+ number: H49623074593tracking: U10000tracking_url:cost: '100.0'@@ -8907,7 +9084,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Linsey Grant+ name: Grady Pacochaaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -8939,7 +9116,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 330 Lovely Street+ address1: 332 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -8958,7 +9135,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 331 Lovely Street+ address1: 333 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9037,7 +9214,7 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: pNUefpiorWppH4tuM9RHiv38+ token: QL7gtUL5AUfgexgDh9iQFWaAis_default: falseis_private: truemeta:@@ -9113,7 +9290,7 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: bQSKNBBhCXtHWSoDUJahXA69+ token: zmk9bk8qkYJRXzjhxhYRV1Ggis_default: falseis_private: trueschema:@@ -9209,7 +9386,7 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: cst3bHUPsMnW4TqL1P89krGH+ token: FjFxxfkdRu9GRLaAmWerHsP1is_default: falseis_private: trueschema:@@ -9271,7 +9448,7 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: NUaszyr9oB7MvNSvd2Ri7qHf+ token: zTCwhxBSEZYoDbdjgF57VnYEis_default: falseis_private: trueschema:@@ -9500,6 +9677,8 @@ tags:description: Markets, countries, currencies, and locales- name: Wishlistsdescription: Customer wishlists+- name: Newsletter Subscribers+ description: Guest and customer newsletter subscriptions (double opt-in)- name: Policiesdescription: Store policies (return policy, privacy policy, terms of service)- name: Digitals@@ -9526,6 +9705,9 @@ x-tagGroups:- name: Wishliststags:- Wishlists+- name: Newsletter Subscribers+ tags:+ - Newsletter Subscribers- name: Policiestags:- Policiesdiff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdxindex 39f71a3935..ede29cb9bc 100644--- a/docs/developer/core-concepts/customers.mdx+++ b/docs/developer/core-concepts/customers.mdx@@ -3,6 +3,8 @@ title: Customersdescription: Customer accounts — registration, authentication, profiles, and guest checkout---+import { Since } from '/snippets/since.mdx';+## OverviewCustomers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.@@ -178,6 +180,64 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/password_resets/RESOn success, the user is automatically logged in and a JWT token is returned. The reset token expires after 15 minutes (configurable via `Spree::Config.customer_password_reset_expires_in`) and is single-use (changing the password invalidates it).+## Newsletter Subscriptions++<Since version="5.5" />++Headless storefronts often need to collect newsletter signups before account creation (footer forms, popup overlays). The Store API exposes a double opt-in subscription flow that mirrors the password reset webhook pattern.++### Step 1: Subscribe++<CodeGroup>++```typescript SDK+await client.newsletterSubscribers.create({+ email: '[email protected]',+ redirect_url: 'https://myshop.com/newsletter/confirm',+})+// Returns the NewsletterSubscriber (verified: false for guests)+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers' \+ -H 'X-Spree-Api-Key: pk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{+ "email": "[email protected]",+ "redirect_url": "https://myshop.com/newsletter/confirm"+ }'+```++</CodeGroup>++The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's [Allowed Origins](/developer/core-concepts/allowed-origins) — URLs that do not match are silently dropped from the webhook payload (secure-by-default).++This fires a `newsletter_subscriber.subscription_requested` event whose payload includes `email`, `verification_token`, and the validated `redirect_url`. Subscribe to this event from your storefront's webhook handler to send the confirmation email — the link in the email should point to `<redirect_url>?token=<verification_token>`. The bundled `spree_emails` package also listens to this event and sends a default confirmation email if you're not running a headless storefront.++If the request is authenticated via a customer JWT and the JWT's email matches the subscribed email, the subscription is **auto-verified** and no event is fired (the user has already proven email ownership).++### Step 2: Verify++<CodeGroup>++```typescript SDK+await client.newsletterSubscribers.verify({+ token: 'token-from-email',+})+// Returns the verified NewsletterSubscriber+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers/verify' \+ -H 'X-Spree-Api-Key: pk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "token": "token-from-email" }'+```++</CodeGroup>++On success, the subscriber is marked verified. If the subscription is linked to a customer record, that customer's `accepts_email_marketing` flag is also set to `true`. Consent is preserved across registration: if a guest subscribes and later registers with the same email, the existing subscriber is reused — registration won't accidentally reset their opt-in state.+## Customer Profile<CodeGroup>diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdxindex ec3dd1884d..8ee371be72 100644--- a/docs/developer/deployment/emails.mdx+++ b/docs/developer/deployment/emails.mdx@@ -24,7 +24,7 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks:- **URL:** `https://your-storefront.com/api/webhooks/spree`- - **Events:** `order.completed`, `order.canceled`, `order.shipped`, `customer.password_reset_requested`+ - **Events:** `order.completed`, `order.canceled`, `order.shipped`, `customer.password_reset_requested`, `newsletter_subscriber.subscription_requested`2. **Configure the storefront** with the webhook secret and email provider:@@ -45,6 +45,7 @@ EMAIL_FROM=Your Store <[email protected]>| `order.canceled` | Cancellation notice || `order.shipped` | Shipping notification with tracking link || `customer.password_reset_requested` | Password reset link |+| `newsletter_subscriber.subscription_requested` | Newsletter double opt-in confirmation link |### Custom Frameworksdiff --git a/docs/developer/storefront/nextjs/customization.mdx b/docs/developer/storefront/nextjs/customization.mdxindex 27bbf9ef00..ed1abe0317 100644--- a/docs/developer/storefront/nextjs/customization.mdx+++ b/docs/developer/storefront/nextjs/customization.mdx@@ -150,6 +150,7 @@ Email templates are React components in `src/lib/emails/`:| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items || `shipment-shipped.tsx` | `order.shipped` | Tracking number and link || `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |+| `newsletter-confirmation.tsx` | `newsletter_subscriber.subscription_requested` | Double opt-in confirmation link |Customize templates by editing these files directly. They use `@react-email/components` for email-safe layout primitives.@@ -175,6 +176,7 @@ export const POST = createWebhookHandler({'order.canceled': handleOrderCanceled,'order.shipped': handleOrderShipped,'customer.password_reset_requested': handlePasswordReset,+ 'newsletter_subscriber.subscription_requested': handleNewsletterConfirmation,},})```diff --git a/packages/sdk/.changeset/store-newsletter-subscribers.md b/packages/sdk/.changeset/store-newsletter-subscribers.mdnew file mode 100644index 0000000000..78d749fe4a--- /dev/null+++ b/packages/sdk/.changeset/store-newsletter-subscribers.md@@ -0,0 +1,7 @@+---+'@spree/sdk': minor+---++Add `client.newsletterSubscribers.create()` and `client.newsletterSubscribers.verify()` for the new Store API newsletter subscription endpoints.++Lets headless storefronts subscribe guests to the newsletter before account creation and confirm the double opt-in via the verification token from the confirmation email. Pass `redirect_url` on `create()` and the storefront receives a `newsletter_subscriber.subscription_requested` webhook with the token + validated redirect URL so it can send the confirmation email itself — same pattern as `customer.password_reset_requested`. When called with a JWT and the customer's own email, the subscription is auto-verified.diff --git a/packages/sdk/examples/newsletter-subscribers/create.ts b/packages/sdk/examples/newsletter-subscribers/create.tsnew file mode 100644index 0000000000..2e560d4573--- /dev/null+++ b/packages/sdk/examples/newsletter-subscribers/create.ts@@ -0,0 +1,18 @@+import { createClient } from '@spree/sdk'++const client = createClient({+ baseUrl: 'https://your-store.com',+ publishableKey: '<api-key>',+})++// region:example+const subscriber = await client.newsletterSubscribers.create({+ email: '[email protected]',+ // Where the verification token should land. Must be in the store's+ // allowed origins. The storefront's webhook handler will send the+ // confirmation email with a link to `<redirect_url>?token=<token>`.+ redirect_url: 'https://your-store.com/newsletter/confirm',+})+// endregion:example++export { subscriber }diff --git a/packages/sdk/examples/newsletter-subscribers/verify.ts b/packages/sdk/examples/newsletter-subscribers/verify.tsnew file mode 100644index 0000000000..55ea514fda--- /dev/null+++ b/packages/sdk/examples/newsletter-subscribers/verify.ts@@ -0,0 +1,14 @@+import { createClient } from '@spree/sdk'++const client = createClient({+ baseUrl: 'https://your-store.com',+ publishableKey: '<api-key>',+})++// region:example+const subscriber = await client.newsletterSubscribers.verify({+ token: 'abc123def456',+})+// endregion:example++export { subscriber }diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.tsindex 38fc367431..fb1b30f883 100644--- a/packages/sdk/src/store-client.ts+++ b/packages/sdk/src/store-client.ts@@ -28,6 +28,7 @@ import type {Locale,LoginCredentials,Market,+ NewsletterSubscriber,Order,OrderListParams,Payment,@@ -601,6 +602,50 @@ export class StoreClient {this.request<AuthTokens>('POST', '/customers', { body: params }),}+ // ============================================+ // Newsletter Subscribers+ // ============================================++ readonly newsletterSubscribers = {+ /**+ * Subscribe an email address to the newsletter for the current store.+ *+ * Behavior:+ * - If the email already has a verified subscription, the existing record is returned unchanged.+ * - Guest subscriptions are created in an unverified state and a+ * `newsletter_subscriber.subscription_requested` webhook event is fired with the+ * verification token + validated `redirect_url`; the storefront sends the+ * confirmation email and the link points at `redirect_url?token=...`.+ * - When the call is authenticated via JWT and the customer's email matches the subscribed+ * email, the subscription is auto-verified — no confirmation email is sent.+ *+ * `redirect_url` must match one of the store's allowed origins (see Allowed Origins+ * in the admin). If it does not, it is silently dropped from the webhook payload to+ * prevent open-redirect / token-exfiltration attacks.+ *+ * Pass `options.token` (JWT) to link the subscription to an authenticated customer.+ */+ create: (+ params: { email: string; redirect_url?: string },+ options?: RequestOptions,+ ): Promise<NewsletterSubscriber> =>+ this.request<NewsletterSubscriber>('POST', '/newsletter_subscribers', {+ ...options,+ body: params,+ }),++ /**+ * Confirm a pending newsletter subscription using the verification token from the+ * confirmation email. On success the subscriber is marked verified and, when linked+ * to a customer, that customer's `accepts_email_marketing` flag is set to `true`.+ */+ verify: (params: { token: string }, options?: RequestOptions): Promise<NewsletterSubscriber> =>+ this.request<NewsletterSubscriber>('POST', '/newsletter_subscribers/verify', {+ ...options,+ body: params,+ }),+ }+readonly customer = {/*** Get current customer profilediff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.tsindex 3043d604cb..0aceb0dc40 100644--- a/packages/sdk/tests/mocks/handlers.ts+++ b/packages/sdk/tests/mocks/handlers.ts@@ -113,6 +113,15 @@ export const fixtures = {quantity: 1,variant_id: 'var_1',},+ newsletterSubscriber: {+ id: 'sub_1',+ email: '[email protected]',+ verified: false,+ verified_at: null as string | null,+ customer_id: null as string | null,+ created_at: '2026-01-01T00:00:00Z',+ updated_at: '2026-01-01T00:00:00Z',+ },}const paginationMeta = { page: 1, limit: 25, count: 1, pages: 1 }@@ -613,4 +622,17 @@ export const handlers = [`${API_PREFIX}/wishlists/:wishlistId/items/:id`,() => new HttpResponse(null, { status: 204 }),),++ // Newsletter Subscribers+ http.post(`${API_PREFIX}/newsletter_subscribers`, () =>+ HttpResponse.json(fixtures.newsletterSubscriber, { status: 201 }),+ ),++ http.post(`${API_PREFIX}/newsletter_subscribers/verify`, () =>+ HttpResponse.json({+ ...fixtures.newsletterSubscriber,+ verified: true,+ verified_at: '2026-01-02T00:00:00Z',+ }),+ ),]diff --git a/packages/sdk/tests/newsletter-subscribers.test.ts b/packages/sdk/tests/newsletter-subscribers.test.tsnew file mode 100644index 0000000000..ecbb37a8d3--- /dev/null+++ b/packages/sdk/tests/newsletter-subscribers.test.ts@@ -0,0 +1,113 @@+import { HttpResponse, http } from 'msw'+import { beforeAll, describe, expect, it } from 'vitest'+import type { Client } from '../src'+import { createTestClient, TEST_BASE_URL } from './helpers'+import { fixtures } from './mocks/handlers'+import { server } from './mocks/server'++const API_PREFIX = `${TEST_BASE_URL}/api/v3/store`++describe('newsletterSubscribers', () => {+ let client: Client+ beforeAll(() => {+ client = createTestClient()+ })++ describe('create', () => {+ it('subscribes a guest email', async () => {+ const result = await client.newsletterSubscribers.create({+ email: '[email protected]',+ })++ expect(result.id).toBe('sub_1')+ expect(result.email).toBe('[email protected]')+ expect(result.verified).toBe(false)+ expect(result.customer_id).toBeNull()+ })++ it('sends the email in the request body', async () => {+ let capturedBody: Record<string, unknown> = {}+ server.use(+ http.post(`${API_PREFIX}/newsletter_subscribers`, async ({ request }) => {+ capturedBody = (await request.json()) as Record<string, unknown>+ return HttpResponse.json(fixtures.newsletterSubscriber, { status: 201 })+ }),+ )++ await client.newsletterSubscribers.create({ email: '[email protected]' })++ expect(capturedBody.email).toBe('[email protected]')+ })++ it('forwards redirect_url for webhook-driven confirmation emails', async () => {+ let capturedBody: Record<string, unknown> = {}+ server.use(+ http.post(`${API_PREFIX}/newsletter_subscribers`, async ({ request }) => {+ capturedBody = (await request.json()) as Record<string, unknown>+ return HttpResponse.json(fixtures.newsletterSubscriber, { status: 201 })+ }),+ )++ await client.newsletterSubscribers.create({+ email: '[email protected]',+ redirect_url: 'https://storefront.example.com/newsletter/confirm',+ })++ expect(capturedBody.redirect_url).toBe('https://storefront.example.com/newsletter/confirm')+ })++ it('forwards a JWT when provided', async () => {+ let capturedAuth: string | null = null+ server.use(+ http.post(`${API_PREFIX}/newsletter_subscribers`, ({ request }) => {+ capturedAuth = request.headers.get('Authorization')+ return HttpResponse.json(+ {+ ...fixtures.newsletterSubscriber,+ verified: true,+ verified_at: '2026-01-02T00:00:00Z',+ customer_id: 'user_1',+ },+ { status: 201 },+ )+ }),+ )++ const result = await client.newsletterSubscribers.create(+ { email: '[email protected]' },+ { token: 'user-jwt' },+ )++ expect(capturedAuth).toBe('Bearer user-jwt')+ expect(result.verified).toBe(true)+ expect(result.customer_id).toBe('user_1')+ })+ })++ describe('verify', () => {+ it('verifies a subscription using the token', async () => {+ const result = await client.newsletterSubscribers.verify({ token: 'abc123' })++ expect(result.verified).toBe(true)+ expect(result.verified_at).toBe('2026-01-02T00:00:00Z')+ })++ it('sends the token in the request body', async () => {+ let capturedBody: Record<string, unknown> = {}+ server.use(+ http.post(`${API_PREFIX}/newsletter_subscribers/verify`, async ({ request }) => {+ capturedBody = (await request.json()) as Record<string, unknown>+ return HttpResponse.json({+ ...fixtures.newsletterSubscriber,+ verified: true,+ verified_at: '2026-01-02T00:00:00Z',+ })+ }),+ )++ await client.newsletterSubscribers.verify({ token: 'verify-token-xyz' })++ expect(capturedBody.token).toBe('verify-token-xyz')+ })+ })+})diff --git a/spree/admin/app/helpers/spree/admin/webhook_endpoints_helper.rb b/spree/admin/app/helpers/spree/admin/webhook_endpoints_helper.rbindex d17189366d..432c44bec5 100644--- a/spree/admin/app/helpers/spree/admin/webhook_endpoints_helper.rb+++ b/spree/admin/app/helpers/spree/admin/webhook_endpoints_helper.rb@@ -93,6 +93,7 @@ module Spreedef custom_webhook_events%w[customer.password_reset_requested+ newsletter_subscriber.subscription_requestedorder.completedorder.paidorder.canceleddiff --git a/spree/api/app/controllers/spree/api/v3/store/newsletter_subscribers_controller.rb b/spree/api/app/controllers/spree/api/v3/store/newsletter_subscribers_controller.rbnew file mode 100644index 0000000000..dab5b0422e--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/store/newsletter_subscribers_controller.rb@@ -0,0 +1,96 @@+module Spree+ module Api+ module V3+ module Store+ class NewsletterSubscribersController < Store::BaseController+ rate_limit to: Spree::Api::Config[:rate_limit_register],+ within: Spree::Api::Config[:rate_limit_window].seconds,+ store: Rails.cache,+ only: [:create, :verify],+ with: RATE_LIMIT_RESPONSE++ # Authentication is optional — the parent's `before_action :authenticate_user`+ # leaves `current_user` nil when no JWT is present, which is the guest path.+ # When a JWT *is* present, we use it to link the subscription to the customer+ # (and auto-verify if the email matches).++ # POST /api/v3/store/newsletter_subscribers+ # Subscribes a guest or authenticated customer to the newsletter for the current store.+ # If the email already has a verified subscription, returns the existing record.+ # If a JWT is provided, the subscription is linked to that customer; if the customer's+ # email matches the subscribed email, the subscription is auto-verified.+ #+ # The optional `redirect_url` is the storefront page that should receive the+ # verification token (e.g. `https://your-store.com/newsletter/confirm`). When+ # provided, it is validated against the store's allowed origins and forwarded+ # in the `newsletter_subscriber.subscription_requested` event so the storefront+ # webhook handler can build the confirmation email link as+ # `redirect_url?token=<verification_token>`.+ def create+ subscriber = Spree::NewsletterSubscriber.subscribe(+ email: params[:email],+ user: current_user,+ store: current_store,+ redirect_url: validated_redirect_url+ )++ if subscriber.errors.any?+ render_errors(subscriber.errors)+ else+ render json: serialize_resource(subscriber), status: :created+ end+ end++ # POST /api/v3/store/newsletter_subscribers/verify+ # Confirms a newsletter subscription using the verification token sent by email.+ # Accepts: { "token": "..." }+ def verify+ token = params[:token]++ if token.blank?+ return render_error(+ code: ERROR_CODES[:parameter_missing],+ message: 'token is required',+ status: :unprocessable_content+ )+ end++ subscriber = Spree::NewsletterSubscriber.for_store(current_store).unverified.find_by(verification_token: token)++ unless subscriber+ return render_error(+ code: ERROR_CODES[:invalid_token],+ message: Spree.t(:newsletter_verification_token_invalid, scope: :api),+ status: :unprocessable_content+ )+ end++ Spree::Newsletter::Verify.new(subscriber: subscriber).call++ render json: serialize_resource(subscriber)+ end++ protected++ def serializer_class+ Spree::Api::V3::NewsletterSubscriberSerializer+ end++ private++ # Validates the requested redirect_url against the current store's allowed+ # origins. Returns nil (the link will be dropped from the event) when the URL+ # is not in the allow-list — same secure-by-default behavior as password resets.+ def validated_redirect_url+ redirect_url = params[:redirect_url]+ return nil if redirect_url.blank?+ return nil unless current_store.allowed_origins.exists?+ return nil unless current_store.allowed_origin?(redirect_url)++ redirect_url+ end+ end+ end+ end+ end+enddiff --git a/spree/api/config/locales/en.yml b/spree/api/config/locales/en.ymlindex 348a2e7b99..43a9792d8f 100644--- a/spree/api/config/locales/en.yml+++ b/spree/api/config/locales/en.yml@@ -9,6 +9,7 @@ en:invalid_taxonomy_id: Invalid taxonomy id.must_specify_api_key: You must specify an API key.negative_quantity: quantity is negative+ newsletter_verification_token_invalid: Newsletter verification token is invalid or has expired.order:could_not_transition: The order could not be transitioned. Please fix the errors and try again.insufficient_quantity: An item in your cart has become unavailable.diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 204ab71ef9..22f1d88945 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -60,6 +60,13 @@ Spree::Core::Engine.add_routes do# Customersresources :customers, only: [:create]+ # Newsletter Subscriptions (guest-accessible: subscribe + verify by token)+ resources :newsletter_subscribers, only: [:create] do+ collection do+ post :verify+ end+ end+# Current customer profile and nested resources (/customers/me/...)namespace :customer, path: 'customers/me' doget '/', action: :show, controller: '/spree/api/v3/store/customers'diff --git a/spree/api/spec/integration/spree/api/v3/store/newsletter_subscribers_spec.rb b/spree/api/spec/integration/spree/api/v3/store/newsletter_subscribers_spec.rbnew file mode 100644index 0000000000..ffdedc90c7--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/store/newsletter_subscribers_spec.rb@@ -0,0 +1,220 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Newsletter Subscribers API', type: :request, swagger_doc: 'api-reference/store.yaml' do+ include_context 'API v3 Store'++ path '/api/v3/store/newsletter_subscribers' do+ post 'Subscribe to the newsletter' do+ tags 'Newsletter Subscribers'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: []]+ description <<~DESC+ Subscribes an email address to the newsletter for the current store.++ Behavior:++ - If the email is already verified for this store, the existing subscription is returned unchanged.+ - If the request is unauthenticated (guest), the subscription is created in an unverified state+ and a `newsletter_subscriber.subscription_requested` event is published containing the+ `verification_token` and the validated `redirect_url`. Storefronts subscribe to this event+ via a webhook to send the confirmation email; the link should point at+ `redirect_url?token=<verification_token>` and call `POST /newsletter_subscribers/verify`+ when the user clicks it.+ - If the request is authenticated via JWT and the customer's email matches the subscribed email,+ the subscription is auto-verified — no event is fired.++ The optional `redirect_url` is where the verification token should land on the storefront. It is+ validated against the store's [Allowed Origins](/developer/core-concepts/allowed-origins) and+ silently dropped from the webhook payload if it does not match (secure-by-default).++ Newsletter consent is preserved across registration: if a guest subscribes and later registers+ with the same email, the existing subscriber record is reused.+ DESC++ sdk_example 'newsletter-subscribers/create'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: 'Authorization', in: :header, type: :string, required: false,+ description: 'Optional Bearer JWT — when present, links the subscription to that customer'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ email: { type: :string, format: 'email', example: '[email protected]' },+ redirect_url: {+ type: :string,+ format: 'uri',+ example: 'https://your-store.com/newsletter/confirm',+ description: 'Storefront URL the verification token should be appended to. Must be in the store\'s allowed origins.'+ }+ },+ required: %w[email]+ }++ response '201', 'subscription created (or existing returned)' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { '' }+ let(:body) { { email: '[email protected]' } }++ schema '$ref' => '#/components/schemas/NewsletterSubscriber'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['email']).to eq('[email protected]')+ expect(data['verified']).to eq(false)+ expect(data['id']).to be_present+ expect(data['customer_id']).to be_nil+ end+ end++ response '201', 'subscription created with a validated redirect_url' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { '' }+ let(:body) do+ {+ email: '[email protected]',+ redirect_url: 'https://storefront.example.com/newsletter/confirm'+ }+ end++ before do+ store.allowed_origins.create!(origin: 'https://storefront.example.com')+ end++ schema '$ref' => '#/components/schemas/NewsletterSubscriber'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['email']).to eq('[email protected]')+ expect(data['verified']).to eq(false)+ end+ end++ response '201', 'subscription created but redirect_url is dropped (not in allowed origins)' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { '' }+ let(:body) do+ {+ email: '[email protected]',+ redirect_url: 'https://evil.example.com/phish'+ }+ end++ before do+ store.allowed_origins.create!(origin: 'https://storefront.example.com')+ end++ schema '$ref' => '#/components/schemas/NewsletterSubscriber'++ run_test! do |response|+ data = JSON.parse(response.body)+ # Subscription itself succeeds; the redirect_url is silently dropped from+ # the webhook event payload to prevent open-redirect / token-exfiltration.+ expect(data['email']).to eq('[email protected]')+ expect(data['verified']).to eq(false)+ end+ end++ response '201', 'auto-verified when JWT matches subscribed email' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:body) { { email: user.email } }++ schema '$ref' => '#/components/schemas/NewsletterSubscriber'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['email']).to eq(user.email)+ expect(data['verified']).to eq(true)+ expect(data['customer_id']).to eq(user.prefixed_id)+ end+ end++ response '422', 'invalid email format' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { '' }+ let(:body) { { email: 'not-an-email' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('validation_error')+ end+ end+ end+ end++ path '/api/v3/store/newsletter_subscribers/verify' do+ post 'Verify a newsletter subscription' do+ tags 'Newsletter Subscribers'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: []]+ description <<~DESC+ Confirms a pending newsletter subscription using the verification token sent by email.++ After successful verification:+ - The subscriber record is marked verified.+ - If the subscription is associated with a customer, that customer's `accepts_email_marketing`+ flag is set to `true`.+ DESC++ sdk_example 'newsletter-subscribers/verify'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ token: {+ type: :string,+ example: 'abc123def456',+ description: 'Verification token from the confirmation email'+ }+ },+ required: %w[token]+ }++ response '200', 'subscription verified' do+ let(:'x-spree-api-key') { api_key.token }+ let!(:subscriber) { create(:newsletter_subscriber, :unverified, email: '[email protected]', store: store) }+ let(:body) { { token: subscriber.verification_token } }++ schema '$ref' => '#/components/schemas/NewsletterSubscriber'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['email']).to eq('[email protected]')+ expect(data['verified']).to eq(true)+ expect(data['verified_at']).to be_present+ end+ end++ response '422', 'invalid or expired token' do+ let(:'x-spree-api-key') { api_key.token }+ let(:body) { { token: 'not-a-real-token' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('invalid_token')+ end+ end++ response '422', 'missing token' do+ let(:'x-spree-api-key') { api_key.token }+ let(:body) { {} }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('parameter_missing')+ end+ end+ end+ end+enddiff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex e30336562f..9658e61680 100644--- a/spree/api/spec/swagger_helper.rb+++ b/spree/api/spec/swagger_helper.rb@@ -75,6 +75,7 @@ RSpec.configure do |config|{ name: 'Customers', description: 'Customer account, addresses, saved payment methods, and order history' },{ name: 'Markets', description: 'Markets, countries, currencies, and locales' },{ name: 'Wishlists', description: 'Customer wishlists' },+ { name: 'Newsletter Subscribers', description: 'Guest and customer newsletter subscriptions (double opt-in)' },{ name: 'Policies', description: 'Store policies (return policy, privacy policy, terms of service)' },{ name: 'Digitals', description: 'Digital product downloads' }],@@ -86,6 +87,7 @@ RSpec.configure do |config|{ name: 'Customers', tags: ['Customers'] },{ name: 'Markets', tags: ['Markets'] },{ name: 'Wishlists', tags: ['Wishlists'] },+ { name: 'Newsletter Subscribers', tags: ['Newsletter Subscribers'] },{ name: 'Policies', tags: ['Policies'] },{ name: 'Digitals', tags: ['Digitals'] }],diff --git a/spree/core/app/models/spree/newsletter_subscriber.rb b/spree/core/app/models/spree/newsletter_subscriber.rbindex e0a2e8a93d..f940f1d3f0 100644--- a/spree/core/app/models/spree/newsletter_subscriber.rb+++ b/spree/core/app/models/spree/newsletter_subscriber.rb@@ -55,10 +55,15 @@ module SpreeSpree::CSV::NewsletterSubscriberPresenter.new(self).callend- def self.subscribe(email:, user: nil, store: nil)+ def self.subscribe(email:, user: nil, store: nil, redirect_url: nil)store ||= Spree::Current.store- Spree::Newsletter::Subscribe.new(email: email, current_user: user, current_store: store).call+ Spree::Newsletter::Subscribe.new(+ email: email,+ current_user: user,+ current_store: store,+ redirect_url: redirect_url+ ).callenddef self.verify(token:)diff --git a/spree/core/app/services/spree/newsletter/subscribe.rb b/spree/core/app/services/spree/newsletter/subscribe.rbindex 63827d4c04..c2b304ec73 100644--- a/spree/core/app/services/spree/newsletter/subscribe.rb+++ b/spree/core/app/services/spree/newsletter/subscribe.rb@@ -1,10 +1,11 @@module Spreemodule Newsletterclass Subscribe- def initialize(email:, current_user: nil, current_store: nil)+ def initialize(email:, current_user: nil, current_store: nil, redirect_url: nil)@email = email@current_user = current_user@current_store = current_store || Spree::Store.current+ @redirect_url = redirect_urlenddef call@@ -20,14 +21,38 @@ module Spreeendend- # publish event to trigger email delivery via subscriber- subscriber.publish_event('newsletter_subscriber.subscribed') unless subscriber.verified?+ publish_subscription_events unless subscriber.verified?subscriberendprivate- attr_reader :email, :current_user, :current_store+ attr_reader :email, :current_user, :current_store, :redirect_url++ def publish_subscription_events+ subscriber.publish_event(+ 'newsletter_subscriber.subscription_requested',+ subscription_requested_payload+ )++ # Legacy lifecycle event — kept for the bundled Spree::NewsletterMailer+ # subscriber. Headless storefronts should listen to+ # `newsletter_subscriber.subscription_requested` instead since it carries+ # the verification_token and validated redirect_url.+ subscriber.publish_event('newsletter_subscriber.subscribed')+ end++ def subscription_requested_payload+ payload = {+ id: subscriber.prefixed_id,+ email: subscriber.email,+ verification_token: subscriber.verification_token,+ store_id: subscriber.store&.prefixed_id,+ customer_id: subscriber.user&.prefixed_id+ }+ payload[:redirect_url] = redirect_url if redirect_url.present?+ payload+ enddef upsert_subscriber@upsert_subscriber ||= Spree::NewsletterSubscriber.find_or_create_by(email: email, store: current_store) do |new_record|diff --git a/spree/core/spec/models/spree/newsletter_subscriber_spec.rb b/spree/core/spec/models/spree/newsletter_subscriber_spec.rbindex 803dcfd033..ba7d7f41b2 100644--- a/spree/core/spec/models/spree/newsletter_subscriber_spec.rb+++ b/spree/core/spec/models/spree/newsletter_subscriber_spec.rb@@ -73,7 +73,7 @@ describe Spree::NewsletterSubscriber, type: :model, newsletter: true dolet(:store) { create(:store) }before do- allow(Spree::Newsletter::Subscribe).to receive(:new).with(email: email, current_user: user, current_store: store).and_return(subscribe_service)+ allow(Spree::Newsletter::Subscribe).to receive(:new).with(email: email, current_user: user, current_store: store, redirect_url: nil).and_return(subscribe_service)endit 'calls subscribe service' do@@ -90,7 +90,7 @@ describe Spree::NewsletterSubscriber, type: :model, newsletter: true dobefore doallow(Spree::Current).to receive(:store).and_return(current_store)- allow(Spree::Newsletter::Subscribe).to receive(:new).with(email: email, current_user: nil, current_store: current_store).and_return(subscribe_service)+ allow(Spree::Newsletter::Subscribe).to receive(:new).with(email: email, current_user: nil, current_store: current_store, redirect_url: nil).and_return(subscribe_service)endit 'calls subscribe service' dodiff --git a/spree/core/spec/services/spree/newsletter/subscribe_spec.rb b/spree/core/spec/services/spree/newsletter/subscribe_spec.rbindex c1a12659ed..f853239e91 100644--- a/spree/core/spec/services/spree/newsletter/subscribe_spec.rb+++ b/spree/core/spec/services/spree/newsletter/subscribe_spec.rb@@ -8,13 +8,15 @@ module Spree{email: email,current_user: user,- current_store: store+ current_store: store,+ redirect_url: redirect_url}endlet(:email) { '[email protected]' }let(:user) { nil }let(:store) { nil }+ let(:redirect_url) { nil }let(:default_store) { @default_store || create(:store) }before do@@ -28,7 +30,8 @@ module Spreeexpect(service.errors).to be_presentend- it 'does not send a confirmation email' do+ it 'does not publish any subscription events' do+ expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscription_requested', anything)expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscribed')service@@ -47,8 +50,8 @@ module Spreeexpect(service).to be_a(NewsletterSubscriber)end- it 'does not send a confirmation email' do- expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscribed')+ it 'does not publish subscription_requested (auto-verified)' do+ expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscription_requested', anything)serviceend@@ -62,8 +65,23 @@ module Spreelet(:user) { create(:user) }let(:email) { '[email protected]' }- it 'sends a confirmation email' do- expect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscribed').once+ it 'publishes subscription_requested with the verification token' do+ published = nil+ allow_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event) do |sub, name, payload = nil|+ published = { name: name, payload: payload } if name == 'newsletter_subscriber.subscription_requested'+ end++ service++ expect(published).to be_present+ expect(published[:payload][:email]).to eq('[email protected]')+ expect(published[:payload][:verification_token]).to be_present+ expect(published[:payload]).not_to have_key(:redirect_url)+ end++ it 'also publishes the legacy subscribed lifecycle event' do+ expect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscription_requested', anything)+ expect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscribed')serviceend@@ -77,6 +95,21 @@ module Spreeendend+ context 'when a redirect_url is provided' do+ let(:redirect_url) { 'https://storefront.example.com/newsletter/confirm' }++ it 'forwards redirect_url in the subscription_requested payload' do+ published = nil+ allow_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event) do |sub, name, payload = nil|+ published = payload if name == 'newsletter_subscriber.subscription_requested'+ end++ service++ expect(published[:redirect_url]).to eq(redirect_url)+ end+ end+context 'when verified subscription already exists' dolet!(:subscriber) { create(:newsletter_subscriber, :verified, email: email, store: default_store) }@@ -88,7 +121,8 @@ module Spreeexpect { service }.not_to change(Spree::NewsletterSubscriber, :count)end- it 'does not send a confirmation email' do+ it 'does not publish any subscription events' do+ expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscription_requested', anything)expect_any_instance_of(Spree::NewsletterSubscriber).not_to receive(:publish_event).with('newsletter_subscriber.subscribed')service@@ -106,7 +140,8 @@ module Spreeexpect { service }.not_to change(Spree::NewsletterSubscriber, :count)end- it 'sends a confirmation email' do+ it 'publishes the subscription_requested event so the email is re-dispatched' do+ expect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscription_requested', anything).onceexpect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscribed').onceservicediff --git a/spree/emails/app/mailers/spree/newsletter_mailer.rb b/spree/emails/app/mailers/spree/newsletter_mailer.rbindex a1add9156b..3fc955765f 100644--- a/spree/emails/app/mailers/spree/newsletter_mailer.rb+++ b/spree/emails/app/mailers/spree/newsletter_mailer.rb@@ -1,10 +1,22 @@module Spreeclass NewsletterMailer < BaseMailer- def email_confirmation(subscriber)+ # @param subscriber [Spree::NewsletterSubscriber]+ # @param redirect_url [String, nil] Storefront page that handles the verification token.+ # When provided, the link is built as `<redirect_url>?token=<verification_token>`.+ # Falls back to `<store.storefront_url>/?token=<verification_token>` for legacy setups.+ def email_confirmation(subscriber, redirect_url: nil)@subscriber = subscriberstore = subscriber.store || Spree::Current.store || Spree::Store.default- @confirm_email_url = spree.verify_newsletter_subscribers_url(token: @subscriber.verification_token, host: store.storefront_url)+ base_url = redirect_url.presence || store.storefront_url+ @confirm_email_url = append_token(base_url, @subscriber.verification_token)mail(to: @subscriber.email, from: from_address, subject: Spree.t('newsletter_mailer.email_confirmation.subject'))end++ private++ def append_token(url, token)+ separator = url.include?('?') ? '&' : '?'+ "#{url}#{separator}token=#{CGI.escape(token.to_s)}"+ endendenddiff --git a/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rb b/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rbindex efee60c26b..4ddedc5f0b 100644--- a/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rb+++ b/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rb@@ -2,7 +2,11 @@module Spreeclass NewsletterSubscriberEmailSubscriber < Spree::Subscriber- subscribes_to 'newsletter_subscriber.subscribed'+ # Listens to the `subscription_requested` event because that's where the+ # validated storefront `redirect_url` is carried. The mailer needs that URL+ # (or falls back to `store.storefront_url`) to build a verification link+ # that actually points to the storefront's confirmation page.+ subscribes_to 'newsletter_subscriber.subscription_requested'def handle(event)subscriber = find_subscriber(event)@@ -12,7 +16,7 @@ module Spreestore = subscriber.store || Spree::Current.store || Spree::Store.defaultreturn unless store.prefers_send_consumer_transactional_emails?- NewsletterMailer.email_confirmation(subscriber).deliver_later+ NewsletterMailer.email_confirmation(subscriber, redirect_url: event.payload['redirect_url']).deliver_laterendprivatediff --git a/spree/emails/spec/mailers/spree/newsletter_mailer_spec.rb b/spree/emails/spec/mailers/spree/newsletter_mailer_spec.rbnew file mode 100644index 0000000000..9bd87d7ac1--- /dev/null+++ b/spree/emails/spec/mailers/spree/newsletter_mailer_spec.rb@@ -0,0 +1,37 @@+require 'spec_helper'++describe Spree::NewsletterMailer, type: :mailer do+ let(:store) { @default_store }+ let(:subscriber) { create(:newsletter_subscriber, :unverified, email: '[email protected]', store: store) }++ describe '#email_confirmation' do+ context 'when a redirect_url is provided' do+ it 'builds the confirmation link from the redirect URL with the verification token appended' do+ message = described_class.email_confirmation(subscriber, redirect_url: 'https://storefront.example.com/newsletter/confirm')++ expect(message.body.encoded).to include("https://storefront.example.com/newsletter/confirm?token=#{subscriber.verification_token}")+ end++ it 'merges the token into an existing query string instead of appending a new one' do+ message = described_class.email_confirmation(subscriber, redirect_url: 'https://storefront.example.com/newsletter/confirm?source=footer')++ expect(message.body.encoded).to include("https://storefront.example.com/newsletter/confirm?source=footer&token=#{subscriber.verification_token}")+ end+ end++ context 'when no redirect_url is provided' do+ it 'falls back to the store storefront URL' do+ message = described_class.email_confirmation(subscriber)++ expect(message.body.encoded).to include(store.storefront_url.to_s)+ expect(message.body.encoded).to include("token=#{subscriber.verification_token}")+ end+ end++ it 'sends the email to the subscriber' do+ message = described_class.email_confirmation(subscriber)++ expect(message.to).to eq([subscriber.email])+ end+ end+enddiff --git a/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rb b/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rbindex a82273ef76..f6a908bde7 100644--- a/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rb+++ b/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rb@@ -7,21 +7,31 @@ RSpec.describe Spree::NewsletterSubscriberEmailSubscriber dolet(:newsletter_subscriber) { create(:newsletter_subscriber, store: store) }let(:subscriber) { described_class.new }- def mock_event(newsletter_subscriber)- double('Event', payload: { 'id' => newsletter_subscriber.prefixed_id })+ def mock_event(newsletter_subscriber, redirect_url: nil)+ payload = { 'id' => newsletter_subscriber.prefixed_id }+ payload['redirect_url'] = redirect_url if redirect_url+ double('Event', payload: payload)endbefore dostore.update!(preferences: store.preferences.merge(send_consumer_transactional_emails: true))end- describe 'newsletter_subscriber.subscribed event' do- it 'sends email confirmation' do- expect(Spree::NewsletterMailer).to receive(:email_confirmation).with(newsletter_subscriber).and_return(double(deliver_later: true))+ describe 'newsletter_subscriber.subscription_requested event' do+ it 'sends email confirmation without a redirect URL when none is provided' do+ expect(Spree::NewsletterMailer).to receive(:email_confirmation).with(newsletter_subscriber, redirect_url: nil).and_return(double(deliver_later: true))subscriber.handle(mock_event(newsletter_subscriber))end+ it 'forwards the redirect URL from the event payload' do+ expect(Spree::NewsletterMailer).to receive(:email_confirmation).+ with(newsletter_subscriber, redirect_url: 'https://storefront.example.com/newsletter/confirm').+ and_return(double(deliver_later: true))++ subscriber.handle(mock_event(newsletter_subscriber, redirect_url: 'https://storefront.example.com/newsletter/confirm'))+ end+context 'when subscriber is already verified' dolet(:newsletter_subscriber) { create(:newsletter_subscriber, :verified) }