From cd1266813c64ed2583952f9b84c651608b72122f Mon Sep 17 00:00:00 2001 From: Benjamin Willems Date: Tue, 23 Jan 2018 13:02:59 -0800 Subject: [PATCH 1/2] Add docs that summarize promotion calculators --- guides/calculators/promotion-calculators.md | 163 ++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 guides/calculators/promotion-calculators.md diff --git a/guides/calculators/promotion-calculators.md b/guides/calculators/promotion-calculators.md new file mode 100644 index 00000000000..d55165492ca --- /dev/null +++ b/guides/calculators/promotion-calculators.md @@ -0,0 +1,163 @@ +# Promotion calculators + +Promotion calculators are similar to [shipping +calculators][shipping-calculators]: the calculate against your preferred +amounts, percentages, and currencies. The main difference is that promotions +adjust prices as discounts rather than charges. + +Solidus includes a number of built-in promotion calculators. Because promotions +can adjust orders, line items, or shipping charges, note that some of the +built-in calculators can only be used on a subset of promotions. + +The rest of this article summarizes the available promotion calculators, grouped +by the types of promotions they can calculator (either order, line item, or +shipment promotions). + +[shipping-calculators]: shipping-calculators.md + +## Order or line item promotions + +The following calculators are available to use on whole-order or line item +promotions: + +- [Flat rate](#flat-rate) +- [Flexi rate](#flexi-rate) +- [Tiered percent](#tiered-percent) + +### Flat rate + +The [`Spree::Calculator::FlatRate` calculator][flat-rate] has the following +preferences: + +- `amount`: The amount per item to calculate. +- `currency`: The currency. The default value is your store's default currency + setting. + +This calculator takes the total of an applicable order or line item and +discounts a percentage of it. + +### Flexi rate + +The [`Spree::Calculator::FlexiRate` calculator][flexi-rate] provides a flexible +rate depending on the items on an order. (Or, a subset of specific line items on +an order.) It has the following preferences: + +- `first_item`: The discounted price of the first item(s). +- `additional_item`: The discounted price of subsequent items. +- `max_items`: The maximum number of items this discount applies to. +- `currency`: The currency. The default value is your store's default currency + setting. + +### Tiered percent + +The [`Spree::Calculator::TieredPercent` calculator][tiered-percent] provides a +tiered percent discount. This allows you to charge a percentage-based discount +that depends on the order total (or applicable line items). For example, you +could set a base discount of 10%, then give a greater discount on orders over +$100, $200, and $500: + +| | Tier | Discount (%) | +|---|------------------|--------------| +| 0 | Base | 10% | +| 1 | Orders over $100 | 15% | +| 2 | Orders over $200 | 20% | +| 3 | Orders over $500 | 25% | + +This calculator has the following preferences: + +- `base_percent`: The base discount for any order where the promotion applies. +- `tiers`: A hash where the key is the minimum order total for the tier and the + value is the tier discount: `{ tier=>discount_percentage }`. +- `currency`: The currency. The default value is your store's default currency + setting. + +[flat-rate]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/flat_rate.rb +[flexi-rate]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/flexi_rate.rb +[tiered-percent]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/tiered_percent.rb + +## Order promotions only + +The following calculators are available to use with order promotions only: + +- [Tiered flat rate](#tiered-flat-rate) +- [Flat percent (item total)](#flat-percent-item-total) + +### Tiered flat rate + +The [`Spree::Calculator::TieredFlatRate` calculator][tiered-flat-rate] provides +a tiered flat rate discount. This allows you to charge a rate-based discount +that depends on the order total. For example, you could set a base discount of +$10, then give a greater discount on orders over $100, $200, and $500: + +| | Tier | Discount ($) | +|---|------------------|--------------| +| 0 | Base | $10 | +| 1 | Orders over $100 | $15 | +| 2 | Orders over $200 | $20 | +| 3 | Orders over $500 | $25 | + +This calculator has the following preferences: + +- `base_amount`: The base discount for any order where the promotion applies. +- `tiers`: A hash where the key is the minimum order total for the tier and the + value is the tier discount: `{ tier=>discount_amount }`. +- `currency`: The currency. The default value is your store's default currency + setting. + +### Flat percent (item total) + +The [`Spree::Calculator::FlatPercentItemTotal`][flat-percent-item-total] +calculator provides a flat, percentage-based discount on an order. In the +`solidus_backend` interface administrators can use this calculator by choosing +the whole-order calculator labeled "Flat Percent". It has the following +preference: + +- `flat_percent`: The percentage that the order should be discounted. + +[tiered-flat-rate]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/tiered_flat_rate.rb +[flat-percent-item-total]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/flat_percent_item_total.rb + +## Line item promotions only + +The following calculators are available to use with line item promotions only: + +- [Distributed amount](#distributed-amount) +- [Percent on line item](#percent-on-line-item) + +### Distributed amount + +The [`Spree::Calculator::DistributedAmount` calculator][distributed-amount] +provides an amount-based discount on all of the applicable line items in an +order. The discount amount is distributed across all of the line items. + +For example, if your promotion offers a $5 discount and a customer orders a $20 +item as well as a $10 item, then the discount is distributed across both items: +$3.33 (on the $20 item) and $1.67 (on the $10 item). + +This calculator has the following preferences: + +- `amount`: The discount amount given if the line items should be discounted. +- `currency`: The currency. The default value is your store's default currency + setting. + +### Percent on line item + +The [`Spree::Calculator::PercentOnLineItem` calculator][percent-on-line-item] +provide a percentage-based discount for each applicable line item in an order. +In the `solidus_backend` interface, this calculator is labeled "Percent Per +Item". It has the following preference: + +- `percent`: The percentage discount that should be given to each applicable + line item. + +[distributed-amount]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/distributed_amount.rb) +[percent-on-line-item]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/percent_on_line_item.rb) + +## Free shipping promotions + +You can create promotions that negate all shipping charges on an order. This +type of promotion does not require a specific calculator. Instead, it uses the +[`Spree::Promotion::Action::FreeShipping` promotion +action][free-shipping-promotion-action] directly. + +[free-shipping-promotion-action]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/promotion/actions/free_shipping.rb From b19be58f9fbbe593d7fb5a8e5d3e85739af49585 Mon Sep 17 00:00:00 2001 From: Benjamin Willems Date: Wed, 14 Mar 2018 15:08:26 -0700 Subject: [PATCH 2/2] Revise promotion calculators docs after PR review Thanks to gmacdougall and kennyadsl for their reviews. --- guides/calculators/promotion-calculators.md | 30 +++++++++++++-------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/guides/calculators/promotion-calculators.md b/guides/calculators/promotion-calculators.md index d55165492ca..a0c632e2053 100644 --- a/guides/calculators/promotion-calculators.md +++ b/guides/calculators/promotion-calculators.md @@ -1,7 +1,7 @@ # Promotion calculators Promotion calculators are similar to [shipping -calculators][shipping-calculators]: the calculate against your preferred +calculators][shipping-calculators]: they calculate against your preferred amounts, percentages, and currencies. The main difference is that promotions adjust prices as discounts rather than charges. @@ -39,35 +39,43 @@ discounts a percentage of it. ### Flexi rate The [`Spree::Calculator::FlexiRate` calculator][flexi-rate] provides a flexible -rate depending on the items on an order. (Or, a subset of specific line items on -an order.) It has the following preferences: +rate depending on the number of items on an order. -- `first_item`: The discounted price of the first item(s). -- `additional_item`: The discounted price of subsequent items. +For example, you could sell one t-shirt for $20. But, if the customer buys five +t-shirts, the four additional t-shirt only costs $15. + +It has the following preferences: + +- `first_item`: The discount rate of the first item(s). +- `additional_item`: The discount rate of subsequent items. - `max_items`: The maximum number of items this discount applies to. - `currency`: The currency. The default value is your store's default currency setting. +To replicate the example above, you could set the `first_item` to `0.0`, the +`additional_item` to `5.0`, and the `max_items` to `5`. + ### Tiered percent The [`Spree::Calculator::TieredPercent` calculator][tiered-percent] provides a tiered percent discount. This allows you to charge a percentage-based discount -that depends on the order total (or applicable line items). For example, you -could set a base discount of 10%, then give a greater discount on orders over -$100, $200, and $500: +that depends on the order total (or applicable line items). + +For example, you could set a base discount of 10%, then give a greater discount +on orders over $100 and $200: | | Tier | Discount (%) | |---|------------------|--------------| | 0 | Base | 10% | | 1 | Orders over $100 | 15% | | 2 | Orders over $200 | 20% | -| 3 | Orders over $500 | 25% | This calculator has the following preferences: - `base_percent`: The base discount for any order where the promotion applies. - `tiers`: A hash where the key is the minimum order total for the tier and the - value is the tier discount: `{ tier=>discount_percentage }`. + value is the tier discount. Using the example from the table above, the hash + could read: `{ $100=>15%, $200=>20% }`. - `currency`: The currency. The default value is your store's default currency setting. @@ -143,7 +151,7 @@ This calculator has the following preferences: ### Percent on line item The [`Spree::Calculator::PercentOnLineItem` calculator][percent-on-line-item] -provide a percentage-based discount for each applicable line item in an order. +provides a percentage-based discount for each applicable line item in an order. In the `solidus_backend` interface, this calculator is labeled "Percent Per Item". It has the following preference: