DOCSEARCHbyAlgolia
Submit Docs

Solidus Guides

website·Indexed 35 days ago

https://guides.solidus.io/

Developer guides and how-to documentation for Solidus, covering topics such as customizing return eligibility rules, calculating return refunds, and managing state machines across versions 4.1 through 4.6 and Next.

Tokens
454.1K
Snippets
2.2K
Records
2.9K
Agent score
41%

What's inside Solidus

  1. Overview of Solidus payment and refund architecture

    Solidus uses a layered architecture for payments and refunds to allow for granular customization and integration with various Payment Service Providers (PSPs). The system is composed of the following core components:

    • Payment Gateways: The lowest level of abstraction; these provide the specific logic required to integrate with a PSP's API (often built on ActiveMerchant).
    • Payment Sources: Models that store information about how a user pays (e.g., credit cards). Reusable sources can be stored in a user's wallet.
    • Payment Methods: Represent the way a customer pays (e.g., PayPal, Stripe, Check). They act as the primary interface for Solidus, delegating calls to payment gateways or providing custom logic for 'virtual' methods (like store credit) that don't require a PSP.
    • Payments (Spree::Payment): Connects user input to the system, associating an order, a payment source, and a payment method. It uses a state machine to track the payment status.
    • Refunds (Spree::Refund): Separate models associated with a payment, allowing flexible refund processing via the #perform! method.

  2. Overview of Solidus Tax Calculation Architecture

    Solidus uses a flexible taxation system centered around tax calculators. These classes implement the logic for calculating taxes on orders and shipping rates.

    While the default system relies on a hierarchy of Tax Categories, Tax Rates, and Rate Calculators, developers can bypass this by implementing a custom tax calculator that uses its own logic (e.g., calling an external API).

    Key Components:

    • Tax Categories: Group tax rates together; assigned to products and shipping methods.
    • Tax Rates: Associate a tax category with a geographic zone and a rate calculator; determines if tax is included in the price.
    • Rate Calculators: Perform the actual math to convert a tax rate into a final currency amount.
    • Tax Calculators: The top-level classes that orchestrate the taxation process for orders and shipping rates.

  3. Overview of Solidus Tax Calculation Architecture

    Solidus uses a flexible taxation system centered around tax calculators. These classes implement the logic for calculating taxes on orders and shipping rates.

    Key components of the default system include:

    • Tax Categories: Group tax rates together; assigned to products and shipping methods.
    • Tax Rates: Associate a tax category with a geographic zone and a rate calculator, and determine if tax is included in the price.
    • Rate Calculators: Perform the actual mathematical conversion of a tax rate into a final currency amount.

    While default tax calculators delegate math to rate calculators, custom tax calculators can be implemented to use independent logic (e.g., external API calls) without relying on rate calculators.

  4. Overview of the legacy Solidus promotions system architecture

    The legacy Solidus promotions system (used up to Solidus 5) uses a rule-based architecture to apply discounts to orders, line items, or shipping fees. It consists of four primary components:

    • Promotion Handlers: Ruby objects that activate a promotion at a specific step in the customer experience (e.g., during shipping or payment).
    • Promotion Rules: Logic that determines if an order is eligible for a promotion (e.g., checking if the order total exceeds a certain amount).
    • Promotion Actions: Logic that defines the actual discount to be applied to eligible orders (e.g., applying free shipping).
    • Adjustments: Records that store the discount information. These are recalculated whenever the order is updated to ensure eligibility still persists.

    Note: Adjustments are a general concept and are also used for other order modifications, such as taxes.

  5. Overview of Solidus authorization architecture

    Solidus manages authorization using a combination of the CanCanCan library and an internal user role system. The architecture consists of three main components:

    1. The Ability Class: A CanCanCan class that defines granular permissions on resources and the conditions under which they are granted.
    2. Permission Sets: Classes that encapsulate groups of related permissions (e.g., StockManagement). These are applied to the user's ability.
    3. Role Configuration: Associates user roles (stored via Spree::RoleUser) with specific collections of permission sets. By default, Solidus provides default (customer) and admin (super-admin) roles.

    When a user is authenticated, Solidus retrieves their roles, collects the associated permission sets, and applies them to the current ability. Unauthenticated users are assigned the default role.

  6. Overview of Solidus authorization architecture

    Solidus manages authorization using a combination of the CanCanCan library and an internal user role system. The architecture consists of three main components:

    1. The Ability Class: A CanCanCan class that defines permissions on resources and the conditions under which they are granted. Solidus uses a custom ability class to support permission sets.
    2. Permission Sets: Classes that encapsulate groups of related permissions (e.g., StockManagement). These are applied to the user's ability.
    3. Role Configuration: Associates user roles (stored in the Spree::RoleUser model) with collections of permission sets. By default, Solidus provides default (customer) and admin (super-admin) roles.

    Permission Resolution Process:

    • If authenticated, Solidus retrieves the user's roles; otherwise, it assumes the default role.
    • It collects all permission sets associated with those roles.
    • It applies those permission sets to the current ability object.

  7. Overview of the Solidus eCommerce platform

    Solidus is a free, open-source eCommerce platform built as a Ruby on Rails engine. It provides a fully functional backend and a strong foundation for production-grade online stores. Because it is built as a Rails engine, it is highly flexible, allowing developers to customize any aspect of the platform using built-in configuration hooks, extensions, or native Ruby and Rails override mechanisms.

  8. Overview of the Solidus eCommerce platform

    Solidus is a free, open-source eCommerce platform built as a Rails engine on the Ruby on Rails framework. It provides a fully functional backend and a strong foundation for production-grade online stores. The platform is designed for high flexibility, allowing developers to customize any aspect of the system using built-in configuration hooks, extensions, or native Ruby and Rails override mechanisms.

  9. Overview of Solidus Payment System Architecture

    Solidus uses a layered architecture for payments and refunds to allow for granular customization and flexibility across different Payment Service Providers (PSPs). The system consists of five primary domain concepts:

    1. Payment Gateways: The lowest level; contains the logic for integrating with a specific PSP's API (often built on ActiveMerchant).
    2. Payment Sources: Models that store payment information (e.g., credit card details). Reusable sources can be stored in a user's wallet.
    3. Payment Methods: Represent the way a customer pays (e.g., PayPal, Stripe, Check). They act as an abstraction layer between Solidus and the Payment Gateway, allowing for 'virtual' methods (like cash on delivery) that don't require a PSP.
    4. Payments (Spree::Payment): The connector between user input and the system, associated with an order, a payment source, and a payment method. It uses a state machine to track processing status.
    5. Refunds (Spree::Refund): Separate models associated with a payment, providing a flexible way to handle money returns via the #perform! method.

  10. Overview of the legacy Solidus promotions system architecture

    The legacy Solidus promotions system (used up to Solidus 5) is a rule-based engine that applies discounts to orders, line items, or shipping fees. It relies on four primary concepts:

    • Promotion Handlers: Trigger the activation of a promotion at specific stages of the customer experience (e.g., during shipping info entry).
    • Promotion Rules: Determine if an order is eligible for a promotion based on specific criteria (e.g., order total exceeds $100).
    • Promotion Actions: Define the actual discount to be applied to eligible orders (e.g., free shipping).
    • Adjustments: Store the discount information. These are recalculated whenever the order is updated to ensure eligibility still holds.

  11. Overview of Solidus Stock Management Architecture

    The Solidus stock system manages the transition of an order to the delivery state. The process is orchestrated by a stock coordinator (default: Spree::Stock::SimpleCoordinator), which builds proposed shipments and available shipping rates for an order.

    If the delivery state is removed or overridden in the order state machine, the stock coordinator will not be called automatically, and must be invoked manually.

    The workflow is split into two main phases:

    1. Package Creation: Determining which stock locations to use and grouping inventory units into packages.
    2. Rate Estimation: Converting packages into shipments and calculating shipping costs based on available methods.

  12. Overview of Solidus tax calculation architecture

    Solidus uses a flexible taxation system based on tax calculators. These classes implement the logic for calculating taxes on orders and shipping rates. The default system relies on three main components:

    • Tax Categories: Groups of tax rates assigned to products and shipping methods.
    • Tax Rates: Associate a tax category with a geographic zone and a rate calculator; they also define if tax is included in the price.
    • Rate Calculators: Perform the actual mathematical conversion of a tax rate into a final currency amount.

    Developers can customize taxation by either writing a custom rate calculator (for specific rates) or replacing the entire tax calculator (for maximum flexibility, such as integrating an external API).