anchor.diff:  ==== Usage Modes
   
  -Kill Bill supports invoicing customers based on their usage data, and the definition of such pricing scheme is defined in the catalog.
  -The `Plan` section of the Kill Bill catalog can contain one or several `usage` section(s) to define how customers will be billed.
  -These sections can be defined in addition to other non usage based billing pricing scheme, such as fixed or recurring price.
  +Kill Bill supports billing customers based on their usage data, and the pricing schemes for this billing are defined in the Kill Bill catalog.
  +The `Plan` section of the catalog can contain one or several `usage` section(s) to define how customers will be billed.
  +These sections can be defined in addition to other, non usage based, billing schemes, such as fixed or recurring price.
   
  -Each usage section will need to specify a `billingMode`:
  -The only billing mode supported today is the `IN_ARREAR` mode, which allows to bill customer based on usage data from previous periods.
  -We plan to add the `IN_ADVANCE` mode in the future to support prepaids-like scenario -- e.g toll bridge pass -- where consumer purchases a
  -certain number of units *in advance* and such units are decremented as consumer uses the service.
  +Each usage section will need to specify a `billingMode`.
  +The only billing mode supported today is the `IN_ARREAR` mode, which allows customers to be billed based on usage data from previous periods.
  +We plan to add the `IN_ADVANCE` mode in the future to support prepaid scenarios such as toll bridge pass, where the customer purchases a
  +certain number of units *in advance* and such units are decremented as the customer uses the service.
   
  -Each usage section will also need to specify a `usageType` and along with it, specify the `unit` (types) for which customer is being billed for -- e.g cell phone/minutes.
  +Each usage section will also need to specify a `usageType` and along with it, specify the `unit` (types) for which the customer is being billed, such as cell phone/minutes.
   The usage type can be one of the following:
   
  -* `CONSUMABLE` : This is is used for defining prices that are based on the number of units (of a certain types) being consumed -- e.g water consumed in the last period. 
  -* `CAPACITY` : This is used for defining prices that are based on rates or upper bound values. In this scheme, we bill based on the maxium value seeing over the period -- e.g MBytes/sec
  +* `CONSUMABLE` : This is used for defining prices that are based on the number of units (of a certain types) being consumed -- e.g water consumed in the last period. 
  +* `CAPACITY` : This is used for defining prices that are based on rates or upper bound values. In this scheme, we bill based on the maximum value that was seen over the period -- e.g MBytes/sec
   
  -The following http://killbill.io/blog/usage-billing[ blog post] provides additional context about this use cases.
  +The following http://killbill.io/blog/usage-billing[ blog post] provides additional context about these use cases.
   
  -For each usage section, we support defining pricing *tiers* to allow billing customer differently based on their usage.
  -Such tiers work differently depending of the usage type, `CONSUMABLE` versus `CAPACITY`.
  +For each usage section, we support defining pricing *tiers*, allowing customers to be billed differently based on their usage.
  +These tiers work differently depending on the usage type, `CONSUMABLE` or `CAPACITY`.
   
   Each usage section also needs to define the `billingPeriod` -- e.g `MONTHLY` -- to define how often and for which period consumers are being billed.
   
   ===== Consumable In Arrear Mode
   
  -In this mode, each `tier` definition contains a `tieredBlock`, that defines the limits and price associated to a particular `unit` type. We support two `TierBlockPolicy` policies:
  +In this mode, each `tier` definition contains a `tieredBlock` that defines the limits and price associated with a particular `unit` type. We support two `TierBlockPolicy` policies:
   
  -* `ALL_TIER`: Users are charged across each tier based on their usage; the idea is to offer some form of tiered pricing where the upper level prices can be charged to a lower amount -- e.g clould usage where we want to reward users to consume more -- or higher -- e.g electricy bill to discourage users to consume more.
  -* `TOP_TIER`: In this model we still go through each tier, but end up charging everything at the top tier pricing. In this model, it probably makes sense to offer lower pricing for the top tier, this is a rewarding model.
  +* `ALL_TIER`: This policy charges users across each tier based on their usage. Higher prices are charged to the less preferred tier. This may be a lower tier, e.g for cloud usage where we want to reward users who consume more, or a higher tier, e.g for an electric bill where we want to encourage users to consume less.
  +* `TOP_TIER`: With this policy we still go through each tier, but everything is charged at the top tier pricing. Here it makes sense to offer lower pricing for the top tier, since this is a rewarding model.
   
   
   ===== Consumable In Arrear Mode: `ALL_TIER`
   
  -Let's start with an example of a `tieredBlock` definition: The following tier block section defines the pricing for the `cell-phone-minutes` unit, and can be understood the following way:
  +To demonstate the `ALL_TIER` policy, let's start with an example of a `tieredBlock` definition. The following tier block section defines the pricing for the `cell-phone-minutes` unit, and can be understood the following way:
   
   [source,bash]
   ----
  
positive.code: </tiers>
  ----
  
  In the `CONSUMABLE` mode, when defining usage section with multiple unit (types), it is important to realize that the consumer *is charged independently
  for each unit*, so for example, with the definition provided above:
  
  Given the following usage data for the period:
  
  * 1500 cell-phone-minutes
  * 2048 Mbytes
  
  The total amount would be 739.4 and is calculated as follows;
  
  Each unit is billed separately as;
  
  cell-phone-minutes:
  
  
negative.code: * The first `100` blocks of this size will be priced at 1.00 EUR
  * If a consumer uses more than `100` blocks of this size, he will be charged at the price of the next tier.
  
  As mentioned previously, each usage section can contain multiple tiers and also charge for multiple unit types.
  The following section shows the defintion for 2 units, *cell-phone-minutes* and *Mbytes*, and defines two tiers.
  The `max` value for the last tier is defined with *-1* which represents an unbounded value:
  
  [source,bash]
  ----
  