SpreeGuides Notes

Spree guides notes

Spree Guides

Products

1. Track uniq products
2. Option Types -> denote the different options for a variant
3. Option Values -> values for option types
4. Product must be assigned at least one option type if you wish to create variants for that product
5. Variants -> individual variants of a Product
6. Master Variant -> tracks basic information such as a count on hand, a price and a SKU
7. Master Variant -> automatically created along with a product
8. Normal Variant -> which are not the master variant are unique based on option types and option values combinations
9. Product Properties -> track individual attributes for a product which don’t apply to all products
10. Product Properties -> common to all variants for a product with same value
11. Prototypes -> way to share common Option Types and Property combinations amongst many different products
12. Taxons -> robust way of categorising products
13. Taxonomy -> hierarchical list which is made up of individual Taxons. Each taxonomy relates to one Taxon, which is its root node.
14. Both taxons and taxonomies are ordered by their position attribute
15. Images-> link to a product through its master variant
16. Images -> sub-variants for the product may also have their own unique images to differentiate them in the frontend
17. Price -> presence or lack of a price for a variant in a particular currency will determine if that variant is visible in the frontend

Orders
1. Information about a customer’s order
2. Flow through state machine, cart -> complete
3. State Machine states => cart -> address -> delivery -> payment -> confirm -> complete
4. Payment state if payment_required? -> true
5. Confirm state if confirmation_required? -> true
6. Complete state if -> no payment required or all payment is done
7. LineItems-> keep track of items within the context of an order
8. Addresses -> order can link to 2 addresses viz. Shipping Address & Billing Address
9.  Adjustments -> affect an order’s final cost by decreasing it (Promotions) or by increasing it (Shipping, Taxes)
10. Payments -> track payment information about an order
11. to update the order’s totals – including associated adjustments and shipments – call the `update_with_updater!` method on that object, which calls out to the `OrderUpdater` class

Payments
1. Multiple payment methods e.g. cheque, card etc.
2. Payment Methods typically represents payment gateways
3. Payments States 
        1.  checkout -> Checkout not completed
        2.  processing -> being processed but not complete, intended to prevent double submissions
        3. pending -> authorised but not captured
        4. failed -> rejected
        5. void -> should not be counted against order
        6. completed -> only these payments count against order total
4. Payment Methods -> different options a customer has for making a payment
5. Payment Methods -> its visibility depends upon criteria set by `PaymentMethod.available` class method
6. Override `auto_capture?` method to override `Spree::Config[:auto_capture]` preference
7. Add `Rails.application.config.spree.payment_methods << YourCustomGateway` to `spree.rb` to add custom payment methods
8. If configured to auto_capture -> `Payment#purchase!` will be called which in turn will call `PaymentMethod#purchase`
        1. If success -> payment is marked `completed`
        2. If unsuccessful -> `failed`
9. If not configured to auto_capture -> `Payment#authorize!` will be called which in turn will call `PaymentMethod#purchase`
        1. If successful -> payment is marked `pending` which then can be captured manually by `capture!`
        2. If unsuccessul -> `failed`
10. Return object from 8, 9 points above is `ActiveMerchant::Billing::Response` which in turn is stored in `spree_log_entries` table as YAML

Promotions
1. Used to give order discounts, add items at no extra costs
2. Can be activated when -
    1. item added to cart
    2. Coupon code
    3. Page visit
3. Activated through `PromotionHandler` Class once checked for eligibility
4. It has `Action` and `Rules`.
    1. Actions - when a promotion is activated its actions are performed
    2. Rules - define for eligibility criteria
5. Actions -
    1. Order Level Adjustment - 
        1. adjustment automatically applied to order
        2. Eligibility rechecked every time when order is saved
    2. Item Level Adjustment -
        1. Adjustment applied to each item Automatically
        2. Eligibility is checked every time a item is updated
    3. Free Shipping - 
        1. all shipments in an order have their prices negated
        2. Eligibility is checked whenever shipments are updated
    4. Create LineItems - 
        1. A series of items added to order which may or may not change order’s price
        2. It may have another action to add another adjustment to nullify the cost of adding the product
6. Create New action by inheriting from `Spree::PromotionAction` and adding `Rails.application.config.spree.promotions.actions << MyPromotionAction` to `spree.rb`
7. Rules - 
    1. FirstOrder - user’s first order
    2. Itemtotal - order’s total value is greater then or equal to a given value
    3. Product - order contains a specific product
    4. User - order is by specific order
    5. UserLoggedIn - user is logged in
    6. Spree 2.4 adds two more rules - 
        1. One Use Per User - used by customer only once
        2. Taxons - order includes products with taxon(s) that you associate this rule with
8. Create New rule - 
    1. inherit from `Spree::PromotionRule`
    2. #eligible? -> true or false if order is eligible or not
    3. #actionable? -> true or false if some items in a order are eligible -> Line Item Adjustment
    4. Adding `Rails.application.config.spree.promotions.rules << Spree::Promotion::Rules::MyPromotionRule` to `spree.rb` 
    5. To get the rule to appear in the admin promotions interface - 
        1. Create Partial in - `app/views/spree/admin/promotions/rules/_my_promotion_rule.html.erb`
        2. Add locale to I18n
        3. Restart server

Adjustments
1. Tracks adjustment to price of an order/ line item/shipment
2. Positive(Charges) or Negative(Credits/Discounts).
3. Source -> Spree::TaxRate or Spree::PromotionAction object ->source of adjustment
4. Adjustable -> Object being adjusted -> Order, LineItem, Shipment
5. Create a new Adjuster - 
    1. Inherits from `Spree::Adjustable::Adjuster::Base`
    2. Implement `#update` method
    3. Add `Spree::Adjustable::Adjuster::MyAdjuster` to `Rails.application.config.spree.adjusters` 

Address
1. Track address info for order or user
2. Must be linked to Spree::Country
3. Optionally linked to Spree::State
4. Zone -> Consists of diff. Zone members(Countries/States)
5. Countries -> containers for states
6. States -> useful for tax purposes

Taxation
1. Spree represents taxes for an order using - tax categories and tax rates
2. Products can be linked to tax categories which in turn decide tax rates
3. One default tax category can be set for entire system
4. Tax Category -> 
    1. has_many Tax Rates
    2. By default every product -> exempted from tax
    3. Product is taxable if and only if it belongs to tax category
5. Tax Rate -> 
    1. linked to Zone(Address)
    2. %age amount charged based on sales price
    3. It includes info about product prices are inclusive or exclusive of taxes
    4. Default Tax Calculator uses item total (excluding shipping) when computing Sales Tax
    5. Default Tax Zone -> 
        1. In cart we don’t know which tax zone will be applicable -> so default
        2. For eg. VAT included prices -> we can calculate actual price and tax price using that
    6. Spree by default uses shipping address for determining tax zone. Instead if Billing Address -> `Spree::Config[:tax_using_ship_address] = false`
    7. Spree Calculators are used for tax calculations
    8. Tax Types
        1. Sales Tax - 
            1. Default tax in spree
            2. Based on the address (zone) tax will be applicable 
        2. Tax Included (VAT/GST) - 
            1. Prices of items are inclusive of taxes
            2. No additional tax needs to be applicable
            3. No order adjustments are made

Calculators
1. All calculators extends from `Spree::Calculator` with two methods -> `.description` and `#compute`
2. Belongs to Calculable -> `Spree::ShippingMethod`, `Spree::TaxRate`, `Spree::Promotion::Action::CreateAdjustment`
3. Available Calculators
    1. Default Tax Calculator ->
    2. Flat % Per Item Total -> 
        1. To set preference  -> `calculator.preferred_flat_percent = 10`
        2. `Adjustable amount  = [item total] x [flat percentage]`
    3. Flat Rate -> 
        1. Two Prefernces -> `preferred_amount` & `currency`
        2. Currency is used to check to see if shipping method is available for an order I.e. if currency don’t matched with shipping’s currency then that shipping method will not be shown on frontend
    4. Flexi Rate -> 
        1. Used for promotional discounts when specific discount for first item and then subsequent discounts for other products
        2. 3 Preferences
            1. first_item -> discounted price of first item
            2. additional_item -> discounted price of subsequent items
            3. max_items -> max no. of items discounts applies to
        3. `Adjustable Amount = first_item discount+ [(items_count - 1), max_item].min * additional item discount`
        4. Minus 1 is done as we already counted first item
    5. Free Shipping -> 
    6. Per Item -> 
        1. Computes value for every item within order
        2. 2 Preferences
            1. Amount -> amount per item to calculate
            2. currency -> currency for this calculator
    7. Percent Per Item
        1. Same as 6.) but instead of flat rate it provides %
    8. Price Sack
        1. Useful when order total is above certain amount
        2. 4 Preferences
            1. `minimal_amount` -> minimum amount of item_total to trigger this
            2. `discount_amount` -> amt. of discount when order_total >= minimal amount
            3. `normal_amount`  -> amt. to decrease from order if order_total < minimal amount
            4. `currency` -> currency for this calculator
4. Creating New Calculator
    1. Inherit from `Spree::Calculator`
    2. Define `.description` and `#compute` methods
    3. If this is for shipping -> instead of `Spree::Calculator` Inherit from.`Spree::ShippingCalculator` and define `#compute_package`
    4. Include your calculator using one of the followings in `spree.rb`
        1. `config.spree.calculators.tax_rates << CustomCalculator`
        2. `config.spree.calculators.shipping_methods << CustomCalculator`
        3. `config.spree.calculators.promotion_actions_create_adjustments << CustomCalculator`
    5. Override `#available?` to make this calculator available or not

Shipments
1. States -> 
    1. Pending -> shipment has back-ordered inventory units or order is not paid
    2. Ready -> shipment has no back -ordered inventory and order is paid
    3. Shipped -> shipment is on its way to buyer
    4. Cancelled -> when order is cancelled, all shipments -> cancelled => inventory - restocked.
2. Shipping Methods ->
    1. Actual services used to send product e.g. FedEx, DHL etc.
    2. 1 shipping method is applicable for 1 zone
    3. Shipping categories can be used to qualify or disqualify a given shipping method
3. Zones -> 
    1. Serves as mechanism to group geographical areas together
    2. Shipping Address -> Zone -> Shipping Methods available to customer
4. Shipping Categories -> 
    1. Useful when shipping price vary depending upon type of product eg. Light/Medium/Heavy etc.
    2. Assigned to products
5. Calculators ->
    1. Component responsible for calculating shipping price for each available shipping method