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.

[Skip CI] Documentation update

Damian Legawiec124437c4eee4
diff --git a/docs/developer/admin/tables.mdx b/docs/developer/admin/tables.mdx
index 4578c23a45..17d3fee622 100644
--- a/docs/developer/admin/tables.mdx
+++ b/docs/developer/admin/tables.mdx
@@ -3,10 +3,6 @@ title: Admin Tables
sidebarTitle: Tables
---
-<Warning>
- Admin Tables are part of the upcoming Spree 5.3 release slated for January 2026.
-</Warning>
-
Spree Admin provides a flexible table system for displaying resource listings with customizable columns, sorting, filtering, and bulk actions. The Tables DSL allows you to define table configurations for your resources and extend existing ones.
<Info>
diff --git a/docs/developer/core-concepts/addresses.mdx b/docs/developer/core-concepts/addresses.mdx
index 934838f849..5595c25fba 100644
--- a/docs/developer/core-concepts/addresses.mdx
+++ b/docs/developer/core-concepts/addresses.mdx
@@ -99,9 +99,9 @@ An address must always link to a `Spree::Country` object. It can optionally link
## Customers
-`Spree::User` can have multiple addresses and can manage them on the Checkout and Account page (or via API). Each `Spree::Address` object has a `user_id` column which links to the User.
+Users can have multiple addresses and can manage them on the Checkout and Account page (or via API). Each `Spree::Address` object has a `user_id` column which links to the User.
-Additionally in the `Spree::User` there is `ship_address_id` and `bill_address_id` columns which indicates which addresses are the default ones for this User.
+Additionally in `Spree.user_class` there are `ship_address_id` and `bill_address_id` columns which indicate the default addresses for this User.
## Checkout
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index 7b2df157c1..8eabf0a0ac 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -3,10 +3,6 @@ title: Events
description: Learn how Spree's event system works and how to subscribe to events.
---
-<Warning>
- Events are part of the upcoming Spree 5.3 release slated for January 2026.
-</Warning>
-
## Overview
Spree includes a powerful event system that allows you to react to various actions happening in your store. When something happens (an order is completed, a product is created, etc.), Spree publishes an event that your code can subscribe to and handle.
@@ -29,6 +25,32 @@ Spree's event system is built on top of [`ActiveSupport::Notifications`](https:/
When an event is published, all matching subscribers are notified. By default, subscribers run asynchronously via ActiveJob to avoid blocking the main request.
+```mermaid
+flowchart TB
+ subgraph Spree Application
+ A[Model Action] --> B[publish_event]
+ B --> C[Event Serializer]
+ C --> D[Spree::Events]
+ end
+
+ subgraph Event Adapter
+ D --> E[Find Matching Subscribers]
+ E --> F{Async?}
+ F -->|Yes| G[Queue ActiveJob]
+ F -->|No| H[Execute Immediately]
+ end
+
+ subgraph Subscribers
+ G --> I[SubscriberJob]
+ I --> J[Your Subscriber]
+ H --> J
+ J --> K[Send Email]
+ J --> L[Sync External Service]
+ J --> M[Update Cache]
+ J --> N[Trigger Webhook]
+ end
+```
+
## Creating a Subscriber
Create a subscriber class in `app/subscribers/` that inherits from `Spree::Subscriber`:
diff --git a/docs/developer/core-concepts/i18n.mdx b/docs/developer/core-concepts/i18n.mdx
index d8afc0382d..5e880c1ea0 100644
--- a/docs/developer/core-concepts/i18n.mdx
+++ b/docs/developer/core-concepts/i18n.mdx
@@ -32,6 +32,51 @@ For currencies, we use [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) symbol
As of Spree 4.6, resources with user-facing content fields now have built in support for translations. Translation functionality is handled by the [Mobility gem](https://github.com/shioyama/mobility). Spree allows you to translate the following resources:
+```mermaid
+erDiagram
+ spree_products ||--o{ spree_product_translations : "has many"
+ spree_taxons ||--o{ spree_taxon_translations : "has many"
+ spree_taxonomies ||--o{ spree_taxonomy_translations : "has many"
+ spree_option_types ||--o{ spree_option_type_translations : "has many"
+ spree_option_values ||--o{ spree_option_value_translations : "has many"
+ spree_properties ||--o{ spree_property_translations : "has many"
+ spree_product_properties ||--o{ spree_product_property_translations : "has many"
+ spree_stores ||--o{ spree_store_translations : "has many"
+
+ spree_products {
+ bigint id PK
+ string status
+ datetime created_at
+ }
+
+ spree_product_translations {
+ bigint id PK
+ bigint spree_product_id FK
+ string locale
+ string name
+ text description
+ string slug
+ string meta_title
+ string meta_description
+ string meta_keywords
+ }
+
+ spree_taxons {
+ bigint id PK
+ bigint taxonomy_id FK
+ bigint parent_id FK
+ }
+
+ spree_taxon_translations {
+ bigint id PK
+ bigint spree_taxon_id FK
+ string locale
+ string name
+ text description
+ string permalink
+ }
+```
+
| Resource | Translatable Fields |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Product | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title` |
diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdx
index 9c18f940ec..3df66499e6 100644
--- a/docs/developer/core-concepts/metafields.mdx
+++ b/docs/developer/core-concepts/metafields.mdx
@@ -22,6 +22,69 @@ Metafields are available from Spree 5.2 onwards.
The metafields system consists of two main models:
+```mermaid
+erDiagram
+ spree_metafield_definitions ||--o{ spree_metafields : "defines schema for"
+ spree_products ||--o{ spree_metafields : "has many"
+ spree_variants ||--o{ spree_metafields : "has many"
+ spree_orders ||--o{ spree_metafields : "has many"
+
+ spree_metafield_definitions {
+ bigint id PK
+ string namespace
+ string key
+ string name
+ string metafield_type
+ string resource_type
+ string display_on
+ datetime created_at
+ }
+
+ spree_metafields {
+ bigint id PK
+ bigint metafield_definition_id FK
+ string type
+ text value
+ string resource_type
+ bigint resource_id
+ datetime created_at
+ }
+
+ spree_products {
+ bigint id PK
+ string name
+ }
+
+ spree_variants {
+ bigint id PK
+ string sku
+ }
+
+ spree_orders {
+ bigint id PK
+ string number
+ }
+```
+
+```mermaid
+flowchart LR
+ subgraph Definition
+ A[MetafieldDefinition] --> B[namespace: properties]
+ A --> C[key: manufacturer]
+ A --> D[type: ShortText]
+ A --> E[resource_type: Product]
+ A --> F[display_on: both]
+ end
+
+ subgraph Instance
+ G[Metafield] --> H[value: Wilson]
+ G --> I[resource: Product #1]
+ G --> J[definition_id: 1]
+ end
+
+ A -.->|"defines schema"| G
+```
+
### MetafieldDefinition
Defines the schema and rules for a metafield type. Think of it as a blueprint that specifies:
diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdx
index 3bfa8ea2f0..6dd7eb5ef2 100644
--- a/docs/developer/core-concepts/users.mdx
+++ b/docs/developer/core-concepts/users.mdx
@@ -2,89 +2,364 @@
title: Users
---
+## Overview
+
In your Spree application you will usually have 2 types of users:
-* Customers - who are the users who will be purchasing products
-* Admins - who are the users who will be managing the Spree store
+* **Customers** - users who browse and purchase products
+* **Admins** - users who manage the store via the Admin Panel
+
+Spree uses two separate user classes to distinguish between them:
+
+| Class | Description | Default |
+|-------|-------------|---------|
+| `Spree.user_class` | Customers who browse and purchase products | `Spree::User` |
+| `Spree.admin_user_class` | Administrators who manage the store via Admin Panel | `Spree::AdminUser` |
+
+<Warning>
+Always use `Spree.user_class` and `Spree.admin_user_class` instead of referencing the classes directly. This ensures compatibility with custom user models.
+</Warning>
+
+<Info>
+You can use your own User classes. More on this in the [Customize Authentication guide](/developer/customization/authentication).
+</Info>
+
+## Customers
+
+Customers are users who browse your store and purchase products. They are managed via `Spree.user_class`.
+
+```mermaid
+erDiagram
+ spree_users ||--o{ spree_orders : "places"
+ spree_users ||--o{ spree_addresses : "has many"
+ spree_users ||--o{ spree_credit_cards : "has many"
+ spree_users ||--o{ spree_payment_sources : "has many"
+ spree_users ||--o{ spree_store_credits : "has many"
+ spree_users ||--o{ spree_gift_cards : "has many"
+ spree_users ||--o{ spree_wishlists : "has many"
+ spree_users ||--o| spree_addresses : "default ship address"
+ spree_users ||--o| spree_addresses : "default bill address"
+ spree_credit_cards ||--|| spree_payment_methods : "belongs to"
+ spree_payment_sources ||--|| spree_payment_methods : "belongs to"
+
+ spree_users {
+ bigint id PK
+ string email
+ bigint ship_address_id FK
+ bigint bill_address_id FK
+ datetime created_at
+ }
+
+ spree_orders {
+ bigint id PK
+ bigint user_id FK
+ string number
+ string state
+ decimal total
+ }
+
+ spree_addresses {
+ bigint id PK
+ string firstname
+ string lastname
+ string address1
+ string city
+ string zipcode
+ }
+
+ spree_credit_cards {
+ bigint id PK
+ bigint user_id FK
+ bigint payment_method_id FK
+ string cc_type
+ string last_digits
+ string name
+ }
+
+ spree_payment_sources {
+ bigint id PK
+ bigint user_id FK
+ bigint payment_method_id FK
+ string type
+ string name
+ }
+
+ spree_store_credits {
+ bigint id PK
+ bigint user_id FK
+ decimal amount
+ string currency
+ }
+
+ spree_gift_cards {
+ bigint id PK
+ bigint user_id FK
+ string code
+ decimal balance
+ string currency
+ }
+
+ spree_wishlists {
+ bigint id PK
+ bigint user_id FK
+ string name
+ boolean is_default
+ }
+
+ spree_payment_methods {
+ bigint id PK
+ string type
+ string name
+ }
+```
Customers can have:
-* **[Addresses](/developer/core-concepts/addresses)**, both billing and shipping
-* **[Orders](/developer/core-concepts/orders)** - a list of products that the user has purchased
-* **Credit Cards** - used on the checkout page to pay for the order
+* **[Addresses](/developer/core-concepts/addresses)** - both billing and shipping
+* **[Orders](/developer/core-concepts/orders)** - a list of products that the customer has purchased
+* **Credit Cards** - saved credit cards for checkout
+* **Payment Sources** - saved non-credit card payment methods (PayPal, Klarna, etc.)
* **Store Credits** - assigned by the store owners, to be used to purchase products
-* **Wishlists** - a list of products that the user has marked as a wishlist
+* **Gift Cards** - gift cards owned by or assigned to the customer
+* **Wishlists** - a list of products that the customer has marked as a wishlist
-## User model
+### Customer Attributes
-The default user class is `Spree::User` which is generated during Spree installation.
+| Attribute | Description | Example Value |
+|-------------------|-----------------------------------------------------------------------------|---------------------|
+| `email` | The email address of the customer | `[email protected]` |
+| `ship_address_id` | References the default shipping address | `2` |
+| `bill_address_id` | References the default billing address | `3` |
-You should however reference Users with an universal `Spree.user_class` to avoid any potential issues, eg.
+There will be more attributes provided by [Devise](https://github.com/plataformatec/devise) gem, but these are the most important ones.
+
+### Customer Methods
+
+`Spree.user_class` includes several [ActiveRecord concerns](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveSupport/Concern.html) which provide additional methods:
```ruby
-Spree.user_class.find_by(email: "[email protected]")
+# Find a customer
+customer = Spree.user_class.find_by(email: "[email protected]")
+
+# Get customer orders
+customer.orders
```
-<Info>
-You can use your own User class. More on this in the [Customize Authentication guide](/developer/customization/authentication).
-</Info>
+```ruby Returns the last incomplete order for the given store.
+customer.last_incomplete_spree_order(store)
+```
-## User attributes
+```ruby Returns the total amount available store credits for the customer in the given store.
+customer.available_store_credits(store)
+```
-Here's the list of attributes for the default `Spree::User` model:
+```ruby Returns the default Wishlist for the given Store.
+customer.default_wishlist_for_store(store)
+```
-| Attribute | Description | Example Value |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `email` | The email address of the user. | `[email protected]` |
-| `ship_address_id` | References the default shipping address associated with the user. | `2` |
-| `bill_address_id` | References the default billing address associated with the user. | `3` |
+```ruby Returns a list of all active payment sources (credit cards, PayPal, Klarna, etc.) that can be used on checkout.
+customer.payment_sources
+```
-There will be lots more attributes provided by [Devise](https://github.com/plataformatec/devise) gem, but these are the most important ones for the user.
+## Admins
+
+Admins are users who manage the store via the Admin Panel. They are managed via `Spree.admin_user_class`.
+
+```mermaid
+erDiagram
+ spree_admin_users ||--o{ spree_role_users : "has many"
+ spree_role_users }o--|| spree_roles : "belongs to"
+ spree_role_users }o--|| spree_stores : "resource"
+ spree_admin_users ||--o{ spree_invitations : "inviter"
+ spree_admin_users ||--o{ spree_invitations : "invitee"
+
+ spree_admin_users {
+ bigint id PK
+ string email
+ datetime created_at
+ }
+
+ spree_role_users {
+ bigint id PK
+ bigint user_id FK
+ bigint role_id FK
+ string resource_type
+ bigint resource_id
+ }
+
+ spree_roles {
+ bigint id PK
+ string name
+ }
+
+ spree_stores {
+ bigint id PK
+ string name
+ }
+
+ spree_invitations {
+ bigint id PK
+ string email
+ string token
+ string status
+ datetime expires_at
+ }
+```
-## User roles
+### Admin Roles
-Each User can have different roles attached, eg. `admin` (which will grant them access to the Spree admin).
+Admin users can have different roles attached which control their permissions in the Admin Panel.
-To attach a role to a user, you can use this code:
+| Role | Description |
+|------|-------------|
+| `admin` | Full access to all Admin Panel features |
+
+<Info>
+You can create custom roles with specific permissions. See the [Customize Permissions guide](/developer/customization/permissions) for more details.
+</Info>
+
+### Managing Admin Access
+
+Resources that include the `Spree::UserManagement` concern (such as `Spree::Store`) provide methods to manage admin access:
```ruby
-user = Spree::User.find_by(email: "[email protected]")
-role = Spree::Role.find_or_create_by(name: 'admin')
+store = Spree::Store.default
+admin = Spree.admin_user_class.find_by(email: "[email protected]")
+role = Spree::Role.find_by(name: 'admin')
+
+# Add an admin to the store with a specific role
+store.add_user(admin, role)
-user.spree_roles << role
+# Add an admin with the default role
+store.add_user(admin)
+
+# Remove an admin's access to the store
+store.remove_user(admin)
+
+# Check admin permissions
+admin.has_spree_role?('admin')
```
-## User methods
+### Admin User Invitation Flow
+
+Spree uses a custom `Spree::Invitation` model to handle admin user invitations. This provides a secure, token-based invitation system with built-in expiration and role assignment.
+
+```mermaid
+flowchart TB
+ A[Admin creates invitation] --> B[Spree::Invitation created]
+ B --> C[Token generated automatically]
+ C --> D["Event 'invitation.created' published"]
+ D --> E[Invitation email sent]
+ E --> F[Invitee clicks invitation link]
+ F --> G{Invitee exists?}
+ G -->|Yes| H[Redirect to login]
+ G -->|No| I[Redirect to registration]
+ H --> J[Invitee logs in]
+ I --> K[Invitee creates account]
+ J --> L[Accept invitation]
+ K --> L
+ L --> M[RoleUser created]
+ M --> N["Event 'invitation.accepted' published"]
+ N --> O[Admin can access resource]
+```
-`Spree::User` includes several [ActiveRecord concerns](https://api.rubyonrails.org/v7.1.3.2/classes/ActiveSupport/Concern.html), which provide additional methods for the user model.
+#### Invitation Model
-Some handy methods are listed below:
+The `Spree::Invitation` model tracks:
-```ruby Returns the last incomplete order for the given store.
-user.last_incomplete_spree_order(store)
+| Attribute | Description |
+|-----------|-------------|
+| `email` | Email address of the invitee |
+| `token` | Secure token for the invitation link |
+| `status` | `pending` or `accepted` |
+| `expires_at` | When the invitation expires (default: 2 weeks) |
+| `resource` | The resource being granted access to (e.g., Store) |
+| `role` | The role to assign upon acceptance |
+| `inviter` | The admin who created the invitation |
+| `invitee` | The user who accepts the invitation |
+
+#### Inviting an Admin via Admin Panel
+
+1. Navigate to **Settings → Users** in the Admin Panel
+2. Click **Invite User**
+3. Enter the new admin's email address
+4. Select the appropriate role
+5. Click **Send Invitation**
+
+The invitee will receive an email with an invitation link.
+
+#### Inviting an Admin via Code
+
+```ruby
+# Create an invitation
+invitation = Spree::Invitation.create!(
+ email: "[email protected]",
+ inviter: current_admin_user,
+ resource: Spree::Store.default,
+ role: Spree::Role.find_by(name: 'admin')
+)
+
+# The 'invitation.created' event triggers the email automatically
+# To skip the email:
+invitation = Spree::Invitation.create!(
+ email: "[email protected]",
+ inviter: current_admin_user,
+ resource: Spree::Store.default,
+ role: Spree::Role.find_by(name: 'admin'),
+ skip_email: true
+)
```
-```ruby Returns the total amount available store credits for the user in the given store.
-user.available_store_credits(store)
+#### Resending an Invitation
+
+```ruby
+invitation = Spree::Invitation.pending.find_by(email: "[email protected]")
+invitation.resend!
```
-```ruby Returns the default Wishlist for the given Store.
-user.default_wishlist_for_store(store)
+#### Accepting an Invitation
+
+When an invitee accepts, the invitation transitions to `accepted` and a `Spree::RoleUser` record is created linking the user to the resource with the specified role.
+
+```ruby
+invitation = Spree::Invitation.pending.find_by(token: params[:token])
+invitation.invitee = current_admin_user
+invitation.accept!
```
-```ruby Returns a list of all active payment sources, e.g., credit cards that can be used on the checkout.
-user.payment_sources
+#### Invitation Expiration
+
+By default, invitations expire after 2 weeks. You can customize this per invitation:
+
+```ruby
+invitation = Spree::Invitation.create!(
+ email: "[email protected]",
+ inviter: current_admin_user,
+ resource: Spree::Store.default,
+ role: Spree::Role.find_by(name: 'admin'),
+ expires_at: 1.month.from_now
+)
```
-## User Permissions
+#### Invitation Events
+
+The invitation system publishes events that you can subscribe to:
+
+| Event | Description |
+|-------|-------------|
+| `invitation.created` | Invitation was created (triggers email) |
+| `invitation.accepted` | Invitation was accepted |
+| `invitation.resent` | Invitation was resent |
+
+## Permissions
-Spree under the hood uses library called [CanCanCan](https://github.com/CanCanCommunity/cancancan) to handle authorization.
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) library to handle authorization for both customers and admins.
-More on permissions can be found in the [Customize Permissions guide](/developer/customization/permissions). We recommend you check this guide after reading all other Core Concepts.
+More on permissions can be found in the [Customize Permissions guide](/developer/customization/permissions).
-## Current user
+## Current User
-In all Spree controllers or any controller inheriting from `Spree::BaseController`, you can access the current user with `spree_current_user` method.
+In Spree controllers or any controller inheriting from `Spree::BaseController`, you can access the current user with `spree_current_user` method:
```ruby
spree_current_user
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdx
index cb88724647..92963e6b23 100644
--- a/docs/developer/core-concepts/webhooks.mdx
+++ b/docs/developer/core-concepts/webhooks.mdx
@@ -3,10 +3,6 @@ title: Webhooks
description: Send real-time HTTP notifications to external services when events occur in your store.
---
-<Warning>
- Webhooks are part of the upcoming Spree 5.3 release slated for January 2026.
-</Warning>
-
## Overview
Webhooks allow your Spree store to send real-time HTTP POST notifications to external services when events occur. When an order is completed, a product is updated, or inventory changes, Spree can automatically notify your CRM, fulfillment service, analytics platform, or any other system.
@@ -21,8 +17,28 @@ Webhooks are built on top of Spree's [event system](/developer/core-concepts/eve
## How Webhooks Work
-```
-Event Published → WebhookEventSubscriber → Find Matching Endpoints → Queue Delivery Jobs → HTTP POST with Signature
+```mermaid
+flowchart LR
+ subgraph Spree Store
+ A[Event Published] --> B[WebhookEventSubscriber]
+ B --> C{Find Matching<br/>Endpoints}
+ C --> D[Create WebhookDelivery]
+ D --> E[Queue DeliveryJob]
+ end
+
+ subgraph Delivery
+ E --> F[Build JSON Payload]
+ F --> G[Sign with HMAC-SHA256]
+ G --> H[HTTP POST]
+ end
+
+ subgraph External Service
+ H --> I{Response}
+ I -->|2xx| J[Success]
+ I -->|Error| K[Retry with Backoff]
+ K -->|Max Retries| L[Mark Failed]
+ K -->|Retry| H
+ end
```
1. An event is published (e.g., `order.completed`)
diff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdx
index d6964a0701..ae7bdc5ebf 100644
--- a/docs/developer/deployment/render.mdx
+++ b/docs/developer/deployment/render.mdx
@@ -98,7 +98,7 @@ We recommend changing credentials after logging in! You can also do it from the
Now you can open the Rails console by running `bin/rails console`.
```ruby
-Spree::User.first.update!(email: "<[email protected]>", password: "<your_password>", password_confirmation: "<your_password>")
+Spree.admin_user_class.first.update!(email: "<[email protected]>", password: "<your_password>", password_confirmation: "<your_password>")
```
</Warning>