@spree/docs 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -0
- package/dist/api-reference/platform/authentication.md +38 -0
- package/dist/api-reference/store-api/authentication.md +188 -0
- package/dist/api-reference/store-api/errors.md +277 -0
- package/dist/api-reference/store-api/idempotency.md +129 -0
- package/dist/api-reference/store-api/introduction.md +34 -0
- package/dist/api-reference/store-api/localization.md +279 -0
- package/dist/api-reference/store-api/metadata.md +160 -0
- package/dist/api-reference/store-api/monetary-amounts.md +65 -0
- package/dist/api-reference/store-api/querying.md +399 -0
- package/dist/api-reference/store-api/rate-limitting.md +103 -0
- package/dist/api-reference/store-api/relations.md +185 -0
- package/dist/api-reference/storefront/authentication.md +88 -0
- package/dist/api-reference/tutorials/adyen-integration-guide-for-android.md +165 -0
- package/dist/api-reference/tutorials/adyen-integration-guide-for-ios.md +194 -0
- package/dist/api-reference/tutorials/quick-checkout-with-stripe.md +248 -0
- package/dist/api-reference/v2/fetching-multiple-resources.md +26 -0
- package/dist/api-reference/v2/filtering-and-sorting.md +53 -0
- package/dist/api-reference/v2/introduction.md +22 -0
- package/dist/api-reference/v2/pagination.md +37 -0
- package/dist/api-reference/webhooks-events.md +883 -0
- package/dist/developer/admin/admin.md +205 -0
- package/dist/developer/admin/authentication.md +59 -0
- package/dist/developer/admin/components.md +711 -0
- package/dist/developer/admin/custom-css.md +243 -0
- package/dist/developer/admin/custom-javascript.md +116 -0
- package/dist/developer/admin/extending-ui.md +1964 -0
- package/dist/developer/admin/form-builder.md +444 -0
- package/dist/developer/admin/helper-methods.md +531 -0
- package/dist/developer/admin/navigation.md +805 -0
- package/dist/developer/admin/tables.md +491 -0
- package/dist/developer/advanced/adding_spree_to_rails_app.md +106 -0
- package/dist/developer/cli/quickstart.md +137 -0
- package/dist/developer/contributing/creating-an-extension.md +258 -0
- package/dist/developer/contributing/developing-spree.md +339 -0
- package/dist/developer/contributing/quickstart.md +32 -0
- package/dist/developer/contributing/updating-extensions.md +67 -0
- package/dist/developer/core-concepts/addresses.md +265 -0
- package/dist/developer/core-concepts/adjustments.md +107 -0
- package/dist/developer/core-concepts/architecture.md +177 -0
- package/dist/developer/core-concepts/calculators.md +323 -0
- package/dist/developer/core-concepts/customers.md +230 -0
- package/dist/developer/core-concepts/events.md +624 -0
- package/dist/developer/core-concepts/imports-exports.md +698 -0
- package/dist/developer/core-concepts/inventory.md +191 -0
- package/dist/developer/core-concepts/markets.md +250 -0
- package/dist/developer/core-concepts/media.md +167 -0
- package/dist/developer/core-concepts/metafields.md +187 -0
- package/dist/developer/core-concepts/orders.md +328 -0
- package/dist/developer/core-concepts/payments.md +710 -0
- package/dist/developer/core-concepts/pricing.md +163 -0
- package/dist/developer/core-concepts/products.md +360 -0
- package/dist/developer/core-concepts/promotions.md +322 -0
- package/dist/developer/core-concepts/reports.md +206 -0
- package/dist/developer/core-concepts/search-filtering.md +237 -0
- package/dist/developer/core-concepts/shipments.md +212 -0
- package/dist/developer/core-concepts/slugs.md +111 -0
- package/dist/developer/core-concepts/staff-roles.md +123 -0
- package/dist/developer/core-concepts/store-credits-gift-cards.md +317 -0
- package/dist/developer/core-concepts/stores.md +117 -0
- package/dist/developer/core-concepts/taxes.md +135 -0
- package/dist/developer/core-concepts/translations.md +120 -0
- package/dist/developer/core-concepts/users.md +299 -0
- package/dist/developer/core-concepts/webhooks.md +378 -0
- package/dist/developer/create-spree-app/quickstart.md +158 -0
- package/dist/developer/customization/api.md +93 -0
- package/dist/developer/customization/authentication.md +88 -0
- package/dist/developer/customization/checkout.md +204 -0
- package/dist/developer/customization/configuration.md +55 -0
- package/dist/developer/customization/decorators.md +523 -0
- package/dist/developer/customization/dependencies.md +232 -0
- package/dist/developer/customization/emails.md +21 -0
- package/dist/developer/customization/extensions.md +92 -0
- package/dist/developer/customization/metadata.md +236 -0
- package/dist/developer/customization/model-preferences.md +130 -0
- package/dist/developer/customization/permissions.md +265 -0
- package/dist/developer/customization/quickstart.md +229 -0
- package/dist/developer/customization/routes.md +24 -0
- package/dist/developer/customization/v4/admin-panel.md +78 -0
- package/dist/developer/customization/v4/authentication.md +210 -0
- package/dist/developer/customization/v4/checkout.md +212 -0
- package/dist/developer/customization/v4/deface.md +251 -0
- package/dist/developer/customization/v4/images.md +86 -0
- package/dist/developer/customization/v4/storefront.md +450 -0
- package/dist/developer/deployment/assets.md +87 -0
- package/dist/developer/deployment/aws.md +335 -0
- package/dist/developer/deployment/caching.md +27 -0
- package/dist/developer/deployment/cdn.md +39 -0
- package/dist/developer/deployment/database.md +155 -0
- package/dist/developer/deployment/docker.md +128 -0
- package/dist/developer/deployment/emails.md +77 -0
- package/dist/developer/deployment/environment_variables.md +111 -0
- package/dist/developer/deployment/heroku.md +51 -0
- package/dist/developer/deployment/render.md +95 -0
- package/dist/developer/getting-started/quickstart.md +82 -0
- package/dist/developer/how-to/custom-payment-method.md +374 -0
- package/dist/developer/how-to/custom-promotion.md +373 -0
- package/dist/developer/how-to/custom-report.md +387 -0
- package/dist/developer/how-to/custom-search-provider.md +230 -0
- package/dist/developer/multi-store/quickstart.md +71 -0
- package/dist/developer/multi-store/setup.md +38 -0
- package/dist/developer/multi-tenant/configuration.md +41 -0
- package/dist/developer/multi-tenant/core-concepts.md +75 -0
- package/dist/developer/multi-tenant/installation.md +96 -0
- package/dist/developer/multi-tenant/quickstart.md +20 -0
- package/dist/developer/multi-vendor/installation.md +45 -0
- package/dist/developer/multi-vendor/quickstart.md +17 -0
- package/dist/developer/sdk/admin/quickstart.md +22 -0
- package/dist/developer/sdk/authentication.md +89 -0
- package/dist/developer/sdk/configuration.md +225 -0
- package/dist/developer/sdk/quickstart.md +82 -0
- package/dist/developer/sdk/store/account.md +67 -0
- package/dist/developer/sdk/store/cart-checkout.md +140 -0
- package/dist/developer/sdk/store/markets.md +151 -0
- package/dist/developer/sdk/store/payments.md +96 -0
- package/dist/developer/sdk/store/products.md +149 -0
- package/dist/developer/sdk/store/wishlists.md +52 -0
- package/dist/developer/security/pci_compliance.md +15 -0
- package/dist/developer/security/security_policy.md +68 -0
- package/dist/developer/storefront/blocks.md +285 -0
- package/dist/developer/storefront/custom-css.md +260 -0
- package/dist/developer/storefront/custom-javascript.md +166 -0
- package/dist/developer/storefront/helper-methods.md +1288 -0
- package/dist/developer/storefront/links.md +298 -0
- package/dist/developer/storefront/nextjs/architecture.md +150 -0
- package/dist/developer/storefront/nextjs/customization.md +141 -0
- package/dist/developer/storefront/nextjs/deployment.md +180 -0
- package/dist/developer/storefront/nextjs/quickstart.md +92 -0
- package/dist/developer/storefront/nextjs/spree-next-package.md +314 -0
- package/dist/developer/storefront/pages.md +163 -0
- package/dist/developer/storefront/sections.md +569 -0
- package/dist/developer/storefront/storefront.md +56 -0
- package/dist/developer/storefront/themes.md +161 -0
- package/dist/developer/tutorial/admin.md +134 -0
- package/dist/developer/tutorial/extending-models.md +380 -0
- package/dist/developer/tutorial/file-uploads.md +121 -0
- package/dist/developer/tutorial/introduction.md +33 -0
- package/dist/developer/tutorial/model.md +41 -0
- package/dist/developer/tutorial/page-builder.md +487 -0
- package/dist/developer/tutorial/rich-text.md +73 -0
- package/dist/developer/tutorial/seo.md +332 -0
- package/dist/developer/tutorial/storefront.md +352 -0
- package/dist/developer/tutorial/testing.md +558 -0
- package/dist/developer/upgrades/2.0-to-2.1.md +46 -0
- package/dist/developer/upgrades/2.1-to-2.2.md +59 -0
- package/dist/developer/upgrades/2.2-to-2.3.md +44 -0
- package/dist/developer/upgrades/2.3-to-2.4.md +42 -0
- package/dist/developer/upgrades/3.0-to-3.1.md +47 -0
- package/dist/developer/upgrades/3.1-to-3.2.md +34 -0
- package/dist/developer/upgrades/3.2-to-3.3.md +70 -0
- package/dist/developer/upgrades/3.3-to-3.4.md +36 -0
- package/dist/developer/upgrades/3.4-to-3.5.md +44 -0
- package/dist/developer/upgrades/3.5-to-3.6.md +40 -0
- package/dist/developer/upgrades/3.6-to-3.7.md +62 -0
- package/dist/developer/upgrades/3.7-to-4.0.md +152 -0
- package/dist/developer/upgrades/4.0-to-4.1.md +92 -0
- package/dist/developer/upgrades/4.1-to-4.2.md +109 -0
- package/dist/developer/upgrades/4.10-to-5.0.md +129 -0
- package/dist/developer/upgrades/4.2-to-4.3.md +100 -0
- package/dist/developer/upgrades/4.3-to-4.4.md +125 -0
- package/dist/developer/upgrades/4.4-to-4.5.md +94 -0
- package/dist/developer/upgrades/4.5-to-4.6.md +119 -0
- package/dist/developer/upgrades/4.6-to-4.7.md +39 -0
- package/dist/developer/upgrades/4.8-to-4.9.md +24 -0
- package/dist/developer/upgrades/4.9-to-4.10.md +24 -0
- package/dist/developer/upgrades/4.x-to-4.8.md +52 -0
- package/dist/developer/upgrades/5.0-to-5.1.md +28 -0
- package/dist/developer/upgrades/5.1-to-5.2.md +127 -0
- package/dist/developer/upgrades/5.2-to-5.3.md +338 -0
- package/dist/developer/upgrades/5.3-to-5.4.md +248 -0
- package/dist/developer/upgrades/quickstart.md +36 -0
- package/dist/integrations/analytics/google-analytics.md +64 -0
- package/dist/integrations/analytics/google-tag-manager.md +78 -0
- package/dist/integrations/integrations.md +39 -0
- package/dist/integrations/marketing/klaviyo.md +99 -0
- package/dist/integrations/payments/adyen.md +90 -0
- package/dist/integrations/payments/paypal.md +41 -0
- package/dist/integrations/payments/razorpay.md +45 -0
- package/dist/integrations/payments/stripe.md +109 -0
- package/dist/integrations/search/meilisearch.md +236 -0
- package/dist/integrations/sso-mfa-social-login/admin-dashboard.md +57 -0
- package/dist/integrations/sso-mfa-social-login/storefront.md +56 -0
- package/package.json +27 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect PayPal payments to Spree Commerce"
|
|
3
|
+
sidebarTitle: PayPal
|
|
4
|
+
description: "Learn how to set up and manage Spree's native PayPal integration."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
PayPal is an online payment system that allows you to send and receive money around the world. You can link your credit card, debit card, or bank account. You can also set up a PayPal Balance account.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Before you can enable PayPal, it must be installed. To do so, you need to run the following command:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
bundle add spree_paypal_checkout && bundle exec rails g spree_paypal_checkout:install
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
After that, you need to make sure to restart the server.
|
|
18
|
+
|
|
19
|
+
## Connect PayPal
|
|
20
|
+
|
|
21
|
+
Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.
|
|
22
|
+
|
|
23
|
+

|
|
24
|
+
|
|
25
|
+
Find PayPal under Available Payment Methods and click **Add**.
|
|
26
|
+
|
|
27
|
+
This will redirect you to the PayPal setup form.
|
|
28
|
+
|
|
29
|
+

|
|
30
|
+
|
|
31
|
+
You will need Client ID and Client Secret from your [PayPal dashboard credentials page](https://www.paypal.com/mep/merchantapps/setup/checkout/apicredentials).
|
|
32
|
+
|
|
33
|
+
> **TIP:** To get your credentials, go to `Business Tools`, select `Online Checkout`, click `Get Started`, select `Have a custom-built site? -> Get Started`, `PayPal Checkout -> Get Started`.
|
|
34
|
+
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
You should see your live and sandbox credentials. Copy API key into `Client ID` and Secret into `Client Secret`.
|
|
38
|
+
|
|
39
|
+
If you wish to test the PayPal payments before going live, copy sandbox credentials and select `Test Mode` option in Spree.
|
|
40
|
+
|
|
41
|
+
Click **Create** to enable PayPal as a payment method on your store.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect Razorpay payments to Spree Commerce"
|
|
3
|
+
sidebarTitle: Razorpay
|
|
4
|
+
description: "Configuring Razorpay in Your Spree Store: A Setup & Management Walkthrough."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Razorpay is a secure payment gateway that enables businesses to accept online payments via cards, UPI, net banking, and wallets. It also supports international transactions across multiple currencies.
|
|
8
|
+
|
|
9
|
+
> **INFO:** Razorpay integration is maintained and developed by [Umesh Ravani](https://github.com/umeshravani).
|
|
10
|
+
>
|
|
11
|
+
> To support this development, please star the [GitHub repository](https://github.com/umeshravani/spree_razorpay) ❤️
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Before you can enable Razorpay, it must be installed. To do so, you need to add this line in Gemfile:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
bundle add spree_razorpay_checkout && bundle exec rails g spree_razorpay_checkout:install
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
After that, you need to make sure to restart the server.
|
|
22
|
+
|
|
23
|
+
## Connect Razorpay
|
|
24
|
+
|
|
25
|
+
Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.
|
|
26
|
+
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
Find Razorpay under Available Payment Methods and click **Add**.
|
|
30
|
+
|
|
31
|
+
This will redirect you to the Razorpay setup form.
|
|
32
|
+
|
|
33
|
+

|
|
34
|
+
|
|
35
|
+
You will need Key and Key Secret from your [Razorpay dashboard credentials page](https://dashboard.razorpay.com/app/website-app-settings/api-keys).
|
|
36
|
+
|
|
37
|
+
> **TIP:** To get your credentials, Navigate to Account & Settings → API Keys (under Website and app settings) → Generate new key to generate key for the selected mode.
|
|
38
|
+
|
|
39
|
+

|
|
40
|
+
|
|
41
|
+
You should see your live and test credentials. Copy both API key into `Key` and Secret into `Key Secret`, also Test API key into `Test Key` and Test Key Secret into `Test Key Secret`
|
|
42
|
+
|
|
43
|
+
If you wish to test the Razorpay payments before going live, just select `Test Mode` option in Spree.
|
|
44
|
+
|
|
45
|
+
Click **Create** to enable Razorpay as a payment method on your store.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect Stripe payments to Spree Commerce"
|
|
3
|
+
sidebarTitle: Stripe
|
|
4
|
+
description: "Learn how to set up and manage Spree's native Stripe integration."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Stripe is a widely used payment processor that enables secure and seamless transactions for online businesses. It supports multiple payment methods, automates payouts, and ensures a smooth checkout experience for customers.
|
|
8
|
+
|
|
9
|
+
> **TIP:** In [Spree Enterprise Edition](https://spreecommerce.org/pricing/), Stripe can also be used to power marketplace payments, enabling automated vendor payouts, split payments, and secure transaction handling.
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
Before you can enable Stripe, it must be installed. To do so, you need to run the following command:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
bundle add spree_stripe && bundle exec rails g spree_stripe:install
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
After that, you need to make sure to restart the server.
|
|
20
|
+
|
|
21
|
+
## Connect Stripe
|
|
22
|
+
|
|
23
|
+
Sign in to your Spree admin dashboard and navigate to **Settings → Payments**.
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
Find Stripe under Available Payment Methods and click **Add**.
|
|
28
|
+
|
|
29
|
+
This will redirect you to the Stripe setup form.
|
|
30
|
+
|
|
31
|
+

|
|
32
|
+
|
|
33
|
+
Simply copy and paste the **Publishable Key** and **Secret Key** from your Stripe dashboard into their respective fields and click **Create** to enable Stripe as a payment method on your store.
|
|
34
|
+
|
|
35
|
+
> **NOTE:** The **Publishable Key** and **Secret Key** can be found in the Get Started section of the Home screen in your Stripe dashboard. Alternatively, they can be found out in **Developers → API Keys**.
|
|
36
|
+
|
|
37
|
+

|
|
38
|
+
|
|
39
|
+
### Additional Settings
|
|
40
|
+
|
|
41
|
+

|
|
42
|
+
|
|
43
|
+
You can optionally configure the following settings for your Stripe payment method:
|
|
44
|
+
|
|
45
|
+
- **Name**: Customize the display name shown for this payment method on the storefront.
|
|
46
|
+
- **Display**: Choose where Stripe should be available:
|
|
47
|
+
- Storefront only
|
|
48
|
+
- Admin panel only
|
|
49
|
+
- Both (recommended)
|
|
50
|
+
- **Auto Capture**: Decide whether payments should be automatically captured at the time of authorization (recommended), or manually captured later.
|
|
51
|
+
- **Active Status**: Enable or disable the payment method. Inactive methods are hidden from checkout but not removed.
|
|
52
|
+
|
|
53
|
+
### Enable Apple Pay
|
|
54
|
+
|
|
55
|
+
To enable Apple Pay (including Apple Pay quick checkout) as a payment method, follow these steps:
|
|
56
|
+
|
|
57
|
+
1. Find ‘payment method domains’ in your Stripe dashboard
|
|
58
|
+
2. Click ‘Add new domain’ and enter your store’s domain
|
|
59
|
+
3. Click ‘Download file’ and attach it using the ‘Choose file’ button in Spree
|
|
60
|
+
4. Click ‘Update’ at the bottom of the page
|
|
61
|
+
5. Click ‘Verify’ to verify the file was uploaded correctly
|
|
62
|
+
|
|
63
|
+
### Test Mode
|
|
64
|
+
|
|
65
|
+
If you'd like to test your checkout flow without processing real payments, Stripe's test mode is a safe and effective way to simulate transactions. To enable it, simply switch your Stripe dashboard to **Test mode** and paste the corresponding **test API keys** into the payment method settings in Spree.
|
|
66
|
+
|
|
67
|
+
## Features
|
|
68
|
+
|
|
69
|
+
Spree’s native Stripe integration supports a wide range of features and payment methods to help you offer a fast, secure, and flexible checkout experience:
|
|
70
|
+
|
|
71
|
+
- Support for quick checkout using Apple Pay, Google Pay, Stripe Link
|
|
72
|
+
- Support for 3D Secure and other security standards
|
|
73
|
+
- Support for off-session payments
|
|
74
|
+
- Support for Storefront API integration (see the API docs here).
|
|
75
|
+
- Accept payments in over 130 currencies
|
|
76
|
+
- Accept Credit Cards, Apple Pay, Google Pay, and more
|
|
77
|
+
- Accept SEPA Direct Debit payments
|
|
78
|
+
- Accept iDEAL payments
|
|
79
|
+
- Accept SOFORT payments
|
|
80
|
+
- Accept Bancontact payments
|
|
81
|
+
- Accept Alipay payments
|
|
82
|
+
- Accept WeChat Pay payments
|
|
83
|
+
- Accept Afterpay, Klarna, Affirm, and more
|
|
84
|
+
|
|
85
|
+
### Storefront Display
|
|
86
|
+
|
|
87
|
+
Spree’s Stripe integration enhances the customer experience with dynamic, context-aware payment options across the storefront:
|
|
88
|
+
|
|
89
|
+
- Installment (BNPL) payments indicator on PDP (Product Detail Page)
|
|
90
|
+

|
|
91
|
+
- Quick payment options on the cart (Apple Pay, Google Pay, Link)
|
|
92
|
+

|
|
93
|
+
- Quick payments bypassing checkout 1st step (Apple Pay, Google Pay, Link)
|
|
94
|
+

|
|
95
|
+
- Various payment options on the payment step (cards, BNPL, Apple Pay, Google Pay, Link)
|
|
96
|
+

|
|
97
|
+
|
|
98
|
+
## Stripe Connect for Marketplaces
|
|
99
|
+
|
|
100
|
+
Spree Commerce [Enterprise Edition](https://spreecommerce.org/spree-commerce-version-comparison-community-edition-vs-enterprise-edition/) comes with a fully automated Stripe Connect integration for [multi-vendor marketplace use cases](https://spreecommerce.org/marketplace-ecommerce/):
|
|
101
|
+
|
|
102
|
+
- Automated split payments between marketplace and vendors
|
|
103
|
+
- Support for multiple payment methods including cards and digital wallets
|
|
104
|
+
- Configurable marketplace fees and commission structures
|
|
105
|
+
- Automated payouts to vendors
|
|
106
|
+
- Comprehensive transaction reporting
|
|
107
|
+
- Built-in fraud prevention tools
|
|
108
|
+
|
|
109
|
+
Feel free to [reach out](https://spreecommerce.org/get-started/) to learn more.
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Meilisearch
|
|
3
|
+
description: "Set up Meilisearch for fast, typo-tolerant product search with faceted filtering"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Overview
|
|
7
|
+
|
|
8
|
+
[Meilisearch](https://www.meilisearch.com/) is a fast, open-source search engine that provides typo tolerance, relevance ranking, faceted filtering, and sub-50ms search responses. Spree includes a built-in Meilisearch search provider that replaces the default SQL-based search.
|
|
9
|
+
|
|
10
|
+
**When to use Meilisearch:**
|
|
11
|
+
- Catalogs with 1,000+ products
|
|
12
|
+
- Need typo tolerance and relevance ranking
|
|
13
|
+
- Want faceted filtering with adjusted counts
|
|
14
|
+
- Require sub-second search responses
|
|
15
|
+
- Multi-locale / multi-currency storefronts
|
|
16
|
+
|
|
17
|
+
**When the default Database provider is sufficient:**
|
|
18
|
+
- Development environments
|
|
19
|
+
- Small catalogs (< 1,000 products)
|
|
20
|
+
- Simple search requirements
|
|
21
|
+
|
|
22
|
+
## Setup
|
|
23
|
+
|
|
24
|
+
### 1. Install Meilisearch
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
```bash macOS (Homebrew)
|
|
28
|
+
brew install meilisearch
|
|
29
|
+
meilisearch
|
|
30
|
+
# Running at http://localhost:7700 — no API key needed for development
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```bash Docker
|
|
34
|
+
docker run -d --name meilisearch \
|
|
35
|
+
-p 7700:7700 \
|
|
36
|
+
-v $(pwd)/meili_data:/meili_data \
|
|
37
|
+
getmeili/meilisearch:latest
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```bash Meilisearch Cloud
|
|
41
|
+
# Sign up at https://www.meilisearch.com/cloud
|
|
42
|
+
# Get your URL and API key from the dashboard
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
> **INFO:** For local development, Meilisearch runs without authentication by default — no API key is needed. For production, set a master key (minimum 16 bytes) via `MEILI_MASTER_KEY` when starting Meilisearch. Use this master key as your `MEILISEARCH_API_KEY`.
|
|
47
|
+
|
|
48
|
+
### 2. Add the gem to your Gemfile
|
|
49
|
+
|
|
50
|
+
```ruby
|
|
51
|
+
gem 'meilisearch', '>= 0.28'
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
bundle install
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 3. Configure environment variables
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# .env
|
|
62
|
+
|
|
63
|
+
# Local development — no API key needed
|
|
64
|
+
MEILISEARCH_URL=http://localhost:7700
|
|
65
|
+
|
|
66
|
+
# Production — use the master key you set when starting Meilisearch
|
|
67
|
+
# MEILISEARCH_API_KEY=your-master-key-min-16-bytes
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### 4. Set the search provider
|
|
71
|
+
|
|
72
|
+
```ruby
|
|
73
|
+
# config/initializers/spree.rb
|
|
74
|
+
Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 5. Index your products
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
rake spree:search:reindex
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
That's it. Your Store API now uses Meilisearch for all product search, filtering, and faceted navigation.
|
|
84
|
+
|
|
85
|
+
## How It Works
|
|
86
|
+
|
|
87
|
+
### Indexing
|
|
88
|
+
|
|
89
|
+
Products are indexed as **one document per market × locale** combination. Each document contains the product's name and description in that locale, the price in that market's currency, and all non-translated fields (categories, options, stock, tags).
|
|
90
|
+
|
|
91
|
+
For example, a store with a US market (USD, English) and an EU market (EUR, German/French) creates 3 index documents per product:
|
|
92
|
+
|
|
93
|
+
| Document ID | Name | Price | Locale | Currency |
|
|
94
|
+
|---|---|---|---|---|
|
|
95
|
+
| `prod_abc_en_USD` | Blue Shirt | 29.99 | en | USD |
|
|
96
|
+
| `prod_abc_de_EUR` | Blaues Hemd | 27.50 | de | EUR |
|
|
97
|
+
| `prod_abc_fr_EUR` | Chemise Bleue | 27.50 | fr | EUR |
|
|
98
|
+
|
|
99
|
+
Products are **only indexed for markets where they have a price**. If a product has no EUR price, no EUR documents are created.
|
|
100
|
+
|
|
101
|
+
Translations use **Mobility with fallback** — if a product has no German translation, the default locale (English) is used.
|
|
102
|
+
|
|
103
|
+
Each document includes:
|
|
104
|
+
- Translated name, description, slug
|
|
105
|
+
- Price and compare-at price in the market's currency
|
|
106
|
+
- Category IDs, option type/value IDs (all prefixed)
|
|
107
|
+
- Stock status, tags, timestamps
|
|
108
|
+
- Store IDs, locale, currency (for filtering)
|
|
109
|
+
|
|
110
|
+
Preview what gets indexed:
|
|
111
|
+
|
|
112
|
+
```ruby
|
|
113
|
+
# Rails console
|
|
114
|
+
product = Spree::Product.first
|
|
115
|
+
product.search_presentation
|
|
116
|
+
# Returns an array of documents — one per market × locale
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Search Flow
|
|
120
|
+
|
|
121
|
+
```curl
|
|
122
|
+
GET /api/v3/store/products?q[search]=shirt&q[price_gte]=20&sort=price
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
1. Controller builds AR scope for security: `store.products.active(currency).accessible_by(ability)`
|
|
126
|
+
2. Meilisearch provider adds base filters: `locale='en' AND currency='USD' AND status='active' AND store_ids='{id}' AND not_discontinued`
|
|
127
|
+
3. Provider sends **one Meilisearch API call**: search + user filters + facets + sort + pagination
|
|
128
|
+
4. Provider intersects Meilisearch product IDs with AR scope (safety net)
|
|
129
|
+
5. Returns products + facets with adjusted counts + pagination
|
|
130
|
+
|
|
131
|
+
The base filters ensure Meilisearch only returns products visible in the current locale and currency. The AR scope is a safety net — it should not filter out any additional products.
|
|
132
|
+
|
|
133
|
+
### Index Name
|
|
134
|
+
|
|
135
|
+
Each store gets its own Meilisearch index: `{store_code}_products`. For a store with code `"my-store"`, the index name is `my_store_products`.
|
|
136
|
+
|
|
137
|
+
## Manual Operations
|
|
138
|
+
|
|
139
|
+
### Reindex all products
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
rake spree:search:reindex
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Index a single product
|
|
146
|
+
|
|
147
|
+
```ruby
|
|
148
|
+
product.add_to_search_index
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Remove a product from the index
|
|
152
|
+
|
|
153
|
+
```ruby
|
|
154
|
+
product.remove_from_search_index
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Preview indexed data
|
|
158
|
+
|
|
159
|
+
```ruby
|
|
160
|
+
product.search_presentation
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Configuration
|
|
164
|
+
|
|
165
|
+
| Environment Variable | Default | Description |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `MEILISEARCH_URL` | `http://localhost:7700` | Meilisearch server URL |
|
|
168
|
+
| `MEILISEARCH_API_KEY` | `nil` | Meilisearch master key. Not needed for local development — only required when Meilisearch is started with `MEILI_MASTER_KEY`. |
|
|
169
|
+
|
|
170
|
+
The index is automatically configured with the correct filterable, sortable, and searchable attributes when you run `rake spree:search:reindex`.
|
|
171
|
+
|
|
172
|
+
## Filterable Attributes
|
|
173
|
+
|
|
174
|
+
The Meilisearch provider automatically configures these filterable attributes:
|
|
175
|
+
|
|
176
|
+
- `product_id` — prefixed product ID (for bulk deletion of locale/currency variants)
|
|
177
|
+
- `status` — product status (always filtered to `active` for Store API)
|
|
178
|
+
- `in_stock` — boolean stock availability
|
|
179
|
+
- `store_ids` — which stores the product belongs to
|
|
180
|
+
- `locale` — document locale (filtered per request)
|
|
181
|
+
- `currency` — document currency (filtered per request)
|
|
182
|
+
- `discontinue_on` — Unix timestamp for discontinuation filtering
|
|
183
|
+
- `price` — price in the document's currency
|
|
184
|
+
- `category_ids` — prefixed category IDs
|
|
185
|
+
- `tags` — product tags
|
|
186
|
+
- `option_value_ids` — prefixed option value IDs
|
|
187
|
+
|
|
188
|
+
## Sortable Attributes
|
|
189
|
+
|
|
190
|
+
- `name` — sort alphabetically (locale-aware via per-locale documents)
|
|
191
|
+
- `price` — sort by price (currency-aware via per-currency documents)
|
|
192
|
+
- `created_at` — sort by creation date
|
|
193
|
+
- `available_on` — sort by availability date
|
|
194
|
+
- `units_sold_count` — sort by best selling
|
|
195
|
+
|
|
196
|
+
## Searchable Attributes
|
|
197
|
+
|
|
198
|
+
- `name` — product name (in document locale)
|
|
199
|
+
- `description` — product description (in document locale)
|
|
200
|
+
- `sku` — variant SKU
|
|
201
|
+
- `option_values` — option value presentations (e.g., "Red", "Small")
|
|
202
|
+
- `category_names` — category names
|
|
203
|
+
- `tags` — product tags
|
|
204
|
+
|
|
205
|
+
## Store API Compatibility
|
|
206
|
+
|
|
207
|
+
The Meilisearch provider is fully compatible with the existing Store API. No client-side changes are needed:
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
// Same SDK calls work with both Database and Meilisearch providers
|
|
211
|
+
const products = await client.products.list({
|
|
212
|
+
search: 'blue shirt',
|
|
213
|
+
price_gte: 20,
|
|
214
|
+
price_lte: 100,
|
|
215
|
+
in_stock: true,
|
|
216
|
+
sort: 'price',
|
|
217
|
+
limit: 12,
|
|
218
|
+
})
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Locale and currency are automatically resolved from request headers (`x-spree-locale`, `x-spree-currency`) — no need to pass them as filter params.
|
|
222
|
+
|
|
223
|
+
## Production Recommendations
|
|
224
|
+
|
|
225
|
+
### Separate search and admin keys
|
|
226
|
+
|
|
227
|
+
Meilisearch supports [tenant tokens](https://www.meilisearch.com/docs/learn/security/tenant_tokens) for fine-grained access control. Use an admin key for indexing and a search key for queries.
|
|
228
|
+
|
|
229
|
+
### Meilisearch Cloud
|
|
230
|
+
|
|
231
|
+
For production deployments, consider [Meilisearch Cloud](https://www.meilisearch.com/cloud) for managed hosting, automatic scaling, and monitoring.
|
|
232
|
+
|
|
233
|
+
## Related Documentation
|
|
234
|
+
|
|
235
|
+
- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search reference
|
|
236
|
+
- [Search Providers](/developer/how-to/custom-search-provider) — Architecture and custom providers
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "SSO and MFA for the Admin Panel"
|
|
3
|
+
sidebarTitle: "Admin SSO & MFA"
|
|
4
|
+
description: "Learn how to secure your Spree admin panel with SSO and MFA integration, using Microsoft Entra ID as an example."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Enterprise businesses require **Single Sign-On (SSO)** and **Multi-Factor Authentication (MFA)** to secure sensitive operations, maintain compliance, and simplify IT administration. For Spree Commerce, the **admin panel** is the heart of your business operations, which means securing access here is critical.
|
|
8
|
+
|
|
9
|
+
## SSO providers
|
|
10
|
+
|
|
11
|
+
There are many popular SSO providers, such as **Microsoft Entra ID**, **Okta**, **Ping Identity**, and **OneLogin**. Each provider may also offer multiple services under its ecosystem.
|
|
12
|
+
|
|
13
|
+
For example, Microsoft’s SSO ecosystem includes:
|
|
14
|
+
|
|
15
|
+
- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
|
|
16
|
+
- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
|
|
17
|
+
|
|
18
|
+
> **NOTE:** For the purposes of this article, we are using **Microsoft** as the example provider.
|
|
19
|
+
|
|
20
|
+
## Why integrate SSO with MFA for the Admin Panel
|
|
21
|
+
|
|
22
|
+
- **Used by staff, merchants, and operators**
|
|
23
|
+
- **Integration with Entra ID** ensures employees can log in using their corporate credentials
|
|
24
|
+
- Benefits include:
|
|
25
|
+
- Higher security
|
|
26
|
+
- Regulatory compliance (SOC2, HIPAA, GDPR)
|
|
27
|
+
- Simplified IT administration
|
|
28
|
+
- Better user experience with SSO
|
|
29
|
+
- With Microsoft solutions, you can also enable **Multi-Factor Authentication (MFA)** or **passwordless options** (Windows Hello, FIDO2 keys) to further strengthen access security
|
|
30
|
+
|
|
31
|
+
## Get Started with SSO and MFA
|
|
32
|
+
|
|
33
|
+
Each SSO integration needs to be scoped individually. The integration plan depends on multiple factors, such as:
|
|
34
|
+
|
|
35
|
+
- **Required SSO provider**
|
|
36
|
+
- Decide whether you’ll use Microsoft Entra ID, Okta, Ping Identity, OneLogin, or another vendor. Each provider offers different features, protocols, and integration options.
|
|
37
|
+
- **SSO provider settings**
|
|
38
|
+
- Each provider has unique configuration details, such as OAuth endpoints, certificates, tenant IDs, and federation settings. You’ll need to gather these to complete integration.
|
|
39
|
+
- **Existing or planned Spree customizations**
|
|
40
|
+
- Custom authentication flows, extended user models, or unique admin permissions may affect how SSO is integrated. These should be reviewed before implementation.
|
|
41
|
+
- **Spree and Ruby on Rails versions**
|
|
42
|
+
- Compatibility matters. Integration strategies can differ depending on whether you’re on the latest Spree release and which Rails version your project runs on.
|
|
43
|
+
- **Use case: single tenant vs. multi-tenant**
|
|
44
|
+
- Single-tenant stores usually need straightforward workforce SSO. Multi-tenant or SaaS-style deployments may require isolated tenant directories and more complex provisioning.
|
|
45
|
+
- **Identity governance requirements** (role-based access, just-in-time provisioning)
|
|
46
|
+
- **User lifecycle management** (provisioning/de-provisioning)
|
|
47
|
+
- **Security posture** (MFA enforcement, conditional access, passwordless policies)
|
|
48
|
+
- **Compliance certifications required** (ISO, SOC2, HIPAA, PCI DSS)
|
|
49
|
+
- **Traffic scale and performance** (concurrent users, global access, load balancing)
|
|
50
|
+
- **Disaster recovery and redundancy** (failover strategies)
|
|
51
|
+
- **Integration with third-party services** (analytics, CDPs, data warehouses)
|
|
52
|
+
|
|
53
|
+
> **INFO:** Let's get in touch so we can scope your requirements and deliver this important integration for your project.
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
- [Book a Call](https://getvendo.com/book-a-demo/) — Schedule a call to explore the options and get your questions answered
|
|
57
|
+
- [Ask a Question](https://spreecommerce.org/get-started/) — Send us a message and share your thoughts
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "SSO and Social Login for the Storefront"
|
|
3
|
+
sidebarTitle: "Storefront SSO & Social Login"
|
|
4
|
+
description: "Enable customer-facing SSO and social login on your Spree storefront, using Microsoft Entra External ID as an example."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Enterprise businesses benefit from offering **customer-facing SSO and social login** because it streamlines the shopping experience and improves conversions. Customers prefer using accounts they already trust instead of creating new ones.
|
|
8
|
+
|
|
9
|
+
## SSO providers
|
|
10
|
+
|
|
11
|
+
There are many popular SSO providers, such as **Microsoft Entra External ID**, **Auth0**, **Okta**, and **Ping Identity**. Each provider may offer several services with different target use cases.
|
|
12
|
+
|
|
13
|
+
For example, Microsoft’s SSO ecosystem includes:
|
|
14
|
+
|
|
15
|
+
- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
|
|
16
|
+
- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
|
|
17
|
+
|
|
18
|
+
> **NOTE:** For the purposes of this article, we are using **Microsoft** as the example provider.
|
|
19
|
+
|
|
20
|
+
## Why integrate SSO and Social Login for the Storefront
|
|
21
|
+
|
|
22
|
+
- **Used by shoppers**
|
|
23
|
+
- Integration with **Entra External ID (B2C)** or other customer identity providers enables frictionless sign-ups and sign-ins
|
|
24
|
+
- Benefits include:
|
|
25
|
+
- Reduced cart abandonment
|
|
26
|
+
- Faster checkout
|
|
27
|
+
- Higher conversion rates
|
|
28
|
+
- Supports **social login options**: Google, Facebook, Amazon, Apple ID, Microsoft
|
|
29
|
+
|
|
30
|
+
## Get Started with SSO and Social Login
|
|
31
|
+
|
|
32
|
+
Each storefront integration must be scoped individually. Consider the following:
|
|
33
|
+
|
|
34
|
+
- **Required SSO provider**
|
|
35
|
+
- Choose from Microsoft Entra External ID, Auth0, Okta, Ping Identity, or others. Your decision depends on features, ecosystem compatibility, and scalability needs.
|
|
36
|
+
- **SSO provider settings, including identity providers**
|
|
37
|
+
- Each SSO platform has unique configuration settings (OAuth endpoints, certificates, client IDs). If you want to enable social logins, you’ll also need to configure providers like Google, Facebook, or Apple.
|
|
38
|
+
- **Scope: social login only vs. SSO + social login**
|
|
39
|
+
- Decide whether you only want to add social login on top of Spree’s existing authentication or fully replace it with a unified SSO + social login solution.
|
|
40
|
+
- **Existing or planned Spree customizations**
|
|
41
|
+
- Customized signup flows, checkout flows, or customer segmentation logic may impact integration design. These need to be factored in during scoping.
|
|
42
|
+
- **Spree and Ruby on Rails versions**
|
|
43
|
+
- Ensure compatibility with your Spree and Rails versions. Older projects may need adjustments to take advantage of newer identity management features.
|
|
44
|
+
- **Identity governance requirements** (segmentation, customer role-based access)
|
|
45
|
+
- **User lifecycle management** (account creation, deactivation, syncing)
|
|
46
|
+
- **Security posture** (MFA for customers, adaptive login, fraud detection)
|
|
47
|
+
- **Compliance certifications required** (GDPR, CCPA, PCI DSS)
|
|
48
|
+
- **Traffic scale and performance** (millions of customer accounts, peak season load)
|
|
49
|
+
- **Disaster recovery and redundancy** (failover, global availability zones)
|
|
50
|
+
- **Integration with third-party services** (marketing automation, CDPs, analytics, loyalty programs)
|
|
51
|
+
|
|
52
|
+
> **INFO:** Let's get in touch so we can scope your requirements and deliver this important integration for your project.
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
- [Book a Call](https://getvendo.com/book-a-demo/) — Schedule a call to explore the options and get your questions answered
|
|
56
|
+
- [Ask a Question](https://spreecommerce.org/get-started/) — Send us a message and share your thoughts
|
package/package.json
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@spree/docs",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Spree Commerce developer documentation for AI agents and local reference",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "CC-BY-4.0",
|
|
7
|
+
"author": "Vendo Connect Inc.",
|
|
8
|
+
"homepage": "https://spreecommerce.org",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "https://github.com/spree/spree.git",
|
|
12
|
+
"directory": "packages/docs"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/spree/spree/issues"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"dist/**/*.md"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "node scripts/build.js",
|
|
22
|
+
"clean": "rm -rf dist"
|
|
23
|
+
},
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=18.0.0"
|
|
26
|
+
}
|
|
27
|
+
}
|