Overview

The Spree::Order model is one of the key models in Solidus. It provides a central place around which to collect information about a customer order. It collects line items, adjustments, payments, addresses, return authorizations, and shipments.

Whenever information about the order is updated, the Spree::OrderUpdater should update the order. If your store creates or changes the functionality around the order, you may need to manually call the order updater .

Orders have the following attributes:

  • number: The unique identifier for this order generated by Spree::Order::NumberGeneratr. It begins with the letter R and ends in a nine-digit number (for example, R123456789). This number is shown to the users, and can be used to find the order by calling Spree::Order.find_by(number: "R123456789").
  • item_total: The sum of all the line items for this order.
  • total: The sum of the item_total and the adjustment_total attributes.
  • state: The current state of the order. See the Order state machine article for more information.
  • adjustment_total: The sum of all adjustments on this order.
  • user_id: The ID for the order's corresponding user. Stored only if the order is placed by a signed-in user.
  • completed_at: The timestamp that logs when the order is completed.
  • bill_address_id and ship_address_id: The IDs for the related Spree::Address objects with billing and shipping address information.
  • payment_total: The sum of all the finalized payments on the order.
  • shipment_state: The current shipment state of the order.
  • payment_state: The current payment state of the order. <!-- TODO: Add link. -->
  • email: The customer-provided email address for the order. This is stored in case the order is for a guest user.
  • special_instructions: Any special shipping instructions that shave been specified by the customer during checkout.
  • currency: The currency for this order. Determined by the Spree::Config[:currency] value that was set at the time of order.
  • last_ip_address: The last IP address used to update this order in the frontend.
  • created_by_id: The ID of object that created this order.
  • shipment_total: The sum of all the shipments associated with an order.
  • additional_tax_total: The sum of all the additional_tax_totals (sales tax) on an order's line items and shipments.
  • promo_total: The sum of all of the promo_totals on an order's shipments, line items, and promotions.
  • channel: The channel specified when importing orders from other stores. For example, if you operate as an Amazon Seller and import orders from Amazon, some orders may have a channel value of amazon. Otherwise, this value is spree.
  • included_tax_total: The sum of all the included_tax_totals (value-added tax) on an order's line items and shipments.
  • item_count: The total amount of line items associated with the order.
  • approver_id: The ID of user that approved the order.
  • approver_name: The name of the user that approved the order.
  • approved_at: The timestamp logging when this order is approved by the approver.
  • confirmation_delivered: Boolean value that indicates that an order confirmation email has been delivered.
  • guest_token: The guest token that links an uncompleted order to a specific guest user (via browser cookies).
  • canceler_id: The ID of user that canceled this order.
  • canceled_at: If the order is cancelled, this timestamp logs when the order was cancelled.
  • store_id: The ID of Spree::Store in which the order has been created.

Because orders are so integral to Solidus, there are a number of methods available that let you easily display order totals and subtotals. For more information, see the Display totals methods article.

The Spree::Order model touches many other models. This section highlights essential models that orders depend on and links to their existing documentation.

Line items

The Spree::LineItem model provides the cost of each item added to an order. Line items provide a link between the order and Spree::Products and Spree::Variants.

Adjustments

The Spree::Adjustment model provides the cost of each adjustment to an order, line item, or shipment on an order. Adjustments can decrease the total (via promotions) or increase it (via shipments and taxes ).

Shipments

The Spree::Shipment model creates shipments according to the items in an order. An order may have multiple shipments: this depends on your store's configured shipping categories and shipping methods and the item in the order.

Shipments use Spree::InventoryUnits. An inventory unit is created for each item added to an order for the purpose of tracking what order and shipment an item belongs to. Inventory units provide a link between the order and Spree::Shipments.

For more information, see the Shipments documentation.

Addresses

The Spree::Address model stores customer addresses and shares them with the order via the ship_address_id and bill_address_id. An order may have one or two different addresses associated it, depending on the customer's preferred shipping and billing address.

Payments

The Spree::Payment model stores payment information for the order. Once the payment object is updated with the amount paid, this updates the corresponding order's payment_total value.

Return Authorizations

The Spree::ReturnAuthorization model stores information about customers returns that have been authorized by an administrator.

Feedback

Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.