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.

Add Store API support for Newsletter Subscribers

Damian Legawiece767f1a9c5c8
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 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: BzLiMBEy42daj8QzPgfdN7VR
user:
id: cus_UkLWZg9DAJ
- first_name: Carrie
- last_name: Metz
+ first_name: Muriel
+ last_name: Rolfson
phone:
accepts_email_marketing: false
- full_name: Carrie Metz
+ full_name: Muriel Rolfson
available_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: ATUxJ8cznsCRdeM94bt6MpFb
user:
id: cus_UkLWZg9DAJ
- first_name: Abram
- last_name: Trantow
+ first_name: Yoshiko
+ last_name: Gerlach
phone:
accepts_email_marketing: false
- full_name: Abram Trantow
+ full_name: Yoshiko Gerlach
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -845,9 +845,9 @@ paths:
data:
- id: cart_gbHJdmfrXB
market_id:
- number: R139181277
- token: HcVHbgtZJ4WxxcynuTKt6p79iQNAxukuSNX
+ number: R664489317
+ token: DNbsRBmEum7pEjvQP1kQfL82Sa9dpamPvNH
customer_note:
currency: USD
locale: en
@@ -889,8 +889,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 583630
- slug: product-583630
+ name: Product 583769
+ slug: product-583769
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -915,7 +915,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H38066716360
+ number: H67163565781
tracking: U10000
tracking_url:
cost: '100.0'
@@ -944,7 +944,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Winfred Dietrich
+ name: Ilona Raynor
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1014,9 +1014,9 @@ paths:
market:
- id: cart_UkLWZg9DAJ
market_id:
- number: R653240222
- token: Lta26Lyfq4EtwsMwD1kt4az1XZLr14fQKqn
+ number: R608295263
+ token: hPKQmwQsRPWzchLyF6W66k6tmz7FDgywVra
customer_note:
currency: USD
locale: en
@@ -1058,8 +1058,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 574608
- slug: product-574608
+ name: Product 571600
+ slug: product-571600
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1084,7 +1084,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H27683996067
+ number: H06444123777
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1113,7 +1113,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Winfred Dietrich
+ name: Ilona Raynor
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1256,8 +1256,8 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R175749722
- token: rrsVnbxwLVc2KkMntz2RqPaKhfxtDk4AaQx
+ number: R614354862
+ token: GFVVFvrWYoqA1u1YH7pVUxznA9FVYYYN16i
email:
customer_note:
currency: USD
@@ -1412,9 +1412,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R662034436
- token: utvMuyjqh2mMd74g3NcvfyCvJVMPqYSZ9At
+ number: R391007411
+ token: TJQaoQquys2FEa6bQAQG6UNsTbugSQWxvu9
customer_note:
currency: USD
locale: 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 out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
store_credit_total: '0.0'
@@ -1583,9 +1583,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R973162333
- token: QPDkdD3JJT4D25jB8dadWYfyrSxvWpPXnp1
+ number: R819048584
+ token: 2fF1kfwXemRtwo39BV6ZNNQHG29ThFThfx7
customer_note: Leave at door
currency: USD
locale: en
@@ -1629,8 +1629,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 631959
- slug: product-631959
+ name: Product 639240
+ slug: product-639240
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -1655,7 +1655,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H29882311098
+ number: H40312398138
tracking:
tracking_url:
cost: '10.0'
@@ -1684,7 +1684,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Casimira Emmerich
+ name: Adella Kris
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1921,9 +1921,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R252978915
- token: 4Lii2eNk6MZSo8FLKpBmUXXTHLTNdTLfAC8
+ number: R632083010
+ token: Hud7FDknGoibTteuPcBENinKizai8DriaWj
customer_note:
currency: USD
locale: en
@@ -1965,8 +1965,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 659809
- slug: product-659809
+ name: Product 659069
+ slug: product-659069
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1991,7 +1991,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H28360472279
+ number: H50751149271
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2020,7 +2020,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Meryl Kohler
+ name: Aurelia McGlynn
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2155,8 +2155,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R923625339
+ number: R775225129
customer_note:
currency: USD
locale: en
@@ -2183,7 +2183,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 676533
- slug: product-676533
+ name: Product 677597
+ slug: product-677597
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2219,7 +2219,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H91422323884
+ number: H07213205217
tracking:
tracking_url:
cost: '10.0'
@@ -2248,7 +2248,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Catharine Cronin
+ name: Phylis Kozey
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2277,8 +2277,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-9ccf88928ac4
- number: PRCUU49P
+ response_code: BGS-d9218ca0c082
+ number: P6TGTMWL
amount: '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: rUy5d5FkkFKRKVTjSNLMmGXC
user:
id: cus_UkLWZg9DAJ
- first_name: Jamal
- last_name: Berge
+ first_name: Iris
+ last_name: Hirthe
phone:
accepts_email_marketing: false
- full_name: Jamal Berge
+ full_name: Iris Hirthe
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -3316,8 +3316,8 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R531767804
+ number: R453573119
customer_note:
currency: USD
locale: 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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 764134
- slug: product-764134
+ name: Product 763572
+ slug: product-763572
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3380,7 +3380,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H30074853996
+ number: H92480409501
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3409,7 +3409,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Sebrina Hermann
+ name: Aleen Powlowski
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3572,8 +3572,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R928393368
+ number: R788321337
customer_note:
currency: USD
locale: 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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 783776
- slug: product-783776
+ name: Product 78558
+ slug: product-78558
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3636,7 +3636,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H92068676734
+ number: H85969598405
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3665,7 +3665,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Shiela Romaguera
+ name: Ruthe Davis
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '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: Zm5W1wfivD9a8J1WsaKiBAyc
user:
id: cus_UkLWZg9DAJ
@@ -3900,12 +3900,12 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Rebekah
- last_name: Dickinson
+ first_name: Jacinta
+ last_name: Lang
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Rebekah Dickinson
+ full_name: Jacinta Lang
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -4039,7 +4039,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -4279,9 +4279,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R944275414
- token: msg6sEmFpE3ouDVpMU1EdLZ3yeuJieR5aTS
+ number: R877670295
+ token: jgYbDf4iuvRHVAFiJSJPC67pctiy9JX6pm3
customer_note:
currency: USD
locale: en
@@ -4330,8 +4330,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 864988
- slug: product-864988
+ name: Product 866689
+ slug: product-866689
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4356,7 +4356,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H39326999271
+ number: H97941431341
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4385,7 +4385,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Darin Nolan
+ name: Delora Kerluke
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4539,9 +4539,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R847897368
- token: o5ZBcbm28ynKSmisZKNn4S6uSzQQ29V4LzP
+ number: R645855426
+ token: xKbwRLgMS3z13qkQ8U9pN6NYL6ofcQ9GHZ7
customer_note:
currency: USD
locale: en
@@ -4583,8 +4583,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 884521
- slug: product-884521
+ name: Product 885251
+ slug: product-885251
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4609,7 +4609,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H45597673137
+ number: H21042794370
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4638,7 +4638,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Angelita Hirthe
+ name: Meri O'Hara
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4781,9 +4781,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R776312936
- token: PZxhxWxQUUeUfBPNAWtA84T3wj4VSjgDAuX
+ number: R735538070
+ token: pJmy9PSsevBtccAFgssJj5xxWh7Zx2avpvg
customer_note:
currency: USD
locale: en
@@ -4827,8 +4827,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 902074
- slug: product-902074
+ name: Product 90269
+ slug: product-90269
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4853,7 +4853,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H84960578003
+ number: H61990909745
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4882,7 +4882,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Marcella Gleason
+ name: Gianna Prosacco
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5039,9 +5039,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R477575561
- token: XmsrQSMW1GjTQXoR84zjmPkRKDBu9wPohGR
+ number: R786565483
+ token: rPCVCzH2MAhdyzFpsLwftnwAWtyVzCAuH5j
customer_note:
currency: USD
locale: en
@@ -5080,8 +5080,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 928799
- slug: product-928799
+ name: Product 924064
+ slug: product-924064
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5106,7 +5106,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H17569959219
+ number: H72899618600
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5135,7 +5135,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Cherilyn Rohan
+ name: Hoa Abshire
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5164,8 +5164,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260513222659480328
- number: PJICQI95
+ response_code: 1-SC-20260521140122745447
+ number: PKDTTE1C
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -5344,9 +5344,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R763170613
- token: jazQ6BN13e6FaHWeFZZtsY3SWiJbYmT32Vs
+ number: R305341957
+ token: cYad5ZEwRxucQSrUZeYvDNJJeNzFMkpais6
customer_note:
currency: USD
locale: en
@@ -5388,8 +5388,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 969841
- slug: product-969841
+ name: Product 967644
+ slug: product-967644
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5414,7 +5414,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H66513225741
+ number: H87527277081
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5443,7 +5443,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Alona Lebsack
+ name: Marget Carter
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5472,8 +5472,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260513222702020297
- number: PRSNCO99
+ response_code: 1-SC-20260521140125170061
+ number: P247ASB1
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -5597,7 +5597,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 35825F9FC9C04D3E
+ code: 5F5907332CD24C13
status: active
currency: USD
amount: '10.0'
@@ -5693,7 +5693,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 3B095595FD9C8DF0
+ code: E7D8EEDBD8B38629
status: active
currency: USD
amount: '10.0'
@@ -5784,9 +5784,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R218798477
- token: FDVh29CghDceRzZhTTRHQcH6RzwtaYu7ZoM
+ number: R898038455
+ token: kwoDUG5ytVevnyteMSLq11LFUoUeQvgvj3C
customer_note:
currency: USD
locale: en
@@ -5834,8 +5834,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 994255
- slug: product-994255
+ name: Product 998774
+ slug: product-998774
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5862,8 +5862,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 1004709
- slug: product-1004709
+ name: Product 1007565
+ slug: product-1007565
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -6006,9 +6006,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R208536174
- token: sPa7oQxwwRHBBMxMdgeELoGPVNup8VFHhKf
+ number: R361093646
+ token: ANzLKaHuynyv78jwmNXN17TGQvYaPbpDZpf
customer_note:
currency: USD
locale: en
@@ -6053,8 +6053,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1035511
- slug: product-1035511
+ name: Product 1032574
+ slug: product-1032574
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6177,9 +6177,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R450595189
- token: egYzsmtmVmA8p8CnZuYJY5xCqPqCXyjvcP2
+ number: R782177832
+ token: 3qTD9CqYFu8if2zPw9fjYJT6bcLLBXgqdkB
customer_note:
currency: USD
locale: en
@@ -6709,6 +6709,182 @@ paths:
message: Country not found
schema:
"$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
+ 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
+ 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:
+ - email
+ "/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
+ 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_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R197640310
+ number: R219546930
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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1079923
- slug: product-1079923
+ name: Product 1078893
+ slug: product-1078893
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6845,7 +7021,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H69918660946
+ number: H66784286474
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6874,7 +7050,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Lasandra Parker
+ name: Naida Boyer
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6906,7 +7082,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 258 Lovely Street
+ address1: 260 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6925,7 +7101,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 259 Lovely Street
+ address1: 261 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7019,9 +7195,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_9a4fd867e33eda3a85f7af87
+ external_id: bogus_a17b47e0398d13f0b001d373
external_data:
- client_secret: bogus_secret_15971e84c2d8ac80
+ client_secret: bogus_secret_5dec9b38272306eb
customer_external_id:
expires_at:
amount: '110.0'
@@ -7119,7 +7295,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_3683ac1ff6e691f3adbfb2ec
+ external_id: bogus_9d936b37603e2d2e9f882ba5
external_data:
client_secret: secret_123
customer_external_id:
@@ -7181,7 +7357,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_9107f7f0c69399f6d227c22c
+ external_id: bogus_62a32b13abfdf70ffe97ebfe
external_data:
client_secret: secret_123
customer_external_id:
@@ -7283,7 +7459,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_16f2990e33899eaa9093a63f
+ external_id: bogus_690fbde1d19bee42865caa8f
external_data:
client_secret: secret_123
customer_external_id:
@@ -7368,8 +7544,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_b86e791bebf1f51c2f249647
- external_client_secret: bogus_seti_secret_21e471b276d8a28b
+ external_id: bogus_seti_c30c9b5f22811f96e01ae78e
+ external_client_secret: bogus_seti_secret_4c73525f5d30ff33
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7468,8 +7644,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_bd7e3c37db41dadfdd3ded55
- external_client_secret: seti_secret_668be0e627f0b82a32113dd8
+ external_id: seti_test_d7fa0cbdbc9e070360f09d67
+ external_client_secret: seti_secret_890b28449262f42d588f7226
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7545,8 +7721,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_88c1489315b6c12dd3f35176
- external_client_secret: seti_secret_a4e461ece2ef965cf95ab200
+ external_id: seti_test_0deba6c34d39f196388036e2
+ external_client_secret: seti_secret_c8e8baf1be390bcebea53f33
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7640,7 +7816,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: PREKGE98
+ number: P8EAYC6L
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -7736,7 +7912,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-05ad8a43-341b-4283-b2b3-42a1597d4c3f
+ slug: privacy-policy-e33e52be-144d-4d70-99a2-978929d3c22a
body: 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-1173606
meta_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: true
in_stock: false
backorderable: 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-1189963
meta_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: true
in_stock: false
backorderable: true
available: 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_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -8131,13 +8308,13 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1453907
- slug: product-1453907
+ name: Product 1451391
+ slug: product-1451391
meta_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: true
in_stock: false
backorderable: true
@@ -8164,7 +8341,7 @@ paths:
amount_in_cents: 999
currency: USD
display_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_UkLWZg9DAJ
market_id:
- number: R001729941
- token: W5ynafzKqDZLvj1bsDGYkxVU9XfM54fj2TU
+ number: R744140023
+ token: pTFm3XRZudeeoLXmviqWz6uNkVtaBp4uLrV
customer_note:
currency: USD
locale: en
@@ -8580,8 +8757,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1655543
- slug: product-1655543
+ name: Product 1658176
+ slug: product-1658176
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8606,7 +8783,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H55534597898
+ number: H59588366435
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8635,7 +8812,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Natalie Lind
+ name: Veta Mitchell
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -8664,8 +8841,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260513222727628021
- number: PZL9IN69
+ response_code: 1-SC-20260521140150066371
+ number: PEHXTQG6
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -8692,7 +8869,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 322 Lovely Street
+ address1: 324 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8711,7 +8888,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 323 Lovely Street
+ address1: 325 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8808,9 +8985,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R023022648
- token: k1F6SZ5iqCV1Vu88Ywos6XpvwkPwy1ARPt6
+ number: R244936382
+ token: Ycdv7VgR4x426YxWUz7eoyGEFZ1sRY4SpaC
customer_note:
currency: USD
locale: en
@@ -8852,8 +9029,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1672629
- slug: product-1672629
+ name: Product 1673068
+ slug: product-1673068
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -8878,7 +9055,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H15373018353
+ number: H49623074593
tracking: U10000
tracking_url:
cost: '100.0'
@@ -8907,7 +9084,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Linsey Grant
+ name: Grady Pacocha
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -8939,7 +9116,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 330 Lovely Street
+ address1: 332 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8958,7 +9135,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 331 Lovely Street
+ address1: 333 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9037,7 +9214,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: pNUefpiorWppH4tuM9RHiv38
+ token: QL7gtUL5AUfgexgDh9iQFWaA
is_default: false
is_private: true
meta:
@@ -9113,7 +9290,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: bQSKNBBhCXtHWSoDUJahXA69
+ token: zmk9bk8qkYJRXzjhxhYRV1Gg
is_default: false
is_private: true
schema:
@@ -9209,7 +9386,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: cst3bHUPsMnW4TqL1P89krGH
+ token: FjFxxfkdRu9GRLaAmWerHsP1
is_default: false
is_private: true
schema:
@@ -9271,7 +9448,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: NUaszyr9oB7MvNSvd2Ri7qHf
+ token: zTCwhxBSEZYoDbdjgF57VnYE
is_default: false
is_private: true
schema:
@@ -9500,6 +9677,8 @@ tags:
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
@@ -9526,6 +9705,9 @@ x-tagGroups:
- name: Wishlists
tags:
- Wishlists
+- name: Newsletter Subscribers
+ tags:
+ - Newsletter Subscribers
- name: Policies
tags:
- Policies
diff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdx
index 39f71a3935..ede29cb9bc 100644
--- a/docs/developer/core-concepts/customers.mdx
+++ b/docs/developer/core-concepts/customers.mdx
@@ -3,6 +3,8 @@ title: Customers
description: Customer accounts — registration, authentication, profiles, and guest checkout
---
+import { Since } from '/snippets/since.mdx';
+
## Overview
Customers 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/RES
On 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.mdx
index 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 Rese
1. **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 Frameworks
diff --git a/docs/developer/storefront/nextjs/customization.mdx b/docs/developer/storefront/nextjs/customization.mdx
index 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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 profile
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index 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.ts
new file mode 100644
index 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.rb
index 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 Spree
def custom_webhook_events
%w[
customer.password_reset_requested
+ newsletter_subscriber.subscription_requested
order.completed
order.paid
order.canceled
diff --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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/config/locales/en.yml b/spree/api/config/locales/en.yml
index 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.rb
index 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
# Customers
resources :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' do
get '/', 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rb
index 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.rb
index 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 Spree
Spree::CSV::NewsletterSubscriberPresenter.new(self).call
end
- 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
+ ).call
end
def self.verify(token:)
diff --git a/spree/core/app/services/spree/newsletter/subscribe.rb b/spree/core/app/services/spree/newsletter/subscribe.rb
index 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 Spree
module Newsletter
class 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_url
end
def call
@@ -20,14 +21,38 @@ module Spree
end
end
- # publish event to trigger email delivery via subscriber
- subscriber.publish_event('newsletter_subscriber.subscribed') unless subscriber.verified?
+ publish_subscription_events unless subscriber.verified?
subscriber
end
private
- 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
+ end
def 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.rb
index 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 do
let(: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)
end
it 'calls subscribe service' do
@@ -90,7 +90,7 @@ describe Spree::NewsletterSubscriber, type: :model, newsletter: true do
before do
allow(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)
end
it 'calls subscribe service' do
diff --git a/spree/core/spec/services/spree/newsletter/subscribe_spec.rb b/spree/core/spec/services/spree/newsletter/subscribe_spec.rb
index 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
}
end
let(: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 Spree
expect(service.errors).to be_present
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
@@ -47,8 +50,8 @@ module Spree
expect(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)
service
end
@@ -62,8 +65,23 @@ module Spree
let(: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')
service
end
@@ -77,6 +95,21 @@ module Spree
end
end
+ 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' do
let!(:subscriber) { create(:newsletter_subscriber, :verified, email: email, store: default_store) }
@@ -88,7 +121,8 @@ module Spree
expect { 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 Spree
expect { 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).once
expect_any_instance_of(Spree::NewsletterSubscriber).to receive(:publish_event).with('newsletter_subscriber.subscribed').once
service
diff --git a/spree/emails/app/mailers/spree/newsletter_mailer.rb b/spree/emails/app/mailers/spree/newsletter_mailer.rb
index 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 Spree
class 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 = subscriber
store = 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)}"
+ end
end
end
diff --git a/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rb b/spree/emails/app/subscribers/spree/newsletter_subscriber_email_subscriber.rb
index 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 Spree
class 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 Spree
store = subscriber.store || Spree::Current.store || Spree::Store.default
return unless store.prefers_send_consumer_transactional_emails?
- NewsletterMailer.email_confirmation(subscriber).deliver_later
+ NewsletterMailer.email_confirmation(subscriber, redirect_url: event.payload['redirect_url']).deliver_later
end
private
diff --git a/spree/emails/spec/mailers/spree/newsletter_mailer_spec.rb b/spree/emails/spec/mailers/spree/newsletter_mailer_spec.rb
new file mode 100644
index 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&amp;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
+end
diff --git a/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rb b/spree/emails/spec/subscribers/spree/newsletter_subscriber_email_subscriber_spec.rb
index 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 do
let(: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)
end
before do
store.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' do
let(:newsletter_subscriber) { create(:newsletter_subscriber, :verified) }