voucherify 0.8.2 → 1.0.0

data/README.md

@@ -1,16 +1,47 @@
-## Voucherify Ruby SDK
-
-[Voucherify](http://voucherify.io?utm_source=github&utm_medium=sdk&utm_campaign=acq) is an API-first platform for software developers who are dissatisfied with high-maintenance custom coupon software. Our product is a coupon infrastructure through API that provides a quicker way to build coupon generation, distribution and tracking. Unlike legacy coupon software we have:
-
-* an API-first SaaS platform that enables customisation of every aspect of coupon campaigns
-* a management console that helps cut down maintenance and reporting overhead
-* an infrastructure to scale up coupon activity in no time
-
-Full documentation is located at [voucherify.readme.io](https://voucherify.readme.io).
-
-### Usage
-
-#### Installation
+<p align="center">
+  <img src="./voucherify-ruby-sdk.png"/>
+</p>
+
+<h3 align="center">Official <a href="http://voucherify.io?utm_source=github&utm_medium=sdk&utm_campaign=acq">Voucherify</a> SDK for Ruby</h3>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/voucherify"><img src="https://img.shields.io/gem/v/voucherify.svg" alt="Gem Version"/></a>
+  <a href="https://rubygems.org/gems/voucherify"><img src="https://img.shields.io/gem/dt/voucherify.svg" alt="Gem Downloads"/></a>
+</p>
+<hr />
+
+<p align="center">
+<b><a href="#migration-from-0-x">Migration from 0.x</a></b>
+|
+<b><a href="#setup">Setup</a></b>
+|
+<b><a href="#error-handling">Error handling</a></b>
+|
+<b><a href="#development">Development</a></b>
+|
+<b><a href="#contributing">Contributing</a></b>
+|
+<b><a href="#changelog">Changelog</a></b>
+</p>
+
+<p align="center">
+API:
+<a href="#vouchers-api">Vouchers</a>
+|
+<a href="#distributions-api">Distributions</a>
+|
+<a href="#validations-api">Validations</a>
+|
+<a href="#redemptions-api">Redemptions</a>
+|
+<a href="#customers-api">Customers</a>
+|
+<a href="#utils">Utils</a>
+</p>
+
+---
+
+## Setup
 
 Add this line to your application's Gemfile:
 
@@ -26,870 +57,217 @@ Or install it yourself as:
 
     $ gem install voucherify
 
-#### Authentication
-
-[Log-in](http://app.voucherify.io/#/login) to Voucherify web interface and obtain your Application Keys from [Configuration](https://app.voucherify.io/#/app/configuration):
-
-![](https://www.filepicker.io/api/file/WKYkl2bSAWKHccEN9tEG)
+[Log-in](http://app.voucherify.io/?utm_source=github&utm_medium=sdk&utm_campaign=acq#/login) to Voucherify web interface and obtain your Application Keys from [Configuration](https://app.voucherify.io/?utm_source=github&utm_medium=sdk&utm_campaign=acq#/app/configuration):
 
 ```ruby
-require "voucherify"
+require 'voucherify'
 
-voucherify = Voucherify.new({
-  "applicationId" => "YOUR-APPLICATION-ID-OBTAINED-FROM-CONFIGURATION",
-  "clientSecretKey" => "YOUR-CLIENT-SECRET-KEY-OBTAINED-FROM-CONFIGURATION"
+voucherify = Voucherify::Client.new({
+  :applicationId => 'YOUR-APPLICATION-ID',
+  :clientSecretKey => 'YOUR-CLIENT-SECRET-KEY'
 })
 ```
 
-#### Error handling
-
-This voucherify gem uses [rest-client](https://github.com/rest-client/rest-client) under the hood for handling HTTP calls. In case of an HTTP 4xx or 5xx error, a RestClient exception is thrown. The server's specific response is available in `.response` of the exception object.
-
-```ruby
-begin
-  voucherify.publish("test")
-rescue => e
-  JSON.parse(e.response)
-end
-```
-
-```json
-{
-    "code": 400,
-    "message": "Couldn't find any voucher suitable for publication."
-}
-```
-
-Please refer to [rest-client documentation](https://github.com/rest-client/rest-client#exceptions-see-httpwwww3orgprotocolsrfc2616rfc2616-sec10html) for more detailed information.
-
-#### Listing vouchers
+## API
 
-Use `voucherify.vouchers(filter)` to get a filtered list of vouchers.
+This SDK is fully consistent with restful API Voucherify provides.
+Detailed descriptions and example responses you will find at [official docs](https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq).
+Method headers point to more detailed params description you can use.
 
-Filter paramters
-- code_query
-- limit (default 10)
-- skip (default 0)
-- category
-- campaign
-- customer
-
-Example:
+### Vouchers API
+Methods are provided within `voucherify.vouchers.*` namespace.
+- [Create Voucher](#create-voucher)
+- [Get Voucher](#get-voucher)
+- [Update Voucher](#update-voucher)
+- [Delete Voucher](#delete-voucher)
+- [List Vouchers](#list-vouchers)
+- [Enable Voucher](#enable-voucher)
+- [Disable Voucher](#disable-voucher)
 
+#### [Create Voucher]
 ```ruby
-voucherify.list({ limit: 10, skip: 20, category: "API Test" })
-```
-
-Result:
-```json
-[{
-    "code": "9mYBpIk",
-    "campaign": null,
-    "category": "API Test",
-    "type": "DISCOUNT_VOUCHER",
-    "discount": {
-    "type": "AMOUNT",
-        "amount_off": 400
-    },
-    "start_date": "2016-03-01T12:00:00Z",
-    "expiration_date": null,
-    "publish": {
-        "object": "list",
-        "count": 1,
-        "data_ref": "entries",
-        "entries": [{
-            "channel": "Email",
-            "customer": "alice.morgan@email.com",
-            "customer_id": "cust_1fnSUBno3iimKTPNDCkjg4xV",
-            "published_at": "2016-01-22T09:25:07Z"
-        }]
-    },
-    "redemption": {
-        "object": "list",
-        "quantity": 3,
-        "data_ref": "redemption_entries",
-        "redeemed_quantity": 1,
-        "redemption_entries": [{
-            "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-            "object": "redemption",
-            "date": "2016-04-24T06:03:35Z",
-            "customer_id": null,
-            "tracking_id": "(tracking_id not set)"
-        }]
-    },
-    "active": true,
-    "additional_info": null,
-    "metadata": null
-}, {
-    "code": "AzTsIH",
-    "campaign": null,
-    "category": "API Test",
-    "type": "GIFT_VOUCHER",
-    "gift": {
-        "amount": 10000,
-        "balance": 5000
-    },
-    "start_date": "2016-03-01T10:00:00Z",
-    "expiration_date": null,
-    "publish": {
-        "object": "list",
-        "count": 1,
-        "data_ref": "entries",
-        "entries": [{
-            "channel": "Email",
-            "customer": "alice.morgan@email.com",
-            "customer_id": "cust_1fnSUBno3iimKTPNDCkjg4xV",
-            "published_at": "2016-01-22T09:25:07Z"
-        }]
-    },
-    "redemption": {
-        "object": "list",
-        "quantity": 0,
-        "data_ref": "redemption_entries",
-        "redeemed_quantity": 0,
-        "redeemed_amount": 0,
-        "redemption_entries": []
-    },
-    "active": true,
-    "additional_info": null,
-    "metadata": null
-}]  
+voucherify.vouchers.create(code, options)
 ```
-
-#### Getting voucher details
-
+Check [voucher object](https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#the-voucher-object).
+#### [Get Voucher]
 ```ruby
-voucherify.get("v1GiJYuuS")
+voucherify.vouchers.get(code)
 ```
-
-Result:
-```json
-{
-    "code": "v1GiJYuuS",
-    "campaign": "vip",
-    "type": "DISCOUNT_VOUCHER",
-    "discount": {
-        "percent_off": 10.0,
-        "type": "PERCENT"
-    },
-    "expiration_date": "2016-12-31T23:59:59Z",
-    "publish": {
-        "object": "list",
-        "count": 1,
-        "data_ref": "entries",
-        "entries": [{
-            "channel": "Email",
-            "customer": "alice.morgan@email.com",
-            "customer_id": "cust_1fnSUBno3iimKTPNDCkjg4xV",
-            "published_at": "2016-01-22T09:25:07Z"
-        }]
-    },
-    "redemption": {
-        "object": "list",
-        "quantity": 3,
-        "data_ref": "redemption_entries",
-        "redeemed_quantity": 1,
-        "redemption_entries": [
-            {
-                "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-                "object": "redemption",
-                "date": "2016-04-24T06:03:35Z",
-                "customer_id": null,
-                "tracking_id": "(tracking_id not set)"
-            }
-        ]
-    },
-    "additional_info": ""
-}
-```
-
-#### Getting voucher redemption
-
+#### [Update Voucher]
 ```ruby
-voucherify.redemption("v1GiJYuuS")
+voucherify.vouchers.update(voucher)
 ```
-
-Result:
-```json
-{
-    "quantity": 3,
-    "redeemed_quantity": 1,
-    "redemption_entries": [
-        {
-            "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-            "object": "redemption",
-            "date": "2016-04-24T06:03:35Z",
-            "customer_id": null,
-            "tracking_id": "(tracking_id not set)"
-        }
-    ]
-}
-```
-
-#### Publishing voucher
-
-This method selects a voucher that is suitable for publication, adds a publish entry and returns the voucher.
-A voucher is suitable for publication when it's active and hasn't been published more times than the redemption limit.
-
-Example:
-
+#### [Delete Voucher]
 ```ruby
-voucherify.publish("First Ride")
+voucherify.vouchers.delete(code, [params])
 ```
-
-or
-
+#### [List Vouchers]
 ```ruby
-voucherify.publish({campaign: "First Ride", channel: "Email", customer: "donny.roll@mail.com"})
+voucherify.vouchers.list
 ```
-
-or
-
+#### [Enable Voucher]
 ```ruby
-voucherify.publish({voucher: "FR-zT-u9I7zG", channel: "Email", customer: "donny.roll@mail.com"})
-```
-
-Positive result:
-
-```json
-{
-   "code": "FR-zT-u9I7zG",
-   "campaign": "First Ride",
-   "category": null,
-   "discount": {
-      "type": "PERCENT",
-      "amount_off": 50
-   },
-   "start_date": "2015-01-01T00:00:00Z",
-   "expiration_date": "2016-12-31T23:59:59Z",
-   "publish": {
-        "object": "list",
-        "count": 1,
-        "data_ref": "entries",
-        "entries": [{
-            "channel": "Email",
-            "customer": "donny.roll@mail.com",
-            "customer_id": "cust_1fnSUBno3iimKTPNDCkjg4xV",
-            "published_at": "2016-01-22T09:25:07Z"
-        }]
-   },
-   "redemption": {
-      "object": "list",
-      "quantity": 0,
-      "data_ref": "redemption_entries",
-      "redeemed_quantity": 0,
-      "redemption_entries": []
-   },
-   "active": true,
-   "additional_info": null
-}
-```
-
-Possible error:
-
-```json
-{
-  "code": 400,
-  "message": "Couldn't find any voucher suitable for publication."
-}
+voucherify.vouchers.enable(code)
 ```
-
-#### Validating vouchers
-
-Validation lets you check if given voucher code can be successfuly redeemed.
-
-`voucherify.validate(code, context)`
-
-The `context` param is generally optional unless you are validating a gift voucher or a voucher with order validation rules. 
-Then you have to pass `order.amount` expressed in cents (e.g. $10 is 1000).
-Validation rules also require to pass `order.items` as a list of objects including `product_id`, `sku_id` and `quantity`.
-
-Example:
-
-```
-validation_result = voucherify.validate("91Ft4U", {
-    tracking_id: "john@lemon.com",
-    customer: {
-         id: "cust_07sVjVsr71Ewot9lVZSrIVLH",
-         source_id: "john@lemon.com",
-         name: "John Lemon"
-    },
-    order: {
-        amount: 1250
-        items: [
-             { product_id: "prod_ELvEXqF4qzB7Rs", sku_id: "sku_GoXSOI4FwJZafb", quantity: 1 },
-             { product_id: "prod_wye1naw5JO5dh3", sku_id: "sku_U3rHSlfOCGUnbo", quantity: 2 }
-        ]
-    }
-})
-```
-
-Successful validation result:
-```
-{"code"=>"91Ft4U", "valid"=>true, "gift"=>{"amount"=>10000, "balance"=>5000}, "tracking_id"=>"john@lemon.com"}
-```
-
-Failed validation result:
-```
-{"code"=>"91Ft4U", "valid"=>false, "reason"=>"gift amount exceeded", "tracking_id"=>"john@lemon.com"}
-```
-
-There are several reasons why validation may fail (`valid: false` response). You can find the actual cause in the `reason` field:
-
-- `voucher not found`
-- `voucher is disabled`
-- `voucher not active yet`
-- `voucher expired`
-- `quantity exceeded`
-- `gift amount exceeded`
-- `customer does not match segment rules`
-- `order does not match validation rules`
-
-#### Redeeming voucher
-
-##### 1. Just by code
-
+#### [Disable Voucher]
 ```ruby
-voucherify.redeem("v1GiJYuuS")
+voucherify.vouchers.disable(code)
 ```
+---
 
-Result (voucher details after redemption):
+### Distributions API
+Methods are provided within `voucherify.distributions.*` namespace.
 
-```json
-{
-    "id": "r_yRmanaA6EgSE9uDYvMQ5Evfp",
-    "object": "redemption",
-    "date": "2016-04-25T10:34:57Z",
-    "customer_id": null,
-    "tracking_id": "(tracking_id not set)",
-    "voucher": {
-        "code": "v1GiJYuuS",
-        "campaign": "vip",
-        "type": "DISCOUNT_VOUCHER",
-        "discount": {
-            "percent_off": 10.0,
-            "type": "PERCENT"
-        },
-        "expiration_date": "2016-12-31T23:59:59Z",
-        "redemption": {
-            "object": "list",
-            "quantity": 3,
-            "data_ref": "redemption_entries",
-            "redeemed_quantity": 2,
-            "redemption_entries": [
-                {
-                    "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-                    "object": "redemption",
-                    "date": "2016-04-24T06:03:35Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                },
-                {
-                    "id": "r_yRmanaA6EgSE9uDYvMQ5Evfp",
-                    "object": "redemption",
-                    "date": "2016-04-25T10:34:57Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                }
-            ]
-        },
-        "active": true,
-        "additional_info": ""
-    }
-}
-```
-
-Error:
-```json
-{
-  "code": 400,
-  "message": "voucher expired or quantity exceeded",
-  "details": "v1GiJYuuS"
-}
-```
-
-##### 2. With tracking id
-
-You can provide a tracking id (e.g. your customer's login or a generated id) to the voucher redemption request.
+- [Publish Vouchers](#publish-vouchers)
 
+#### [Publish Vouchers]
 ```ruby
-voucherify.redeem("v1GiJYuuS", "alice.morgan")
+voucherify.distributions.publish(campaign_name)
 ```
 
-Result:
-```json
-{
-    "id": "r_yRmanaA6EgSE9uDYvMQ5Evfp",
-    "object": "redemption",
-    "date": "2016-04-25T10:34:57Z",
-    "customer_id": "cust_84LPwcHJ1jVEpxV1uF9nLLBB",
-    "tracking_id": "alice.morgan",
-    "voucher": {
-        "code": "v1GiJYuuS",
-        "campaign": "vip",
-        "type": "DISCOUNT_VOUCHER",
-        "discount": {
-            "percent_off": 10.0,
-            "type": "PERCENT"
-        },
-        "expiration_date": "2016-12-31T23:59:59Z",
-        "redemption": {
-            "quantity": 3,
-            "redeemed_quantity": 3,
-            "redemption_entries": [
-                {
-                    "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-                    "object": "redemption",
-                    "date": "2016-04-24T06:03:35Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                },
-                {
-                    "id": "r_yRmanaA6EgSE9uDYvMQ5Evfp",
-                    "object": "redemption",
-                    "date": "2016-04-25T10:34:57Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                },
-                {
-                    "id": "r_irOQWUTAjthQwnkn5JQM1V6N",
-                    "object": "redemption",
-                    "date": "2016-04-25T12:04:08Z",
-                    "customer_id": "cust_84LPwcHJ1jVEpxV1uF9nLLBB",
-                    "tracking_id": "alice.morgan"
-                }
-            ]
-        },
-        "active": true,
-        "additional_info": ""
-    }
-}
-```
+---
 
-##### 3. With customer profile
+### Validations API
+Methods are provided within `voucherify.validations.*` namespace.
 
-You can record a detailed customer profile consisting of an `source_id`, `name`, `email`, `description` and a `metadata` section that can include any data you wish. Voucherify will create (or update) provided customer profile in its database.
+- [Validate Voucher](#validate-voucher)
 
+#### [Validate Voucher]
 ```ruby
-voucherify.redeem({
-    "voucher" => "v1GiJYuuS",
-    "customer" => {
-        "source_id" => "alice.morgan",
-        "name" => "Alice Morgan",
-        "email" => "alice@morgan.com",
-        "description" => "look ma no hands",
-        "metadata" => {
-            "locale" => "en-GB",
-            "shoeSize" => 36.6
-        }
-    }
-})
+voucherify.validations.validate_voucher(code, [context])
 ```
 
-##### 4. With customer id
+---
 
-If you already created a customer profile in Voucherify's database, whether it was implicitly by providing it to the `redeem` function or explicitly by invoking the [`customer.create`](#create-customer) method, you can identify your customer in following redemptions by a generated id (starting with `cust_`).
+### Redemptions API
+Methods are provided within `voucherify.redemptions.*` namespace.
 
-```ruby
-voucherify.redeem({
-        "voucher" => "v1GiJYuuS",
-        "customer" => {
-            "id" => "cust_C9qJ3xKgZFqkpMw7b21MF2ow"
-        })
-```
-
-##### 5. With order amount
-
-Redeeming a gift voucher requires passing order amount. The same applies to vouchers with validation rules on order's total amount.  
-Order amount have to be expressed in cents, as an integer. For example $22.50 should be provided as 2250.
-Gift voucher balance will be used to cover the order amount entirely or partially.
+- [Redeem Voucher](#redeem-voucher)
+- [List Redemptions](#list-redemptions)
+- [Get Voucher's Redemptions](#get-vouchers-redemptions)
+- [Rollback Redemption](#rollback-redemption)
 
+#### [Redeem Voucher]
 ```ruby
-voucherify.redeem({
-        "voucher" => "91Ft4U",
-        "order" => {
-            "amount" => 2250
-        })
-```
-
-##### 6. With order items
+voucherify.redemptions.redeem(code, [params])
 
-Vouchers with validation rules regarding products or SKUs require to pass `order.items`.
-Items are a list of objects consisting of `product_id`, `sku_id` and `quantity`.
-
-```javascript
-voucherify.redeem({
-        voucher: "91Ft4U",
-        order: {
-            items: [
-                { product_id: "prod_ELvEXqF4qzB7Rs", sku_id: "sku_GoXSOI4FwJZafb", quantity: 1 },
-                { product_id: "prod_wye1naw5JO5dh3", sku_id: "sku_U3rHSlfOCGUnbo", quantity: 2 }
-            ]
-        })
+// Removed!
+voucherify.redemptions.redeem(code, tracking_id) // use: voucherify.redemptions.redeem(code, {:customer => {:source_id => 'source_id'}})
 ```
-
-#### Listing redemptions
-
-Use `voucherify.redemptions(filter)` to get a filtered list of redemptions.
-Filter parameters:
-
-- limit (default: 100)
-- page (default: 0)
-- start_date (default: beginning of current month)
-- end_date (default: end of current month)
-- result - Success | Failure-NotExist | Failure-Inactive
-- customer - id or source_id
-
-
-Example - 1000 successful redemptions from April 2016:
-
+#### [List Redemptions]
 ```ruby
-filter = {
-    limit: 1000,
-    page: 0,
-    start_date: "2016-04-01T00:00:00",
-    end_date: "2016-04-30T23:59:59",
-    result: "Success"
-}
-
-voucherify.redemptions(filter)
+voucherify.redemptions.list
+voucherify.redemptions.list(params)
 ```
-
-#### Creating vouchers
-
-Use `voucherify.create(code, options)` to create new vouchers.
-
-You can specify voucher's code in the first parameter or pass `nil` to let Voucherify generate one.
-By default a generated code is a 8 characters long alphanumeric string, however,
-you can define how to create the random code passing a `code_config` hash:
-- `length` - Number of characters in a generated code (excluding prefix and postfix).
-- `charset` - Characters that can appear in the code.
-- `prefix` - A text appended before the code.
-- `postfix` - A text appended after the code.
-- `pattern` - A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.
-
+#### [Get Voucher's Redemptions]
 ```ruby
-code = "EASTER-2016" # use given voucher code
-code = nil # for an automatically generated string
-
-# single-use voucher with 10% off discount that is valid throughout the whole 2016
-opts = {
-  code_config: {
-     charset: "0123456789",
-     pattern: "TEST-#####"
-  },
-  category: "New Customers",
-  type: "DISCOUNT_VOUCHER",
-  discount: {
-    percent_off: 10.0,
-    type: "PERCENT"
-  },
-  start_date: "2016-01-01T00:00:00Z",
-  expiration_date: "2016-12-31T23:59:59Z",
-  redemption: {
-    quantity: 1
-  }
-}
-
-voucherify.create(code, opts)
+voucherify.redemptions.get_for_voucher(code)
 ```
-
-Result (voucher details):
-```json
-{
-    "code": "9Yi5g",
-    "campaign": null,
-    "category": "New Customers",
-    "type": "DISCOUNT_VOUCHER",
-    "discount": {
-        "type": "PERCENT",
-        "percent_off": 10.0
-    },
-    "start_date": "2016-01-01T00:00:00Z",
-    "expiration_date": "2016-12-31T23:59:59Z",
-    "publish": {
-        "object": "list",
-        "count": 0,
-        "data_ref": "entries",
-        "entries": []
-    },
-    "redemption": {
-        "object": "list",
-        "quantity": 1,
-        "data_ref": "redemption_entries",
-        "redeemed_quantity": 0,
-        "redemption_entries": []
-    },
-    "active": true,
-    "additional_info": null,
-    "metadata": null
-}
-```
-
-#### Updating vouchers
-
-You can change some properties of a voucher that has been already created:
-- category
-- start date
-- expiration date
-- active
-- additinal info
-- metadata
-
-Other fields than listed above won't be modified. Even if provided they will be silently skipped.
-
-Use `voucherify.update(voucher_update)` to update a voucher.
-
+#### [Rollback Redemption]
 ```ruby
-voucher_update = {
-  "code" => "Summer-2016",
-  "category" => "Season",
-  "start_date" => "2016-07-01T00:00:00Z",
-  "expiration_date" => "2016-08-31T23:59:59Z",
-}
+voucherify.redemptions.rollback(redemption_id, [params])
 
-updated_voucher = voucherify.update(voucher_update)
+// Removed!
+voucherify.redemptions.rollback(code, tracking_id, reason) // use: voucherify.redemptions.rollback(code, {:customer => {:source_id => 'source_id'}, :reason => 'reason'})
 ```
+Check [redemption rollback object](https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#the-redemption-rollback-object).
 
-#### Disabling a voucher
-
-```ruby
-voucherify.disable("EASTER-2016")
-```
+---
 
-The response has empty body.
+### Customers API
+Methods are provided within `voucherify.customers.*` namespace.
 
-#### Enabling a voucher
+- [Create Customer](#create-customer)
+- [Get Customer](#get-customer)
+- [Update Customer](#update-customer)
+- [Delete Customer](#delete-customer)
 
+#### [Create Customer]
 ```ruby
-voucherify.enable("EASTER-2016")
+voucherify.customers.create(customer)
 ```
-
-The response has empty body.
-
-#### Rollback redemption
-
-You can revert a redemption by calling `voucherify.rollback(redemption_id, tracking_id*, reason*, callback*)`.
-This operation creates a rollback entry in voucher's redemption history (`redemption.redemption_entries`)
-and gives 1 redemption back to the pool (decreases `redeemed_quantity` by 1).
-
+Check [customer object](https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#the-customer-object).
+#### [Get Customer]
 ```ruby
-voucherify.rollback("r_irOQWUTAjthQwnkn5JQM1V6N", "alice.morgan")
-```
-
-Result:
+voucherify.customers.get(customer_id)
 ```
-{
-    "id": "rr_1634wLkb8glgRXrTmsxRzDBd",
-    "object": "redemption_rollback",
-    "date": "2016-04-25T10:35:02Z",
-    "customer_id": "cust_84LPwcHJ1jVEpxV1uF9nLLBB",
-    "tracking_id": "alice.morgan",
-    "redemption": "r_irOQWUTAjthQwnkn5JQM1V6N",
-    "voucher": {
-        "code": "v1GiJYuuS",
-        "campaign": "vip",
-        "discount": {
-            "percent_off": 10.0,
-            "type": "PERCENT"
-        },
-        "expiration_date": "2016-12-31T23:59:59Z",
-        "publish": {
-            "object": "list",
-            "count": 0,
-            "data_ref": "entries",
-            "entries": []
-        },
-        "redemption": {
-            "object": "list",
-            "quantity": 3,
-            "data_ref": "redemption_entries",
-            "redeemed_quantity": 2,
-            "redemption_entries": [
-                {
-                    "id": "r_gQzOnTwmhn2nTLwW4sZslNKY",
-                    "object": "redemption",
-                    "date": "2016-04-24T06:03:35Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                },
-                {
-                    "id": "r_yRmanaA6EgSE9uDYvMQ5Evfp",
-                    "object": "redemption",
-                    "date": "2016-04-25T10:34:57Z",
-                    "customer_id": null,
-                    "tracking_id": "(tracking_id not set)"
-                },
-                {
-                    "id": "r_irOQWUTAjthQwnkn5JQM1V6N",
-                    "object": "redemption",
-                    "date": "2016-04-25T12:04:08Z",
-                    "customer_id": "cust_84LPwcHJ1jVEpxV1uF9nLLBB",
-                    "tracking_id": "alice.morgan"
-                },
-                {
-                    "id": "rr_1634wLkb8glgRXrTmsxRzDBd",
-                    "object": "redemption_rollback",
-                    "date": "2016-04-25T10:35:02Z",
-                    "customer_id": "cust_84LPwcHJ1jVEpxV1uF9nLLBB",
-                    "tracking_id": "alice.morgan",
-                    "redemption": "r_irOQWUTAjthQwnkn5JQM1V6N"
-                }
-            ]
-        },
-        "active": true,
-        "additional_info": ""
-    }
-}
-```
-
-#### Create customer
-
+#### [Update Customer]
 ```ruby
-customer = {
-  name: "John Doe",
-  email: "john@email.com",
-  description: "Sample description about customer",
-  metadata: {
-    lang: "en"
-  }
-}
-
-voucherify.create_customer(customer)
+voucherify.customers.update(customer)
 ```
-
-Result:
-
-```json
-{
-    "id": "cust_WGG615E92dhOHz7PV9Vo9gk9",
-    "created_at": "2016-06-12T15:52:49Z",
-    "description": "Sample description about customer",
-    "email": "john@email.com",
-    "metadata": {
-        "lang": "en"
-    },
-    "name": "John Doe",
-    "object": "customer"
-}
-```
-
-#### Get customer
-
+#### [Delete Customer]
 ```ruby
-voucherify.get_customer("cust_WGG615E92dhOHz7PV9Vo9gk9")
-```
+voucherify.customers.delete(customer_id)
+```
+
+---
+
+### Migration from 0.x
+
+Version 1.x of the SDK is not backwards compatible with versions 0.x.
+Changes made in version 1.x mostly relate to grouping methods within namespaces.
+So all you need to do is to follow the list bellow and just replace methods
+with their namespaced equivalent.
+
+- `Voucherify.new(params)` - `Voucherify::Client.new(params)`
+- `voucherify.create(voucher)` - [voucherify.vouchers.create](#create-voucher)
+- `voucherify.get(voucher_code)` - [voucherify.vouchers.get](#get-voucher)
+- `voucherify.update(voucher)` - [voucherify.vouchers.update](#update-voucher)
+- `voucherify.list(params)` - [voucherify.vouchers.list](#list-vouchers)
+- `voucherify.enable(voucher_code)` - [voucherify.vouchers.enable](#enable-voucher)
+- `voucherify.disable(voucher_code)` - [voucherify.vouchers.disable](#disable-voucher)
+- `voucherify.publish(campaign_name)` - [voucherify.distributions.publish](#publish-vouchers)
+- `voucherify.validate(voucher_code, params)` - [voucherify.validations.validate](#validate-voucher)
+- `voucherify.redeem(voucher_code, tracking_id)` - [voucherify.redemptions.redeem](#redeem-voucher)
+- `voucherify.redemption(voucher_code)` - [voucherify.redemptions.get_for_voucher](#get-vouchers-redemptions)
+- `voucherify.redemptions(params)` - [voucherify.redemptions.list](#list-redemptions)
+- `voucherify.rollback(redemption_id, tracking_id, reason)` - [voucherify.redemptions.rollback](#rollback-redemptions)
+- `voucherify.create_customer(customer)` - [voucherify.customers.create](#create-customer)
+- `voucherify.get_customer(customer_id)` - [voucherify.customers.get](#get-customer)
+- `voucherify.update_customer(customer)` - [voucherify.customers.update](#update-customer)
+- `voucherify.delete_customer(customer_id)` - [voucherify.customers.delete](#delete-customer)
+- `Utils.round_money(value)` - `Voucherify::Utils.round_money(value)`
+- `Utils.validate_percent_discount(discount)` - `Voucherify::Utils.validate_percent_discount(discount)`
+- `Utils.validate_amount_discount(discount)` - `Voucherify::Utils.validate_amount_discount(discount)`
+- `Utils.validate_unit_discount(discount)` - `Voucherify::Utils.validate_unit_discount(discount)`
+- `Utils.calculate_price(base_price, voucher, [unit_price])` - `Voucherify::Utils.calculate_price(base_price, voucher, [unit_price])`
+- `Utils.calculate_discount(base_price, voucher, [unit_price])` - `Voucherify::Utils.calculate_discount(base_price, voucher, [unit_price])`
+
+---
+
+### Utils
+
+#### Available methods
+
+- `Voucherify::Utils.round_money(value)`
+- `Voucherify::Utils.validate_percent_discount(discount)`
+- `Voucherify::Utils.validate_amount_discount(discount)`
+- `Voucherify::Utils.validate_unit_discount(discount)`
+- `Voucherify::Utils.calculate_price(base_price, voucher, [unit_price])`
+- `Voucherify::Utils.calculate_discount(base_price, voucher, [unit_price])`
+
+---
+
+## Error handling
 
-Result:
-
-```json
-{
-    "id": "cust_WGG615E92dhOHz7PV9Vo9gk9",
-    "created_at": "2016-06-12T15:52:49Z",
-    "description": "Sample description about customer",
-    "email": "john@email.com",
-    "metadata": {
-        "lang": "en"
-    },
-    "name": "John Doe",
-    "object": "customer"
-}
-```
-
-#### Update customer
+This voucherify gem uses [rest-client](https://github.com/rest-client/rest-client) under the hood for handling HTTP calls. In case of an HTTP 4xx or 5xx error, a RestClient exception is thrown. The server's specific response is available in `.response` of the exception object.
 
 ```ruby
-customer = {
-  id: "cust_WGG615E92dhOHz7PV9Vo9gk9",
-  description: "Sample description about customer with changes"
-}
-voucherify.update_customer(customer)
+begin
+  voucherify.distributions.publish('test')
+rescue => e
+  JSON.parse(e.response)
+end
 ```
 
-Result:
-
 ```json
 {
-    "id": "cust_WGG615E92dhOHz7PV9Vo9gk9",
-    "created_at": "2016-06-12T15:52:49Z",
-    "description": "Sample description about customer with changes",
-    "email": "john@email.com",
-    "metadata": {
-        "lang": "en"
-    },
-    "name": "John Doe",
-    "object": "customer"
-}
-```
-
-#### Delete customer
-
-```ruby
-voucherify.delete_customer("cust_WGG615E92dhOHz7PV9Vo9gk9")
-```
-
-The response has empty body.
-
-#### Utilities
-
-These methods are used to help calculate prices and discounts.
-
-```ruby
-Utils.calculate_price(base_price, voucher, unit_price)
-Utils.calculate_discount(base_price, voucher, unit_price)
-```
-
-Example:
-
-```ruby
-voucher = {
-  category: "New Customers",
-  type: "DISCOUNT_VOUCHER",
-  discount: {
-    percent_off: 10.0,
-    type: "PERCENT"
-  },
-  start_date: "2016-01-01T00:00:00Z",
-  expiration_date: "2016-12-31T23:59:59Z",
-  redemption: {
-    quantity: 1
-  }
-}
-```
-```ruby
-Utils.calculate_price(20.0, voucher, 0);
-```
-
-Result:
-```ruby
-18
-```
-
-Example:
-
-```ruby
-voucher = {
-  category: "New Customers",
-  type: "DISCOUNT_VOUCHER",
-  discount: {
-    amount_off: 7.0,
-    type: "AMOUNT"
-  },
-  start_date: "2016-01-01T00:00:00Z",
-  expiration_date: "2016-12-31T23:59:59Z",
-  redemption: {
-    quantity: 1
-  }
+    "code": 400,
+    "message": "Couldn't find any voucher suitable for publication."
 }
 ```
-```ruby
-Utils.calculate_discount(20.0, voucher, 0);
-```
 
-Result:
-```ruby
-7
-```
+Please refer to [rest-client documentation](https://github.com/rest-client/rest-client#exceptions-see-httpwwww3orgprotocolsrfc2616rfc2616-sec10html) for more detailed information.
 
 ## Development
 
@@ -902,6 +280,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 Bug reports and pull requests are welcome on GitHub at https://github.com/rspective/voucherify-ruby-sdk.
 
 ## Changelog
+- **2016-12-15** - `1.0.0` - introduced namespaces, unified method names, updated README. Migration from versions 0.x required [migration from version 0.x](#migration-from-0x)
 - **2016-12-02** - `0.8.2` - support gift vouchers in utils, fix price and discount calculations for amount discounts 
 - **2016-10-03** - `0.8.1` - publish update 
 - **2016-08-02** - `0.8.0` - validate voucher
@@ -923,3 +302,22 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rspect
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[Create Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#create-voucher
+[Get Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#vouchers-get
+[Update Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#update-voucher
+[Delete Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#delete-voucher
+[List Vouchers]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#list-vouchers
+[Enable Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#enable-voucher
+[Disable Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#disable-voucher
+[Publish Vouchers]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#publish-voucher
+[Validate Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#validate-voucher
+[Redeem Voucher]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#redeem-voucher
+[List Redemptions]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#list-redemptions
+[Get Voucher's Redemptions]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#vouchers-redemptions
+[Rollback Redemption]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#rollback-redemption
+
+[Create Customer]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#create-customer
+[Get Customer]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#read-customer
+[Update Customer]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#update-customer
+[Delete Customer]: https://docs.voucherify.io/reference?utm_source=github&utm_medium=sdk&utm_campaign=acq#delete-customer