Initial promotions documentation #2467
Conversation
| - `FirstOrder`: Eligible for a customer's first order only. | ||
| - `FirstRepeatPurchaseSince`: Eligible for a customer's first repeat purchase | ||
| since a specified date. | ||
| - `NthOrder`: Eligible for a customer's *n*th order only. |
There was a problem hiding this comment.
The italics at *n*th order here messes up the syntax highlighting for the rest of the article, but GitHub renders the Markdown fine, and my text editor's syntax highlighting is fine. Weird?
guides/promotions/overview.md
Outdated
| - `apply_automatically`: If `true`, the promotion is activated and applied | ||
| automatically once all of the [eligibility checks](#eligibility) have passed. | ||
|
|
||
| Note that you can access promotion information using the `promotion` method its |
There was a problem hiding this comment.
Was the word "on" missed after the word "method"?
guides/promotions/overview.md
Outdated
| 2. The administrator creates `Spree::PromotionRule`s for the promotion. | ||
| - In this case, they use the rule type "Item Total" | ||
| (`Spree::Promotion::Rules::ItemTotal`) and set the rule so that the | ||
| promotion must be greater than $100 USD. |
There was a problem hiding this comment.
Do you mean the order must be greater than $100 USD?
benjaminwil
force-pushed
the
initial_promotions_documentation
branch
from
b653b23 to
54cfcf8
Compare
guides/promotions/overview.md
Outdated
|
|
||
| Take note of the following promotion attributes: | ||
|
|
||
| - `name`: The administrative name for the promotion. |
There was a problem hiding this comment.
This name will also show up in the adjustment label for promotions that have one of those actions. So it's not entirely limited to admins.
guides/promotions/overview.md
Outdated
| [promotion rules](#promotion-rules) must be met. | ||
| - `path`: If the promotion is activated when the customer visits a URL, this | ||
| value is the path for the URL. | ||
| - `per_code_usage_limit`: Specifies how many codes can be used before the |
There was a problem hiding this comment.
This is how many times each code can be used before becoming inactive. There's also usage_limit which more closely matches the definition here. (How many times the promotion can be applied before becoming inactive.)
guides/promotions/overview.md
Outdated
| Different types of promotions would change the customer's experience of | ||
| promotion activation. For example, the customer might be required to enter a | ||
| promotion code to activate some promotions, while a free shipping promotion | ||
| would be applied automatically. |
There was a problem hiding this comment.
while a free shipping promotion would be applied automatically.
That isn't always the case. You could have free shipping that only applies after a customer enters a code or visits a specific page.
| - `CreateQuantityAdjustments`: Creates per-quantity adjustments. For example, | ||
| you could create an action that gives customers a discount on the first three | ||
| t-shirts that they order. | ||
| - `FreeShipping`: Creates an adjustment that subtracts all shipping charges. |
There was a problem hiding this comment.
I would use "negates" instead of "subtracts", but that might just be personal preference.
| model][promotion-actions]: | ||
|
|
||
| - `CreateAdjustment`: Creates a single adjustment for the current | ||
| `Spree::Order`. |
There was a problem hiding this comment.
Creates a single adjustment associated to the order. I might also add something about not recommending its use. Order-level adjustments don't work particularly well with taxes or refunds.
| - `CreateAdjustment`: Creates a single adjustment for the current | ||
| `Spree::Order`. | ||
| - `CreateItemAdjustments`: Creates an adjustment for each `Spree::LineItem` in | ||
| the current order. |
There was a problem hiding this comment.
Will create adjustments on each applicable line item. (e.g.: If there's a product rule, it will only apply to products matching the rule.)
| the current order. | ||
| - `CreateQuantityAdjustments`: Creates per-quantity adjustments. For example, | ||
| you could create an action that gives customers a discount on the first three | ||
| t-shirts that they order. |
There was a problem hiding this comment.
Creates adjustments based on groups of items, not just the first set of matching items. So the action would apply based on the number of groups of t-shirts.
e.g.: 0-2 shirts - doesn't apply, 3-5 shirts - applies once, 6-8 shirts - applies twice, etc.
| ## Register a custom promotion action | ||
|
|
||
| You can create a new promotion action for Solidus by creating a new class that | ||
| inherits from `Spree::PromotionAction`: |
There was a problem hiding this comment.
I might also mention that it must implement the perform(options = {}) method that should return a boolean declaring whether the action was applied successfully.
Also, that it's recommended that it define a remove_from(order) as well.
guides/promotions/promotion-rules.md
Outdated
| - `FirstRepeatPurchaseSince`: Eligible for a customer's first repeat purchase | ||
| since a specified date. | ||
| - `NthOrder`: Eligible for a customer's *n*th order only. | ||
| - `ItemTotal`: Eligible if the order total is less than or greater than a |
There was a problem hiding this comment.
I would try to be more specific that it's the order's item total. (i.e.: Before taxes/shipping/other discounts/etc.)
guides/promotions/promotion-rules.md
Outdated
|
|
||
| Note that whenever an order, line item, or shipment with a promotion adjustment | ||
| on it is updated, the [eligibility][eligibility] of the promotion is re-checked | ||
| and the promotion actions are re-applied. |
There was a problem hiding this comment.
the promotion actions are re-applied.
Might be a bit misleading. The action isn't really re-applied. The amount will be re-calculated and the eligibility of the adjustment will be changed based on the eligibility and if the amount becomes $0. But I'm pretty sure all of the logic in the action's perform(options = {}) method won't be re-run.
|
@adammathys Thanks for your review. I've addressed your comments. If you could re-review whenever you've got a chance that'd be great. 👍 |
benjaminwil
force-pushed
the
initial_promotions_documentation
branch
from
ea25f74 to
a4c28c9
Compare
This section gives a high-level overview of what happens when a promotion is being added in the backend, then how it gets applied when a customer is checking out. This example uses a free shipping promotion, since that would be a very typical use case for promotions. There is still room for examples that create other types of discounts.
Thanks to adammathys for his review.
I ported the Spree promotions guide, rewrote, and expanded it to be a number of articles.
I have not yet mentioned all of the aspects of the promotions system. For example, I didn't even acknowledge that
Spree::PromotionCodeexists. But what's in this PR is a good starting point. Future promotions documentation PRs will be smaller.There is some repetition between the
overview.mdand other articles, but I think introducing major concepts in an overview article is helpful.I would appreciate any feedback you have.
This is part a larger project to improve Solidus's documentation. See this gist with the high-level table of contents. Where and how this documentation will exist is still up for discussion.