Merge pull request #2678 from benjaminwil/returns_docs/reimbursements

Add documentation for Spree::Reimbursements and Spree::ReimbursementTypes

guides/returns/reimbursement-types.md

@@ -0,0 +1,47 @@
+# Reimbursement types
+
+<!-- TODO:
+  This article is a stub. It is not yet a good indicator of how reimbursement
+  types should be used, or how they relate to reimbursements and return items.
+-->
+
+Each [return item][return-items] should be associated with one of your store's
+`Spree::ReimbursementType`s.
+
+By default, the `solidus_backend` interface offers one reimbursement type to
+store administrators: `Spree::ReimbursmentType::StoreCredit`. When a
+`Spree::Reimbursement` is created with this type, a
+`Spree::Reimbursement::Credit` is created for the full amount each return item
+associated with the reimbursement.
+
+Solidus provides some other [built-in reimbursement types][reimbursement-types]
+that you can register and use in your store.
+
+[reimbursement-types]: https://github.com/solidusio/solidus/tree/master/core/app/models/spree/reimbursement_type
+[return-items]: return-items.md
+
+## Preferred and override reimbursement types
+
+Each `Spree::ReturnItem` object has the following attributes that link the item
+to a reimbursement type:
+
+- `preferred_reimbursement_type_id`: The ID for the reimbursement type that was
+  first set for the return item.
+- `override_reimbursement_type_id`: An optional reimbursement type that
+  overrides the preferred reimbursement type.
+
+When a store administrator is ready to reimburse the customer, they can override
+the preferred reimbursement type for another one. This allows store
+administrators to change a customer return to satisfy the customer without
+losing the history of the customer return.
+
+## Reimbursement types helpers
+
+Solidus's built-in reimbursement types extend the
+[`Spree::ReimbursementType::ReimbursementHelpers`
+class][reimbursement-helpers-class], which is where much of their core
+functionality originates. If you need to make your own reimbursement types, or
+you want a better understanding of how reimbursement types work, see the source
+code.
+
+[reimbursement-helpers-class]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/reimbursement_type/reimbursement_helpers.rb 

guides/returns/reimbursements.md

@@ -0,0 +1,28 @@
+# Reimbursements
+
+<!-- TODO:
+  This article is a stub.
+-->
+
+A `Spree::Reimbursement` represents your store's compensation to the customer
+who is returning items. For example, if a customer is not happy with the quality
+of your product and they decide to return it, your store may want to offer them
+store credit for the price of the item.
+
+A `Spree::Reimbursement` can represent the reimbursement of one or many
+`Spree::ReturnItem`s. However, if the return items have different
+`Spree::ReimbursementType`s assigned, then multiple reimbursements are created
+for a single customer return.
+
+Each `Spree:Reimbursement` object has the following attributes:
+
+- `number`: A unique eleven-character number that identifies the reimbursement.
+  The number starts with `RI`. For example: `RI123456789`.
+- `reimbursement_status`: The status of the current reimbursement.
+- `customer_return_id`: The ID for the `Spree::CustomerReturn` that is
+  associated with this reimbursement.
+- `order_id`: The ID for the `Spree::Order` that is associated with the items on
+  the reimbursement.
+- `total`: The total value of the reimbursement. Depending on the
+  `Spree::ReimbursementType`, this value may be `nil`.
+