# Solidus

Open-source Rails ecommerce framework with admin, REST API and a starter storefront.

Solidus is a set of Ruby gems that add a full ecommerce engine to a Rails app: catalog, orders, payments, shipping, promotions and an admin. A documented REST API ships in the same repo and uses a user API key as a bearer token. You configure it in a Ruby initializer and in admin screens, and extend it with Rails code.

- Capabilities: adaptable, operable
- Vertical: ecommerce
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/solidusio/solidus (BSD-3-Clause), 5347 stars, last commit 2026-11-05
- Last activity: 2026-11-05
- Page: apps/solidusio--solidus.html
- JSON: apps/solidusio--solidus.json

## Use it when

- you have a Rails team and want a full ecommerce engine you can change, not a hosted shop
- you want your agent to manage products and orders through a REST API with an API key

## Gotchas

- It is a framework: you generate a Rails app, so adapting means Ruby, not config
- The API needs a user API key. Keys are generated only for admins by default and shown at admin/users/<id>/edit; sign-in for other users needs solidus_auth_devise or custom code
- No MCP server or agent skill; the agent calls the REST API directly
- Some extensions that rely on the legacy frontend do not work with the starter storefront

## Editions

- Free: Free, open source
  - source: https://github.com/solidusio/solidus
  - installable: bundle add solidus && bin/rails generate solidus:install
- Solidus Cloud: price not recorded, closed source
  - hosted: https://solidus.io/enterprise

## Adaptable: make it yours

Effort: light-edit (4 things to edit), surface kind admin-ui

config/initializers/spree.rb (generated from spree.rb.tt) sets Spree.config preferences such as currency, inventory tracking, image attachment modules, admin logo and static payment credentials read from ENV. Store rules (promotions, shipping, tax, payment methods) live in the admin and database. Storefront changes copy the starter frontend into your app and edit views; new behavior is Rails code or extension gems.

- Env vars: SOLIDUS_STRIPE_API_KEY, SOLIDUS_STRIPE_PUBLISHABLE_KEY, SOLIDUS_STRIPE_WEBHOOK_SIGNING_SECRET
- Config files: config/initializers/spree.rb
- Prompt files: none
- Accounts you'll need: payment provider such as Stripe or PayPal (optional)

## Operable: what an agent can drive

Operability: official. Interface: api at https://github.com/solidusio/solidus/tree/main/api (published by the builder, local).

### Reach (partial coverage)

- Manage products, variants and images: reachable. api/config/routes.rb: resources :products, :variants, :images; OAS /products
- Organize taxonomies, taxons, option types and properties: reachable. routes.rb: resources :taxonomies, :taxons, :option_types, :properties
- Create and manage orders: reachable. routes.rb: resources :orders with line_items, payments, coupon_codes; OAS /orders
- Run checkout: reachable. routes.rb: resources :checkouts; api/openapi/checkout-flow.md
- Ship orders and move shipments: reachable. routes.rb: resources :shipments; OAS /shipments/transfer_to_location
- Track inventory and stock locations: reachable. routes.rb: resources :stock_locations, :stock_items, :stock_movements
- Handle returns and customer returns: reachable. routes.rb: resources :return_authorizations, :customer_returns
- Manage users and addresses: reachable. routes.rb: resources :users with address_book. Store credit is read-only: store_credit_events has only mine
- Create promotions: not reachable. routes.rb exposes resources :promotions, only: [:show]; the promotions and legacy_promotions engines route creation only under admin. Coupon codes can be applied to orders, not created
- Configure payment methods, shipping methods and tax rates: not reachable. No routes for them in api/config/routes.rb, only zones and stores; set in the admin or the initializer

## Code stack

- Languages: Ruby, JavaScript
- Frameworks: Ruby on Rails, ViewComponent
- Package manager: bundler
- Database: PostgreSQL, MySQL, SQLite
- Hosting target: any Rails host

## Evidence and confidence

- formFactor: README: Ruby on Rails ecommerce gems with admin and API (confidence 0.95)
- executionModel: no model in the stack (confidence 0.95)
- operability: api/README.md and api/openapi/authentication.md in solidusio/solidus (bearer API key); routes in api/config/routes.rb (confidence 0.85)
- effort: core/lib/generators/solidus/install/templates/config/initializers/spree.rb.tt; storefront/README.md says views are copied into your project (confidence 0.75)
- editions: BSD-3-Clause open source. solidus.io/enterprise offers hosted Solidus Cloud with resource-based pricing and no published price, so price is null (confidence 0.8)
- active: gh api: pushed 2026-11-05; release v4.8.1 on 2026-11-05
- license: LICENSE, solidus.gemspec and the GitHub license API all say BSD-3-Clause on 2026-11-06
- install: guides.solidus.io/getting-started/installing-solidus: bundle add solidus, then bin/rails generate solidus:install
- reach:  (confidence 0.9)
- provenance:  (confidence 0.3)

## Open questions

- Is the openapi file complete against routes.rb? The OAS lists fewer paths than the routes file.
- Solidus Cloud has no published price; the page says to get in touch.

## Sources

- https://solidus.io/ (sourcing:ecommerce:curated)
- https://github.com/solidusio/solidus/tree/main/api (analysis)