Overview

The Spree::Adjustment model is used to track price adjustments. For example, taxes and promotions generate price adjustments. Adjustments can be either a positive or a negative amount.

Adjustments values come from adjustment sources (for example, a tax rate or a promotion action ), and they affect the total price of an adjustable (an order , line item, or shipment ).

Adjustments have the following attributes:

• adjustable_type and adjustable_id: The object being adjusted. This object is a specific order, line item, or shipment.
• source_type and source_id: The source of the adjustment – typically a tax rate or a promotion action.
• amount: The dollar amount of the adjustment.
• label: The label for the adjustment. This indicates what the adjustment is for.
• eligible: Indicates whether the adjustment is eligible to adjust the object it is associated with.
• included: If set to true, the adjustment amount is included in the final price of the object it is associated with. Otherwise, the adjustment is added to the total price. This property only applies to tax adjustments. See the taxation documentation for more information.
• finalized: Indicates whether the adjustment is finalized. If set to true, then the adjustment is no longer automatically updated.

Adjustment sources

Adjustment values are sourced from other objects. Typically, a Spree::TaxRate or a Spree::PromotionAction provide the amount value to an adjustment.

The following objects are the sources of adjustments:

• Spree::PromotionAction: An amount generated by promotion rules.
• Spree::TaxRate: An amount generated by a tax rate.
• Spree::UnitCancel: The amount of an inventory unit that was ordered but never shipped.
• Spree::ReturnAuthorization: The amount from a line item that is being returned.

Tax adjustments

Note that tax adjustments may be treated differently than promotional adjustments in some circumstances:

• By default, promotional adjustments are always applied before tax adjustments. This is to comply with well-known tax regulations. See the taxation documentation for more information.
• Typically, an adjustment's value is added to the price of the object it is associated with. However, value-added tax adjustments are already included in the price and do not change any totals.

Adjustables

Adjustables are objects whose prices can be adjusted, and include:

• Spree::Order: The adjustment for an entire order.
• Spree::LineItem: The adjustment for a single line item of an order.
• Spree::Shipment: The adjustment for the price of shipping.

Charges vs. credits

Adjustments can be positive or negative amounts. For convenience, you can use the adjustment scopes charge or credit to retrieve only positive or only negative amounts.

Adjustment scopes

You can call scopes on Spree::Adjustments themselves or on any class that has an adjustments association – like orders, line items, and/or shipments.

For example, you can find all of the adjustments with an eligible value of true for orders, line items, and shipments:

• Spree::Order.find(1).adjustments.eligible: Returns all of the eligible adjustments on the order with ID 1.
• Spree::LineItem.find(1).adjustments.eligible: Returns all of the eligible adjustments on the line item with ID 1.
• Spree::Shipment.find(1).adjustments.eligible: Returns all of the eligible adjustments on the shipment with ID 1.

List of adjustment scopes

• tax: Returns adjustments sourced from a Spree::TaxRate object.
• price: Returns adjustments that adjust a Spree::LineItem object.
• shipping: Returns adjustments that adjust a Spree::Shipment object.
• promotion: Returns adjustments sourced from a Spree::PromotionAction object.
• return_authorization: Returns adjustments sourced from a Spree::ReturnAuthorization object.
• eligible: Returns adjustments that are eligible to adjust the adjustable object that they are associated with. For example, if a tax adjustment is eligible, it would be successfully applied to its line item.
• charge: Returns adjustments with a positive value.
• credit: Returns adjustments with a negative value.
• is_included: Returns adjustments that are included in the object's price. Typically, only value-added tax adjustments have this value.
• additional: Adjustments which modify the object's price. The default for all adjustments.

Adjustment associations

Spree::Orders, Spree::LineItems, and Spree::Shipments are all adjustables .

To retrieve these adjustments on an order, call the adjustments association:

    
      Spree::Order.find(1).adjustments

    
  

If you want to retrieve the line item adjustments, you can use the line_item_adjustments method:

    
      Spree::Order.find(1).line_item_adjustments

    
  

Or, if you want to retrieve the shipment adjustments, you can use the shipment_adjustments method:

    
      Spree::Order.find(1).shipment_adjustments

    
  

Finally, if you want to retrieve all of the adjustments on the order, you can use the all_adjustments method.

    
      Spree::Order.find(1).all_adjustments