Solidus Returnly
===============

This gem adds the required APIs to allow returnly obtain an estimate, process a return and apply a reimbursement


Spree/Solidus
-----
This gem can be installed on spree and solidus, to release a new version to both registries you need to run 
`bash
$ rake both_releases
`
this will generate two packages, `solidus-returnly` and `spree-returnly`

Current Compat Versions:
 - Solidus : `~>2.0.0`
 - Spree   : `~>3.0.1`

Installation
------------

Add solidus_returnly to your Gemfile:

```ruby
gem 'solidus-returnly'
```

Bundle your dependencies and run the installation generator:

```shell
bundle
bundle exec rails g solidus_returnly:install
```

Testing
-------

First bundle your dependencies, then run `rake`. `rake` will default to building the dummy app if it does not exist, then it will run specs, and [Rubocop](https://github.com/bbatsov/rubocop) static code analysis. The dummy app can be regenerated by using `rake test_app`.

```shell
bundle
bundle exec rake
```

When testing your applications integration with this extension you may use it's factories.
Simply add this require statement to your spec_helper:

```ruby
require 'solidus/returnly/factories'
```

Solidus/Spree Sandbox 
---------------------

You can create a sandbox spree installationm
```shell
git clone git@github.com:solidusio/solidus.git
cd solidus
git co v2.0
bundle install
rake sandbox
cd sandbox
rake spree_auth:admin:create
```

default admin credentials:
```
Email [admin@example.com]
Password [test123]
```

this will create a pristine solidus installation you can add the `solidus_returnly` gem and test the endpoints live  

API 
---

To get an estimate of the return order and taxes

`POST /api/returnly/orders/:order_number/refund_estimate`

Payload:
```json
{
  "items": [
    { 
      "order_line_item_id": "{spree order line item id}", 
      "units": 1
    }
  ]
}
```

Response:

```json 
{
  "product_amount": "{money}",
  "tax_amount": "{money}",
  "discount_amount": "{money}",
  "total_refund_amount": "{money}",
  "refundable_shipping_amount": "{money}",
  "refundable_shipping_tax_amount": "{money}",
  "max_refundable_amount": "{money}",
  "refunds_by_payment_method": [
    {
      "code": "Credit Card",
      "amount": "{money}",
      "original_transaction_id": 1
    }
  ]
}
```

To process the return and apply the reimbursement**immediately** 
you can pass the `restock` parameter on false to prevent the api
to immediately change the stock in the default warehouse

`POST /api/returnly/orders/:order_number/refund` 

Payload:

```json
{  
  "items": [    
    { 
      "order_line_item_id": "{x_order_line_item_id1}",
      "units": 2,
      "restock": true
    }  
  ],
  "notify_shopper": true,
  "product_refund_amount": "{money}",
  "shipping_refund_amount": "{money}",
  "refund_note": "comment text"
}
```

Response:

```json 
{
  "refund_id": "{x_refund_id}",
  "user_id": "{optional merchant user ID}",
  "line_items": [    
    { 
      "refund_line_item_id": "{x_refund_line_item_id1}",
      "order_line_item_id": "{x_order_line_item_id1}", 
      "units": 2 
    },  
  ],
  "transactions": [ 
    {
      "id": "{refund tx id}",
      "amount": "{money}"
    }
  ],
  "refund_note": "comment text",
}
```


Overriding Refund Logic
--------------

Is possible to override the default behavior of the Refund Gem by extending the following classes

`lib/solidus/returnly/refund/return_item_restock_policy.rb`

```ruby
class CustomReturnItemRestockPolicy < ReturnItemRestockPolicy
        def should_return_item?(return_item)
          return_item.cost > 1 
        end
end
```

`lib/solidus/returnly/refund/amount_calculator.rb`

```ruby 
class CustomAmountCalculator < AmountCalculator
        def return_item_refund_amount(return_item)
          default_amount(return_item) - 5.0
        end
end
```

to set your custom classes to the returns process just 
add an initializer file: `cofnig/initializers/returnly.rb`

```ruby 
      Returnly.configure do |config|
        config.return_item_amount_calculator = CustomAmountCalculator
        config.return_item_restock_policy = CustomReturnItemRestockPolicy
        config.refunder = CustomRefunder
        config.refund_calculator = CustomRefunderCalculator
      end
```

Copyright (c) 2017 Returnly Technologies, Inc