RubyGems - workarea - Versions diffs - 3.4.16 → 3.4.17 - Mend

workarea 3.4.16 → 3.4.17

Files changed (572) hide show

data/docs/source/articles/order-pricing.html.md DELETED Viewed

@@ -1,389 +0,0 @@
----
-title: Order Pricing
-excerpt: This document provides information to help you develop the skills of explaining and extending order pricing.
----
-Order Pricing
-======================================================================
-To facilitate [orders](orders.html)—transactions between shoppers and retailers, often including [shipping](shipping.html)—Workarea must reliably compute the prices for these transactions.
-These computations include the price of each order item, potentially adjusted for customizations, overrides, and discounts;
-and the overall price of the order, including shipping and tax, also potentially adjusted.
-Fortunately, Workarea computes this information automatically and does not require any developer intervention.
-However, as a developer, you must be prepared to _explain_ the pricing of a specific order or all orders to a retailer.
-For example, a retailer may ask you why the total price of a particular order was unexpectedly low.
-Or, you may need to explain why Workarea is computing tax subtotals differently than the retailer's accounting department.
-Furthermore, you may need to _extend_ the pricing logic for a retailer, perhaps to charge a fee for gift wrapping, or to replace Workarea's tax calculations with those from an integrated service.
-This document provides information to help you develop the skills of __explaining__ and __extending__ order pricing.
-After reviewing an __example__ order and some shared __context__, you will learn the primary concepts to help you develop these skills.
-Specifically, to explain _why_ an order is priced as it is, you should work backward from __pricing totals__, which are computed from __price adjustments__ by __pricing totals objects__.
-To explain _how_ price adjustments are created, you should examine __pricing calculators__.
-And to _change_ how price adjustments are created, you should implement your own pricing calculators which honor the __pricing calculator contract__, and re-configure the __pricing calculators collection__ to contain your custom calculators.
-We'll explore each of these topics in turn, but first let's make things more concrete with an example.
-Example Order
-----------------------------------------------------------------------
-Throughout this document, we'll use a specific order as a running example.
-The following diagrams represent Storefront views of this order:
-![Order pricing cart example](../images/order-pricing-cart-example.png)
-![Order pricing placed order example](../images/order-pricing-placed-order-example.png)
-The first diagram represents the order as a cart, while the second represents the same order after a shipping address is provided.
-Both views of the order include computed pricing information.
-The top two rows of each diagram represent _item-level_ prices, while the table following the line items represents _order-level_ prices.
-_All_ of this pricing information is computed repeatedly until the order is placed.
-Order Pricing in Context
-----------------------------------------------------------------------
-The pricing information for each order must be re-computed continually because Workarea's commerce model is cyclical.
-Shoppers shop and admins manage, changing the states of various domain models.
-The current states of these models must be reflected in the prices shown to shoppers and authorized on their payments.
-The following diagram (adapted from [Commerce Model](commerce-model.html)) represents this cycle:
-![Order pricing within the commerce model](../images/commerce-model-order-pricing.png)
-Shoppers _create and manage carts_ by adding, removing, and updating order items and promo codes.
-Shoppers additionally set the shipping address and shipping service within checkout, allowing them to _place the orders_.
-Simultaneously, admins (and/or automated systems integrated with Workarea) _manage the catalog_ and _merchandise the store_ by manipulating SKU prices, sales, discounts (on items, orders, and shippings), shipping services, and tax rates.
-To account for these ongoing changes, Workarea re-prices each cart before showing it to the shopper, including each checkout screen.
-Each time a cart is priced, the results are a "snapshot" of the pricing for the transaction at that moment in time.
-At the conclusion of checkout, when the order is placed, the pricing information is computed one last time and persisted as a permanent record (on the order, items, and shippings).
-Familiarity with this lifecycle is indispensable when developing the skills of explaining and extending order pricing.
-Let's move on to those specific skills.
-Skill: Explaining Order Pricing
-----------------------------------------------------------------------
-From a system architecture perspective, `Pricing.perform` is the API call responsible for pricing orders.
-Additionally, when setting the shipping address and shipping service in checkout, a call to `Shipping#set_shipping_service` precedes `Pricing.perform` to initiate pricing.
-However, when a retailer questions the pricing of an order, you can likely trace their inquiry to a specific total or subtotal.
-They may think the _total price_ of a particular order seems too low or the _tax subtotal_ seems to be off by a cent or two for most orders.
-Therefore, to explain _why_ an order is priced as it is, you should work backward from __pricing totals__, which are computed from __price adjustments__ by __pricing totals objects__.
-### Pricing Totals
-_Pricing totals_ are computed money values stored within fields on each order, its items, and its associated shippings.
-These fields represent the total price and various subtotals of the order transaction.
-Many of these values are displayed to the shopper directly.
-Examples are highlighted in the following diagram, which also indicates the underlying API calls to query the values.
-![Totals within order pricing example](../images/order-pricing-example-totals.png)
-There are additional totals fields, which are not shown in the above diagram.
-For example, the total of each shipping is shown only when an order has multiple shippings.
-Also, the total _value_ of an order or item is displayed in some Admin screens and used for calculations, such as discounts.
-The following code example queries for _all_ pricing totals for our example order:
-```ruby
-order_id = '123321'
-order = Workarea::Order.find(order_id)
-items = order.items
-shippings = Workarea::Shipping.by_order(order.id).to_a
-puts order.subtotal_price
-# 250.00
-puts order.shipping_total
-# 10.00
-puts order.tax_total
-# 2.00
-puts order.total_price
-# 202.00
-puts order.total_value
-# 190.00
-puts items.first.total_price
-# 100.00
-puts items.first.total_value
-# 76.00
-puts items.last.total_price
-# 150.00
-puts items.last.total_value
-# 114.00
-puts shippings.first.shipping_total
-# 10.00
-puts shippings.first.tax_total
-# 2.00
-```
-Querying the pricing totals for an order transaction is an important first step toward explaining the pricing for the order.
-From a pricing total, you can work backward to specific __price adjustments__, which we explore next.
-### Price Adjustments
-_Price adjustments_ are documents embedded within order items and shippings that represent the "raw" pricing data for the order.
-This data is used to calculate the order totals.
-It may be helpful to think of the order totals as a credit card receipt which shows only a summary of what was charged to your card, while the price adjustments are collectively the "itemized" receipt with more granular details.
-While most price adjustments are used internally—to compute totals—some are shown directly to shoppers.
-The following diagram highlights and annotates the values in our placed order example that are read directly from price adjustments.
-![Adjustments within order pricing example](../images/order-pricing-example-adjustments.png)
-To explain the pricing for an order, look up the relevant adjustments.
-Remember that these are documents embedded within the order's items and shippings.
-The following code example queries for _all_ price adjustments for our example order:
-```ruby
-item_price_adjustments = items.map(&:price_adjustments).reduce(&:+)
-shipping_price_adjustments = shippings.map(&:price_adjustments).reduce(&:+)
-all_price_adjustments = item_price_adjustments + shipping_price_adjustments
-all_price_adjustments.count
-# => 10
-all_price_adjustments.first.class
-# => Workarea::PriceAdjustment
-```
-To understand how adjustments become totals, first examine a single price adjustment.
-Most notably, it has a money `:amount`, either postive or negative, and a `:price`, which you should think of as a price _type_.
-The price type is always one of `'item'`, `'order'`, `'shipping'`, or `'tax'`, and these are sometimes additionally referred to as "levels" (e.g. item-level vs order-level).
-The adjustment document also has several metadata fields describing the price, including `:description`.
-Now consider the adjustments in aggregate again.
-The following diagram creates a visual "stack" of the adjustments for our example order, each with its amount, price type, and description.
-![Price adjustments diagram](../images/price-adjustments-diagram.png)
-To calculate `Order#total_price`, Workarea simply sums _all_ the amounts:
-![Order total price diagram](../images/order-total-price-diagram.png)
-All other order totals (i.e. subtotals) are calculated by summing a _subset_ of the same price adjustments.
-The logic for each totals field is based on the adjustment price types and the objects on which they are stored.
-For example, `Order#subtotal_price` is calculated by summing only the _item-level_ adjustments.
-![Order subtotal price diagram](../images/order-subtotal-price-diagram.png)
-Similarly, the shipping and tax totals are calculated by summing only the _shipping_ and _tax_ adjustments, respectively:
-![Order shipping total diagram](../images/order-shipping-total-diagram.png)
-![Order tax total diagram](../images/order-tax-total-diagram.png)
-The total price for each _item_ is the sum of the item-level adjustments stored within that particular item.
-The following diagram represents the total for the second item:
-![Order item total price diagram](../images/order-item-total-price-diagram.png)
-As a final example, the _total value_ of an order is the sum of its item- and order-level adjustments, or explained differently: the value of the _merchandise_, which includes most discounts, but excludes shipping and tax. (Expect a retailer or another developer to ask you about this; it's a common question).
-![Order total value diagram](../images/order-total-value-diagram.png)
-( If you're wondering why items embed both item- and order-level adjustments, or why some adjustments are embedded within shippings instead of items, we'll cover that with __pricing calulators__. )
-The lesson here is each total can be deconstructed into a subset of the order transaction's price adjustments.
-Recall the recipe for this: work backward from pricing totals, which are computed from price adjustments by __pricing totals objects__.
-We'll therefore look at pricing totals objects next.
-### Pricing Totals Objects
-_Pricing totals objects_ are the objects responsible for calculating and writing the pricing totals to the order, items, and shippings each time an order is priced.
-They encapsulate the logic for creating each pricing total from the "stack" of price adjustments for a given order and shippings.
-Therefore, to deconstruct a total into price adjustments, you must look up the logic for that total within a pricing totals object, and reverse it.
-The specific API calls that calculate and write the pricing totals are `OrderTotals#total` and `ShippingTotals#total`.
-To find the implementations of these methods within your application or plugin, run the following command from your project's root:
-```bash
-find $(bundle show workarea-core) -path '*/app/*/pricing/*_totals.rb'
-```
-This command lists the pathnames of the classes where these methods are defined within your project.
-Open the classes in your editor and locate the code assigning a value to the totals field you are trying to deconstruct.
-From there, you can see which price adjustments factor into that total.
-You may want to literally or metaphorically create a diagram like those above that show which of the adjustments contribute to a particular total.
-(
-Pricing totals objects use a special-purpose collection class, `PriceAdjustmentSet`, to subset and sum adjustments, thus creating totals.
-These collections are effectively arrays with a few additional methods that encapsulate the logic for subsetting and summing based on the price type of the adjustments.
-If you find these collections unintuitive, review the class definition and Mongoid extension that provides their behavior.
-)
-```bash
-find $(bundle show workarea-core) -path '*/app/*/price_adjustment_*.rb'
-```
-After you've identified specific price adjustments, look at them more closely.
-In addition to amount, price (type), and description, each adjustment has the additional fields `:calculator` and `:data`:
-```ruby
-sample_price_adjustment = all_price_adjustments.sample
-sample_price_adjustment.calculator
-# => "Workarea::Pricing::Calculators::ItemCalculator"
-sample_price_adjustment.data
-# => {"on_sale"=>true, "original_price"=>125.0, "tax_code"=>"simple"}
-```
-The `:calculator` field indentifies the class of object that created the adjustment when the order was last priced.
-That calculator determined the amount and price of the adjustment, and wrote the adjustment's description and additional metadata, which it stored in the adjustment's `:data` field.
-These details may provide enough information to answer the retailer's question about the order's pricing.
-When these details are _not_ enough, you'll have to dig deeper to explore _how_ the price adjustment was created.
-As the name of the `:calculator` field implies, price adjustments are created by __pricing calculators__.
-### Pricing Calculators
-_Pricing calculators_ are objects that _adjust_ the pricing of an order transaction by creating price adjustments on the items and shippings during the pricing of the order.
-More specifically, each calculator inherits from `Pricing::Calculator` and implements `Pricing::Calculator#adjust`.
-This method encapsulates the logic for creating the price adjustments the calculator is responsible for.
-During the pricing of an order, each calculator is given the opportunity to adjust the order pricing by writing adjustments to the items and shippings.
-This process is managed by `Pricing.perform`, which begins by clearing all price adjustments from the order's items and shippings.
-(There is one type of adjustment that isn't cleared, for historical reasons, which is the adjustment that shippings write to themselves, outside of `Pricing.perform`.
-These adjustments represent the price of the shipping service for each shipping.)
-`Pricing.perform` then calls `#adjust` on each pricing calculator, providing it the opportunity to create price adjustments on the items and shippings.
-This process builds the price adjustment stack that you've seen many times above.
-The following diagram illustrates this process for our example order.
-The order has two items and one shipping.
-The example shown represents the final pricing of the order, during the "place order" action.
-The pricing process begins with a single price adjustment on the shipping.
-Each calculator then has the opportunity to adjust the pricing; some do nothing while other create adjustments (which are highlighted).
-The end result is the familiar stack of price adjustments used to calculate the pricing totals.
-![Pricing calculators diagram](../images/pricing-calculators-diagram.png)
-It's important to understand this overall process because each calculator has access to the adjustments created by the calculators that precede it.
-Knowledge of the process therefore helps you understand each calculator's implementation of `#apply`, which are not explained in this document.
-Some of these implementations are quite complex and defer to other subsystems, such as discounts and taxes.
-Until each of these implementations can be sufficiently documented, you'll need to explore them on your own.
-The following command prints the pathnames of all pricing calculators available to your application:
-```bash
-find $(pwd) $(bundle show --paths | grep workarea) \
--path '*/app/*/pricing/calculators/*.rb'
-```
-Plugins and applications can also provide their own pricing calculators, which is the basis of __extending order pricing__.
-Skill: Extending Order Pricing
-----------------------------------------------------------------------
-Sometimes, the business requirements of a retailer require you to do more than _explain_ order pricing; you must _extend_ it.
-A retailer may add a new feature that affects pricing, such as offering gift wrapping for a fee; or they may want to replace an existing feature, such as using an integrated service to calculate taxes rather than Workarea's default logic.
-Fortunately, for requirements such as these, Workarea provides a clear path for extension.
-To extend pricing, you must change how price adjustments are created.
-To do this, you should implement your own pricing calculators which honor the __pricing calculator contract__, and re-configure the __pricing calculators collection__ to include your custom calculators.
-(
-It's worth mentioning that you should first look for a [plugin](https://plugins.workarea.com) that does what you need.
-I borrowed this document's use cases from existing plugins.
-)
-### Pricing Calculator Contract
-To create your own pricing calculator, define a class which satisfies the _pricing calculator contract_.
-Fundamentally, this is a class which includes `Pricing::Calculator` and implements `Pricing::Calculator#apply`.
-(
-I'll continue to explain this process conceptually, but for a more detailed, procedural explanation of creating your own pricing calculators, see [Add or Replace a Pricing Calculator](add-or-replace-a-pricing-calculator.html).
-)
-`Pricing::Calculator#apply` has access to several objects and collections via the methods `#order`, `#shippings`, `#pricing`, and `#discounts`; and it must satisfy two responsibilities: determine which objects should receive the price adjustments, and create the price adjustments on those objects.
-To determine the objects, start with this simple rule: create _item_ and _order_ adjustments on _items_, and create _shipping_ and _tax_ adjustments on _shippings_.
-This rule follows the logic of the Core calculators, which write shipping and tax adjustments to shippings because those adjustments require a shipping address to compute.
-However, your calculator may need to look for _specific_ items and shippings.
-For example, the customizations calculator creates adjustments for only those items that include customizations.
-Adjustments to the entire order, say _$50 off your entire order_, must be distributed across the items, since the order has no price adjustments of its own.
-Also, the retailer likely wants the cost distributed in the case of a customer returning a single item.
-To create the adjustments, use `Order::Item#adjust_pricing` or `Shipping#adjust_pricing`, and provide the following `PriceAdjustment` attributes:
-| Attribute      | Description |
-| -------------- | ----------- |
-| `:amount`      | The money amount which may be displayed and will contribute to pricing totals |
-| `:price`       | The type of adjustment, either `'item'`, `'order'`, `'shipping'`, or `'tax'`, which determines to which totals the amount contributes and where it's displayed |
-| `:description` | A brief description of the adjustment, which may display directly to shoppers |
-| `:calculator`  | The class of your calculator, as a string |
-| `:data`        | A hash of additional data for audit and/or implementation purposes; see base calculators for examples |
-After creating a calculator that meets these requirements, you must manipulate the __pricing calculators collection__ to include your calculator.
-### Pricing Calculators Collection
-The _pricing calculators collection_ is a configurable value—a [SwappableList](swappable-list-data-structure.html)—which holds the ordered list of pricing calculators which can adjust the pricing of orders during each `Pricing.perform`.
-In other words, the list of which pricing calculators run, in which order, is configurable.
-The following code example queries the current configuration of an application:
-```ruby
-Workarea.config.pricing_calculators.class
-# => Workarea::SwappableList
-puts Workarea.config.pricing_calculators
-# Workarea::Pricing::Calculators::ItemCalculator
-# Workarea::Pricing::Calculators::CustomizationsCalculator
-# Workarea::Pricing::Calculators::OverridesCalculator
-# Workarea::Pricing::Calculators::DiscountCalculator
-# Workarea::Pricing::Calculators::TaxCalculator
-```
-You must modify this list to include your custom pricing calculator.
-Use the methods of [SwappableList](swappable-list-data-structure.html) to insert your calculator before or after an existing calculator, or to replace an existing calculator.
-You should _replace_ a calculator when you want to _change_ how its price adjustments are created, like using a tax service integration to create tax adjustments, rather than Workarea's tax subsystem.
-In contrast, _insert_ your calculator to add an _additional_ upcharge for a feature, such as gift wrapping.
-When inserting a new calculator, its position in the list is important.
-The default calculator order obeys the following logic:
-1. Start with a subtotal for each item
-2. Add the cost of any customizations (e.g. engraving)
-3. Reduce the item or order cost according to order-specific overrides (e.g. a customer service credit)
-4. Apply discounts
-5. Calculate tax
-You should not change the sequence of the default calculators, since they depend on this order.
-For example, an item subtotal must be present before an override can reduce its price, and all other prices must be determined before tax can be calculated.
-When inserting a new calculator, determine where it fits into this logic.
-In most cases, a new calculator is added to create an additional upcharge, and should therefore be inserted after the customizations calculator (which performs a similar function).
-However, review the logic above, and determine where your calculator fits.
-Summary
-----------------------------------------------------------------------
-Workarea handles the complication of computing order prices, but you should develop the skills of explaining and extending order pricing.
-Both skills depend on a knowledge of Workarea's cycle of commerce, which requires all orders to be continually re-priced until they are placed.
-To explain a cart or placed order's pricing, start from one or more pricing totals, which are money fields on the order, items, and shippings.
-Deconstruct those fields back into price adjustments, documents embedded in items and shippings that represent the raw pricing data for that order.
-To do so, look at the implementations of the pricing totals objects, specifically the `#total` method, which encapsulates the logic to go from adjustments to totals.
-Examine the fields of the price adjustments, and attempt to explain the order's pricing from that data.
-If insufficient, use the meta data on the price adjustments to identify which pricing calculators created them.
-Study the implementation of `#apply` for each calculator to see in more detail how each price was created.
-To extend the pricing logic, define your own pricing calculators, each of which must implement an `#apply` method that creates price adjustments on zero or more of the items and shippings that make up an order.
-Ensure that each price adjustment has an amount, price, and metadata such as description and calculator.
-Include each of your pricing calculators in the configurable pricing calculators collection, either as a new calculator or as a replacement for an existing calculator.
-Always preserve the order of the default calculators, while placing new calculators in a logical postion within the collection.

data/docs/source/articles/orders-and-items.html.md DELETED Viewed

@@ -1,210 +0,0 @@
----
-title: Orders & Items
-excerpt: Orders are transactions between consumers and the retailer. Consumers create orders in the Storefront, as carts, to which they add items (and optionally promo codes). Consumers complete checkouts, thereby placing their orders. The placed orders, which
----
-# Orders & Items
-[Orders](orders.html) are transactions between consumers and the retailer. Consumers create orders in the Storefront, as carts, to which they add items (and optionally promo codes). Consumers complete checkouts, thereby placing their orders. The placed orders, which act as permanent records of the transactions, are accessible to the retailer through the Admin.
-The `Order` class (which is also a module/namespace) is the primary model representing these transactions. Each order [document](application-document.html) represents an order through its entire life cycle, from cart through order management. An order model therefore fulfills the roles of purchase order, invoice, and detailed receipt for a transaction.
-The `Order` model and its embedded items identify the consumer and the items that make up the transaction and their prices. More specifically, a placed order is composed of the following data:
-- The identity of the consumer and their environment
-- One or more items, each composed of:
-  - A SKU, quantity, and additional details to identify and price the item
-  - One or more price adjustments representing granular pricing details
-  - The calculated item-level price totals
-- Zero or more promo codes, which may affect item and order pricing
-- The calculated order-level price totals
-## Consumer & Environment
-Each order stores information identifying the consumer, who is either a guest, a user, an admin guest browsing, or an admin impersonating a user.
-At a minimum, a placed order has an email:
-```
-order = Workarea::Order.sample
-# => #<Workarea::Order _id: 39F628D36D, ... >
-order.email
-# => "bobbyclams@workarea.com"
-```
-An order may have additional contextual information, such as the consumer’s IP address and an order _source_, such as `'storefront'`, `'admin'`, or `'api'`:
-```
-order.ip_address
-# => "127.0.0.1"
-order.source
-# => "storefront"
-```
-Orders placed by users, admins impersonating users, and admins guest browsing will additionally store the IDs of both users as the `user_id` and `checkout_by_id`. These values are foreign keys that relate the order to `User` models. Similarly, orders placed through a web browser store the `user_activity_id`, which relates the order to a `UserActivity` model<sup><a href="#notes" id="note-1-context">[1]</a></sup>.
-```
-order.user_id
-# => "5ab2b5b3eefbfe12dbb4b44b"
-order.user_activity_id
-# => "5ab2b5b3eefbfe12dbb4b44b"
-order.checkout_by_id
-# => "5ab2b5b3eefbfe12dbb4b44b"
-```
-Additional details about the consumer, such as name and shipping and billing addresses, are stored on other models and are not a concern of the `Order` model.
-## Items
-Each order contains _items_, an embedded collection of type `Order::Item`.
-```
-order.items.count
-# => 2
-order.items.first.class
-# => Workarea::Order::Item
-```
-Each item document contains the data the retailer needs to fulfill the item (SKU, quantity, and customizations), additional data to calculate the price(s) of the item (SKU details), and records of the actual prices calculated (price adjustments and item totals).
-### SKU, Quantity & Details
-Each item represents a good or service from the retailer’s catalog, identified by its _SKU_. Typically, the SKU and quantity provide the minimum data required to fulfill the item. However, some items allow customization by the consumer (for example engraving or monogramming), in which case additional data is collected to perform the customization during fulfillment.
-```
-item = order.items.first
-# => #<Workarea::Order::Item _id: 5ab2b5eceefbfe12dbb4b451, ... >
-item.sku
-# => "524376751-4"
-item.quantity
-# => 1
-item.customizations
-# => {}
-```
-In most cases, additional details are saved on the item to ensure the item is priced accurately. The pricing subsystem uses a series of calculators to determine the total price of each item and the order overall. These calculators often depend on the additional item details to calculate pricing as expected. These details include the product ID and attributes (the entire product model, serialized), the categories in which the product appears, and whether the item is discountable.
-```
-item.product_id
-# => "66BC7BEA53"
-pp item.product_attributes.keys
-# ["_id",
-# "tags",
-# "active",
-# "subscribed_user_ids",
-# "details",
-# "filters",
-# "template",
-# "purchasable",
-# "name",
-# "digital",
-# "description",
-# "slug",
-# "updated_at",
-# "created_at",
-# "variants"]
-pp item.category_ids
-# ["5ab2b04beefbfe1185011c9d",
-# "5ab2b04beefbfe1185011c9f",
-# "5ab2b04beefbfe1185011c9b"]
-item.discountable
-# => true
-```
-The forthcoming guide, “Managing Carts”, will describe API calls for fetching these details and storing them on the order item.
-### Price Adjustments
-Each time an order is priced, the granular pricing details are stored on the item as _price adjustments_, an embedded collection of type `Workarea::PriceAdjustment`. These embedded documents provide the necessary details to determine the total price of an item (in the case of a cart) and a record of how that price was determined (in the case of a placed order).
-```
-item.price_adjustments.count
-# => 2
-price_adjustment = item.price_adjustments.last
-# => #<Workarea::PriceAdjustment _id: 5ab2b0a2eefbfe11850123f2, ... >
-price_adjustment.amount.to_f
-# => -8.32
-price_adjustment.description
-# => "10% Off Order"
-```
-Item pricing is volatile; prices fluctuate and vary based on quantity, sales, discounts, and other factors. The unit price of an item and the adjustments that may apply due to active discounts and other factors are likely to change from order to order, and may even change within the lifespan of a single cart. Therefore, each order is continually re-priced until it is placed.
-While the details of order pricing and price adjustments are outside the scope of this guide, one detail is notable here: order items and [shippings](shipping.html) are the only models that embed price adjustments. All _order_ and _item_ adjustments are stored on an order’s _items_, while all _shipping_ and _tax_ adjustments are stored on the _shippings_ related to the order.
-### Item Totals
-Additionally, each time an order is priced, the total price and value<sup><a href="#notes" id="note-2-context">[2]</a></sup> of each item are written onto the item as fields. These values provide a snapshot of the “agreed upon” price of the item, as calculated by the pricing module. The consumer can metaphorically “negotiate” this price by shopping at a different time (during a sale or promotion) or applying promo codes to the order.
-In the case of a cart, these values may change before the order is placed. The values are displayed to the consumer when viewing the cart and throughout checkout. In the case of a placed order, these represent the price at which the item sold, which may differ for another consumer purchasing the same item or the same consumer when placing a different order.
-```
-item.total_price.to_f
-# => 83.24
-item.total_value.to_f
-# => 74.92
-```
-## Promo Codes
-Returning to the order, in addition to items, consumers can add promo codes, which may qualify the order or its items for discounts, resulting in more favorable pricing for the consumer. Unlike items, which are embedded documents, promo codes are simply strings stored in an array on the order.
-```
-order.promo_codes
-# => ["10PERCENTOFF"]
-```
-The order model provides API calls to add promo codes, which ensure the collection contains only unique, uppercase string values. The forthcoming “Managing Carts” guide will cover this topic.
-## Order Totals
-Similarly to item totals, when the pricing module prices an order, it writes the order-level totals to the order as fields. For a cart, these values represent the last calculated “asking price” of the order, and for a placed order they represent the final transaction prices. The Storefront displays these values in the cart and checkout for the consumer, and the Admin displays these values to the retailer in the order administration screens and reports.
-```
-order.subtotal_price.to_f
-=> 153.23
-order.shipping_total.to_f
-=> 7.0
-order.tax_total.to_f
-=> 10.14
-order.total_price.to_f
-=> 155.05
-order.total_value.to_f
-=> 137.91
-```
-While the full details of pricing are outside the scope of this guide, note that subtotal price is derived from the price adjustments stored on the _items_, while the shipping and tax totals are derived from the price adjustments stored on the related _shippings_.
-## Summary
-- Orders build and record consumer/retailer transactions, which contain the consumer’s identity, the items being transacted, and the “current” pricing as calculated by the pricing subsystem
-- Each item on an order contains the SKU and quantity, along with other details to accurately price the item
-- Consumers can add promo codes to the order, which may also affect pricing
-- Pricing is recorded on each item as granular price adjustments and calculated item-level totals, and on the order as calculated order-level totals
-## Notes
-[1] User activity is an aspect of the Workarea recommendations subsystem that will be covered in more detail in future documentation.
-[2] Upcoming pricing documentation will describe the concept of price vs value.

data/docs/source/articles/orders.html.md DELETED Viewed

@@ -1,66 +0,0 @@
----
-title: Orders
-excerpt: 'Workarea applications facilitate orders: transactions between consumers and retailers. Due to their complexity, orders are enabled by and recorded across many models within the Workarea platform. More specifically, various models within the Order, Shi'
----
-# Orders
-Workarea applications facilitate <dfn>orders</dfn>: transactions between consumers and retailers. Due to their complexity, orders are enabled by and recorded across many models within the Workarea platform. More specifically, various models within the `Order`, `Shipping`, `Payment`, `Pricing`, `Inventory`, and `Fulfillment` modules enable and record these transactions.
-However, at the core of each of these transaction is an `Order` model. The order model uniquely identifies the transaction, and using its `id`, you can join the various models, providing a complete record of the transaction.
-## Seeding Order Data
-Workarea provides [seeds](seeds.html) for orders, which are defined in `Workarea::OrdersSeeds`. This seeds script creates a variety of placed orders, as well as the user, shipping, and payment data needed to place those orders.
-Each order is placed through <dfn>checkout</dfn>, a process that joins an order with the other models necessary to represent a complete consumer/retailer transaction.
-Finally, the script _fulfills_ each order, which involves capturing the associated payment and marking the items shipped.
-## Joining Order Data
-Using the first seeded order as its subject, the following example demonstrates how you can join an order model with the corresponding shippings, payment, inventory transactions, and fulfillment. In practice, this sort of in-application join is typically performed in a [view model](view-models.html).
-```
-order = Workarea::Order.first
-shippings = Workarea::Shipping.where(order_id: order.id).to_a
-# => [#<Workarea::Shipping _id: 5a95ab0707dd423bb63a92d0, ...>]
-payment = Workarea::Payment.find(order.id)
-# => #<Workarea::Payment _id: 048E031F8B, ...>
-inventory_transactions =
-  Workarea::Inventory::Transaction.where(order_id: order.id).to_a
-# => [#<Workarea::Inventory::Transaction _id: 5a95ab0a07dd423bb63a931, ...>]
-fulfillment = Workarea::Fulfillment.find(order.id)
-# => #<Workarea::Fulfillment _id: 048E031F8B, ...>
-```
-## The Order Module
-As you can see in the example above, the `id` of the Order model is what relates the various models. Central to order modeling is the `Order` module and its primary models: `Order` and `Order::Item`.
-The following order module topics are pertinent to Workarea application and plugin developers:
-- [The _order_ and _order item_ abstractions](orders-and-items.html)
-  - What they represent
-  - How they are structured
-- Order statuses and states
-- Managing carts
-- Indexing and searching for orders
-- Managing placed orders
-- Exporting orders
-- Canceling orders
-- Copying orders
-- Order reporting and insights
-- Extending orders
-## Summary
-- Orders are transactions between consumers and retailers, which are represented by various models within the Workarea platform
-- The model central to a consumer/retailer transaction is `Order`; its `id` joins the other models
-- The platform provides seeds to bootstrap an environment with placed orders
-- Forthcoming guides will explain the order and item abstractions and the various uses of orders within the platform