Orders

Overview

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

Order Attributes

Attribute	Description
number	The unique identifier for this order. It begins with the letter R and ends in a 9-digit number. This number is shown to the users, and can be used to find the order by calling Spree::Order.find_by(number: number).
item_total	The sum of all the line items for this order.
adjustment_total	The sum of all adjustments on this order.
total	The result of the sum of the item_total and the adjustment_total.
payment_total	The total value of all finalized payments.
shipment_total	The total value of all shipments’ costs.
additional_tax_total	The sum of all shipments’ and line items’ additional_tax.
included_tax_total	The sum of all shipments’ and line items’ included_tax.
promo_total	The sum of all shipments’, line items’ and promotions’ promo_total.
state	The current state of the order. To read more about the states an order goes through, read The Order State Machine section of this guide.
email	The email address for the user who placed this order. Stored in case this order is for a guest user.
user_id	The ID for the corresponding user record for this order. Stored only if the order is placed by a signed-in user.
completed_at	The timestamp of when the order was completed.
bill_address_id	The ID for the related Address object with billing address information.
ship_address_id	The ID for the related Address object with shipping address information.
shipping_method_id	The ID for the related ShippingMethod object.
created_by_id	The ID of object that created this order.
shipment_state	The current shipment state of the order. It takes into account all shipments. Described below in Order Shipment states section.
payment_state	The current payment state of the order. It takes into account all payments. Described below in Order Payment states section.
special_instructions	Any special instructions for the store to do with this order. Will only appear if Spree::Config[:shipping_instructions] is set to true.
currency	The currency for this order, eg. USD
last_ip_address	The last IP address used to update this order in the frontend.
channel	The channel specified when importing orders from other stores. e.g. amazon.
item_count	The total value of line items’ quantity.
approver_id	The ID of user that approved this order.
confirmation_delivered	Boolean value indicating that confirmation email was delivered.
token	The token stored corresponding to token stored in cookies.
canceler_id	The ID of user that canceled this order.
store_id	The ID of Store in which this order was created.

Order methods

Here is a list of methods you may find useful:

Method	Description
outstanding_balance	The outstanding balance for the order, calculated by taking the total and subtracting payment_total.
display_item_total	A “pretty” version of item_total. If item_total was 10.0, display_item_total would be $10.00.
display_adjustment_total	Same as above, except for adjustment_total.
display_total	Same as above, except for total.
display_outstanding_balance	Same as above, except for outstanding_balance.

To see all available methods, please check the Order model source code.

The Order State Machine

Each Order flows through a state machine, beginning at a cart state and ending up at a complete state.

This is the default order flow and can be adjusted or overhauled completely.

More on this topic at Customizing Checkout page.

The default states are as follows:

1. cart

   Initial state, you can treat it as a draft order

2. address

   Buyer started the checkout process and is on the address step

3. delivery

   Buyer has added Shipping and Billing addresses, now he or she needs to select a delivery option

4. payment

   Buyer selected delivery option, now he or she needs to add a payment option

   Only available if Order#payment_required? returns true. For most orders it will be true, but if the order is paid entirely with Store Credit it will be false.

5. confirm

   Buyer added payment option, now he or she needs to confirm the order

   Only available if Order#confirmation_required? returns true

6. complete

   Order was placed. It will set the completed_at date to the current time.

Assuming that an order meets the criteria for the next state, you will be able to transition it to the next state by calling next on that object, eg.

order = Spree::Order.find_by(number: 'R123456')
order.next

If this returns false, then the order does not meet the criteria. To work out why it cannot transition, check the result of an errors method call.

Order Shipment states

Alongside the global Order state there’s also shipment_state column which indicates the state of all shipments. Order can have multiple shipments.

State	Description
shipped	all Shipments are in the shipped state
partial	at least one Shipment has a state of shipped and there is another Shipment with a state other than shipped or there are InventoryUnits associated with the order that have a state of sold but are not associated with a Shipment
ready	all Shipments are in the ready state
backorder	there is backordered inventory associated with an order
pending	all Shipments are in the pending state

For more on this please go to Shipment States page.

Order Payment states

Alongside the global Order state there’s also payment_state column which indicates the state of all payments. Order can have multiple payments.

State	Description
paid	payment_total is equal to total
balance_due	payment_total is less than total
credit_owed	payment_total is greater than total
failed	most recent payment is in the failed state
void	order is canceled and payment_total is equal to zero

For more on this please go to Payment States page.

Line Items

Line items are used to keep track of items within the context of an order. These records provide a link between orders, and Variants.

When a variant is added to an order, the price of that item is tracked along with the line item to preserve that data. If the variant’s price were to change, then the line item would still have a record of the price at the time of ordering.

Addresses

An order can link to two Address objects. The shipping address indicates where the order’s product(s) should be shipped to. This address is used to determine which shipping methods are available for an order.

The billing address indicates where the user who’s paying for the order is located. This can alter the tax rate for the order, which in turn can change how much the final order total can be.

For more information about addresses, please read the Addresses guide.

Adjustments

Adjustments are used to affect an order’s final cost, either by decreasing it (Promotions) or by increasing it (Shipping, Taxes).

For more information about adjustments, please see the Adjustments guide.

Payments

Payment records are used to track payment information about an order. Each Order can hold multiple payments, eg. one for each credit card or debit card and one for the store credit.

For more information, please read the Payments guide.

Return Authorizations

An order can have many ReturnAuthorization objects. These records keeps track of which items have been authorized for return and how the user will be compensated — either via exchanging the item(s) or a reimbursement.

Updating an Order

If you change any aspect of an Order object within code and you wish to update the order’s totals — including associated adjustments and shipments — call the update_with_updater! method on that object, which calls out to the OrderUpdater class.

For example, if you create or modify an existing payment for the order which would change the order’s payment_state to a different value, calling update_with_updater! will cause the payment_state to be recalculated for that order.

Another example is if a LineItem within the order had its price changed. Calling update_with_updater! will cause the totals for the order to be updated, the adjustments for the order to be recalculated, and then a final total to be established.