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

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

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/refunds/:order_number/estimate`

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

Response:

```json 
{
  "total_amount": "{money}",
  "subtotal_amount": "{money}",
  "tax_amount": "{money}",
  "discount_amount": "{money}",
  "shipping_amount": "{money}",
  "line_items": [
    {
      "order_line_item_id": "{x_order_line_item_id1}",
      "quantity": 1,
      "total_amount": "{money}",
      "subtotal_amount": "{money}",
      "tax_amount": "{money}",
      "discount_amount": "{money}",
    }
  ]
}
```

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/refunds/:order_number` 

Payload:

```json
{  
  "line_items": [    
    { 
      "order_line_item_id": "{x_order_line_item_id1}",
      "quantity": 2 
    },  
  ],
  "transactions": [{
    "parent_id": "{parent (order) tx id}",
    "amount": "{money}"
  }],
  "note": "comment text",
  "restock": true
}
```

Response:

```json 
{
  "refund_id": "{x_refund_id}",
  "created_at": "{timestamp}",
  "updated_at": "{timestamp}",
  "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}", 
      "quantity": 2 
    },  
  ],
  "transactions": [
    "id": "{refund tx id}",
    "amount": "{money}"
  ],
  "note": "comment text",
  "restock": true
}
```


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