Merge pull request #2459 from benjaminwil/adjustments_documentation

Adjustments documentation

guides/adjustments/overview.md

@@ -0,0 +1,155 @@
+# Overview of adjustments
+
+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](#adjustment-sources) (a tax
+rate or promotion action), and then affect the total price of an
+[adjustable](#adjustables) (an order, line item, or shipment).
+
+<!-- TODO:
+  Add links to documentation about orders, line items, and shipments.
+-->
+
+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.
+
+<!-- TODO:
+  Add links to taxation documentation.
+-->
+
+## 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, tax adjustments are always applied before promotional 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.
+
+<!-- TODO:
+  Add links to relevant taxation documentation.
+-->
+
+## Adjustables
+
+Adjustables are the objects whose prices can be adjusted. The following objects
+can be adjustables:
+
+- `Spree::Order`: The adjustment for an entire order.
+- `Spree::LineItem`: The adjustment for a single line item on 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](adjustment-scopes.html.markdown) `charge` or `credit` to
+retrieve only positive or negative amounts.
+
+## Adjustment scopes
+
+You can call [scopes][rails-scopes] on `Spree::Adjustment`s 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 the ID `1`.
+- `Spree::LineItem.find(1).adjustments.eligible`: Returns all of the eligible
+  adjustments on the line item with the ID `1`.
+- `Spree::Shipment.find(1).adjustments.eligible`: Returns all of the eligible
+  adjustments on the shipment with the 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.
+
+<!-- TODO:
+  Add link to taxation documentation to `is_included` item in the list.
+-->
+
+[rails-scopes]: http://guides.rubyonrails.org/active_record_querying.html#scopes
+
+## Adjustment associations
+
+`Spree::Order`s, `Spree::LineItem`s, and `Spree::Shipment`s are all
+[adjustables](#adjustables).
+
+To retrieve these adjustments on an order, call the `adjustments`
+association:
+
+```ruby
+Spree::Order.find(1).adjustments
+```
+
+If you want to retrieve the line item adjustments, you can use the
+`line_item_adjustments` method:
+
+```ruby
+Spree::Order.line_item_adjustments
+```
+
+Or, if you want to retrieve the shipment adjustments, you can use the
+`shipment_adjustments` method:
+
+```ruby
+Spree::Order.shipment_adjustments
+```
+
+Finally, if you want to retrieve all of the adjustments on the order, you can
+use the `all_adjustments` method.
+
+```ruby
+Spree::Order.all_adjustments
+```
+